8 About TMF Orders (Cloud Native Only)
Note:
TMF orders are supported for OSM cloud native deployments only.Introduction
- TMF622 Product Ordering Management: This specification defines the Product Order entity and describes operations that can be performed on it. It is intended to cover the COM order fulfillment layer. Its input is an order containing ordered products, bundles, discounts, and so on. Fulfillment of the product order involves handling all operations that act on the ordered products, like partner ordering and shipping. Fulfillment includes transforming the product order into one or more service orders (operations on Customer Facing Services) directed towards a downstream fulfillment system.
- TMF641 Service Ordering Management: This specification defines the Service Order entity and describes operations that can be performed on it. It is intended to cover the SOM order fulfillment layer. Its input is an order containing service entities with associated actions. Fulfillment typically involves interacting with service inventory and network activation, and may also include workforce management and shipping.
About Standards
TMForum
- TMForum created the TMF 630 REST API Design Guidelines to help applications extend the APIs defined by TMF. The OSM extensions align with the documented guidance.
- TMForum provides a means for vendors to "verify the successful implementation of Open APIs in commercial products and real-world deployments" by way of a TMF compliance toolkit. Oracle achieved a successful status on the OSM implementation of both the TMF 622 (v4.0.0) and TMF 641 (v4.1.0) specifications.
For more information, go to: http://www.tmforum.org.
OpenAPI Initiative
The OpenAPI Initiative documents patterns that should be used when extending the schema object. OSM 622 and 641 extensions in this area align with the documented guidance. Parsing technology is used to validate that the structure and syntax of imported TMF specifications at design time aligns with OpenAPI Initiative v3.0.1.
For more information, go to: https://www.openapis.org/.
Terminology
- Object: This is an object that lives in OSM and is managed by OSM.
- API: This is the interface OSM presents in support of the Object.
- Specification: This is the description of the Object, the API, and its semantics; OSM uses this to model, operate, and present the Object.
The following table describes the terminology.
| Name | Type | Description |
|---|---|---|
| Hosted Order | Object | This is the main resource of OSM - each instance represents an order and OSM executes order fulfillment for it, and presents it to the outside world. |
| Hosted Order API | API | This is how the hosted order is presented to the outside world. TMForum examples for this are TMF622 and TMF641. In UML, this is termed as "Provided Interface" and in TMFC (TMForum Component), as "Exposed API". |
| Hosted Order Specification | Specification | The Hosted Order expressed as an OpenAPI, its API and its semantics. |
| TMF cartridge | set of OSM cartridges | A TMF Cartridge is built around exactly one Hosted Order Specification, and provides the fulfillment logic for that order type. |
| Freeform cartridge | set of OSM cartridges | Freeform cartridges include all cartridges prior to 7.5.0 as well as non-TMF cartridges in 7.5.0. |
| Hosted Order Specification | Specification | The Hosted Order expressed as an OpenAPI, its API and its semantics. Used in a TMF cartridge. |
| System Interaction Specification | Specification | The REST API of an external system, expressed as an OpenAPI. Used in any type of cartridge - TMF or freeform. |
Overview of TMF in OSM
When one of the two supported TMF ordering specifications is incorporated into the OSM TMF support framework, it is referred to as a Hosted Order Specification. The hosted order specification is carried in one or more TMF cartridges.
When the cartridges are deployed, the hosted specification is persisted to the OSM DB schema. From here, the Hosted Order Specification is accessed by the OSM Managed Server containers and the OSM Gateway microservice containers. The Managed Servers use this information to enable TMF-related capabilities when an incoming order is processed by this cartridge. These capabilities include the automatic generation of TMF notifications (events) and the ongoing calculation of TMF state.
The TMF microservice containers also use the Hosted Order Specification information to expose the correct REST API to the outside world, and to translate between that API and OSM's internal components and models.
The following diagram illustrates the deployment of a Hosted Specification.
Figure 8-1 Deployment of Hosted Specification
About TMF Specifications
Configuring an OSM instance with TMF ordering support begins with the TMF specification. TMF specifications are based on the OpenAPI Specification which "defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic." Given the critical role of the specification itself, it is important to look inside and understand how different aspects are realized in OSM's TMF framework.
Paths Object
The paths object holds a path to individual endpoints as well as the operations permitted on an endpoint. When OSM cloud native hosts one of the TMF ordering specifications, the endpoints you see defined inside the TMF OpenAPI would be exposed by the OSM Gateway component. The delete and patch operations are unsupported by OSM as there are alternative mechanisms to achieve the same. See the Order Action Comparison table in "About the OSM Endpoints".
The following image shows the paths object in the specification file for TMF622 Product Order.
Figure 8-2 Paths in the specification file
The following diagram shows how the paths object is reflected in OSM.
TMF specifications define not only the endpoints of an application but the event notifications that would travel northbound as well. These are identified in the OpenAPI document as endpoints with the keyword "listener" in the path. Publishing an event is done by posting the event to the listener address.
Event notifications are the vehicle for vital information about the resource, getting communicated to the external world. Lifecycle events such as creation, state change events and certain types of data updates are examples of notifications that OSM Gateway would emit.
The following image shows the listener (Event Notifications) objects in the specification file for TMF622 Product Order.
Figure 8-4 Listeners in the specification file
The following diagram shows how the Event Notifications are reflected in OSM.
Each of the relevant TMF specifications includes a data model that defines the entities involved in support of the domain - product or service. With the TMF framework in OSM, the importing of a TMF specification results in the automatic creation of CDTs for all of the schemas defined in the OpenAPI.
The following image shows the schema objects in the specification file for TMF622 Product Order.
Figure 8-6 Schema objects in TMF 622 Product Order
The following diagram shows how the schema is reflected in OSM.
About OSM Extensions
While the TMF 622 and 641 specifications provide endpoints for basic interactions with an order management system (post and get), they lack a comprehensive set of endpoints that align with OSM's advanced capabilities. In response, OSM has followed the guidelines from TMF 630 and made extensions to TMF's canonical 622 specification.
With the addition of OSM endpoints, upstream components have access to a full range of capabilities that includes creating new orders, submitting revisions, cancel orders, abort orders, suspend and resume orders, and fetch and search for orders using the full set of REST API endpoints described in the OSM extended specification. It is strongly recommended to use the specifications with OSM extensions for both Product Order and Service Order.
In the TMFSchemas sub-folder in the toolkit, OSM extensions have the suffix -OSM in the filename.
About the Specification Version
- The first three digits are reserved for TMForum as TMF specifications are versioned with a three-number scheme.
- The fourth number is reserved for Oracle OSM to version extensions supported by the application itself.
- The fifth number is available for solution developers to version their additional extensions.
About the OSM Endpoints
- The ReviseProductOrder or ReviseServiceOrder task resource must be used instead of PATCH to leverage OSM's comprehensive amendment capabilities.
- OSM's powerful purge capabilities must be used instead of DELETE in order to provide uniform lifecycle management across orders at scale.
- SuspendProductOrder or SuspendServiceOrder: To request the suspension of an order; this is subject to the logic in the Order Lifecycle Policy as well as the configured grace period for in-progress tasks.
- ReviseProductOrder or ReviseServiceOrder: To request a revision to a running order; this is subject to TMF state validation, additional logic in the Order Lifecycle Policy (for solution-specific PONR) as well as the configured grace period for in-progress tasks.
- ResumeProductOrder and ResumeServiceOrder: To resume a previously suspended order.
- AbortProductOrder and AbortServiceOrder: To halt an in-progress order immediately regardless of its current position in the fulfillment.
The range of order actions in OSM prior to TMF support, map onto the range of actions implemented by OSM's new TMF framework.
The following table provides the mapping for TMF622 ProductOrder. The mapping for TMF641 ServiceOrder follows the same pattern.
| Order Action | Canonical TMF Specification | OSM Extended Specification |
|---|---|---|
| Create | POST /productOrder | Same as canonical |
| Update | PATCH /productOrder/<id> | Not supported, use "Revise" |
| Delete | DELETE /productOrder/<id> | Not supported, use OSM purging mechanisms |
| Suspend | via PATCH | POST /suspendProductOrder |
| Resume | via PATCH | POST /resumeProductOrder/<id> |
| Cancel | POST /cancelProductOrder | Same as canonical |
| Abort | Not supported | POST /abortProductOrder/<id> |
| Revise | via PATCH | POST /reviseProductOrder |
| List | GET /productOrder | Same as canonical |
| Find | GET /productOrder/{id} | Same as canonical |
Task Resources
A task resource is used to expose operations that are not easily represented as CRUD operations. TMF uses this pattern for CancelProductOrder and CancelServiceOrder. OSM has continued to use this pattern to model other operations such as revise, suspend, resume and abort.
Some task resources are persisted, resulting in an id which is separate and distinct from the main productOrder id (or serviceOrder id). Clients can use this id to discover the status of the task resource. (GET /reviseProductOrder/{id})
Abort and resume are simple task resources, not requiring persistence of the request. See the Order Processing Sequence Diagrams in this chapter to understand the interaction between the main resource and the task resource.
About OSM Event Notifications
- OSM emits additional creation and state-change events for the suspend and revise task resources. These notifications communicate the state of the task resource and NOT the main order resource.
- Event subscription mechanisms are not used (POST and DELETE on hub). Instead, an Event Target System configuration is used to define a single listener for each Hosted Order Specification. It is expected that this single listener will either consume the events itself, or serve it to a message broker (for example, Kafka).
- Where an operation is not supported (for example, DELETE), then any corresponding event notification is also unsupported (for example, ProductOrderDeleteEvent).
- OSM has scoped the AttributeValueChange events to only trigger on changes to order item state or order item characteristic changes.
- This is a single field. If there are multiple changes to be communicated, then a convention would need to be introduced and communicated to the upstream system so it could effectively parse the data.
- Alternatively, if each event is restricted to a single change, then there is a risk of flooding the system with more events than are needed.
OSM has attempted to resolve these shortcomings in a robust, schema driven way. The fieldPath has been extended to be an array of compound structures that identifies the specific change including action (add, remove), JSON path to the change and the old value.
- OSM has restricted the changes that would trigger the AV event. Changes are limited to the order item state or the order item characteristic fields.
- OSM would include multiple updates in a single event. All updates, whether within a single line item or across multiple line items, would be included in an event, so long as they are all made within the same orderUpdate call to OSM core.
ProductOrderAttributeValueChangeEventOSM payload : {
"eventId":"c6fd423a-777b-4a7e-ae89-d4e12060461a",
"eventTime":"2023-10-19T13:26:25.587Z",
"eventType":"ProductOrderAttributeValueChangeEventOSM",
"fieldPath":[{"change":"add","path":"$..productOrderItem[?(@.id=='0CX-1Z8QSX')].state","oldValue":""}],
"event":{"productOrder":{
"@type":"ProductOrderOSM",
"category":"salesOrder",
"description":"TMF622 OSM Product Order",
"externalId":"456850-osm",
.......
"productOrderItem":[{
"@type":"ProductOrderItem",
"id":"0CX-1Z8QSX",
"action":"add",
"state":"inProgress",
................About the OSM Schema
This section describes the OSM schema extensions.
TMF specifications define a set of order states that have been enhanced in the OSM extended specification. These states are final and cannot be altered. TMF state changes would be communicated upstream in the <resource>StateChangeEvent.
The TMF state is reflected inside the TMF object data served through the REST API (GET /productOrder or GET /serviceOrder). When using any of the OSM UIs (Web Services API, XML API, Task Web UI, Order Management Web client UI), the order state field shown reflects the OSM order state, and not the TMF state.
The following table lists the mappings and usage of the TMF order states:
Table 8-1 Mappings and Usage of the TMF Order States
| TMF State | Usage | OSM Order State |
|---|---|---|
| acknowledged | Not used | Not applicable |
| rejected | Not used Rejected requests are handled through a synchronous HTTP response with appropriate HTTP response code | Not applicable |
| pending | Initial State. After order is created, but before any task has started. Initial State for future dated orders | Created |
| held | Not used | Not applicable |
| inProgress | Order is running | InProgress |
| cancelled | Order has finished being cancelled | Cancelled |
| completed | Order has finished execution with no failures | Completed |
| failed | Order has finished execution and all order lines have failed | Completed |
| partial | Order has finished execution with order lines having a mix of success and failure | Completed |
| assessingCancellation | Not used | InProgress |
| pendingCancellation | Order is running a cancellation request | Amending |
The following table lists the mappings and usage of the state extensions by OSM:
Table 8-2 Mappings and Usage of the State Extensions by OSM
| TMF State | Usage | OSM Order State |
|---|---|---|
| amending | Order is processing a revision request | Amending |
| amending.suspended | Order was processing a revision request but is currently suspended | Amending |
| amending.fallout | Order was processing a revision request but is now waiting on fallout exception resolution | Amending |
| amending.fallout.suspended | A revision request was waiting on fallout exception resolution but is now suspended | Amending |
| pendingCancellation.suspended | Order was running a cancellation request but is now suspended | Amending |
| pendingCancellation.fallout | Order was running a cancellation request but is now waiting on fallout exception resolution | Amending |
| pendingCancellation.fallout.suspended | A cancellation request was waiting on fallout exception resolution but is now suspended | Amending |
| inProgress.fallout | Order is running but is waiting on fallout exception resolution | InProgress |
| inProgress.suspended | Order was running but is currently suspended | InProgress |
| inProgress.fallout.suspended | An order waiting on fallout exception resolution but is now suspended | InProgress |
TMF specifications define a set of order item states that have been enhanced in the OSM extended specification. These states are final and cannot be altered. Changes to order item state would be reflected in the <resource>AttributeValueChangeEvent.
- inProgress.suspended
- inProgress.fallout.suspended
- amending.suspended
- amending.fallout.suspended
- pendingCancellation.suspended
- pendingCancellation.fallout.suspended
When viewing fallout orders in the Order Operations and Fallout Management user interface, there is a column heading for Customer Name. This name would be populated from order data that you control at design-time. The hosted specification entity in Design Studio has a text field where a JSON path can be provided that points to a specific data field under the productOrder or serviceOrder.
-
The import of a 622 specification defaults the value to $.billingAccount.name, but can be modified by the cartridge developer.
-
The import of a canonical 641defaults the value to $.externalReference.name but can be modified by the cartridge developer.
-
The 641 specification has no "natural" location in the schema where a customer name might be found. OSM has therefore extended the 641 schema to introduce a customer name field directly under the serviceOrder.
-
If an OSM extended 641 specification is imported, then the default value will be $.customerName.
About Customer Extensions to TMF Specifications
- Adhering to OpenAPI guidelines when making schema extensions
- Adding to the schema of the primary object (ProductOrder or ServiceOrder) in terms of order data
- Keeping the set of Endpoints (paths) and operations and their contents unchanged
- Keeping the set of Event Notifications (listeners) and their contents unchanged
- Keeping the set of Task Resources and their contents unchanged
- Keeping the set of order state and order item state definitions unchanged (that is, preserve the set of states as-is)
About the Hosted Order Specification
Once the required schema extensions have been made to the specification (optional), the specification needs to be imported into Design Studio. Design Studio analyzes this document and creates multiple cartridge entities automatically. The most visible auto-created cartridge content is a Complex Data Type conforming to the schema in the Hosted Order Specification. A TMF order type can be created by the cartridge developer, using a CDT, as the model of the Product Order or Service Order. Other auto-created cartridge content includes the delivery fulfillment mode, internal roles for TMF support, and Order Lifecycle Policy.
The cartridge developer can then proceed with the standard cartridge development process, creating orchestration entities, processes, tasks, automation plugins, and so on. Building the cartridge results in Design Studio embedding the Hosted Order Specification into the par file along with all the other cartridge content.
About Hosting Expectations
- A Complex Data Type (CDT) is created to match the structure and typing as per the schema for the Product Order or Service Order in the Hosted Order Specification. The cartridge developer must add this exactly once to the order template for a TMF order as a root level element with the name ProductOrder or ServiceOrder, as applicable. This is the primary resource of the Hosted Order Specification.
- A cartridge developer can add more entries to the order template in order to facilitate the actual fulfillment of the order, outside of the primary resource. The primary resource and its underlying CDT can only be modified by using a modified Hosted Order Specification.
- While Order Recognition Rule and Order Lifecycle Policy continue to be managed by the cartridge developer, OSM samples are provided with the data transformation from incoming order request to the order template and will check cancellation and revision automatically against orders and order items in a final TMF state (completed, partial, or failed). These behaviours must be preserved in order to satisfy TMF compliance requirements.
- OSM manages the TMF state field, both at order level and at order item level. The times when cartridge developer needs to signal a state, they must use only an automation framework API to do so (for example, to signal TMF "failed" state for an order item).
- OSM automatically emits order state change events (ProductOrderStateChangeEvent, ServiceOrderStateChangeEvent) whenever there is a change to the order's TMF state.
- OSM automatically emits attribute value change events (ProductOrderAttributeValueChangeEvent, ServiceOrderAttributeValueChangeEvent) whenever specific data (order item state and anything in the order item characteristics) in the auto-generated order template changes. The most common of these would be to signal changes to the state of an order item.
- A cartridge developer can update the business content (primarily, order item characteristics) of the primary resource as part of the order fulfillment. Such updates allow new data from fulfillment to be reflected via GET calls on the primary resource, and where applicable, for events to be generated. For more details about updating TMF data, see OSM Modeling Guide.
About TMF Cartridges
The TMF Cartridge type provides the most support to cartridge developers and system administrators when OSM operates on TMF orders. A TMF Cartridge is built around exactly one Hosted Order Specification, and provides the fulfillment logic for that order type (Product Order or Service Order). The TMF Cartridge is a solution cartridge, and consists of one or more component cartridges - all deployed as one unit.
The term Freeform Cartridge refers to the non-TMF cartridges. Freeform cartridges include all cartridges prior to 7.5.0 as well as non-TMF cartridges in 7.5.0. These cartridges are characterized by a fully open design-time experience, allowing complete flexibility in all of OSM's capabilities - order structure, order state behaviour, eventing and notifications, orchestration, automation, and so on.
Note:
It is important to note that these two cartridge types cannot be combined. If you have a Freeform cartridge, you cannot simply change the order type to TMF. You must start from scratch.The following diagram illustrates the TMF support framework and the Freeform cartridge framework.
The Freeform Cartridge framework encompasses all of OSM's capabilities as exposed to the cartridge. However, when a TMF Cartridge is created from a Hosted Order Specification, some OSM capabilities are taken over by the TMF Support Framework.
- Generating the CDT to represent the primary object (order) in the Hosted Order Specification's schema
- Calculating TMF state and generating state change events
- Monitoring changes to the primary object and generating attribute-value change events
- Propagating data changes from orchestration components back into the primary object
Both the Freeform Cartridge as well as the TMF Cartridge have access to the functionality to support REST interactions. Design Studio provides developers with the capability to send and receive REST requests, responses, and events with external systems (Target Systems) using a System Interaction Specification. See OSM Concepts for details. Also, refer to the OSM Modeling Guide for more information on working with TMF cartridges.
About Event Target System
While the Hosted Specification lists a set of notifications, there must also be configuration to define a listener address for the recipient of the events. This is done via a two-part configuration.
Design Configuration
The Hosted Specification entity in Design Studio includes an "Event Target System" name which reflects a logical system name. All events coming from orders linked to a given Hosted Order Specification (including specification version) are sent to this consumer. Because OSM Gateway emits notifications to a single system only, if the solution design requires events to be sent to multiple consumers or to be filtered in user-defined ways, this is the responsibility of the single consumer defined in the Event Target System.
Deployment Configuration
The cloud native toolkit looks in the specification files for a mapping between the logical target system name (project specification) as well as the URL to the consumer and any authentication configuration (instance specification). At runtime, OSM Gateway resolves the logical target system name for a given Hosted Order Specification by reading deployment artifacts created by the toolkit during instance creation.
The following diagram illustrates the configuration of event target system.
Order Processing Sequence Diagrams
This section provides order processing sequence diagrams for the following flows of a TMF order:
- Basic order flow
- Suspend and Resume
- Cancel order
- Revise order
The following diagram illustrates the Basic Order flow of a TMF order.
The following diagram illustrates the Suspend and Resume Order flow of a TMF order.
The following diagram illustrates the Cancel Order flow of a TMF order.
The following diagram illustrates the Revise Order flow of a TMF order.
