Open APIs

Hello,

Wanted to discuss if there is any guideline around what 'href' field under 'service' resource should denote in a 640 Vs 641 (under each Service Order Item) responses. Should this point to a 'Service Inventory' representation or to a ServiceActivationAndConfiguration URL?

 In 640 API user guide, as part of the example of a request/response for activating a new service on the network (page 27) - the created service's href given denotes a serviceActivationAndConfiguration URL. (eg: https://mycsp.com:8080/tmf-api/ServiceActivationAndConfiguration/v4/service/5351). This seem to make sense as 640 operations are expected to directly operate on network and the ServiceActivationAndConfiguration URL can be considered as the representation of the service on the network.

 However there could be implementations that orchestrates both Network and Service Inventory update along with 640 operations (Ref: https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?GroupId=31&MessageKey=37d4cdf6-a887-43c2-8773-436f399e01a1&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer). IG1224 NaaS Service Management v5.1.0 ( page 21, Figure 12: Order Management sequence flow)  also denotes that as part of a 640 operation, internally domain updates the inventory.

In case of 641 – The general expectation is that as part of 641 order , internally both 638 and 640 are invoked and both service inventory and network are updated during the order journey. In TMF 641 User guide examples (page 27)  for modify - one of the service order item href points to the serviceInventory as  http://serverlocation:port/serviceInventoryManagement/v4/service/12

 So – Is there a guideline/general recommendation around what service href should point to in these different cases? or is this subject to implementation/interpretation?

------------------------------
Ambily Narayanan Unni
Telstra Corporation
------------------------------

Hi @Jonathan Goldberg , @Derrick Evans , @Koen Peeters , @David Milham ,  curious to hear your inputs on this based on some of the previous 638, 640, 641 discussions.​​​​

------------------------------
Ambily Narayanan Unni
Telstra Corporation
------------------------------

Hi Ambily
I would suggest the following:

• TMF638 service repository - returned href should definitely be a reference to the endpoint that allows direct retrieval of the service from the inventory
• TMF641 service order - the href at the top level is of course a reference to the service order, not to services that are being dealt with in the order. In the order items, services embedded by value (e.g. new services) will not have href, services embedded by reference should have href pointing to TMF638
• TMF640 service activation - tricky one here. I am responsible for the example :( (mycsp.com:8080 is a giveaway) from about 4 years ago. But it is not a given that the network elements will actually be able to respond to the GET request, and perhaps a specific implementation would reroute to the inventory.

@Ludovic Robert and @Kamal Maghsoudlou may also want to weigh in here​​

------------------------------
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: Jun 20, 2022 19:43
From: Ambily Narayanan Unni
Subject: service href - representation in context of 640 and 641 APIs

Hi @Jonathan Goldberg , @Derrick Evans , @Koen Peeters , @David Milham ,  curious to hear your inputs on this based on some of the previous 638, 640, 641 discussions.​​​​

------------------------------
Ambily Narayanan Unni
Telstra Corporation
------------------------------

This is actually a very good question and it show that a clarification is needed.

I am alligned with Jonathan. For TMF638 and TMF641 the href definitely points to the inventory.
For TMF640 service activation the story is indeed more tricky. TMF640 in principle pushes a service that already exists in the inventory into a network element.
This results in a digital twin of the service with one instance in the inventory and the other instance on the network element.
Do these twins have the same href? I see two options:

1/ Under the assumption is that TMF640 only copies the infromation from inventory to network element there is potentially no need for a differen href.

2/ Under the assumption that TMF640 creates another instance on the network element the href should be different. But that may even imply that it is not the same type of entity. In that case TMF640 should probably handle a different entity than the inventory. Maybe it should become Service (inventory) and ServiceConfiguration (network)? I personally struggle with the fact that we have 2 OpenAPI TMF638 & TMF640 that seem to handle the same entity.

I am personaly inclined towards the second option, but more discussion seems required.

@Zoltan Gelencser @Hugo Vaughan: maybe we should discuss this as part of the network component definition?
​​​

------------------------------
Koen Peeters
OryxGateway
------------------------------

Original Message:
Sent: Jun 21, 2022 02:51
From: Jonathan Goldberg
Subject: service href - representation in context of 640 and 641 APIs

Hi Ambily
I would suggest the following:

• TMF638 service repository - returned href should definitely be a reference to the endpoint that allows direct retrieval of the service from the inventory
• TMF641 service order - the href at the top level is of course a reference to the service order, not to services that are being dealt with in the order. In the order items, services embedded by value (e.g. new services) will not have href, services embedded by reference should have href pointing to TMF638
• TMF640 service activation - tricky one here. I am responsible for the example :( (mycsp.com:8080 is a giveaway) from about 4 years ago. But it is not a given that the network elements will actually be able to respond to the GET request, and perhaps a specific implementation would reroute to the inventory.

@Ludovic Robert and @Kamal Maghsoudlou may also want to weigh in here​​

------------------------------
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: Jun 20, 2022 19:43
From: Ambily Narayanan Unni
Subject: service href - representation in context of 640 and 641 APIs

Hi @Jonathan Goldberg , @Derrick Evans , @Koen Peeters , @David Milham ,  curious to hear your inputs on this based on some of the previous 638, 640, 641 discussions.​​​​

------------------------------
Ambily Narayanan Unni
Telstra Corporation

Thanks for all the insightful comments Thanks @Jonathan Goldberg , @Koen Peeters
I agree with @Koen Peeters on the second point - The concept of two APIs managing the Service entity is bit confusing.

How about affectedService[x].href being used in Service Problem Management? Should that refer to inventory itself as given in 656 API examples while submitting a service problem?
Also same question applies to TMF 653 Service Test management for 'relatedService' . One of the examples show 'relatedService' as below and I am not clear if this is meant to refer to an inventory or a 640 URL.

"relatedService": {
"href": "https://mycsp.com:8080/tmf-api/serviceManagement/v4/service/21",
"id": "21",
"name": "gameService",
"@referredType": "Service"
},
​​​​

------------------------------
Ambily Narayanan Unni
Telstra Corporation
------------------------------

Original Message:
Sent: Jun 21, 2022 06:18
From: Koen Peeters
Subject: service href - representation in context of 640 and 641 APIs

This is actually a very good question and it show that a clarification is needed.

I am alligned with Jonathan. For TMF638 and TMF641 the href definitely points to the inventory.
For TMF640 service activation the story is indeed more tricky. TMF640 in principle pushes a service that already exists in the inventory into a network element.
This results in a digital twin of the service with one instance in the inventory and the other instance on the network element.
Do these twins have the same href? I see two options:

1/ Under the assumption is that TMF640 only copies the infromation from inventory to network element there is potentially no need for a differen href.

2/ Under the assumption that TMF640 creates another instance on the network element the href should be different. But that may even imply that it is not the same type of entity. In that case TMF640 should probably handle a different entity than the inventory. Maybe it should become Service (inventory) and ServiceConfiguration (network)? I personally struggle with the fact that we have 2 OpenAPI TMF638 & TMF640 that seem to handle the same entity.

I am personaly inclined towards the second option, but more discussion seems required.

@Zoltan Gelencser @Hugo Vaughan: maybe we should discuss this as part of the network component definition?
​​​

------------------------------
Koen Peeters
OryxGateway
------------------------------


Original Message:
Sent: Jun 21, 2022 02:51
From: Jonathan Goldberg
Subject: service href - representation in context of 640 and 641 APIs

Hi Ambily
I would suggest the following:

• TMF638 service repository - returned href should definitely be a reference to the endpoint that allows direct retrieval of the service from the inventory
• TMF641 service order - the href at the top level is of course a reference to the service order, not to services that are being dealt with in the order. In the order items, services embedded by value (e.g. new services) will not have href, services embedded by reference should have href pointing to TMF638
• TMF640 service activation - tricky one here. I am responsible for the example :( (mycsp.com:8080 is a giveaway) from about 4 years ago. But it is not a given that the network elements will actually be able to respond to the GET request, and perhaps a specific implementation would reroute to the inventory.

@Ludovic Robert and @Kamal Maghsoudlou may also want to weigh in here​​

------------------------------
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: Jun 20, 2022 19:43
From: Ambily Narayanan Unni
Subject: service href - representation in context of 640 and 641 APIs

Hi @Jonathan Goldberg , @Derrick Evans , @Koen Peeters , @David Milham ,  curious to hear your inputs on this based on some of the previous 638, 640, 641 discussions.​​​​

------------------------------
Ambily Narayanan Unni
Telstra Corporation

To clarify the point about the two APIs (and BTW we have the same for Resource - TMF639 inventory and TMF702 activation)

Although the data model is the same in the two APIs - Service (or Resource), the purpose is completely different, and having two APIs and two end-points is justified.

• The Inventory APIs deal strictly with (well) the inventory, i.e. persistent storage of the data. The POST and PATCH operations are synchronous by definition
• The Activation APIs deal with the network (directly, or via proxy software), and cause "things to happen". Recognizing that the network may be slow to respond, the POST and PATCH operations can be synchronous, using the Monitor pattern

The interesting question, which is not resolved in the documentation, is how to correlate between the service (or resource) in the inventory and the corresponding item in the network. It will probably be an implementation decision, perhaps using externalIdentification structure in inventory entity to relate to the network entity.

------------------------------
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: Jun 22, 2022 03:07
From: Ambily Narayanan Unni
Subject: service href - representation in context of 640 and 641 APIs

Thanks for all the insightful comments Thanks @Jonathan Goldberg , @Koen Peeters
I agree with @Koen Peeters on the second point - The concept of two APIs managing the Service entity is bit confusing.

How about affectedService[x].href being used in Service Problem Management? Should that refer to inventory itself as given in 656 API examples while submitting a service problem?
Also same question applies to TMF 653 Service Test management for 'relatedService' . One of the examples show 'relatedService' as below and I am not clear if this is meant to refer to an inventory or a 640 URL.

"relatedService": {
"href": "https://mycsp.com:8080/tmf-api/serviceManagement/v4/service/21",
"id": "21",
"name": "gameService",
"@referredType": "Service"
},
​​​​

------------------------------
Ambily Narayanan Unni
Telstra Corporation
------------------------------


Original Message:
Sent: Jun 21, 2022 06:18
From: Koen Peeters
Subject: service href - representation in context of 640 and 641 APIs

This is actually a very good question and it show that a clarification is needed.

I am alligned with Jonathan. For TMF638 and TMF641 the href definitely points to the inventory.
For TMF640 service activation the story is indeed more tricky. TMF640 in principle pushes a service that already exists in the inventory into a network element.
This results in a digital twin of the service with one instance in the inventory and the other instance on the network element.
Do these twins have the same href? I see two options:

1/ Under the assumption is that TMF640 only copies the infromation from inventory to network element there is potentially no need for a differen href.

2/ Under the assumption that TMF640 creates another instance on the network element the href should be different. But that may even imply that it is not the same type of entity. In that case TMF640 should probably handle a different entity than the inventory. Maybe it should become Service (inventory) and ServiceConfiguration (network)? I personally struggle with the fact that we have 2 OpenAPI TMF638 & TMF640 that seem to handle the same entity.

I am personaly inclined towards the second option, but more discussion seems required.

@Zoltan Gelencser @Hugo Vaughan: maybe we should discuss this as part of the network component definition?
​​​

------------------------------
Koen Peeters
OryxGateway


Original Message:
Sent: Jun 21, 2022 02:51
From: Jonathan Goldberg
Subject: service href - representation in context of 640 and 641 APIs

Hi Ambily
I would suggest the following:

• TMF638 service repository - returned href should definitely be a reference to the endpoint that allows direct retrieval of the service from the inventory
• TMF641 service order - the href at the top level is of course a reference to the service order, not to services that are being dealt with in the order. In the order items, services embedded by value (e.g. new services) will not have href, services embedded by reference should have href pointing to TMF638
• TMF640 service activation - tricky one here. I am responsible for the example :( (mycsp.com:8080 is a giveaway) from about 4 years ago. But it is not a given that the network elements will actually be able to respond to the GET request, and perhaps a specific implementation would reroute to the inventory.

@Ludovic Robert and @Kamal Maghsoudlou may also want to weigh in here​​

------------------------------
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: Jun 20, 2022 19:43
From: Ambily Narayanan Unni
Subject: service href - representation in context of 640 and 641 APIs

Hi @Jonathan Goldberg , @Derrick Evans , @Koen Peeters , @David Milham ,  curious to hear your inputs on this based on some of the previous 638, 640, 641 discussions.​​​​

------------------------------
Ambily Narayanan Unni
Telstra Corporation