4 Using TMF REST APIs (Cloud Native Only)
REST (Representational State Transfer) APIs are widely used for communication between different software components over HTTP and HTTPS. The OpenAPI specification provides a common language to describe such REST APIs. TMForum has defined specifications that represent the operations of an order management system for a communications service provider.
OSM supports the following TMF ordering specifications:
-
TMF 622 Product Ordering
-
TMF 641 Service Ordering
Note:
TMF REST APIs are supported for OSM cloud native deployments only.Before reading this chapter, read the chapter about TMF Ordering Support in OSM Concepts.
About TMF Ordering in OSM
The design-time journey for TMF ordering support involves importing one of the two supported TMF specifications into Design Studio. Further, design-time configuration provides the necessary support that enables OSM to "host" the specification. When this TMF cartridge is deployed, the OSM Gateway microservice dynamically exposes the REST endpoints that are defined in the specification. If the hosted order specification is TMF 622, this would result in endpoints such as /productOrder. Conversely, if a TMF 641 hosted order specification is deployed, then OSM Gateway would expose endpoints such as /serviceOrder.
Supported Endpoints
This section lists the supported endpoints in the TMF622 and TMF641 specifications. The support either comes from the canonical TMF specification or from extensions made by OSM. If an endpoint is not listed, then it is not supported.
Table 4-1 Supported Endpoints
API Endpoint | Supported Through |
---|---|
/productOrder /serviceOrder |
Canonical or OSM Extension |
/cancelProductOrder /cancelServiceOrder |
Canonical or OSM Extension |
/suspendProductOrder /suspendServiceOrder |
OSM Extension |
/reviseProductOrder /reviseServiceOrder |
OSM Extension |
/resumeProductOrder/{id} /resumeServiceOrder/{id} |
OSM Extension |
/abortProductOrder/{id} /abortServiceOrder/{id} |
OSM Extension |
For further details about each API, refer to the REST API Reference for Oracle Communications Order and Service Management Cloud Native.
Authentication and Authorization
OSM Gateway is secured with OpenID Connect (OIDC). OIDC permissions for users are granted for all operations on OSM Gateway. Access to individual operations cannot be controlled in the same granular fashion as it is for Task Web Client operations via the order lifecycle policy.
In order to access TMF REST APIs, which are secured, the request must contain an access token to gain access for that request. Endpoints that are secured are not only those operating on the hosted object (Product Order or Service Order) and related task resources, but also on the incoming events from external TMF and other sources. Any user who is successfully authenticated with the REST API is automatically authorized to execute all operations in the API across all the orders and task resources defined in the API.
- Client ID
- Client Secret
- Access Token URL
- Scope
- Grant Type (= Client Credentials)
Note:
These credentials, which are used for token generation, should match with those specified in the OIDC credential secret. See the section about creating OSM Gateway secrets in the OSM Cloud Native Deployment Guide for more details.The generated token is added to the header for the requests. The same token can be used for future requests until it expires.
Header Key Authorization
Header Value Bearer access-token
Constructing the Endpoint
Construct the HTTP request on the client as follows:
- API Endpoint URL: It is the combination of the base URL and endpoint path. All API endpoints are relative to the base URL. A complete URL is formed when the base URL is appended with endpoint paths. If version is prefixed with v in the server URL in the OpenAPI specification, then the endpoint version must also be prefixed with v. See the example that follows.
- Request Type: Set the REST Request type as specified for the endpoint.
- Request Headers: Set any required headers as specified by the Open API specification.
- Request Parameters: Include any query parameters and path parameters if required by the API.
- Request Body: Include the payload if required by the API.
- Authentication: Acquire the credentials that are required to generate an access token. Once a token is generated, pass the access token in the Authorization header.
For a Create Product Order request, the following table shows the API attributes and example values:
Table 4-2 API Attributes and Values
API Attribute | Value |
---|---|
API Endpoint URL |
http://hostname:port/orchestration/sr/quick/tmf-api/productOrderingManagement/v4.0.0.1.0/productOrder where hostname and port are the access details of the Kubernetes cluster exposed by your Ingress Controller or Load Balancer. |
Request Type | POST |
Request Header | Content-Type:application/json (The key-value added as header.) |
Request Body | json payload of ProductOrder_Create Schema |
Authentication | Authorization:Bearer access-token (The key-value added as header.) |
Registering for Events
The TMF specifications define not only the endpoints and operations but northbound event notifications as well. TMF 622 and TMF 641 events communicate important information about the resource - lifecycle events such as creation and completion, state changes and certain types of data updates.
The design-time configuration for hosting a specification includes an "Event Target System" name. This should be the logical name for the upstream system that brokers event notifications. The logical system name is decoupled from the actual connection details so that cartridge deployment is not impacted by a specific environment.
At runtime, OSM Gateway would attempt to resolve the logical target system name. To do so, the logical system must be defined in the CNTK instance specification along with the actual server details and any related security scheme. See the OSM Cloud Native Deployment Guide for further details about CNTK configuration.
The following table lists events that are defined in TMF622 and TMF641 specifications:
Table 4-3 List of Supported Events
Events | Canonical | OSM-Extended | Supported? |
---|---|---|---|
ProductOrderCreateEvent | Available | Available | Supported |
ServiceOrderCreateEvent | Available | Available | Supported |
ProductOrderAttributeValueChangeEvent | Available | Available | Supported |
ServiceOrderAttributeValueChangeEvent | Available | Available | Supported |
ProductOrderDeleteEvent | Available | Not Available | Not Supported |
ServiceOrderDeleteEvent | Available | Not Available | Not Supported |
ProductOrderStateChangeEvent | Available | Available | Supported |
ServiceOrderStateChangeEvent | Available | Available | Supported |
ProductOrderInformationRequiredEvent | Available | Not Available | Not Supported |
ServiceOrderInformationRequiredEvent | Available | Not Available | Not Supported |
ServiceOrderMilestoneEvent | Available | Not Available | Not Supported |
ServiceOrderJeopardyEvent | Available | Not Available | Not Supported |
CancelProductOrderCreateEvent | Available | Available | Supported |
CancelServiceOrderCreateEvent | Available | Available | Supported |
CancelProductOrderStateChangeEvent | Available | Available | Supported |
CancelServiceOrderStateChangeEvent | Available | Available | Supported |
CancelProductOrderInformationRequiredEvent | Available | Not Available | Not Supported |
CancelServiceOrderInformationRequiredEvent | Available | Not Available | Not Supported |
SuspendProductOrderCreateEvent | Not Available | Available | Supported |
SuspendServiceOrderCreateEvent | Not Available | Available | Supported |
SuspendProductOrderStateChangeEvent | Not Available | Available | Supported |
SuspendServiceOrderStateChangeEvent | Not Available | Available | Supported |
ReviseProductOrderCreateEvent | Not Available | Available | Supported |
ReviseServiceOrderCreateEvent | Not Available | Available | Supported |
ReviseProductOrderStateChangeEvent | Not Available | Available | Supported |
ReviseServiceOrderStateChangeEvent | Not Available | Available | Supported |
The details about each event are available in REST API Reference for Oracle Communications Order and Service Management Cloud Native .
These events will be published to the event target system.
target-system_url/productOrderingManagement/<version>/listener/<event-name>
For
TMF641 related event, the endpoint URL of the event to which it will be published looks as
follows:target-system_url/serviceOrdering/<version>/listener/<event-name>
target-system_url
is the base context URL of the target
system which will be picked from the CNTK instance.
Let us consider, for an OSM cloud native instance as the target system,
sr
and slow
as the project and instance names respectively
and the OSM-Extended TMF622 OpenAPI specification deployed. The OSM-Extended TMF622
Specification has version as part of the server URL in the OpenAPI specification file in the
OSM SDK. Say, this version is v4.0.0.1.0. The Target System URL will be:
http://hostname:port/orchestration/sr/slow/tmf-api
If the event is ProductOrderStateChangeEvent, the endpoint looks like:
http://hostname:port/orchestration/sr/slow/tmf-api/productOrderingManagement/v4.0.0.1.0/listener/ProductOrderStateChangeEvent
This constructed endpoint must be exposed by the Target System in order to receive the notifications.
About the Payload
OSM Gateway expects payload of JSON type and converts it to XML for OSM.
Sample JSON Payload
{
"@type": "ProductOrderOSM_Create",
"description": "sales order Request",
"category": "salesOrder",
"externalId": "456789",
"requestedStartDate": "2022-08-22T17:42:14.668Z",
"priority": "high",
"agreement": [
{
"@type": "AgreementRef",
"id": "1",
"name": "John",
"href": "bar"
}
],
"billingAccount": {
"@type": "BillingAccountRef",
"id": "9SIA-DR5BW",
"name": "e2e_individual20200428233218579@cheers.com",
"href": "bar"
},
"channel": [
{
"@type": "RelatedChannel",
"id": "1",
"name": "foo",
"href": "bar"
}
],
"note": [
{
"@type": "Note",
"id": "1",
"author": "Jean Pontus",
"date": "2022-07-30T08:13:59.509Z",
"text": "This is a TMF 622 Sample Solution product order"
}
],
"payment": [
{
"@type": "PaymentRef",
"id": "2365",
"href": "https://host:port/paymentManagement/v4/cashPayment/2365",
"name": "Cash payment for access fee",
"@referredType": "Payment"
}
],
"productOfferingQualification": [
{
"@type": "ProductOfferingQualificationRef",
"id": "ABC-1Z8QMG",
"name": "dummyPOQualification"
}
],
"quote": [
{
"@type": "QuoteRef",
"id": "ABC-123AGG",
"name": "dummyQuote"
}
],
"relatedParty": [
{
"@type": "RelatedParty",
"id": "456-dd-df45",
"href": "https://host:port/partyManagement/v4/individual/456-dd-df45",
"name": "Joe Doe",
"role": "Seller",
"@referredType": "Individual"
},
{
"@type": "RelatedParty",
"id": "ff55-hjy4",
"href": "https://host:port/partyRoleManagement/v4/customer/ff55-hjy4",
"name": "Jean Pontus",
"@referredType": "Customer"
}
],
"productOrderItem": [
{
"@type": "ProductOrderItem",
"quantity": 1,
"id": "0CX-1Z8QSX",
"action": "add",
"appointment": {
"@type": "AppointmentRef",
"id": "ABC",
"href": "dummy",
"description": "dummyAppointment"
},
"billingAccount": {
"@type": "BillingAccountRef",
"id": "0CX-1XRFRM"
},
"itemPrice": [
{
"@type": "OrderPrice",
"billingAccount": {
"@type": "BillingAccountRef",
"id": "9SIA-DR5BW",
"name": "e2e_individual20200428233218579@cheers.com",
"href": "bar"
},
"price": {
"@type": "Price",
"percentage": 30.00,
"taxRate": 0
},
"priceAlteration": [
{
"@type": "PriceAlteration",
"applicationDuration": 12,
"priceType": "recurring",
"price": {
"@type": "Price",
"percentage": 30.00,
"taxRate": 40.50
},
"productOfferingPrice": {
"@type": "ProductOfferingPriceRef",
"id": "123-ABC",
"name": "dummyPOPriceRef",
"href": "dummy2"
}
}
],
"productOfferingPrice": {
"@type": "ProductOfferingPriceRef",
"id": "123-ABC",
"name": "dummyPOPriceRef",
"href": "dummy3"
}
}
],
"itemTerm": [
{
"@type": "OrderTerm",
"description": "Tariff plan 12 Months commitment",
"name": "12Months"
}
],
"itemTotalPrice": [
{
"@type": "OrderPrice",
"billingAccount": {
"@type": "BillingAccountRef",
"id": "9SIA-DR5BW",
"name": "e2e_individual20200428233218579@cheers.com",
"href": "bar"
},
"price": {
"@type": "Price",
"percentage": 10.00,
"taxRate": 20.50
},
"priceAlteration": [
{
"@type": "PriceAlteration",
"applicationDuration": 12,
"priceType": "recurring",
"price": {
"@type": "Price",
"percentage": 10.05,
"taxRate": 20.5
},
"productOfferingPrice": {
"@type": "ProductOfferingPriceRef",
"id": "123-ABC",
"name": "dummyPOPriceRef",
"href": "dummy4"
}
}
],
"productOfferingPrice": {
"@type": "ProductOfferingPriceRef",
"id": "123-ABC",
"name": "dummyPOPriceRef",
"href": "dummy5"
}
}
],
"payment": [
{
"@type": "PaymentRef",
"id": "2365",
"href": "https://host:port/paymentManagement/v4/cashPayment/2365",
"name": "Cash payment for access fee",
"@referredType": "Payment"
}
],
"product": {
"@type": "ProductRefOrValue",
"id": "0CX-1Z8QMG",
"isBundle": false,
"isCustomerVisible": true,
"name": "Amazon Prime",
"agreement": [
{
"@type": "AgreementItemRef",
"id": "1",
"name": "John",
"href": "bar"
}
],
"billingAccount": {
"@type": "BillingAccountRef",
"id": "9SIA-DR5BW",
"name": "e2e_individual20200428233218579@cheers.com",
"href": "barProduct"
},
"place": [
{
"@type": "RelatedPlaceRefOrValue",
"id": "456-dd-df45",
"href": "https://host:port/partyManagement/v4/individual/456-dd-df45",
"name": "Joe Doe",
"role": "Seller"
}
],
"productCharacteristic": [
{
"@type": "Characteristic",
"name": "Channel",
"valueType": "string",
"value": "Amazon Prime"
},
{
"@type": "Characteristic",
"name": "QoS",
"valueType": "string",
"value": "1080P"
},
{
"@type": "Characteristic",
"name": "BillingAccount",
"valueType": "object",
"value": {
"@type": "BillingAccountRef",
"id": "15"
}
}
],
"productOffering": {
"@type": "ProductOfferingRef",
"id": "14305",
"href": "https://host:port/productCatalogManagement/v4/productOffering/14305",
"name": "Amazon Prime"
},
"productOrderItem": [],
"productPrice": [
{
"@type": "ProductPrice",
"priceType": "recurring",
"name": "Amazon Prime",
"recurringChargePeriod": "month",
"unitOfMeasure": "GB",
"billingAccount": {
"@type": "BillingAccountRef",
"id": "9SIA-DR5BW",
"name": "e2e_individual20200428233218579@cheers.com",
"href": "barProductPrice"
},
"price": {
"@type": "Price",
"percentage": 30.00,
"taxRate": 0
},
"productPriceAlteration": [
{
"@type": "PriceAlteration",
"applicationDuration": 12,
"priceType": "recurring",
"price": {
"@type": "Price",
"percentage": 30.00,
"taxRate": 40.50
},
"productOfferingPrice": {
"@type": "ProductOfferingPriceRef",
"id": "456-ABC",
"name": "dummyPOPriceRef",
"href": "dummy8"
}
}
],
"productOfferingPrice": {
"@type": "ProductOfferingPriceRef",
"id": "987-ABC",
"name": "dummyPOPriceRef",
"href": "dummy9"
}
}
],
"productSpecification": {
"@type": "ProductSpecificationRef",
"name": "Digital TV PS",
"id": "0CX-1YAFD5"
}
},
"productOffering": {
"@type": "ProductOfferingRef",
"id": "0CX-1YAFD5",
"name": "Amazon Prime"
},
"productOfferingQualificationItem": {
"@type": "ProductOfferingQualificationItemRef",
"id": "0CX-1YAFD5",
"productOfferingQualificationId": "ABC-123",
"name": "Amazon Prime Qualification item"
},
"productOrderItem": [],
"productOrderItemRelationship": [
{
"@type": "OrderItemRelationship",
"id": "123",
"relationshipType": "dummyBundles"
}
],
"quoteItem": {
"@type": "QuoteItemRef",
"quoteId": "ABC-123AGG",
"quoteName": "dummyQuote",
"id": "ABC",
"name": "dummyQuoteItem"
}
}
]
}
Sample XML Payload
<productOrder xmlns="http://oracle.communications.orchestration.com/tmf-api/productOrderingManagement/4.0.0.1.0/productOrder/inputMessage" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ProductOrderOSM_Create">
<description>sales order Request</description>
<category>salesOrder</category>
<externalId>456789</externalId>
<requestedStartDate>2022-08-22T17:42:14.668Z</requestedStartDate>
<priority>high</priority>
<agreement xsi:type="AgreementRef">
<id>1</id>
<name>John</name>
<href>bar</href>
</agreement>
<billingAccount xsi:type="BillingAccountRef">
<id>9SIA-DR5BW</id>
<name>e2e_individual20200428233218579@cheers.com</name>
<href>bar</href>
</billingAccount>
<channel xsi:type="RelatedChannel">
<id>1</id>
<name>foo</name>
<href>bar</href>
</channel>
<note xsi:type="Note">
<id>1</id>
<author>Jean Pontus</author>
<date>2022-07-30T08:13:59.509Z</date>
<text>This is a TMF 622 Sample Solution product order</text>
</note>
<payment xsi:type="PaymentRef">
<id>2365</id>
<href>https://host:port/paymentManagement/v4/cashPayment/2365</href>
<name>Cash payment for access fee</name>
<_referredType>Payment</_referredType>
</payment>
<productOfferingQualification xsi:type="ProductOfferingQualificationRef">
<id>ABC-1Z8QMG</id>
<name>dummyPOQualification</name>
</productOfferingQualification>
<quote xsi:type="QuoteRef">
<id>ABC-123AGG</id>
<name>dummyQuote</name>
</quote>
<relatedParty xsi:type="RelatedParty">
<id>456-dd-df45</id>
<href>https://host:port/partyManagement/v4/individual/456-dd-df45</href>
<name>Joe Doe</name>
<role>Seller</role>
<_referredType>Individual</_referredType>
</relatedParty>
<relatedParty xsi:type="RelatedParty">
<id>ff55-hjy4</id>
<href>https://host:port/partyRoleManagement/v4/customer/ff55-hjy4</href>
<name>Jean Pontus</name>
<_referredType>Customer</_referredType>
</relatedParty>
<productOrderItem xsi:type="ProductOrderItem">
<quantity>1</quantity>
<id>0CX-1Z8QSX</id>
<action>add</action>
<appointment xsi:type="AppointmentRef">
<id>ABC</id>
<href>dummy</href>
<description>dummyAppointment</description>
</appointment>
<billingAccount xsi:type="BillingAccountRef">
<id>0CX-1XRFRM</id>
</billingAccount>
<itemPrice xsi:type="OrderPrice">
<billingAccount xsi:type="BillingAccountRef">
<id>9SIA-DR5BW</id>
<name>e2e_individual20200428233218579@cheers.com</name>
<href>bar</href>
</billingAccount>
<price xsi:type="Price">
<percentage>30.0</percentage>
<taxRate>0.0</taxRate>
</price>
<priceAlteration xsi:type="PriceAlteration">
<applicationDuration>12</applicationDuration>
<priceType>recurring</priceType>
<price xsi:type="Price">
<percentage>30.0</percentage>
<taxRate>40.5</taxRate>
</price>
<productOfferingPrice xsi:type="ProductOfferingPriceRef">
<id>123-ABC</id>
<name>dummyPOPriceRef</name>
<href>dummy2</href>
</productOfferingPrice>
</priceAlteration>
<productOfferingPrice xsi:type="ProductOfferingPriceRef">
<id>123-ABC</id>
<name>dummyPOPriceRef</name>
<href>dummy3</href>
</productOfferingPrice>
</itemPrice>
<itemTerm xsi:type="OrderTerm">
<description>Tariff plan 12 Months commitment</description>
<name>12Months</name>
</itemTerm>
<itemTotalPrice xsi:type="OrderPrice">
<billingAccount xsi:type="BillingAccountRef">
<id>9SIA-DR5BW</id>
<name>e2e_individual20200428233218579@cheers.com</name>
<href>bar</href>
</billingAccount>
<price xsi:type="Price">
<percentage>10.0</percentage>
<taxRate>20.5</taxRate>
</price>
<priceAlteration xsi:type="PriceAlteration">
<applicationDuration>12</applicationDuration>
<priceType>recurring</priceType>
<price xsi:type="Price">
<percentage>10.05</percentage>
<taxRate>20.5</taxRate>
</price>
<productOfferingPrice xsi:type="ProductOfferingPriceRef">
<id>123-ABC</id>
<name>dummyPOPriceRef</name>
<href>dummy4</href>
</productOfferingPrice>
</priceAlteration>
<productOfferingPrice xsi:type="ProductOfferingPriceRef">
<id>123-ABC</id>
<name>dummyPOPriceRef</name>
<href>dummy5</href>
</productOfferingPrice>
</itemTotalPrice>
<payment xsi:type="PaymentRef">
<id>2365</id>
<href>https://host:port/paymentManagement/v4/cashPayment/2365</href>
<name>Cash payment for access fee</name>
<_referredType>Payment</_referredType>
</payment>
<product xsi:type="ProductRefOrValue">
<id>0CX-1Z8QMG</id>
<isBundle>No</isBundle>
<isCustomerVisible>Yes</isCustomerVisible>
<name>Amazon Prime</name>
<agreement xsi:type="AgreementItemRef">
<id>1</id>
<name>John</name>
<href>bar</href>
</agreement>
<billingAccount xsi:type="BillingAccountRef">
<id>9SIA-DR5BW</id>
<name>e2e_individual20200428233218579@cheers.com</name>
<href>barProduct</href>
</billingAccount>
<place xsi:type="RelatedPlaceRefOrValue">
<id>456-dd-df45</id>
<href>https://host:port/partyManagement/v4/individual/456-dd-df45</href>
<name>Joe Doe</name>
<role>Seller</role>
</place>
<productCharacteristic xsi:type="Characteristic">
<name>Channel</name>
<valueType>string</valueType>
<value>Amazon Prime</value>
</productCharacteristic>
<productCharacteristic xsi:type="Characteristic">
<name>QoS</name>
<valueType>string</valueType>
<value>1080P</value>
</productCharacteristic>
<productCharacteristic xsi:type="Characteristic">
<name>BillingAccount</name>
<valueType>object</valueType>
<valueXml>
<xmlData>
<object xsi:type="BillingAccountRef">
<id>15</id>
</object>
</xmlData>
</valueXml>
</productCharacteristic>
<productOffering xsi:type="ProductOfferingRef">
<id>14305</id>
<href>https://host:port/productCatalogManagement/v4/productOffering/14305</href>
<name>Amazon Prime</name>
</productOffering>
<productPrice xsi:type="ProductPrice">
<priceType>recurring</priceType>
<name>Amazon Prime</name>
<recurringChargePeriod>month</recurringChargePeriod>
<unitOfMeasure>GB</unitOfMeasure>
<billingAccount xsi:type="BillingAccountRef">
<id>9SIA-DR5BW</id>
<name>e2e_individual20200428233218579@cheers.com</name>
<href>barProductPrice</href>
</billingAccount>
<price xsi:type="Price">
<percentage>30.0</percentage>
<taxRate>0.0</taxRate>
</price>
<productPriceAlteration xsi:type="PriceAlteration">
<applicationDuration>12</applicationDuration>
<priceType>recurring</priceType>
<price xsi:type="Price">
<percentage>30.0</percentage>
<taxRate>40.5</taxRate>
</price>
<productOfferingPrice xsi:type="ProductOfferingPriceRef">
<id>456-ABC</id>
<name>dummyPOPriceRef</name>
<href>dummy8</href>
</productOfferingPrice>
</productPriceAlteration>
<productOfferingPrice xsi:type="ProductOfferingPriceRef">
<id>987-ABC</id>
<name>dummyPOPriceRef</name>
<href>dummy9</href>
</productOfferingPrice>
</productPrice>
<productSpecification xsi:type="ProductSpecificationRef">
<name>Digital TV PS</name>
<id>0CX-1YAFD5</id>
</productSpecification>
</product>
<productOffering xsi:type="ProductOfferingRef">
<id>0CX-1YAFD5</id>
<name>Amazon Prime</name>
</productOffering>
<productOfferingQualificationItem xsi:type="ProductOfferingQualificationItemRef">
<id>0CX-1YAFD5</id>
<productOfferingQualificationId>ABC-123</productOfferingQualificationId>
<name>Amazon Prime Qualification item</name>
</productOfferingQualificationItem>
<productOrderItemRelationship xsi:type="OrderItemRelationship">
<id>123</id>
<relationshipType>dummyBundles</relationshipType>
</productOrderItemRelationship>
<quoteItem xsi:type="QuoteItemRef">
<quoteId>ABC-123AGG</quoteId>
<quoteName>dummyQuote</quoteName>
<id>ABC</id>
<name>dummyQuoteItem</name>
</quoteItem>
</productOrderItem>
</productOrder>
It is possible that payloads contain data that is not part of the schema defined in the specification that is used. You have control to determine whether strict parsing should be used or whether extra data can simply be silently pruned. The validations property in the project specification will be used to set incoming and outgoing validations. You can specify STRICT and PRUNE.