10 Modeling a TMF Solution (Cloud Native Only)
This chapter describes how to model a TMF solution.
Before learning how to model a TMF solution, see the chapter about TMF concepts in OSM Concepts.
Note:
TMF solution modeling is supported for OSM cloud native deployments only.About Specifications
The first consideration when modeling a TMF solution is to define the specification to be used.
- Orders cannot be suspended or resumed
- Orders cannot be aborted
- Existing orders cannot be revised (amended)
- TMF has no state to indicate fallout
Because of this, it is strongly recommended to start with the OSM extended specifications which align with OSM's advanced order management capabilities.
- Does your billing system need extra information that is not found in the existing billingAccountRef schema?
- Does your productOrder need to track shipment tracking information?
- Are you integrating with an edge system that requires data that does not exist inside the specification of interest?
These are the types of questions that you need to answer and then modify the schema of the specification accordingly. See OpenAPI Specification documentation as well.
All schema changes that you make must result in a version increase inside the specification. The 5th digit of the version is provided for your use.
About Cancelling or Revising an Inflight Order
The canonical TMF 622 and 641 specifications include support for order cancellations but not for revisions. When support for revisions is a requirement, then the OSM extended specifications must be used (either directly or as the base for customer schema extensions).
Cancel and revise are both implemented using the TMF pattern of a task resource. Refer to the TMF 630 guidelines for further details.
Cancel Specific Behavior
Requested cancellation date in the cancel payload is not supported. You cannot request a future date for cancellation via this field. All requests are processed immediately.
Revise Specific Behavior
Revisions to a future-dated order (that are in a TMF state of Pending) are processed immediately. The waiting base order would be updated with the revised data.
The task resource representing the revision request will complete, the OSM revision order will complete and the base order will reflect the amended data and will remain in TMF pending state (OSM waiting state), until the future-dated date arrives.
Design-time Considerations
For TMF cartridges, cancellations are processed as an amendment with no order lines, which would trigger undo mode of all completed tasks.
- The cancel fulfillment mode does not need to be created in Design Studio.
- Amendment tab configuration for an order (will be read only for TMF orders).
Automation tasks still need to configure the various execution modes.
Runtime Considerations
OSM Gateway exposes endpoints for cancelling or revising a product or service order and all existing cancel or revise mechanisms (Task Web client, SOAP webservice, and so on) are no longer permitted.
OSM Gateway rejects cancels or revisions where the base order contains any order item in a final TMF state (partial, failed, completed).
Order Key
In Freeform cartridges, order key configuration is needed as a way to correctly identify the base order the revision is applied to. It did not reflect the OSM order id but a piece of data inside the order payload that could be used as a unique identifier of the base order.
REVISE
ReviseProductOrderOSM_Create:
required:
- baseOrderRef
- productOrder
type: object
description: OSM extension to create the ReviseProductOrder resource. This represents an OSM revision request.
properties:
baseOrderRef:
$ref: '#/components/schemas/BaseOrderRefOSM'
productOrder:
$ref: '#/components/schemas/ProductOrder_Create'
.......In the above example, the BaseOrderRefOSM has the id of the targetted base order.
CANCEL
CancelProductOrder_Create:
required:
- productOrder
type: object
properties:
cancellationReason:
type: string
description: Reason why the order is cancelled.
productOrder:
$ref: '#/components/schemas/ProductOrderRef'In the example above, the ProductOrderRef has the id of the targetted base order.
Version
Version is still an important piece of the amendment functionality. However, the handling is different for TMF Orders. Instead of the order carrying the version information inside the payload, it is passed as the HTTP header "X-VERSION". Providing this header is optional for cancels, but mandatory for revise operations.
Callers can supply the HTTP header X-VERSION on the create request, but if omitted (as is generally the case for create), then OSM starts versioning at 1. When a GET is invoked, the header "X-VERSION" indicating the version of the order currently being processed, is returned to the caller.
Once the caller has this information, any subsequent requests for revise or cancel can include an incremented count.
While the mechanism to pass the version information is different for TMF orders, the logic that dictates acceptance or rejection is the same. Orders with a version higher than the order currently processing version are accepted and those with a version lower are rejected.Impact of PONR
When a cancel request is received, OSM Gateway checks if any order items are in a final state and if so, the request is rejected. This is a form of implicit PONR as TMF states are final (partial, failed, completed). Therefore, a cancel cannot be performed.
If OSM Gateway accepts the cancel request, there is still a chance for the cartridge to reject it if the order or order items have reached PONR. See "Modeling PONR" for details about how the lifecycle policy can reject orders.
Grace Period
A grace period refers to a configurable period of time that OSM will wait for currently processing tasks to complete, before transitioning an order. In Freeform cartridges, you can pass a grace value during Web Service API invocation.
TMF orders do not allow you to supply a grace period when invoking the REST APIs. Grace period must be defined within the cartridge for TMF orders.
Events about Cancel and Revise Task Resource
The following events are emitted automatically to the event target system in response to lifecycle milestones of the task resource.
Table 10-1 Cancel and Revise Task Resource Events
| OSMGW Endpoint | Task Resource Events |
|---|---|
| /cancelProductOrder |
cancelProductOrderCreateEvent cancelProductOrderStateChangeEvent |
| /reviseProductOrder |
reviseProductOrderCreateEvent reviseProductOrderStateChangeEvent |
| /cancelServiceOrder |
cancelServiceOrderCreateEvent cancelServiceOrderStateChangeEvent |
| /reviseServiceOrder |
reviseServiceOrderCreateEvent reviseServiceOrderStateChangeEvent |
Task Resource Sequence Diagram
The lifecycle of a task resource is different from the main resource. The following diagrams show how the two lifecycles interact and when events are delivered in relation to the main resource events.
Modeling PONR
For TMF orders, the modeling pattern with respect to the Point of No Return of an order or order item is different.
- PONR detection
- Propagation of the PONR to the upstream system
- Order amendment and cancellation handling for PONR
PONR detection
- For Freeform cartridges, PONR is configured within a Fulfillment Pattern. An Order Component is selected, and then a specific fulfillment state value can be chosen as the PONR.
- TMF cartridges are required to model the PONR as an order item characteristic within the product model. Population of this field signals PONR has been reached.
In both cases, an automation plugin updates a piece of order data in response to values received from the edge system. With plugins in the Freeform cartridge, this process is a mechanical update to the fulfillment state field.
In the case of TMF cartridge plugins, they must be aware of which characteristic needs to be updated, and also what value from the edge system results in a change to this characteristic. For example, a field "PONRReached" that takes Y and N values would be set to N on order creation. At some point during fulfillment, an automation plugin would change this value to "Y" based on the external fulfillment state received from the edge system.
Propagation of PONR to upstream system
- For reeform cartridge, Model Driven Milestones (MDM) is the mechanism to propagate the PONR to upstream systems.
- TMF cartridges rely on the AttributeValueChangeEvent (Product and Service) to inform upstream systems of a change to the characteristic representing PONR status. Because attribute events are triggered for changes to ANY characteristic value, it becomes the responsibility of the event listener to identity the characteristic holding PONR status and check its value.
Order amendment and cancellation handling for PONR
For both TMF and Freeform cartridges, the handling of amendment and cancellations for orders and order items that may have reached PONR is the same. In both types of cartridges, the objective would be to reject cancellation or revision requests when PONR has been reached. To do this, the order lifecycle policy would have a rule condition defined with a backing XQuery that is responsible for scanning either the fulfillment state field (Freeform cartridges) or the characteristic value (TMF cartridges) to either pass or fail the condition.
Implicit PONR
For TMF cartridges only, there is an implicit PONR. When any order item reaches a final TMF state, then the entire order can be considered as having reached PONR and cancellations and amendments would be rejected by OSM Gateway.
Change Order Support
- The entire order is included in the change request, lines that have changed as well as lines that have not
- Only the content that has changed is included (and often the necessary parent lines)
Choosing between the two depends on many variables including the product model and capabilities of the edge systems. Neither TMF nor OSM are prescriptive about which modeling pattern is used. However, there are some details within the specifications that may influence which technique is ultimately employed.
Canonical TMF
TMF ordering specifications support action codes on a line item to identify whether it holds a change. Beyond that, there is no support inherent in the TMF specification for identifying what the change is. When there is no indicator as to the specific change, the downstream systems must be idempotent, which implies that those systems own the data and therefore have a view of the current state of the object. When passed a new set of data, they can determine what the change is and what action to take. This puts the onus on the systems that OSM talks to, for determining what data is changed and whether it requires an action or not.
This pattern can be expensive for systems and whether or not external systems in the ecosystem behave according to the TMF view, cannot be dictated by the Product Ordering layer.
OSM Extended Specifications
On lines with an action code of "modify", changes are often contained within the characteristic set - new ones added, characteristics no longer required or simply a change of value on an existing characteristic. Examples include an upgrade from 5MB to 10MB bandwidth, or an upgrade to a premium service which results in new characteristics for callWaiting and callForwarding.
OSM recognizes this and offers optimized handling of characteristic changes via the OSM extended specification.
OSM schema extensions have been made to provide additional details about a characteristic - an action code as well as the previous value. This of course relies on the upstream system to populate this data, but if utilized, it can relieve pressure on the downstream systems to calculate the exact nature of the change.
See the TMF 622 REST Specification for change order modeling examples.
Order Fulfillment Modes
The runtime handling for fulfillment mode is different for TMF orders. With Freeform cartridges, something in the order data would need to map to the right fulfillment mode. With TMF orders, the fulfillment mode does not need to be embedded into the payload and for order creation nor for order cancellations, The calling system in fact does not need to do anything at all. OSM has assumed responsibility for mapping these two order operations properly.
If an additional fulfillment mode was modeled in the TMF cartridge (for example, TSQ), then the calling system would need to supply this value through the HTTP header "X-Fulfillment-Mode". OSM Gateway would forward the FF mode to OSM and would match against deployed fulfillment modes.
Upstream Listener
- An Event Target System must be defined on the hosted order specification in Design Studio.
- Only a single system can be configured. It is expected that this single listener will either consume the events itself, or serve it to a message broker (for example, Kafka).
- The event target system would be the intended recipient of all events that are emitted. The upstream system can ignore messages it is not interested in.
Fault tolerance configuration for target systems is available in the toolkit's specification files. See OSM Cloud Native Deployment Guide for details on configuring target systems.
About TMF Order Events For the External Event Listener
The events for TMF orders run by OSM are listed in the REST API reference guide. See REST API reference guide for the details of the events offers and the schema of the events.
- OSM has restricted the changes that will trigger the AtributeValueChange event. Changes are limited to the order item state or the order item characteristic fields.
- OSM will include multiple updates in a single event. All updates - whether within a single line item or across multiple line items - will be included in an event, so long as they are all made within the same orderUpdate call to OSM core.