11 Implementing a TMF Solution (Cloud Native Only)
This chapter describes how to implement a TMF solution.
Before reading this chapter, see the chapter about TMF concepts in OSM Concepts.
Note:
TMF solution modeling is supported for OSM cloud native deployments only.You need to ensure that the cartridge management variable OSM_RUNTIME_TYPE value is set to "MultiService".Accessing the Specifications
The TMF specification files are available in the cloud native SDK download file, in the TMFSchemas sub-folder. OSM extensions have the suffix -OSM in the filename.
Oracle recommends that you use the specifications with OSM extensions ( -OSM suffix in the filename) for both Product Order and Service Order. These extensions provide comprehensive access to OSM's advanced capabilities and have been created in line with the guidelines from TMF630.
About Extending the Specifications
The OSM extended specifications can be extended further to meet your implementation requirements by:
- Adhering to TMF630 and OpenAPI guidelines on schema extensions.
- Adding to the schema of the primary object (ProductOrder or ServiceOrder) in terms of order data.
- Keeping the set of Paths (endpoints) and their contents unchanged.
- Keeping the set of Notifications (events) and their contents unchanged.
- Keeping the set of Task Resources and their contents unchanged.
- Keeping the set of State definitions unchanged (preserve the set of states as-is).
The Hosted Order specification consists of the TMForum specification with OSM schema extensions, all expressed as an OpenAPI 3.0 document.
Considerations When Extending the Main Resource
TMF uses a pattern of defining a schema object for the incoming create order payload,
that is different from the main resource. Using TMF 622 as an example, the
POST /productOrder endpoint accepts a payload with a schema type
ProductOrder_Create, which is
specific to the creation request. It does not contain some data found in the
ProductOrder schema, such as the id, as this is populated by the application
not provided by the caller.
On the OSM side, the TMF order template includes the CDT structure representing the main resource, which is "ProductOrder" in this case.
The ORR data transormation xquery is responsible for transforming the
ProductOrder_Create into the
ProductOrder. You are free to do this translation as you see fit. However,
the documented solution relies on a simple naming convention. See the Order
Data Rule section.
This xquery depends on the main resource name to be related to the
incoming schema name in a specific way. When processing the incoming root
element, the xquery strips off _Create and uses the
remaining string as the root for the OSM order data. To use this xquery, any
extensions that are made to the main resource must have a schema object for
creation that follows the Resource_Create
convention.
Example: Incompatible naming
ProductOrder_Create
ProductOrder_CreateOSMLooking at the above example, if you had named the schema for
creation as ProductOrder_CreateOSM, then the xquery would
not have done the transformation correctly and order submission would
fail.
Instead, the extension is called
ProductOrderOSM_Create. The xquery determines
correctly that the root resource type is ProductOrderOSM,
which is an extension of the canonical ProductOrder.
Example: Compatible naming
ProductOrder_Create
ProductOrderOSM_CreateIf extensions are made to the main resource (ProductOrder or ServiceOrder), consider this naming convention.
About Versioning the Specifications
When you import a TMF specification into Design Studio, the resulting hosted order specification will have a 5-digit scheme. This is true even if the canonical is imported and there were no extensions added. The TMF specification would say "v4". However, this would be converted to 4.0.0.0.0 for usage inside OSM.
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.
Figure 11-1 Versioning the Specification Files
Cartridge developers must maintain the integrity of the versioning by updating the version (specifically, the fifth number) if changes are made. While it is mandatory to increment the version when there are non-backward-compatible changes, it is recommended to increment the version for all changes to the specification.
About the "ANY" Schema Type
For schemas that refer to "Any" schema, a true "Any" type is not supported because the type of the object is unknown.
The convention TMF uses is that, with the schema object that refers Any, there must be an accompanying string to identify the type and this should point to a known type in the schema. This is more of a dynamic resolution of what will be passed.
Any is used in the canonical specification, for the characteristic value. The accompanying string to identify its type is valueType.
The following abstract shows characteristic schema from the canonical specification:
schema :
Characteristic:
required:
- name
- value
type: object
properties:
name:
type: string
description: Name of the characteristic
valueType:
type: string
description: Data type of the value of the characteristic
value:
$ref: '#/components/schemas/Any'
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
description: A URI to a JSON-Schema file that defines additional attributes
and relationships
format: uri
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
description: Describes a given characteristic of an object or entity through
a name/value pair.During the Data Structure Definition (DSD) generation, while importing the hosted specification for a schema which is of Any type, an additional element of xmlData type will be generated.
For characteristic, valueXml, which is not part of specification, will be generated:
-
The valueType field identifies whether the value is of primitive type string (integer, boolean, string, dateTime, date...) or object type.
-
If valueType is string, the value field would have the value and the valueXml field would be blank.
-
If valueType is of object type, the value field would be blank and the valueXml field would have the objects.
-
Either the value or valueXml field would be available based on the valueType field.
Examples of JSON to XML Conversions
The following example shows the JSON payload when valueType is string:
{
"productCharacteristic": [{
"@type": "Characteristic",
"name": "Call Forwarding",
"valueType": "string",
"value": "Y"
}]
}The following example shows the XML payload when valueType is string:
<productCharacteristic xsi:type="Characteristic">
<_type>Characteristic</_type>
<name>Call Forwarding</name>
<valueType>string</valueType>
<value>Y</value>
</productCharacteristic>The following example shows the JSON payload when valueType is object:
{
"productCharacteristic": [{
"@type": "Characteristic",
"name": "BillingAccount",
"valueType": "object",
"value": {
"@type": "BillingAccountRef",
"id": "15"
}
}]
}The following example shows the XML payload when valueType is object:
<productCharacteristic xsi:type="Characteristic">
<_type>Characteristic</_type>
<name>BillingAccount</name>
<valueType>object</valueType>
<valueXml>
<xmlData>
<object xsi:type="BillingAccountRef">
<_type>BillingAccountRef</_type>
<id>15</id>
</object>
</xmlData>
</valueXml>
</productCharacteristic>About anyOf, allOf, and oneOf
OpenAPI Specification (OAS) describes the various uses of the discriminator object in conjunction with the allOf, anyOf, and oneOf constructs. For details, see the documentation at: https://spec.openapis.org/oas/v3.0.1#discriminator-object.
OSM supports only allOf. The OSM schema extensions use allOf and a discriminator is added to the parent along with propertyName and mapping details. OSM extensions consistently specify the "@type" field as the discriminator propertyName.
In practice, this means that any JSON payload submitted to OSM Gateway when it is hosting an OSM hosted specification must include the @type element on schema objects that have been extended by OSM. You should continue this pattern when making schema extensions and should remember to populate any extensions with the appropriate @type value.
The following is an example of an OSM extension using allOf:
schema:
CharacteristicOSM:
description: OSM extension to include additional (optional) data on a product characteristic
allOf:
- $ref: '#/components/schemas/Characteristic'
- type: object
properties:
unitOfMeasure:
type: string
description: Unit of measure of the value associated with a characteristic. Like MB,GB,Minutes,...
actionCode:
type: string
description: Action taken on a characteristic in a MACD scenario - is it a new value being introduced - existing indicates no change - modifiedAttributs changes the value and delete would remove this characteristic value from the asset
enum:
- new
- existing
- modified
- delete
previousValue:
type: string
description: Value of a characteristic in the original New Product Order (before this Product Order makes a change to it)
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
description: A URI to a JSON-Schema file that defines additional attributes
and relationships
format: uri
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name Characteristic:
required:
- name
- value
type: object
discriminator:
propertyName: '@type'
mapping:
Characteristic: '#/components/schemas/Characteristic'
CharacteristicOSM: '#/components/schemas/CharacteristicOSM' "productCharacteristic": [
{
"@type": "CharacteristicOSM",
"name": "Authorization Code",
"value": "AB1234CD"
}]Including the discriminator object on the parent is optional when using allOf. However, it makes the schema extensions more readable.
About TMF Cartridges and Non-TMF Cartridges
A TMF Cartridge 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.
Non-TMF cartridges are refered to as Freeform 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/notifications, orchestration, automation, and so on.
Table 11-1 Value for Cartridge Management Variable
| Cartridge Type | Variable | Value |
|---|---|---|
| TMF Cartridge | OSM_RUNTIME_TYPE | MultiService |
| Non-TMF Cartridge | OSM_RUNTIME_TYPE | WLS |
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 a TMF cartridge from scratch.Once the TMF configuration is applied, 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 cartridge par file along with all the other cartridge content.
TMF Cartridge Versioning
The version for auto-generated cartridges is specified during the import process. Once a solution is out of the development phase, if schema changes are introduced to the specification, both the specification and the generated OSM cartridge version should be incremented.
TMF Cartridge Target Version
The target version on all OSM cartridges must be set to 7.5.0.
About Importing the Hosted Order Specification
Access the TMF or OSM extended specifications from the OSM Cloud Native SDK download file, in the TMFSchema sub folder. It is strongly recommended to use the OSM extended specification either directly or as a base for custom schema extensions. An OpenAPI parser with support for version 3.0.1 must be able to parse this file once extensions are made. Otherwise, it would be rejected during the import process.
Refer to the Service Catalog and Design Design Studio Modeling OSM Orchestration Online Help for instructions about importing a Hosted Order Specification.
- An OSM cartridge containing some of the entities that are necessary for the TMF framework.
- A second cartridge would contain a set of Complex Data Types (CDT) created to match the structure and typing as per the schema for the Product Order or Service Order in the Hosted Order Specification.
Design Studio does not allow an update to the Hosted Order specification via a menu option. To remove an older version of the Hosted Specification, delete the existing cartridges and re-import the updated specification. You will need to re-apply any changes you have made to the lifecycle policy and fulfillment mode. For this reason, it is important to keep the generated entities and cartridges free from custom additions as these would get removed during this process.
Deployment of a Hosted Order Specification
The specification is bundled with the cartridge par file and is the mechanism for getting it into the database. It is important to note that the specification lifecycle is independent of the cartridge lifecycle.
When a cartridge is undeployed, the specification is not removed and remains in the database. If an attempt is made to deploy a TMF cartridge (new deploy or re-deploy) that bundles a specification of the same version, but with content differences, then the cartridge deploy would fail as the specification with that version already exists. All specification changes should be accompanied by a version increase.
About Fulfillment Modes
When a Hosted Order specification is imported, one of the auto-generated entities is a fulfillment mode named deliver. This fulfillment mode is required for TMF cartridges and should not be renamed or deleted. It should be modified, however, to ensure that its namespace matches the other orchestration entities in the cartridge. Refer to the orchestration process for the correct namespace to be used.
Fulfillment modes for cancel are no longer needed for TMF orders. New fulfillment modes should only be added to support additional types of fulfillment such as TSQ.
The following xquery snippet can be used as a template for the fulfillment mode expression on the order sequence:
(: Declare OSM name space :)
declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
(: Declare incoming order name space:)
declare namespace tmf="http://oracle.communications.orchestration.com/tmf-api/productOrderingManagement/%{TMF622_VERSION}/productOrder/inputMessage";
declare variable $TMF_FULFILLMENT_MODE := "deliver";
declare variable $TMF_FULFILLMENT_NS := "mycompany.tmf.productorder";
let $fulfillmentModeCode := <osm:fulfillmentMode name="{$TMF_FULFILLMENT_MODE }" namespace="{$TMF_FULFILLMENT_NS }"/>
return $fulfillmentModeCodeAbout TMF Order Lifecycle Policy
A default order lifecycle policy is generated that contains the transitions required for the TMF framework to function correctly. This entity may be moved to another cartridge to prevent cyclic dependencies when roles in other cartridges are referenced.
This policy should be modified to add additional transitions for your custom roles, but the existing configuration for "osm-gateway-internal-role" must be left in place.
Automation Users and Roles
Automation users should continue to be given permissions needed as they would in Freeform cartridges.
Fallout Resolution Users and Roles
A role should be created in Design Studio that can be granted the permissions necessary to perform fallout resolution actions. This workgroup should be distinct and separate from automation groups. (for example "FalloutResolutionRole"). This role should be given the required permissions in the order lifecycle policy to enable all fallout resolution actions.
Table 11-2 Required permissions for fallout resolution actions
| State | Transition | Description |
|---|---|---|
|
InProgress Amending Cancelling |
Manage Order Fallout |
This permission is required to enable the Retry Task option in the Task Web client (Fallout Exception Actions menu. Not supported for suspended state. |
|
InProgress Suspended Amending Cancelling |
Abort Order | This permission is required to enable the Abort Order option (Fallout Exception Actions menu) in the Task Web client. |
|
InProgress Suspended Amending Cancelling |
Fail Order | This permission is required to enable the Fail Order option (Fallout Exception Actions menu) in the Task Web client. |
- The user performing the fallout action should be added to the same workgroup as the automation user. This enables the fallout user to see the correct content in the Task Web client.
- Any automation task that is capable of raising a fallout exception should have the "assigned" state available on the task editor state/status tab. This allows users that share the same workgroup, to re-assign a task to themselves.
- From the Task Web client, the fallout user should re-assign the task to themselves.
- Using the Task Web client Editor view, or by choosing the menu action "Manually Complete Task", the fallout user can manually complete the task.
About Data Dictionary
The import process creates a cartridge containing a set of Complex Data Types (CDT) that represent the schema of the productOrder or serviceOrder as defined in the specification. This saves time for cartridge developers who would otherwise have to manually construct the data model in Design Studio.
CDT content is always significant. The cartridge developer should be aware that a change to any content within the productOrder will trigger amendment processing, as all of the data is modeled as CDT.
About the Order Template
- Master Order Template
- Order Item Specification Order Template
About the Master Order Template
To the master order template, you should add the CDT representing your order resource - either ProductOrder or ServiceOrder to the root (outside ControlData). It is important to note that even if there are extensions to the main resource (ProductOrderOSM), you should not add these sub-types into the order template. Because the extensions are sub-classed from the main resource and implemented in OSM as CDTs, the exact typing is handled at runtime.
Figure 11-2 Order Template with ProductOrder Information
The payload served to OSM Gateway by the calling system includes a '@type' field that declares the concrete schema type that is populated. The '@type' field should specify the exact schema extension used.
{
"description": "TMF OSM Product Order",
"category": "salesOrder",
"externalId": "456855",
"@type": "ProductOrderOSM_Create",
.......About the Order Item Specification Order Template
- An order item property must be created named either "ProductOrderItem" or "ServiceOrderItem"
- An XQuery sample for populating this structure follows.
- The CDT representing the order item type from the schema (ProductOrderItem or ServiceOrderItem) must be added to the order template of the order item specification.
Note:
Design Studio restrictions preventing the addition of a CDT to the order template have been lifted for cartridges with a target server version of 7.5.0.(: Sample XQuery to populate the order item specification property - ProductOrderItem. This XQuery does not retain the hierarchy of order items, it only returns the incoming data for a single line item :)
declare namespace oms="http://www.metasolv.com/OMS/OrderModel/2002/06/25";
declare namespace tmfbase="%{TMF_CDT_NAMESPACE}";
(: Declare OSM name space :)
declare namespace model="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace tmf="http://oracle.communications.orchestration.com/tmf-api/productOrderingManagement/%{TMF622_VERSION}/productOrder/inputMessage";
declare variable $tmfbase := "%{TMF_CDT_NAMESPACE}";
(: Ensure that incoming order has mentioned name space:)
declare variable $line := if (fn:exists( fn:root(.)/tmf:productOrderItem)) then fn:root(.)/tmf:productOrderItem else .;
declare function local:copyButTrimChildProductOrderItem(
$parentName as xs:string?,
$element as element(),
$first as xs:boolean,
$trim as xs:boolean) as element()*
{
let $concreteType := fn:data($element/@xsi:type)
let $elementName := local-name($element)
return
if (fn:exists($concreteType) ) then (
let $qName :=
if ($first = fn:true()) then (fn:QName($tmfbase, "ProductOrderItem"))
else (fn:QName($tmfbase, $elementName))
return
if($elementName = "productOrderItem" and $trim = fn:true()) then ()
else (
element {$qName}
{
attribute { "type" } { fn:concat("{", $tmfbase, "}", $concreteType) },
attribute { "xsi:type" } { fn:concat(xs:string("tmfbase"),":", $concreteType) },
attribute { "tmfbase:type" } { fn:concat(xs:string("tmfbase:"), $concreteType) },
for $child in $element/node()
return
if ($child instance of element())
then local:copyButTrimChildProductOrderItem($concreteType, $child, fn:false(), fn:true())
else $child
}
)
)
else (
if($elementName = "productOrderItem" and $trim = fn:true()) then ()
else (
element {node-name($element)}
{
$element/@*,
(
for $child in $element/node()
return
if ($child instance of element())
then local:copyButTrimChildProductOrderItem((), $child, fn:false(), fn:true())
else $child
)
}
)
)
};
local:copyButTrimChildProductOrderItem((), $line, fn:true(), fn:false())Figure 11-3 Order Template with Product Order Item Information
As is the case on the master order template, the CDT structure that should be placed under ControlData/OrderItem should be the base type from the TMF specification and not any extended types. The concrete schema will get resolved at runtime by specifying the '@type' property on the productOrderItem (or serviceOrderItem) on the incoming order payload.
"productOrderItem": [
{
"@type": "ProductOrderItem<extension>",
"quantity": 1,The TMF Order Item (ProductOrderItem or ServiceOrderItem) is exposed to fulfillment functions as a property of the orderItemRef within a function. This allows automation tasks associated to update the ProductOrderItem or ServiceOrderItem directly.
Figure 11-4 ProductOrderItem within a Function
The data returned when a GET endpoint is invoked consists of all POI or SOI under ControlData/OrderItem as well as the PO or SO at the root.
About the Significance of CDT
During amendment processing, OSM analyzes the changed data at an element level. Only changes to data elements that have been marked as significant will trigger amendment processing. In OSM, CDTs are always considered significant which means that for TMF orders, a change to any data field within the main resource (ProductOrder or ServiceOrder) will trigger compensation.
Cartridge developers that want more control over this process can configure a rule on the order lifecycle policy (the same functionality as Freeform cartridges) where a more thorough evaluation can be done. This can result in rejecting orders with changes that are deemed insignificant to the fulfillment logic of the cartridge.
About TMF Orders and Permissions
- The auto-generated lifecycle policy should be referenced.
- The TMF Order checkbox must be selected.
- The hosted order specification must be selected.
This configuration controls the inclusion of mandatory cartridge configuration that can be produced internally during the design studio build.
Once an order is designated to be a TMF order, the cartridge developer is responsible for adding the required permissions.
Permissions for Internal Gateway Role
- The osm-internal-gateway-user auto-generated during the import process must be added to the permissions tab of an order.
- On the details tab, Create Order access must be given.
- A flexible header for ControlData/OrderFulfillmentState must be added.
- A query task with the default settings must also be defined. This view does not need to follow a specific naming convention, but does need access to everything in the order template.
Figure 11-5 Internal Gateway Role Configuration
About Order Recognition
Recognition Rule
With freeform cartridges, clients send an XML create order request directly to OSM. Cartridge developers must understand the payload structure and the XML namespace associated with the order as this information is typically used to identify matching order requests.
When OSM hosts a TMF specification, OSM Gateway creates the actual request to OSM. While the payload structure is known (defined inside the TMF specification), the XML namespace carried on the order is crafted by OSM Gateway. As cartridge developers are still responsible for coding order recognition, they must be made aware of the namespace that will be used. The incoming document namespace reflects the hosted specification name and version number. If you open the hosted specification editor in Design Studio, you can verify both of these values.
The prefix of the document namespace is a constant -
http://oracle.communications.orchestration.com/
The suffix can be formatted from the following information:
hostedSpecName/<hostedSpecVersion/resourceName/inputMessage
Cartridge developers should use OSM best practices to capture version information as a model variable. As the hosted specification is up-versioned through its lifecycle (resulting in a version change), the model variable must be updated but not the xquery code.
The order recognition xquery provided below can be used in conjunction with a cartridge model variable that defines 'TMF622_VERSION' to match the hosted specification version.
Recognition
(: Declare TMF name space :)
declare namespace tmf="http://oracle.communications.orchestration.com/tmf-api/productOrderingManagement/%{TMF622_VERSION}/productOrder/inputMessage";
(: Ensure that incoming order is found and only one:)
fn:count(//tmf:productOrder)=1Order Data Rule
This section provides information about model variable and sample xquery.
Model Variable
The auto-generated OSM cartridge contains an auto-generated model variable
called TMF_CDT_NAMESPACE populated with
CDTCartridgeName/CDTCartridgeVersion.
For example, if the cartridge was called "PO_Base" with version 1.1.1.1.1, then the variable value would have a value of "PO_Base/1.1.1.1.1"
This variable is necessary in many cartridge XQueries to reference the namespace of the OSM CDT entities correctly. In the XQuery sample mentioned below, we can see it is needed to set the namespace on the order data being created and returned to OSM.
XQuery
The following xquery sample will populate the TMF resource anchor root node (i.e /ProductOrder) in the order template from the TMF Order data submitted at runtime.
OrderDataRule
declare namespace oms="http://www.metasolv.com/OMS/OrderModel/2002/06/25";
declare namespace tmfbase="%{TMF_CDT_NAMESPACE}";
(: Declare OSM name space :)
declare namespace model="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace tmf="http://oracle.communications.orchestration.com/tmf-api/productOrderingManagement/%{TMF622_VERSION}/productOrder/inputMessage";
declare variable $tmfbase := "%{TMF_CDT_NAMESPACE}";
(: Ensure that incoming order has mentioned name space:)
declare variable $root := //tmf:productOrder;
declare function local:copyButTrimProductOrderItem(
$element as element(),
$first as xs:boolean) as element()*
{
let $type := fn:data($element/@xsi:type)
let $elementName := local-name($element)
return
if ($elementName != "productOrderItem") then (
if (fn:exists($type) ) then (
let $qName :=
if ($first = fn:true()) then (fn:QName($tmfbase, "ProductOrder"))
else (fn:QName($tmfbase, $elementName))
let $concreteType :=
if ($first = fn:true()) then (fn:substring-before($type, "_Create"))
else ($type)
return
element {$qName}
{
attribute { "type" } { fn:concat("{", $tmfbase, "}", $concreteType) },
attribute { "xsi:type" } { fn:concat(xs:string("tmfbase"),":", $concreteType) },
attribute { "tmfbase:type" } { fn:concat(xs:string("tmfbase:"), $concreteType) },
for $child in $element/node()
return
if ($child instance of element())
then local:copyButTrimProductOrderItem($child, fn:false())
else $child
}
)
else (
element {node-name($element)}
{
$element/@*,
(
for $child in $element/node()
return
if ($child instance of element())
then local:copyButTrimProductOrderItem($child, fn:false())
else $child
)
}
)
)
else ()
};
let $description := $root/tmf:description/text()
return
<_root>
{local:copyButTrimProductOrderItem($root, fn:true())}
</_root>
)
About Updating the TMF Order Item with Downstream Data
- <resource> (_root/ProductOrder)
- ControlData/OrderItem/<resource>OrderItem (ControlData/OrderItem/ProductOrderItem)
When OSM emits TMF events about the order resource, or when a GET endpoint is invoked, the data returned comes directly from the TMF data in these two locations. There are some considerations for cartridge developers to think about, with respect to where downstream data updates will be stored on the order item.
Is the data update modeled as an order item characteristic that is empty on the incoming create request, but gets populated based on downstream data and then propagated upstream (network address)?
OR is the data something fulfillment related, applying equally to all order items regardless of the product specification (shipment tracking details)?
These different types of data can be modeled in two ways.
Updates to Order Item Characteristics
Updates to a TMF Order Item (ProductOrderItem or ServiceOrderItem) characteristics trigger the automated <resource>AttributeValueChangeEvent with a pointer to the exact data change.
If a data update is destined for a line item characteristic, then there is a nuance about the OSM order data that must be considered.
OSM's parameter binding feature will dynamically map the data representing the line attributes on an incoming create order payload to the dynamicParams area of the control data.
For TMF orders, a CDT representing the entire order item is added to the control data. This means that the line item characteristics are held in two places in the OSM order data - ControlData/OrderItem/ProductOrderItem and the OSM mapped parameters inside dynamicParams as shown in Figure 11-6.
Note that one location is OSM order data and the other is TMF data.
Which location should cartridge developers update with their plugin script? The two characteristic areas should be kept in sync at all times, and to that end OSM uses the "Reverse Data Propagation" (RDP) feature that is responsible for this.
During PSR modeling, the specific data element that will be populated from downstream systems, should have the "Supports Reverse Propagation" checkbox selected. This should not be turned on for all data elements in a PSR entity, but only the ones where the value will originate downstream.
Figure 11-7 Reverse Propagation Configuration
Figure 11-8 Data Propagation When RDP is Enabled
This feature is available only when the TMF Order Item Characteristic is a primitive type. Characteristics that are objects or arrays are not supported with RDP.
Note:
If the incoming characteristic name is different than what is modeled in design studio, then you should be utilizing the "key" feature along with order item parameter bindings. In this way, the reverse propagation will take into account the key and will be able to find the correct source characteristic. Do NOT use the parameter binding xquery to do any such manipulation from one value to another as data will not be able to be propagated. As an example, if your upstream system will be sending a Characteristic name with underscores "Authorization_Code" but your PSR entity in Design Studio has a data element "AuthorizationCode", you should not use the parameter binding xquery to strip the underscore but rather you should use the "key" feature which is intended to rectify discrepancies between commercial and technical naming.
Transformed Order Items
For line items that are involved in OTM, updates to a TransformedOrderItem/dynamicParams can cause OTM to update an OrderItem/dynamicParams. When combined with the RDP for TMF orders, that will also include propagation to the original source TMF Order Item.
To update the TMF order item characteristic data, cartridge developers only need to focus on updating the dynamic parameter under the transformedOrderItem.
Updates to General Order Item Data
For updates that are more general in nature (ie. shipment tracking info), it does not make sense to model that as Characteristics of a product or service. This class of data would be added under the TMF order item.
General Order Item data such as these examples would be reflected in responses to a GET endpoint invocation, but do not trigger upstream events. In order for callers to be aware of the new data, an explicit GET invocation would be required.
About TMF Order State
Calculating and propagating TMF order and order item state are handled internally by OSM.
Changes to the Order state are communicated through StateChangeEvents.
For order processing sequence diagrams showing StateChangeEvents, see "About TMF Orders (Cloud Native Only)" in OSM Concepts guide.
Figure 11-9 TMF Order (ProductOrder or ServiceOrder) State Transitions
Table 11-4 summarizes the states for a TMF Order (ProductOrder or ServiceOrder).
Table 11-3 States of a TMF Order
| TMF State | Usage | OSM Order State |
|---|---|---|
| acknowledged | Not used | NA |
| rejected |
Not used Rejected requests are handled through a synchronous HTTP response with appropriate HTTP response code. |
NA |
| pending |
Initial State. After order is created, but before any task has started. Initial State for future dated orders. |
Created |
| held | Not used | NA |
| inProgress | Order is executing. | 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 executing a cancellation request. | Amending |
Table 11-4 summarizes the states for a TMF Order (ProductOrder or ServiceOrder).
Table 11-4 States of a TMF Order Extended 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 executing a cancellation request but is now suspended. | Amending |
| pendingCancellation.fallout | Order was executing 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 executing but is waiting on fallout exception resolution. | InProgress |
| inProgress.suspended | Order was executing but is currently suspended. | InProgress |
| inProgress.fallout.suspended | An order waiting on fallout exception resolution but is now suspended. | InProgress |
Implications of TMF Partial and TMF Failed State
In all cases, the TMF Failed state and TMF Partial state are final states. This means that no further work is done on the entity that has entered this state. For example, if a line item enters TMF Failed state, no further processing can happen for that line item in the orchestration plan; if the order enters TMF Failed state, no further activity can occur on the order.
About TMF Order Item State
Changes to order item state are communicated through AttributeValueChangeEvents.
Figure 11-10 TMF Order Item (ProductOrderItem or ServiceOrderItem) State Transitions
Table 11-5 summarizes the state transitions for a TMF OrderItem (ProductOrderItem or ServiceOrderItem).
Table 11-5 State Transitions for a TMF OrderItem (ProductOrderItem or ServiceOrderItem)
| From State/To State | Pending | InProgress | InProgress.fallout | pendingCancellation | pendingCancellation.fallout | amending | amending.fallout | failed | completed | cancelled |
|---|---|---|---|---|---|---|---|---|---|---|
| pending | NA | Associated Fulfillment Function Started. | NA | NA | NA | NA | NA | NA | Pending Order Item is not associated to any Fulfillment Function and contains no child order item. | Cancel Order Accepted For Pending Order Item. |
| InProgress | NA | NA | Associated Fulfillment Function fallout | Cancel Order accepted for InProgress order item. | NA | Amend Order accepted for InProgress order item. | NA | Cartridge signals Order item is not success. | Associated Fulfillment function completed without error. | NA |
| InProgress.fallout | NA | Order Item Fallout resolved and associated Fulfillment Function retry. | NA | Cancel Order accepted for fallout Order item with cancel activities | NA | Amend Order accepted for fallout Order item with amendment activities | NA | Cartridge signals Order item is not success. | NA | Cancel Order accepted for fallout Order item without cancel activities. |
| pendingCancellation | NA | NA | NA | NA | Associated Fulfillment Function fallout during cancel. | NA | NA | Cartridge signals Order item is not success. | NA | Cancel process completed without error. |
| pendingCancellation.Fallout | NA | NA | NA | Fallout resolved for cancelling order item and associated Fulfillment Function retry. | NA | NA | NA | Cartridge signals Order item is not success. | NA | NA |
| amending | NA | Amendment completed and there are remaining fulfillment function to be executed. | NA | NA | NA | NA | Associated Fulfillment Function fallout during amendment. | Cartridge signals Order item is not success. | NA | NA |
| amending.fallout | NA | NA | NA | NA | NA | Fallout resolved for amending order item and associated Fulfillment Function retry. | NA | Cartridge signals Order item is not success. | NA | NA |
| failed | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA |
| completed | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA |
| cancelled | NA | NA | NA | NA | NA | NA | NA | NA | NA | NA |
About Fulfillment State and Processing State
The ControlData/OrderItem/OrderItemFulfillmentState and ControlData/OrderItem/OrderItemProcessingState fields are now reserved for OSM use, for the calculation of TMF State. They will hold calculated TMF state values and will be communicated to upstream systems via the TMF StateChangeEvents.
Cartridges must not update these fields and should not use this field in fulfillment state mapping.
- Order Component Order Item Processing State - Processing State of an Order Item within an Order Component. The input value of the state here can be optionally driven by external fulfillment state.
- Order Item Processing State - Processing State of an Order Item aggregated from child order item's processing state as well as all processing state of itself across all order component.
OSM Processing State value is different than the TMF product Order item state. Table 11-6 describes the state mapping between OSM Order Item and TMF Product Order Item.
Table 11-6 OSM Order Item and TMF Product Order Item State Mapping
| Processing State | OSM Order State | Processing Direction | Product Order Item State |
|---|---|---|---|
| NotStarted | NA | NA | pending |
| InProgress | in_progress | FORWARD | InProgress |
| InProgressWithWarnings | in_progress | FORWARD | InProgress |
| InProgressWithFailures | in_progress | FORWARD | inProgress.fallout |
| InProgress | amending | FORWARD | amending |
| InProgressWithWarnings | amending | FORWARD | amending |
| InProgressWithFailures | amending | FORWARD | amending.falllout |
| Completed | in_progress, amending | FORWARD | completed |
| CompletedWithWarnings | in_progress, amending | FORWARD | completed |
| PartiallyFailed | in_progress, amending, cancelling | FORWARD, REVERSE | partial |
| Undoing | amending | REVERSE | amending |
| UndoingWithWarnings | amending | REVERSE | amending |
| UndoingWithFailures | amending | REVERSE | amending.fallout |
| Undoing | cancelling | REVERSE | pendingCancellation |
| UndoingWithWarnings | cancelling | REVERSE | pendingCancellation |
| UndoingWithFailures | cancelling | REVERSE | pendingCancellation.fallout |
| UndoCompleted | cancelling | REVERSE | cancelled |
| UndoCompletedWithWarnings | cancelling | REVERSE | cancelled |
| UndoFailed | cancelling | REVERSE | failed |