TMF629 Documentation vs Conformance Inconsistency

6. RE: TMF629 Documentation vs Conformance Inconsistency

Like

TM Forum Member

Eduardo Sanchez

Posted Oct 27, 2021 04:11

Thanks Jonathan. How can I have a follow up with the TM Forum focals for CTKs so that I am aware when the CTK is updated or any other resolution.

------------------------------
Eduardo Sanchez
MATRIXX Software
------------------------------

Original Message

Original Message:
Sent: Oct 25, 2021 09:35
From: Jonathan Goldberg
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi all
engagedParty is definitely mandatory in Customer (and PartyRole) creation, it represents the party who is playing the Customer (or PartyRole).
However there was a defect in older versions in this area, and it's possible that when it was fixed they didn't update the examples.
Regarding the charset, I've sent a mail to the TM Forum focals for CTKs asking them to take a look.
Hope it helps.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Oct 19, 2021 06:47
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Adinan,

You are right, the problem was not caused by the relatedParty since the CTK-Customer-4.0.0 postman collection was sending engagedParty.

The problem is on a header, the swagger.json spec available in the TMF website and used to generate the OpenAPI server specifies that the server should produce and consume "application/json;charset=utf-8":

consumes: [
   "application/json;charset=utf-8"
],
produces: [
   "application/json;charset=utf-8"
],

Therefor the server created using this OpenAPI spec produces and consumes "application/json;charset=utf-8" but then the CTK is not sending that format, instead it sends: "application/json" which is not interpreted as the same thing:

"request": {
   "method": "POST",
   "header": [
     {
	"key": "Accept",
	"value": "application/json"
     },...

When the CTK request with header Accept: "application/json" is received the server responds with a "406 Not Acceptable" error response.
So there are two options, manually change the swagger.json to:

consumes: [
   "application/json"
],
produces: [
   "application/json"
],

or change the conformance toolkit to send "application/json;charset=utf-8", both of these resources are produced and released by TMF and ideally should not be changed, so I am not sure how to proceed.

Any suggestions?

------------------------------
Eduardo Sanchez
MATRIXX Software

Original Message:
Sent: Oct 15, 2021 14:18
From: Adinan Sousa
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Eduardo,

I agree with you about the inconsistency in the documentation, but in this case I believe that the inconsistency is in the examples, which has relatedParty instead of engagedParty, but when talking about the CTK, the mandatory attributes are engagedParty and name as you can see on the schema, then in this case it seems that there is no need to change it.

Best regards,
Adinan Sousa

------------------------------
Adinan Sousa
Ericsson Inc.

Original Message:
Sent: Oct 14, 2021 11:39
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

I am currently working in the implementation of TMF629 OpenAPI using the official documentation (TMF629_Customer_Management_Specification_API_REST_R19.0.0.pdf) from the following page https://projects.tmforum.org/wiki/display/API/Open+API+Table, but I am facing problems when running the CTK (Conformant Toolkit).

The OpenAPI swagger file clearly specifies the following two mandatory params:

[ "engagedParty", "name" ],

This makes sense according to the documentation diagrams and also to the documentation Create Customer section which specifies clearly which are the two mandatory fields:

But in that same documentation just a few lines after it show an example request body which does not fulfill the mandatory fields:

As you can see there "name" and "relatedParty" are used as a sample request instead of "name" and "engagedParty", also that same request body is the one used by the CTK when running the Customer postman calls to create a customer.

My API is failing because it needs to have an engagedParty instead of relatedParty.

Has anybody faced this kind of problem, and if so how should I proceed? how can I get the CTK changed so that it follows the documentation?

Thanks

------------------------------
Eduardo Sanchez
MATRIXX Software
------------------------------

7. RE: TMF629 Documentation vs Conformance Inconsistency

Like

TM Forum Member

Jonathan Goldberg

Posted Oct 27, 2021 04:35

Hi Eduardo
The most obvious step to take would be to put a Confluence watch on the Open API table pages. This way you get email notification when anything changes.

The main table here
The early access here

To add a watch, simply click the eye icon (labeled Watch) at the top right of the page.

The main table here
The early access here

Hope it helps

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------

Original Message

Original Message:
Sent: Oct 27, 2021 04:10
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

Thanks Jonathan. How can I have a follow up with the TM Forum focals for CTKs so that I am aware when the CTK is updated or any other resolution.

------------------------------
Eduardo Sanchez
MATRIXX Software

Original Message:
Sent: Oct 25, 2021 09:35
From: Jonathan Goldberg
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi all
engagedParty is definitely mandatory in Customer (and PartyRole) creation, it represents the party who is playing the Customer (or PartyRole).
However there was a defect in older versions in this area, and it's possible that when it was fixed they didn't update the examples.
Regarding the charset, I've sent a mail to the TM Forum focals for CTKs asking them to take a look.
Hope it helps.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Oct 19, 2021 06:47
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Adinan,

You are right, the problem was not caused by the relatedParty since the CTK-Customer-4.0.0 postman collection was sending engagedParty.

The problem is on a header, the swagger.json spec available in the TMF website and used to generate the OpenAPI server specifies that the server should produce and consume "application/json;charset=utf-8":

consumes: [
   "application/json;charset=utf-8"
],
produces: [
   "application/json;charset=utf-8"
],

Therefor the server created using this OpenAPI spec produces and consumes "application/json;charset=utf-8" but then the CTK is not sending that format, instead it sends: "application/json" which is not interpreted as the same thing:

"request": {
   "method": "POST",
   "header": [
     {
	"key": "Accept",
	"value": "application/json"
     },...

When the CTK request with header Accept: "application/json" is received the server responds with a "406 Not Acceptable" error response.
So there are two options, manually change the swagger.json to:

consumes: [
   "application/json"
],
produces: [
   "application/json"
],

or change the conformance toolkit to send "application/json;charset=utf-8", both of these resources are produced and released by TMF and ideally should not be changed, so I am not sure how to proceed.

Any suggestions?

------------------------------
Eduardo Sanchez
MATRIXX Software

Original Message:
Sent: Oct 15, 2021 14:18
From: Adinan Sousa
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Eduardo,

I agree with you about the inconsistency in the documentation, but in this case I believe that the inconsistency is in the examples, which has relatedParty instead of engagedParty, but when talking about the CTK, the mandatory attributes are engagedParty and name as you can see on the schema, then in this case it seems that there is no need to change it.

Best regards,
Adinan Sousa

------------------------------
Adinan Sousa
Ericsson Inc.

Original Message:
Sent: Oct 14, 2021 11:39
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

I am currently working in the implementation of TMF629 OpenAPI using the official documentation (TMF629_Customer_Management_Specification_API_REST_R19.0.0.pdf) from the following page https://projects.tmforum.org/wiki/display/API/Open+API+Table, but I am facing problems when running the CTK (Conformant Toolkit).

The OpenAPI swagger file clearly specifies the following two mandatory params:

[ "engagedParty", "name" ],

This makes sense according to the documentation diagrams and also to the documentation Create Customer section which specifies clearly which are the two mandatory fields:

But in that same documentation just a few lines after it show an example request body which does not fulfill the mandatory fields:

As you can see there "name" and "relatedParty" are used as a sample request instead of "name" and "engagedParty", also that same request body is the one used by the CTK when running the Customer postman calls to create a customer.

My API is failing because it needs to have an engagedParty instead of relatedParty.

Has anybody faced this kind of problem, and if so how should I proceed? how can I get the CTK changed so that it follows the documentation?

Thanks

------------------------------
Eduardo Sanchez
MATRIXX Software
------------------------------

8. RE: TMF629 Documentation vs Conformance Inconsistency

Like

TM Forum Member

Eduardo Sanchez

Posted Oct 27, 2021 05:25

Thanks!

------------------------------
Eduardo Sanchez
MATRIXX Software
------------------------------

Original Message

Original Message:
Sent: Oct 27, 2021 04:34
From: Jonathan Goldberg
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Eduardo
The most obvious step to take would be to put a Confluence watch on the Open API table pages. This way you get email notification when anything changes.

The main table here
The early access here

To add a watch, simply click the eye icon (labeled Watch) at the top right of the page.

The main table here
The early access here

Hope it helps

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Oct 27, 2021 04:10
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

Thanks Jonathan. How can I have a follow up with the TM Forum focals for CTKs so that I am aware when the CTK is updated or any other resolution.

------------------------------
Eduardo Sanchez
MATRIXX Software

Original Message:
Sent: Oct 25, 2021 09:35
From: Jonathan Goldberg
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi all
engagedParty is definitely mandatory in Customer (and PartyRole) creation, it represents the party who is playing the Customer (or PartyRole).
However there was a defect in older versions in this area, and it's possible that when it was fixed they didn't update the examples.
Regarding the charset, I've sent a mail to the TM Forum focals for CTKs asking them to take a look.
Hope it helps.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Oct 19, 2021 06:47
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Adinan,

You are right, the problem was not caused by the relatedParty since the CTK-Customer-4.0.0 postman collection was sending engagedParty.

The problem is on a header, the swagger.json spec available in the TMF website and used to generate the OpenAPI server specifies that the server should produce and consume "application/json;charset=utf-8":

consumes: [
   "application/json;charset=utf-8"
],
produces: [
   "application/json;charset=utf-8"
],

Therefor the server created using this OpenAPI spec produces and consumes "application/json;charset=utf-8" but then the CTK is not sending that format, instead it sends: "application/json" which is not interpreted as the same thing:

"request": {
   "method": "POST",
   "header": [
     {
	"key": "Accept",
	"value": "application/json"
     },...

When the CTK request with header Accept: "application/json" is received the server responds with a "406 Not Acceptable" error response.
So there are two options, manually change the swagger.json to:

consumes: [
   "application/json"
],
produces: [
   "application/json"
],

or change the conformance toolkit to send "application/json;charset=utf-8", both of these resources are produced and released by TMF and ideally should not be changed, so I am not sure how to proceed.

Any suggestions?

------------------------------
Eduardo Sanchez
MATRIXX Software

Original Message:
Sent: Oct 15, 2021 14:18
From: Adinan Sousa
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Eduardo,

I agree with you about the inconsistency in the documentation, but in this case I believe that the inconsistency is in the examples, which has relatedParty instead of engagedParty, but when talking about the CTK, the mandatory attributes are engagedParty and name as you can see on the schema, then in this case it seems that there is no need to change it.

Best regards,
Adinan Sousa

------------------------------
Adinan Sousa
Ericsson Inc.

Original Message:
Sent: Oct 14, 2021 11:39
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

I am currently working in the implementation of TMF629 OpenAPI using the official documentation (TMF629_Customer_Management_Specification_API_REST_R19.0.0.pdf) from the following page https://projects.tmforum.org/wiki/display/API/Open+API+Table, but I am facing problems when running the CTK (Conformant Toolkit).

The OpenAPI swagger file clearly specifies the following two mandatory params:

[ "engagedParty", "name" ],

This makes sense according to the documentation diagrams and also to the documentation Create Customer section which specifies clearly which are the two mandatory fields:

But in that same documentation just a few lines after it show an example request body which does not fulfill the mandatory fields:

As you can see there "name" and "relatedParty" are used as a sample request instead of "name" and "engagedParty", also that same request body is the one used by the CTK when running the Customer postman calls to create a customer.

My API is failing because it needs to have an engagedParty instead of relatedParty.

Has anybody faced this kind of problem, and if so how should I proceed? how can I get the CTK changed so that it follows the documentation?

Thanks

------------------------------
Eduardo Sanchez
MATRIXX Software
------------------------------

10. RE: TMF629 Documentation vs Conformance Inconsistency

Like

TM Forum Member

Leo Hodgson

Posted Jan 20, 2022 09:00
Edited by Marlon Almazan Jan 26, 2022 12:21

Hi all

The current version of the Conformance Profile document for TMF629 shows the attribute engagedParty as Optional. There is a comment "The sub-property
@referredType is mandatory" but this is still a bit confusing and inconsistent with the main specification document.

Thanks for clarifying.

Regards,

------------------------------
Leo Hodgson
Cerillion Technologies Limited
------------------------------

Original Message

Original Message:
Sent: Oct 26, 2021 21:28
From: Vance Shipley
Subject: TMF629 Documentation vs Conformance Inconsistency

In an Accept or Content-Type HTTP header these are equivalent:

application/json

application/json;charset=utf-8

The MIME type for JSON is provided in RFC4627 where the default encoding is defined as UTF-8.

The TM Forum should however be consistent in their use to avoid the sort of trouble you experienced.

------------------------------
Vance Shipley
SigScale

Original Message:
Sent: Oct 19, 2021 06:47
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Adinan,

You are right, the problem was not caused by the relatedParty since the CTK-Customer-4.0.0 postman collection was sending engagedParty.

The problem is on a header, the swagger.json spec available in the TMF website and used to generate the OpenAPI server specifies that the server should produce and consume "application/json;charset=utf-8":

consumes: [
   "application/json;charset=utf-8"
],
produces: [
   "application/json;charset=utf-8"
],

Therefor the server created using this OpenAPI spec produces and consumes "application/json;charset=utf-8" but then the CTK is not sending that format, instead it sends: "application/json" which is not interpreted as the same thing:

"request": {
   "method": "POST",
   "header": [
     {
	"key": "Accept",
	"value": "application/json"
     },...

When the CTK request with header Accept: "application/json" is received the server responds with a "406 Not Acceptable" error response.
So there are two options, manually change the swagger.json to:

consumes: [
   "application/json"
],
produces: [
   "application/json"
],

or change the conformance toolkit to send "application/json;charset=utf-8", both of these resources are produced and released by TMF and ideally should not be changed, so I am not sure how to proceed.

Any suggestions?

------------------------------
Eduardo Sanchez
MATRIXX Software

Original Message:
Sent: Oct 15, 2021 14:18
From: Adinan Sousa
Subject: TMF629 Documentation vs Conformance Inconsistency

Hi Eduardo,

I agree with you about the inconsistency in the documentation, but in this case I believe that the inconsistency is in the examples, which has relatedParty instead of engagedParty, but when talking about the CTK, the mandatory attributes are engagedParty and name as you can see on the schema, then in this case it seems that there is no need to change it.

Best regards,
Adinan Sousa

------------------------------
Adinan Sousa
Ericsson Inc.

Original Message:
Sent: Oct 14, 2021 11:39
From: Eduardo Sanchez
Subject: TMF629 Documentation vs Conformance Inconsistency

I am currently working in the implementation of TMF629 OpenAPI using the official documentation (TMF629_Customer_Management_Specification_API_REST_R19.0.0.pdf) from the following page https://projects.tmforum.org/wiki/display/API/Open+API+Table, but I am facing problems when running the CTK (Conformant Toolkit).

The OpenAPI swagger file clearly specifies the following two mandatory params:

[ "engagedParty", "name" ],

This makes sense according to the documentation diagrams and also to the documentation Create Customer section which specifies clearly which are the two mandatory fields:

But in that same documentation just a few lines after it show an example request body which does not fulfill the mandatory fields:

As you can see there "name" and "relatedParty" are used as a sample request instead of "name" and "engagedParty", also that same request body is the one used by the CTK when running the Customer postman calls to create a customer.

My API is failing because it needs to have an engagedParty instead of relatedParty.

Has anybody faced this kind of problem, and if so how should I proceed? how can I get the CTK changed so that it follows the documentation?

Thanks

------------------------------
Eduardo Sanchez
MATRIXX Software
------------------------------

Open APIs