This article introduces the concept and behaviour of Inflight Change & Cancels in ServiceNow Order Management. (SOMT i.e. Sales & Order Management for Telecom)
DYK (Did You Know) is a series of articles that introduces simple and basic concepts of the working of ServiceNow TMT Applications.
Application: Order Management (SOMT/OMT)
Release: All applicable
What orders are eligible for Inflights?
An Order (Product or Service) that is currently in an 'In Progress' state and has not reached the Point of Return (PONR) is eligible for Inflights.
Note: The PONR flag is set via an OOTB Flow action 'Set PONR on Line Items under Top Line Item' and is an implementation decision.
Scope of Inflights
SOMT supports the following Inflight use cases -
- Inflight Change
- Change of Characteristics, Order Line Item Contact, Quantity, Related Item
- Add, Change or Cancel of Order Line Items.
- Inflight Cancel
- Cancel an entire Order
Interfaces
Inflights are supported via both the Open APIs as well the Agent Workspace.
- API Operations (TMF622/641)
- Patch Operation
- Update OLI(s)
- Add or Cancel OLI(s)
- Cancel Order Operation
- Patch Operation
- Agent Workspace
- Revise OLI(s)
- Add or Cancel OLI(s)
- Cancel Order
How to Add or Cancel OLIs via payload?
A question that often gets asked, is how to Add and/or Cancel an Order Line Item via Open APIs?
This is applicable to both the Ordering Open APIs - TMF622 & TMF641.
Add new OLI
When adding a new Order Line Item, use the Patch Operation.
Set the action = add, for the new OLI.
The actions for all other OLIs remain unchanged from the previous POST operation.
Cancel OLI
When canceling an Order Line Item that was previously submitted, use the Patch Operation.
For the OLI(s) to be cancelled, set an additional field "revisionOperation = cancel" in the payload.
All other OLIs remain unchanged including their action.
Here's an example of an Order to Cancel an OLI, with a snippet of the payload.
Notice the second line of the json payload.
{
"id": "903",
"revisionOperation": "cancel",
"ponr": "false",
"quantity": 1,
"priority": 4,
"action": "add",
"product": {
"@type": "Product",
"productCharacteristic": [
{
"name": "Security Type",
"valueType": "choice",
"value": "Base",
"previousValue": ""
}
],
"productSpecification": {
"id": "a6514bd3534560102f18ddeeff7b1247",
"name": "SD-WAN Security",
"version": "",
"internalVersion": "1",
"internalId": "a6514bd3534560102f18ddeeff7b1247",
"@type": "ProductSpecificationRef"
}
So what happens when an Inflight Order is submitted?
First and foremost, the Patch/Cancel order request is validated against the current Order State and PONR flag status.
Post validations,
- All running Orchestration Subflows are cancelled.
- SOMT redecomposes the Order to identify any delta based on the Inflight change.
- The Orchestration Subflows are relaunched.
Also, on acceptance of the Inflight order certain fields are updated to provide the user contextual information and also for SOMT to use it in logic where necessary.
- The 'Version' field is set to 1 when the first order is submitted and any subsequent Inflight orders increment the version on the Order, Order Line Item and it's affected & related Domain Order.
- The 'Revision Operation' is a key field that indicates the type of revision operation. The default value for this is 'None' and set for the v1 of the Order.
- for an Inflight of type Change (i.e. non-Cancel type) this field is set to a value of 'Update' against the Order Line Item and Domain Orders.
- It is set to 'Cancel' in the following scenarios -
- At the Order level when the entire Order is getting cancelled, alternatively set only at the OLI(s) getting cancelled.
State Machine Transitions
Along with setting of specific fields, the states for the Order and OLIs also are updated as the Inflight Order progresses from submission to processing. These are described in the below diagram.
What is the behaviour of Order Tasks during an Inflight?
Order Tasks in SOMT represent both the manual tasks assigned to users/groups or they are auto tasks mapped to REST actions for provisioning etc.
The behaviour of Order Tasks - especially the ones already completed and/or in progress - at the time of receipt of Inflight order can be controlled and configured via the Order Tasks configuration in the Subflows.
Note: This is applicable for both the Order Tasks and Planned Order Tasks.
Primarily there are four Order Task Inflight Configuration options as shown below.
Using Inflight Change Type you can choose the change type for which Inflight behaviour for the Order Task is to be applied. There are multiple options available OOTB - Characteristic, Contact, Price, Quantity, Related Items.
Additional types can be added but which requires additional development work.
The type 'Characteristics' is most prominently used.
The Inflight Change Option gives three options - 'Any Characteristics', 'Characteristics from Request Definition' or 'None' (default).
- Any Characteristics: Re-execute the task irrespective of which characteristic is changing.
- Characteristic from Request Definition: Re-execute the task only if the Characteristic is changing that is mapped against the RD mapped to this specific task.
When the Inflight Change Order goes through re-decomposition and the Subflows are re-launched, the above configuration will decide if the Order Task should be re-executed or skipped.
The below table provides a matrix view of the Order Task behaviour based on two factors - the previous state of the Order Task and the Inflight configuration for that Order Task in the Subflow.
And then there are additional configuration options Inflight Task Fields and Cancel Task Fields.
This configuration provides an option to set task fields values for the to be re-executed Order tasks when the subflows are re-launched.
As an example, the OOTB demo data sets the Short Description for such tasks to "REDO <Task name>" or "UNDO <Task name>" which helps in distinguishing tasks from Happy path v/s Inflight.
Inflight setup recommendation/example
Let's take a simple orchestration subflow with some Order Tasks in different current states for version 1 of the Order before receiving an Inflight.
Now, as we said in the beginning, an Order Task can represent a Manual Task or a collection of one or more automated tasks.
Let's consider Ship CPE Order Task represents a collection of Auto Tasks which requires 3rd party integrations via API calls.
The Auto Tasks may be different or in a different sequence based on a happy path versus Inflight Change/Cancel.
This can be controlled using the 'Revision Operation' field and built in a subflow as below.
As you will notice, depending upon the Revsion Operation the Ship CPE Order Task will invoke different Auto Tasks to mitigate/compensate for the change/cancellation. The above example shows the happy path run time scenario when Revision Operation = None.
On receiving an Inflight Change (Amend) Order, the existing running Subflows are cancelled, the order is re-decomposed and the subflow is re-launched.
The re-launched subflow refers to the Inflight config set up defined at the task level and the subflow from our example looks like below.
This example, assumes the Inflight change of Characteristics was not from the Request Definition mapped to the Billing Task. Hence, the previously completed 'Setup Billing Profile' task remains in a completed state.
The 'Design Circuit' and 'Ship CPE' tasks that were previously in progress, remain in 'In Progress' while taking the new Task fields values.
Finally the 'Install & Test' task that was never executed moves to a 'Scheduled' state to finally move to 'In Progress' when the preceding tasks are completed.
And the mapped auto task actions for the 'Amend Ship CPE' will now take the path for the switch case where Revision Operation = Update as below.
On completing all the Order Tasks, the order will complete as normal.
Inflights are a complex topic. To the readers of this article, I invite you to provide us your feedback/questions which will help us improve the product.
Based on feedback, I will update the articles for any gaps or additional material that may help it make complete.
