Modeling Changes to Orders

10 Modeling Changes to Orders

This chapter describes how to model change order management in an Oracle Communications Order and Service Management (OSM) solution.

About Amendment Processing and Compensation

To revise or cancel in-flight orders, OSM performs amendment processing. Amendment processing analyzes the requested changes, determines how to make the changes, and processes them. Amendment processing functions as follows:

A base order is submitted and is currently processing; it is not in the Not Started, Completed, or Aborted state. The upstream system submits a revision or a cancel order. The new version of the order includes all of the data relevant to the order, not just changed data. The upstream system does not need to identify the changes to OSM or explicitly provide the discrepancies; OSM determines the discrepancies during amendment processing by comparing the new version with the version of the order currently being processed.

To submit the revision order, the upstream system can use either the CreateOrder web service operation or the CreateOrderBySpecification web service operation.

The new version of the order can:
- Change existing data
- Remove existing data
- Add new data
Note:

You can create revision orders by using the Task web client. This is typically used only for testing or for low-volume order processing.
OSM receives the revision order. OSM checks to see if the base order is amendable. You enable amendment processing on the order specification. If the base order is not amendable, the order is not a revision order.

Note:

When you model orders, make sure that orders that are expected to be amended are configured to be amendable. If not, an order that is sent as a revision order is instead processed as a new order. This can cause errors during fulfillment because there are two orders fulfilling the same services for the same customer.
OSM checks in-flight orders for a matching value to an order key. For example, you can specify to use the sales order number as the order key. In that case, when OSM processes an order, it looks for an in-flight order that has the same sales order number. If OSM finds an in-flight order with a matching sales order number, OSM treats the new incoming customer order as a revision on the existing order. See "About Order Keys" for more information.

OSM now has two orders to work with: the revision order and the base order.

Note:

Many types of orders do not require an orchestration plan; for example, some service orders are created specifically for a simple service provisioning task and therefore require no dependencies.
OSM performs further checks on the base order to determine if the order is allowed to be amended. OSM does the following:
- OSM checks to see if the base order is in a state that can be amended. Orders in the Not Started, Completed, or Aborted state cannot be amended. You can customize the allowed transitions to the amending order state by configuring the order life-cycle policy. See "Modeling Order Life-Cycle Policy States and Transitions" for more information.
- OSM ensures that the base order has not passed the point of no return (PONR). The PONR is the point in the processing of an order item after which order amendments are either impossible or incur some penalty. In this case, a revision order might not be possible. See "Fulfillment Pattern Point of No Return" for information.
- OSM checks to see if the incoming customer order has a version identifier. If OSM has a version identifier, OSM compares the value of the version to the version of the in-flight order. If the version of the in-flight order is greater than the version of the incoming customer order, the incoming revision is ignored.
If a revision cannot be processed, or if the order life-cycle has not allowed the revision, the revision order is set to the Failed state, and the base order continues to be processed.
OSM determines whether amendment processing is needed by analyzing order data at the following levels:
- OSM compares the revision order data and the base order data (or the revision order data and the last submitted revision order data) to see if a compensation is needed. (Compensation defines the actions that need to be taken to perform amendment processing; for example, undo and redo.) See "About Order-Level and Task-Level Compensation Analysis" for more information.
- During compensation, OSM compares task data for each task in the order process to further validate the compensation requirements. See "About Order-Level and Task-Level Compensation Analysis" for more information.
- OSM uses the significance of the data to determine if compensation is needed at both stages. Data significance enables you to optimize amendment processing in a way that compensation is considered only for changes to data that is marked as significant. Data that is not marked significant is updated but does not get included in the compensation plan if its value is changed. See "About Data Significance" for more information.
  Note:
  
  If an amendment is received while a task is in a fallout execution mode, OSM does the following:
  - If the task is not configured to be compensated if it is in progress, the execution mode of the task does not change as a result of the amendment order.
  - If the task is configured to be compensated if it is in progress, and the amendment contains changes to significant data:
    - If the task is still needed after the changes to the order from the amendment are considered, it transitions automatically to (normal) Redo mode.
    - If the task is no longer needed after the changes to the order from the amendment are considered, it transitions automatically to (normal) Undo mode.
    In both of these cases, ensure that your automation code (for the Redo or Undo execution mode) contains a check to see if the task has been in a fallout execution mode, and also whatever code is needed to resolve any actions that have been taken in the fallout execution mode. For example, if your automation for Do in Fallout mode opens a trouble ticket, your Redo automation should check to see whether it needs to close a trouble ticket.
  - If the amendment order contains no changes to significant data, the execution mode of the task does not change as a result of the amendment order.
After determining that amendment processing is needed, OSM transitions the order to the Amending state.

Note:

OSM queues orders that need amending. Therefore it is possible for multiple revisions of the same order to exist in the queue. If amending the order is allowed, OSM chooses the latest version of the amendments in the queue by comparing the optional version identifiers (if configured) or, if there is no configured version identifier, by comparing the dates and times that the amendments were received.

In the Process Amendment state, OSM determines the compensation required. For example, OSM might redo a task with different values for one or more data elements on the task data that were used for input into the task.

For process-based orders, the tasks are analyzed to find the impact of the changes. That impact determines the compensation plan. For example, OSM might need to redo a task with different data values or undo a task if it is no longer required. The data comparison is based on the data in the creation task of the base order and the revision order. See OSM Concepts for information.

For orchestration orders, the order components of the orchestration plan are analyzed to determine which order components need to be redone, undone, or done for the first time (amend do). The tasks of the sub-processes run for each of those order components to be compensated are also analyzed.
OSM handles the base order and the revision order as follows:
- For the base order, OSM creates a new orchestration plan that includes the order components and their dependencies. Any order components with data that has changed as a result of the revision are redone. Any order components that have been processed but are no longer required in the revision are undone in reverse dependency sequence. Any order components that are inserted as new requirements are fulfilled. The order state is set to Amending.
- For the revision order, OSM transitions it to the Completed state because its only purpose was to revise the base order.
OSM processes the changes according to the compensation plan it calculated and re-calculates the compensation plan needed after every change. OSM performs the necessary undo, redo, and amend do operations on order components (for orchestration orders) and on tasks (for both orchestration orders and process-based orders).

Figure 10-1 shows a simplified amendment processing flow.

Figure 10-1 Amendment Processing

Description of "Figure 10-1 Amendment Processing"

Note:

Messages from external systems can be returned to a task for which the receiver is temporarily unable to receive a response. This can happen, for example, if an order is being amended or is suspended. When this happens, OSM saves the returned message to the database, to wait until the order is ready for the task. This message will be removed when the message is resent to the receiver or when it becomes irrelevant (for example, because the order has been purged). This functionality is on by default, but you can turn it off, for example if your solution already handles messages of this type in a different way. To turn this feature off, use the oracle.communications.ordermanagement.AutomationResponseMessageParkingEnabled parameter in the oms-config.xml file. See OSM System Administrator's Guide for more information about this parameter and about the oms-config.xml file.

A simple example of a revision order is as follows:

A customer orders a DSL service at 3 MBps. An order is created and sent to OSM.

Figure 10-2 shows the start of the process. In this example, the process begins with the Verify_ADSL_Service task and then transitions to the Assign_Port task.

Figure 10-2 Amendment Order Example

Description of "Figure 10-2 Amendment Order Example"
OSM verifies that the 3 MBps service is available and transitions to the next task, Assign_Port.
While the order is waiting for port assignment, the customer calls back and asks a customer service representative (CSR) to change the order to 5 MBps. The CSR creates a revision order in the CRM system with the revised bandwidth value of 5 MBps and submits the order to OSM.
OSM receives the incoming customer order, and detects that it is a revision to an in-flight order.
OSM accepts the revision order, calculates the compensation plan, and begins to run it. OSM knows that compensation is necessary because the data (bandwidth) that was on the order as input data when this task ran previously has now changed. The revision order requests that the Verify_ADSL_Service_Availability task must be redone to ensure that the 5 MBps service is available.
The value set by the Verify_ADSL_Service_Availability task is changed.

Figure 10-3 shows the order displayed in the Task web client. In this figure, the Verify_ADSL_Service_Availability task has an execution mode of Redo. Because the port has not been assigned yet, the Assign Port task has an execution mode of Do, but it cannot be worked on until the order completes compensation for the revision.

The task execution mode can be Undo, Redo, Do, Amend Do, Undo in Fallout, Redo in Fallout, Do in Fallout, and Amend Do in Fallout. (See "About Task Execution Modes" for more information.)

Figure 10-3 Amendment Displayed in the Task Web Client

Description of "Figure 10-3 Amendment Displayed in the Task Web Client"
The revision order transitions directly to the Completed state. This is because the revision order is used only for updating the base order. For revision tracking, OSM maintains a record of the revision order as part of the order history.
After verifying that the revised bandwidth is available, the base order continues processing.

You can monitor revisions in the web clients. Figure 10-4 shows a revision order (Order 7) and Figure 10-5 shows the base order that it revised (Order 6).

Figure 10-4 Revision Order in the Order Management Web Client

Description of "Figure 10-4 Revision Order in the Order Management Web Client"

Figure 10-5 Amended Order in the Order Management Web Client

Description of "Figure 10-5 Amended Order in the Order Management Web Client"

About Revising or Canceling Orders by Using the Task Web Client

In most cases, revision orders are submitted from an order-source system. You can also revise and cancel orders by using the OSM Task web client; for example, by using the Amend Order menu command. This is useful for testing revisions and cancellations within OSM, however, this method is not appropriate for production systems.

You should use the Task web client to submit amendments only when the order was submitted from the Task web client originally or when the upstream system cannot submit an amendment. If the upstream system submits an amendment after you manually submit an amendment, data synchronization errors can occur.

When you use the Task web client to amend an order:

OSM creates another order, with a new order ID number, for the revision. The new order includes all of the creation task data from the in-flight order.
The Task web client displays the revision order.
You can then change the data required for the revision and submit the revision order.

Caution:

If you use revision versioning, increment the revision version.

About Order Keys

When receiving an order flagged as amendable, OSM checks in-flight orders for a matching value in an order key. (You configure the order key when you model the order specification.) For example, you can specify to use the sales order number as the order key. In that case, when OSM processes an order, it looks for an existing order that has the same sales order number and amends that order.

Tip:

Because OSM must check the order key for all in-flight amendable orders, you should make orders amendable only if they might need to be amended. That way, OSM does not need to check for an order key for orders that would not be amended.

You define the order key in the order specification as one or more XPath expressions that reference one or more data elements in the incoming customer order. If you use multiple data elements, the values are concatenated in the order key.

OSM generates an order key when the order is created. To assign an order key:

The order key data elements must be part of the creation task data.
The order key must be identical between the base order and the revision orders and must not change.
The order must be flagged as amendable.

Order key values should not be modified after an order is submitted. For more information about creating valid order keys, see, "Modeling Valid Data Keys."

About Submitting Multiple Revisions of an Order

In some cases, multiple revisions to a single order are submitted. Each revision is expected to be a new revision of the in-flight order, not a cumulative comparison of previous revisions. The latest amendment is assumed to be the most complete revision containing all of the changes from earlier revisions. Intermediate revisions are not processed by OSM.

You can use versioning in the revision orders to recognize the order of the revisions as OSM receives them. For example:

If revisions are received out of sequence, OSM ensures that the latest revision is used. If a revision is received while a current revision on the same order is being compensated, and if processing of revising in-flight revision orders is enabled (see "About Revising In-flight Revision Orders" for more details), OSM initiates the termination of the current revision and changes the compensation state of the current revision to Terminating and queues the latest revision. After the current revision reaches a safe point, OSM terminates the current revision and starts processing the latest revision. If processing of revising in-flight revision orders is not enabled, OSM completes the compensation for the current revision before processing the latest version. If a version is received that is earlier than the current revision being processed, the earlier version is ignored.
If several revisions are received, OSM discards interim revisions and applies the latest revision because it represents the latest customer instructions for the order and is a complete copy of the base order.

To configure revision versioning, you specify a data element on the incoming customer order that OSM checks when processing revisions for the order. You specify the data element as an XPath expression in the order specification Amendable tab. For example, if the data element is <version>, the XPath expression is:

_root/version

About Compensation States

The following diagram shows compensation state transitions and the life-cycle of a revision order.

Figure 10-6 Compensation State Transitions

Description of "Figure 10-6 Compensation State Transitions"

Accepted: This state indicates that the revision order is accepted by OSM. OSM evaluates order life cycle policy when the revision order is received before accepting it. This state is a transitional state until the revision processing on the base order starts.
In progress: This state indicates that the revision processing has started on the order.
Completed: This state indicates that the revision processing is complete.
Queued: This state indicates that the revision order is queued.
- OSM queues the revision on a base order that is in the In-progress state if the Process Amendment transaction in the order state policy is not enabled. If the Process Amendment transaction is enabled, OSM re-evaluates the condition on order data changes and dequeues the revision. See "Disabling Processing of Revisions on In-flight Revision Orders" for more details.
- OSM queues the revision order when the base order is in the Amending state. Revision order remains queued until either the current revision processing is terminated (default configuration) or revision processing is completed.
Skipped: This state indicates that the revision order is skipped. This happens on a queued revision, when it is replaced by a new revision.
Terminating: This state indicates a transition period before OSM starts processing the latest revision on the order. During this period, OSM provides support to clean up all Started compensation tasks by ensuring they reach a known state.
Terminated: This state indicates that the compensation is terminated safely.

About Revising In-flight Revision Orders

OSM can process a revision order while it is still processing a revision on the same order that it received earlier, without having to wait for the ongoing revision order to complete. When a revision on an in-flight revision order is received, OSM initiates the termination of the current revision and changes the compensation state of the current revision to Terminating and queues the latest revision. After the current revision reaches a safe point, OSM terminates the current revision and then starts processing the latest revision.The compensation processing of the current revision transitions to a new revision safely, at the earliest, instead of waiting for the completion of the current revision processing. With this functionality, OSM can process order changes quickly, while reducing the operational expenses by optimizing the work needed to be done for subsequent order changes, and carries forward pending tasks that were not executed in the previous revisions to the latest revision.

Note:

By default, processing of revisions on in-flight revision orders is enabled for cartridges with target version 7.4.0.0.0. For information on enabling and disabling processing of revisions on in-flight revision orders, see "Disabling Processing of Revisions on In-flight Revision Orders".

OSM processes a revision on an ongoing revision order as follows:

While amendment processing is still in progress for the revision order, OSM receives another revision on the order.

OSM initiates the termination of the current revision and changes the compensation state of the current revision to Terminating and the latest revision is queued. Once the current revision reaches a safe point, the current revision is terminated. See "About Terminating Compensation" for details about what happens in the Terminating state and when OSM terminates in-flight revision processing.
OSM merges the compensation plan of the new revision order with that of the previous revision that was terminated.

OSM does the following when it merges the compensation plans:
- OSM carries forward all the Not Started Redo compensation tasks from the terminated revision.
  
  Note:
  
  OSM compensates these tasks only if there are significant data changes compared to their prior execution.
- If there are pivot- sub-processes that have not started prior to the arrival of the new revision, OSM carries them forward into the latest order revision processing and executes them in a proper sequence.

About Insignificant Revision

When OSM receives a revision that has only insignificant data changes, the changes are applied immediately, while the processing of the ongoing revision is still in progress. Thus, a revision with insignificant data is not delayed. Also, it does not interrupt or impact the current revision processing.

About Terminating Compensation

When OSM receives a revision order while it is still processing a revision on the same order that it received earlier, OSM terminates the compensation for the ongoing revision order before processing the new revision. The Terminating state provides a transitional stage to ensure that the current compensation plan is executed further until it reaches a safe point before starting and processing the latest revision that is queued. To avoid unnecessary processing, OSM does not create successors on the redo tasks upon its completion during the Terminating state.

The revision processing of an ongoing revision remains in the Terminating state until the following conditions are met:

The compensation remains in the Terminating state until all Undo tasks are executed and completed.
If there is a new component/pivot- sub-process in the current revision and it has started prior to the arrival of the new revision, the compensation of the current revision remains in the Terminating state until the execution of the new component/pivot sub-process is completed through the execution of tasks in the Amend-Do execution mode.
If there is a change in flow during compensation (for example, if a Redo task is completed at a status that is different from the status that it was executed earlier). The compensation of the current revision remains in the Terminating state until the dead path is rolled back, which is done by undoing all tasks in the dead path, and the new path is executed and completed by executing the tasks in the Amend-Do mode.

OSM terminates the compensation when it considers the current state of the compensation has reached a safe point (when the aforementioned conditions are met) and starts processing the queued revision. OSM merges the terminated compensation plan with the new compensation plan to ensure that the compensation tasks which were skipped are now executed as part of the processing of the new revision order.

Disabling Processing of Revisions on In-flight Revision Orders

By default, processing of revisions on in-flight revision orders is enabled for cartridges with target version 7.4.0.0.0.

To disable this functionality, you configure the Process Amendment transaction for the Amending order state. You configure the Process Amendment transaction for the Amending order state by removing the permission to the Amending - Process Amendment transaction for a selected role. For details on removing and granting permissions to transactions, see the topic about Configuring Order Lifecycle Policies in Design Studio Modeling OSM Processes Online Help.

Example: Revising an In-flight Revision Order

A simple example of how OSM processes revision on an in-flight revision order is as follows:

A customer orders a DSL service with 3 MBps bandwidth. An order is created and sent to OSM.

Figure 10-7 shows the start of the process. In this example, the process begins with the Verify_ADSL_Service task and then transitions to the Assign_Port task.

Figure 10-7 Amendment Order Example

Description of "Figure 10-7 Amendment Order Example"
OSM verifies that the service with 3 MBps is available and transitions to the next task, Assign_Port.
On availability of a port, it transition to the Activate DSLAM task.
While the Activate DSLAM task is being completed, the customer calls back and requests to change the bandwidth to 5 MBps.

The CSR creates a revision order in the CRM system with the revised bandwidth value of 5 MBps and submits the order to OSM.
OSM receives the incoming customer order and detects that it is a revision to an in-flight order.
OSM accepts the revision order, calculates the compensation plan, and begins to run it. OSM recognizes that compensation is necessary because the data (bandwidth) that was on the order as input data when this task ran previously has now changed.
The revision order requests that the Verify_ADSL_Service_Availability task be redone to ensure that the 5 MBps service is available.

The value set by the Verify_ADSL_Service_Availability task is changed. The Verify_ADSL_Service_Availability task has an execution mode of Redo.
While the order is running the Verifying_ADSL_Service_Availability task, the customer calls back and requests to change the bandwidth to 10 MBps.

The CSR creates another revision order in the CRM system with the revised bandwidth value of 10 MBps and submits the order to OSM.
OSM receives the incoming customer order, and detects that it is a revision to an in-flight revision order.
OSM accepts the revision and initiates the termination of the current revision and queues the latest revision. You can monitor the amendment in the Amendments tab in the Order Management Web Client.
On completion of the Verify_ASDL_service_availability compensation task, the current revision gets Terminated and the Assign_Port compensation task is not started. This task is carried forward to the latest revision.
OSM carries forward the Not Started Assign_Port compensation task from the terminated revision.

Note:

OSM compensates these tasks only if there are significant data changes compared to their prior execution.

About Controlling When Amendment Processing Starts

You can delay amendment processing for an order. For example, the order might be in the middle of running an automated task that is executing system interactions with fulfillment systems, so you want to postpone the processing of the revision until after the tasks complete. After the system interaction is complete, OSM can begin processing the revision.

During amendment processing, the order is in the Amending state, which prevents normal processing such as task updates. This allows compensation to deal with one set of data changes without also needing to carry out normal processing activities at the same time. To manage the transition to the Amending state, OSM does the following:

Checks permissions to allow or postpone the processing of the revision.
Checks if a grace period is set to allow all order activity to settle. If so, it waits for the grace period to end.
Transitions the order to the Amending state.

To control when amendment processing starts, you use the order life-cycle policy to control OSM transactions. A transaction is an action taken by the OSM system. For example, for the In Progress state, you can prevent the Process Amendment transaction from occurring until a condition is true.

See "Modeling Order Life-Cycle Policy States and Transitions" for more information about transactions.

To manage amendment processing, OSM uses two order state transactions, in the following order:

Submit amendment. This transaction occurs when the revision order is submitted. You can specify conditions that determine if the order can be amended or not. Because the evaluation of the condition is triggered when the revision order is submitted, the condition does not need to be based on data, but it can include data as part of the condition.
Process amendment. If the revision order is accepted, OSM evaluates this transaction to determine if the amendment can be processed now, or if it needs to wait for a specified amount of time, or if it needs to wait until all accepted tasks are completed. This condition is evaluated based on data in the order. If the condition returns false, the amendment is queued. The condition is re-evaluated whenever the data changes. When the condition evaluates to true, the transition to the Amending state can occur.

A grace period specifies a period of time to wait for all accepted tasks to complete before an order can transition to a different state. For example, if an automated task has sent a request to an external system, but the external system has not responded, OSM does not know if the task has been completed and therefore does not know if the task needs to be compensated. A grace period set on the Process Amendment order state transaction can allow the order the opportunity to reach a known state for all current tasks before transitioning to the Amending state.

Grace periods are defaulted to be indefinite, so OSM waits until all currently accepted tasks are completed before transitioning to the target state. You can limit the grace period:

You can set the grace period to zero, which specifies that OSM not wait for any accepted tasks to complete before transitioning to the target state
You can provide a time limit; for example, one hour (to give all accepted tasks a limited time to complete before transitioning to the target state).

If an automation response is received for a task after the order has transitioned to the Amending state, an automation exception is thrown, because the automation plug-in cannot process the response when the order is in the Amending state. The automation exception is sent to the JMS response queue and is retried. When the retry limit is reached, the message is forwarded to an error destination, if one is configured. To manage exceptions that occur during amendment processing, you can review the errors to determine if the messages can be resubmitted or handled by fallout.

If there are multiple queued revisions waiting for the grace period to end, OSM selects the latest version among the queued amendments to process. The other versions are assumed to be out of date and are ignored. See "About Submitting Multiple Revisions of an Order" and "Modeling Order Life-Cycle Policy States and Transitions" for more information.

About Compensation

The following sections describe how compensation occurs.

About Order-Level and Task-Level Compensation Analysis

When the revision order is received, OSM analyzes the differences between the revision order data and the base order data (or between this revision order data and the last submitted revision order data) to see if a compensation is indicated. Changes and updates to order data can occur in the context of task data views or order data views.

OSM then begins analyzing impacted tasks. OSM provides the following data perspectives for each individual task which are snapshots of data that OSM uses to calculate whether a task needs to be compensated. These data perspectives are:

Historical order perspective (HOP): Specifies the data used when the task last ran in Do mode and changed to the Completed state (or Redo mode if the task last ran as part of compensation for a previously submitted revision order).
Contemporary order perspective (COP): Specifies the unchanged task data from the last time the task completed in Do or Redo mode (for example, from the tasks run for the base order or for a previous revision order). COP also shows any new or changed data from the current revision order and from the tasks triggered from that revision order that compensated prior in the process flow to the compensation task currently being analyzed.
Real-time order perspective (ROP): Specifies the last change to a parameter value by any task or at the order level (for example through order-level updates). This perspective may be different from the COP because the COP only provides a view of task data for previously run compensation tasks and revision order data and may not represent the last change to a parameter value. For example, the COP may include unchanged data from when the parameter that was originally processed by the Task, but that same data parameter could have been updated in a later task and so the current data would have a different value than the one displayed in the COP.

Figure 10-8 describes a process-based order, where a subscriber requests ADSL service with 3MBps speed. The order is submitted to OSM and service fulfillment begins. The subscriber calls back while the base order is in-flight and has just completed the Activate DSLAM task and requests the order be changed from 3MBps to 5MBps speed. In this scenario, the existing port does not support 5MBps. The compensation process proceeds as follows:

Figure 10-8 Changing a Service Request

Description of "Figure 10-8 Changing a Service Request"

When OSM receives the revision order, OSM compares the creation task data of the revision order with the creation task data of the base order to determine if any data changes have occurred to significant data.
Because the bandwidth changed from 3 MBps to 5 MBps and the bandwidth parameter is designated as significant, OSM begins task-level analysis for the first task in the process. OSM compares the Verify ADSL Service Availability HOP and COP and determines that the task must be redone because of the bandwidth change and because the compensation strategy for that task is redo.

OSM updates the results of the task and any data changes because of redoing the task to the ROP. The Verify ADSL Service Availability ROP becomes the COP for the Ship Modem task and the Assign Port task.
The compensation mode for Ship Modem is Do Nothing, so no compensation analysis occurs for that task. The compensation mode for Assign Port is Redo, so compensation analysis begins for that task. OSM compares the HOP and COP for the Assign Port task and determines that the task must be redone because of the bandwidth change. OSM adds the result of redoing the task to the ROP which includes the bandwidth change and a new port ID because the original port ID could not handle the increased bandwidth requirement. The ROP becomes the COP for the Activate DSLAM task.
The compensation mode for Activate DSLAM is Undo then Do, so compensation analysis begins for that task. OSM compares the HOP and the COP for the Activate DSLAM task and determines that the task must be undone then redone because of the new port ID and the bandwidth changes. OSM adds the results to the ROP. Processing continues normally after this task.

Note:

In this scenario, Activate DSLAM is the last task; however, if there had been additional tasks that had completed after Activate DSLAM, OSM would have had to undo them all prior to undoing Activate DSLAM regardless of the compensation strategy associated with those subsequent tasks. This scenario only applies to tasks running in Undo then Do mode.

You can use update order transactions to make changes to order data using automation plug-ins from the task context (this includes automated task, task event, and task jeopardy notification automations) and also from the order context (this includes order-level notification, event, and jeopardy automations). OSM captures any data update made from a task context in the HOP and COP and are therefore guaranteed to be reflected in any compensation analysis for that task initiated by new revision orders. Order updates can also be applied to the order-level data by referencing the view for that order data defined in the query task that you can associate to an order in the Order Specification editor Permissions tab, Query Task sub tab (see "Modeling Query Tasks for Order Automation Plug-ins" for more information about query tasks for order-level data). Updates at the order data level should be done with care because these updates are not included as part of compensation analysis and do not generate a HOP or COP. OSM attempts to apply any order-level change to the closest task that has been created or completed, but these updates are not guaranteed deterministically like the task-level updates are. For more information about how update orders can be used in automation plug-ins, see OSM Developer's Guide.

OSM does the following when discrepancies occur between the contemporary order perspective and the historical order perspective:

Adds revision order nodes if they do not match nodes of the last submitted order data or the nodes in the historical task perspective.
Changes revision order node values if the nodes do match the values found in the last submitted order data or the nodes in the historical task perspective.
Deletes nodes if the nodes are in the last submitted order data or in the historical task perspective but not in the revision order.

In Oracle Communications Design Studio, you can model compensation strategies for manual and automated tasks statically from a predefined list or dynamically from revision order data. If you model the compensation task dynamically, you can create an XQuery that has access to order data provided in the contemporary and historical perspectives as well as a comparison between the two. You can use the results of this comparison to dynamically select an appropriate task-level compensation strategy. For more information about compensation strategies, see "Modeling Compensation for Tasks".

About Order Data Position and Order Data Keys

OSM compares order data in the following ways:

By comparing the position of the XML nodes of the base order (or last submitted revision order), with the position of the XML nodes in the current revision order. This is not the recommended method, since the result of the comparison can be unexpected and cause compensation to behave in a way you do not want.
By comparing order data keys in the order specification order template tab for specific data elements. This is the recommended method. When OSM receives a revision order, it compares the order data keys from the revision order with the order data keys in the base order (or last submitted revision order). When OSM finds a matching order data key, it compares the values in each element.

Note:

OSM uses order data keys to determine order data changes during compensation and to identify pivot nodes that generate multiple task instances based on multi-instance data nodes (see "Generating Multiple Task Instances from a Multi-Instance Field") and should be distinguished from order keys used to match base orders with revision orders (see "About Order Keys").

To set an order key for a data element value, you must specify the data element as an XPath expression in the Key subtab on the Order Template Node editor.

Oracle recommends using order data keys for multi-instance data nodes to differentiate between instances of the same data node, because the results are predictable. For example, the data structure in Figure 10-9 can be used multiple times to identify different product specifications. You can associate an order data key to the children nodes of specification to uniquely identify each instance of a product specification contained in a customer order.

Figure 10-9 Order Data Key Defined in Design Studio

Description of "Figure 10-9 Order Data Key Defined in Design Studio"

For example, you could set a key on specification that points to the name child node. For expression for this key would be:

./name

For more information about creating valid order keys, see, "Modeling Valid Data Keys."

About Data Significance

During amendment processing, OSM identifies all tasks in the order that are affected by the changed order data. It then determines whether the data being changed is flagged as significant. (When you define orders or tasks, you can mark data as Significant or Not Significant. By default, all data is flagged significant.) OSM compensates only those tasks that process significant data.

If any of the data changes are significant, OSM transitions the order to the Amending state and builds a compensation plan based on all affected tasks, creating redo or undo compensation tasks as necessary.

Changes to non-significant data are updated on the in-flight order. For example, if the customer's preferred contact method (email or text message) is marked as non-significant, a revision order that changes only that data does not trigger amendment processing. Instead, the base order is changed, and the revision order is completed without starting amendment processing. The next task that uses the changed data uses the updated values.

You can configure data significance at the following levels:

Data Dictionary
Order template data
Task data

Each level can inherit or override the significance flag of its parent level. The Data Dictionary is at the top parent level. You can also configure significance for data structure definitions, but they do not participate in inheritance.

In addition to the data significance levels mentioned above, you can access the data in the order template from the Order Template tabs in the Order Item editor and the Order Component editor. If you change the significance of data in these tabs, you are actually altering the data in the order template.

The order template can inherit or override the data significance specified in the Data Dictionary. This allows one order type to consider the data significant while another order type does not.

The task data can inherit the data significance set in the order template only to override it as non-significant data. This allows data to be significant in one task and not significant in another. In that case, a revision with that one data element changed would cause the task that considers the data element significant to be compensated: the task that does not consider it significant will not be compensated. The exception to this is that you cannot override the significance of the following types of data at the task level:

data elements defined in data structure definitions
the ControlData/OrderItem element and its children, if you have selected Support Distributed Order Template in the Order Item Specification editor Property References tab

It is not possible to specify a data element as not significant at the order level and significant at the task level.

Figure 10-10 shows how data significance can be inherited and overridden.

Figure 10-10 Data Significance Inheritance

Description of "Figure 10-10 Data Significance Inheritance"

Figure 10-11 shows data significance specified in the Data Dictionary. Because this is the top level, there is nothing to inherit the significance from, so there is no inheritance option.

Figure 10-11 Data Significance Specified in the Data Dictionary

Description of "Figure 10-11 Data Significance Specified in the Data Dictionary"

Figure 10-12 shows data significance specified in the order template. In this example, the significance is inherited from the Data Dictionary.

Figure 10-12 Data Significance Specified in the Order Template

Description of "Figure 10-12 Data Significance Specified in the Order Template"

Figure 10-13 shows significance specified in the task data. Note that the significance is either inherited, or it is not significant. There is no option for significant: instead, that value is inherited from the order template.

Figure 10-13 Data Significance Specified in the Task Data

Description of "Figure 10-13 Data Significance Specified in the Task Data"

About Task Execution Modes

Tasks run in the following modes:

Do. This is the normal execution mode of a task when the order is in the In Progress state.
Undo. This execution mode is used when the task must undo work that has already been done; for example, to un-assign a port when an order is canceled.

Undoing tasks is performed in reverse order to how they were run. For example, if task B was completed after task A, then task B is undone before task A is undone.

Undo is used when the order component in the base order has completed, and the revision order has no corresponding order component. A cancellation order, therefore, can include no order components. This causes all of the order components in the base order to be undone. The Orchestration Plan tab in the Order Management web client displays nothing when this is the case, indicating that the order may have been canceled.
Redo. This execution mode is used when the task must redo work that has already been done; for example, a port assignment task that needs to be performed again because the input value of bandwidth is different as a result of the revision order. Redoing tasks is performed as an optimization of the Undo and Do operations for a task in a single operation.

The Redo execution mode is used when an order component has completed in the base order, and the revision order has the same order component, but specifies different order items or data values.
Amend Do. This execution mode is used when a new task must be performed while the order is in the Amending state. For example, the revision order might specify to add a service that was not in the base order. Because normal processing is not allowed during amendment processing, the Do mode cannot be used; Amend Do is used instead.

The Amend Do execution mode functions like the Do execution mode. When a task runs in the Amend Do mode, all of the permissions and automation plug-in logic for the Do mode of that task apply.

See "Example 3: Amend Do Compensation" for an example of how the Amend Do execution mode is used.

Note:

You can specify which tasks can by amended by the Redo and Undo compensation modes, but Amend Do is not configurable. This is because OSM determines when Amend Do is required, and the logic followed is that of the Do mode.
Do in Fallout. This is the mode for a task that executes when the task fails while running in Do mode.
Undo in Fallout. This is the mode for a task that executes when the task fails while running in Undo mode.
Redo in Fallout. This is the mode for a task that executes when the task fails while running in Redo mode.
Amend Do in Fallout. This is the mode for a task that executes when the task fails while running in Amend-Do mode.

The Amend Do in Fallout execution mode functions like the Do in Fallout execution mode. When a task runs in the Amend Do in Fallout mode, all of the permissions and automation plug-in logic for the Do in Fallout mode of that task apply.

See "Example 3: Amend Do Compensation" for an example of how the Amend Do execution mode is used.

Note:

You can specify which tasks can by amended by the Redo in Fallout and Undo in Fallout compensation modes, but Amend Do in Fallout is not configurable. This is because OSM determines when Amend Do in Fallout is required, and the logic followed is that of the Do in Fallout mode.

Table 10-1 summarizes the possible combinations and the required compensation for a revision order.

Table 10-1 Compensation Types

Base Order Component	Revision Order Component	Compensation Type
Exists	Does not exist	Undo or Undo in Fallout
Does not exist	Exists	Do or do in Fallout (run after compensation is complete) or Amend Do or Amend Do in Fallout (while the order is in the Amending state.
Exists	Exists, no changes found	No compensation required
Exists	Exists, changes found	Redo or Redo in Fallout
Exists	Exists, changes found that also causes process flow changes during compensation	Redo or Redo in Fallout for the impacted tasks that do not require a new process flow. Undo or Undo in Fallout for tasks in a process flow that are undone. Amend Do or Amend Do in Fallout for completely new process flows.

Modeling Compensation for Tasks

To perform compensation, OSM must identify the tasks that need to be compensated and then do, undo, or redo them in the appropriate sequence. OSM applies these compensation execution modes regardless of whether the task is running in normal mode or in failed mode.

A task needs to be compensated if it was completed and a change to at least one significant data element in the task's data has been made. Tasks in the Received, Accepted, Assigned, or a user-defined state can also be compensated.

Note:

When a task is compensated, all its successors must be compensated, whether or not they have significant changes.

Determining Task Compensation Strategy

In the Design Studio Task Editor Compensation tab (see Figure 10-14), you can model:

Static amendment processing compensation strategies for manual and automated tasks using a predefined list. Static compensation strategies are appropriate when the compensation requirements for a task are invariable.
Dynamic amendment processing compensation strategies for manual and automated tasks based on revision order data using an XQuery expression. Dynamic compensation strategies are appropriate when more than one compensation strategy is required for a task. For example, you could model the XQuery expression to select an Undo then do compensation strategy if the revision order bandwidth parameter is greater than 50 MB, and only a redo compensation strategy if the bandwidth parameter is less than 50 MB. For more information about dynamically modeling amendment processing compensation strategies, see "About Task Compensation Strategy XQuery Expressions".

Figure 10-14 Task Compensation Options

Description of "Figure 10-14 Task Compensation Options"

As shown in Figure 10-14, there are two scenarios that need to be compensated:

The task needs to be re-evaluated. This means that the task includes significant data and needs to be compensated.

The static amendment processing compensation options are:
- Redo in one operation. This option is recommended because it performs the fewest number of Undo and Do operations necessary for compensation.
  
  In the case of a manual task, the task will appear in the worklist in Redo mode, and the user can display the historical perspective and the contemporary perspective of the task data (from the last time the task was run) in two separate tabs. The user updates the data on the Contemporary Perspective tab and completes the task.
- Undo and Redo in two operations. Use this option when you need to roll back all order changes and perform the task again from the beginning. This option is useful when interacting with an external system that has no redo action but can process equivalent do and undo actions (for example, in the external system, implement and cancel).
  
  Note:
  
  When this option is used, it forces all completed tasks subsequent to this task to be undone in reverse sequence prior to executing the undo and then do of this task. To redo the task, you need to roll back all subsequent tasks first, then undo the task and redo it.
- Do nothing. Use this option if redoing the task is not necessary. For example, a task that sends a customer survey email would not need to be redone, even if it includes significant data.
In addition, you can select the Compensation Expression check box and enter an XQuery that dynamically selects an amendment processing compensation option at run time based on order data. The dynamic compensation takes precedence over the static compensation unless there is an error in the XQuery itself. If there is an XQuery error, then OSM reverts to the compensation selected with the static radio buttons.
The task is no longer required. This occurs when an order is canceled or when a branch of completed tasks in a process becomes obsolete due to a revision.

Figure 10-15 shows a process that has two potential paths. In this example, the base order followed the path from Task_1 to Task_2_1. The revision caused the path to change to follow Task_1 to Task_2_2. This means that Task_2_1, Task_3_1, and Task_4_1 do not need any compensation, because they are no longer on the path required to fulfill the order.

Figure 10-15 Process with Two Paths

Description of "Figure 10-15 Process with Two Paths"

The static amendment processing compensation options are:
- Undo. This option rolls back the task by executing the task in Undo mode to perform the roll-back operation. In the case of a manual task, this requires that the rollback be acknowledged manually in the Task web client. You cannot update the task data for an undo of a manual task in the Task web client, because the system will automatically put the data back to what it was prior to the task executing.
- Do nothing. This option rolls back the task automatically, without creating an undo task.
In addition, you can select the Compensation Expression check box and enter an XQuery that dynamically selects an amendment processing compensation option at run time based on order data. The dynamic compensation takes precedence over the static compensation unless there is an error in the XQuery itself. If there is an XQuery error, then OSM reverts to the compensation selected with the static radio buttons.

About Compensating In Progress Tasks

You can configure whether a task is included in compensation when it is completed or in progress, or you can use an XQuery expression that evaluates whether an in progress task can be included in compensation based on order data. Compensating in progress tasks is important for long running tasks where a response to a request takes hours or even days to return but the task still needs to be compensated. If you specify that a task can be compensated while it is in progress, you can also specify whether a grace period should be observed before performing the compensation. In addition, you must use an XQuery expression to evaluate any changes to the compensating task data to identify when the compensation has completed and the task can enter into normal do mode again.

For example, some automated plug-ins communicating with workforce management systems may involve the dispatching of personnel to perform work over several days. In such cases the automation plug-in sends the dispatch request to the workforce management system, and remains in progress until such time as the work completes. If a revision order were to arrive that changes some aspects of the work, then the in progress automation plug-in responsible for sending the original request should be included in the compensation plan. You can specify an XQuery that evaluates data on the in progress task communicating to the work force management system that determines if the task needs to be compensated. In addition, you can specify whether a wait period should be observed before starting compensation. You must also write an XQuery that determines when compensation has completed, for example, when the task receives the response from the new request indicating the workforce management system has received the new work details and has begun to processing the request.

Figure 10-16 shows the configuration options for determining when compensation should occur on an in progress task, whether a grace period should be observed before starting task compensation, and when compensation should complete.

Figure 10-16 In Progress Task Compensation Options

Description of "Figure 10-16 In Progress Task Compensation Options"

In the When an amendment occurs this task will be compensated if it is: area, you can select:

Completed: OSM only considered the task in compensation if it is in the completed state.
Completed or In Progress: OSM considers the task in compensation if it is in the completed state and also if it is in progress (for example, in the received, assigned, accepted, or a custom states.)
In Progress Compensation Include Expression: You can specify an XQuery that uses task data to determine whether the in progress task should be compensated. This XQuery expression overrides the Completed and Completed or In Progress options except when the XQuery is invalid.
In Progress Compensation Complete Expression: You can specify an XQuery expression that uses task data to determine whether the in progress task should be compensated.

In the When an amendment occurs if this task is in progress it will: area, you can specify what grace period should be observed before beginning task compensation on the in progress task:

Wait for the grace period: OSM observes the grace period specified on the order-life cycle for the Process Amendment transition.
Be excluded from the grace period: OSM does not observe a grace period.
Wait for specified duration: OSM observes the grace period statically configured for the task in seconds, minutes, hours, or days.
Dynamic Expression: OSM uses an XQuery expression that dynamically specifies the wait duration based on revision order data. This XQuery expression overrides the other options except when the XQuery is invalid. For more information about compensation strategy XQuery expressions, see "Compensation XQuery Expression".

About Task Compensation Strategy XQuery Expressions

You can dynamically assign compensation strategies to tasks by creating XQuery expressions in the Design Studio Task Editor Compensation tab for re-evaluation compensation strategies or compensation strategies for when a task is no longer required.

Note:

If the XQuery expression is invalid OSM logs the error but does not rollback the transaction. Instead, OSM uses the static compensation strategy as the default.

This section refers to the Design Studio OSM Automated Task or Manual Task editor, Compensation tab Compensation Expression XQuery field for re-evaluation compensation strategies:

Context: The context for this XQuery is the current order data. You can get the current order data using the XML API GetOrder.Response function.
Prolog: You can declare the XML API namespace to use the GetOrder.Response function in the XQuery body to extract the order information. You must declare the java:oracle:communications.ordermanagement.compensation. ReevaluationContext OSM Java package that provides methods that access the contemporary and historical order perspectives and compares the two. You can use the results of this comparison to determine what compensation strategy is required for a task based on revision order data.

For example:
```
declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace context = "java:oracle:communications.ordermanagement.compensation.ReevaluationContext";
declare namespace log =  "java:org.apache.commons.logging.Log";

declare variable $log external; 
declare variable $context external;
```
For more information about the classes in the OSM packages, install the OSM SDK and extract the OSM Javadocs from the SDK/osm7.w.x.y.z-javadocs.zip file (where w.x.y.z represents the specific version numbers for OSM). See OSM Installation Guide for more information about installing the OSM SDK.

Body: The body must return a valid compensation option.

For example, the following XQuery expression creates variables for the ReevaluationContext methods. The expression then checks that a specific value exists in the $value variable and that the value in the $significantValue variable both exists and is significant. If the value exists and is significant, then the expression sets the compensation strategy for the task to Undo then Do (undoThenDo in the ReevaluationContext Java class). If not, then the expression sets the compensation strategy to Redo (redo in the ReevaluationContext Java class).

let $inputDoc := self::node()
let $hopDoc := context:getHistoricalOrderDataAsDOM($context)
let $ropDoc := context:getCurrentOrderDataAsDOM($context) 
let $diffDoc := context:getDataChangesAsDOM($context)
let $value := $inputDoc/GetOrder.Response/_root/service[name='BB']//orderItemRef/specificationGroup//specification[value='100']
let $significantValue := $diffDoc/Changes/Add[@significant='true']/specification[value='100']
let $currentValue := $ropDoc/ GetOrder.Response/_root/service[name='BB']//orderItemRef/specificationGroup//specification[value='100']
 
return if (fn:exists($value) and fn:exists($significantValue))
then
    context:undoThenDo($context)
else
    context:redo($context)

This section refers to the Design Studio OSM Automated Task or Manual Task editor, Compensation tab Compensation Expression XQuery field for when a task is no longer required. The context, prolog, and body are similar to the XQuery expression for the re-evaluation strategy, except that the XQuery expression implements the java:oracle:communications.ordermanagement.compensation.RollbackContext package.

For example:

declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace context = "java:oracle:communications.ordermanagement.compensation.RollbackContext";
declare namespace log =  "java:org.apache.commons.logging.Log";
 
declare variable $log external; 
declare variable $context external;
 
let $inputDoc := self::node()
let $hopDoc := context:getHistoricalOrderDataAsDOM($context)
let $ropDoc := context:getCurrentOrderDataAsDOM($context) 
let $diffDoc := context:getDataChangesAsDOM($context)
 
let $value := $inputDoc/GetOrder.Response/_root/service[name='BB']//orderItemRef/specificationGroup//specification[value='100']
return if (fn:exists($value))
then
    context:undo($context)
else
    context:doNothing($context)

About Managing Compensation in the Task Web Client

When an automated task is redone, it is redone automatically. When a manual task is redone, the Task web client displays the task with an execution mode of Redo. The manual task must be processed in the Task web client.

To manage compensation in the Task web client, you can do the following:

Perform manual undo and redo operations.
Display the execution mode under which the tasks is running (Do, Redo, or Undo).
Display the order state; for example, Amending.
Display the historical data (the data as it was when the task last run) in the historical order perspective when editing a task.

Note:

You can assign roles in Design Studio to specify who can redo and undo tasks in the Task web client. OSM also supports the ability to assign the different execution modes of a task to different roles. This is useful because OSM can compensate using both manual and automated tasks. For example, the regular processing of a task in Do mode could be automated, and the Undo and Redo modes for the same task could be set to a special role to be done manually.

See OSM Task Web Client User's Guide for more information.

Modeling Compensation for Rules in Processes

You can specify to redo a rule in a process, or to do nothing. Because rules only evaluate data, and therefore do not modify data or interact with other systems, there is no undo necessary for a rule.

Modeling Compensation for Task Automation Plug-Ins

An automated task can include multiple automation plug-ins; for example, senders and receivers. Each automation plug-in can be associated with one or more execution modes. For example, if you create an automated task to activate a service, you can use the same logic to handle the initial activation request and the redo compensation for the activation request.

Each automated task can have separate plug-ins for each of the three modes; Do, Redo, and Undo. When an automated task runs in Redo or Undo mode, OSM provides information about the task data that was present when the task was last ran. For redo tasks, the Automation framework provides the historical data, the contemporary data, and the delta to the automation plug-in for use in the plug-in logic you write. See OSM Developer's Guide for more information.

Compensation Examples

The following examples show different compensation scenarios.

Example 1: Compensation During Provisioning

Figure 10-17 shows a compensation scenario for an orchestration order. In this example, OSM is running in the central order management role, fulfilling multiple functions.

The base order requires provisioning, billing, and customer account order components (sync customer).
A revision order is submitted while the order is carrying out provisioning tasks. The revision order replaces a medium-capacity service (3 MBps) with a high-capacity service (8 MBps). In this case, the content of the order components has changed in the revision order's orchestration plan, but the order components it contains and their dependencies remain the same.
Because the revision order was received during the base order provisioning, the compensation specifies that the provisioning order component must be redone, after which the order returns to the In Progress state, and the billing and sync customer components are then run with no compensation required.

Figure 10-17 Example of Compensation that Occurs During Provisioning

Description of "Figure 10-17 Example of Compensation that Occurs During Provisioning"

Example 2: Compensation During Billing

Figure 10-18 shows a compensation scenario for billing:

The base order includes provisioning order components for a fixed-line service and a cable broadband service.
A revision order is received after the provisioning order components are complete but while the billing order components are being processed. The revision order cancels the fixed-line service.
The compensation plan specifies to undo the fixed-line service and to redo the billing order components. The cable broadband service requires no compensation. Following the redo of the billing order components, the order resumes normal processing.

Figure 10-18 Compensation for Removing a Service

Description of "Figure 10-18 Compensation for Removing a Service"

Example 3: Amend Do Compensation

Figure 10-19 shows a scenario for Amend Do compensation:

The base order includes provisioning order components for a broadband service.
A revision order is submitted while billing order components are being processed. The revision order adds a fixed-line service.
The compensation plan creates a new dependency between the fixed-line service and the broadband service. Therefore, OSM must use Amend Do to first perform the new task and then process the broadband service order components. The billing order components are redone, and processing continues normally.

Figure 10-19 Compensation for Adding a Service

Description of "Figure 10-19 Compensation for Adding a Service"

Examples of Changes to Orchestration Plans

You can use the OSM Order Management web client to see how compensation affects an order's orchestration plan.

Figure 10-20 shows how an orchestration plan changes when a single service attribute changes. In this example, the connection speed changes from 8 MBps to 16 MBps. The order components remain the same, but the value of the connection speed changes in the provisioning component and in the billing component.

Figure 10-20 Orchestration Change Due to Revision: Change Service Attribute

Description of "Figure 10-20 Orchestration Change Due to Revision: Change Service Attribute"

Figure 10-21 shows how an orchestration plan changes when a revision order removes a service from the base order. In the example, the Fixed service was ordered in the base order, but it was removed in the revision order. The provisioning and billing components are removed, and the DSL provisioning component no longer has a dependency on the Fixed order component.

Figure 10-21 Orchestration Change Due to Revision: Remove Service From Order

Description of "Figure 10-21 Orchestration Change Due to Revision: Remove Service From Order"

Figure 10-22 shows how an orchestration plan changes when a service is added by a revision order. In this example, the Fixed service is added. This creates a new dependency for the DSL provisioning component.

Figure 10-22 Orchestration Change Due to Revision: Add Service to Order

Description of "Figure 10-22 Orchestration Change Due to Revision: Add Service to Order"

Modeling a Point of No Return

The following sections describe how to model a point of no return on an order where a revision order is no longer possible.

Fulfillment Pattern Point of No Return

There are two ways to set a point of no return. The first, only available for orchestration orders, is to set it on the fulfillment pattern using fulfillment states. The second is to write an expression in the order life-cycle policy.

When you use the fulfillment pattern to set a point of no return, the point of no return rules set a point of no return value for that order component. Order life-cycle policy conditions can then leverage this point of no return value for restricting order amendments. See "Life-Cycle Policy Point of No Return" for more information.

When you create a point of no return, model the following in Design Studio:

Define fulfillment states. These are required before configuring a point of no return on the fulfillment pattern. See "Modeling Fulfillment States and Processing States" for more information.
Define a point of no return value list in the fulfillment pattern. Create a name for your point of no return and indicate whether it is a hard point of no return or not. Alternatively, you can create a point of no return value on the fulfillment pattern extended by your fulfillment pattern and allow the point of no return values to be inherited.
Define point of no return rules for the point of no return values you created. Point of no return rules are specified at the order component level. Point of no return rules involve selecting one or more fulfillment states to map to the specified point of no return value. Additionally, because order component definitions are hierarchical, a sub-component of the order component associated with the orchestration plan inherits the point of no return rules defined on the orchestration plan order component. This sub-component may also specify its own additional point of no return rules.

Life-Cycle Policy Point of No Return

When you use life-cycle policies to set a point of no return, you define the point of no return as an expression in the order life-cycle policy, by setting conditions on the Submit Amendment transaction.

The following example shows a simple point of no return expression:

declare namespace oms="urn:com:metasolv:oms:xmlapi:1";
declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";

let $taskData := fn:root(.)/GetOrder.Response
let $rootData := $taskData/_root

return
    if (($rootData/PoNR/text() = "HARD")) 
    then (
        true()
    ) else (
        false()
    )

When a revision order is received, OSM checks the life-cycle policy to see if there are any point of no return conditions preventing the transition to the Amending order status. If OSM finds any point of no return conditions that are met, the order is not allowed to be amended. In the example above, if the broadband service is billed before the fixed-line service is provisioned, the order has passed the point of no return, even though the fixed-line service has not passed its point of no return.

If the life-cycle policy determines that the revision is not allowed, an OrderTransactionNotAllowedFault message is returned to the order-source that submitted the revision order.

About Modeling Order Change Management

When you model order change management, you configure the following OSM entities:

Data dictionary. When you create data elements, you can assign them significance. If data is significant, it is considered for amending. See "About Data Significance" for more information.
Order specification. When you create an order specification, you configure the following:
- Data significance at the order level. You can inherit significance from the Data Dictionary, or you can define order-specific significance. See "About Data Significance" for more information.
- If the order is amendable or not.
- The order key. See "About Order Keys" for more information.
- The data element that defines the order version. See "About Submitting Multiple Revisions of an Order" for more information.
- Whether or not to publish order events about amendment processing. You can choose to publish events when an amendment is started, completed, queued, being terminated, terminated or abandoned. An amendment can be abandoned when it is queued for processing and a subsequent amendment supersedes it. See "Modeling Order Life-Cycle Policy States and Transitions" for more information.
Tasks. You can configure the following:
- Data significance at the task level. See "About Data Significance" for more information.
- How the tasks should be compensated. See "Modeling Compensation for Tasks" for more information.
- The roles that can redo and undo tasks.
- If automated, the automation plug-ins for redo and undo modes of tasks.
Rules in processes. You can configure if the rule should be redone or not. See "Modeling Compensation for Rules in Processes" for more information.
Order life-cycle policy. You configure the conditions that allow an order to be amended. See "About Controlling When Amendment Processing Starts" and "Life-Cycle Policy Point of No Return" for more information. See "Modeling Order Life-Cycle Policy States and Transitions" for information about order states.

Troubleshooting Order Change Management Modeling

You can use the following methods to troubleshoot your order change management modeling:

You can use the following OrderManagementDiag.wsdl web service operations:
- GetOrderCompensations: Returns a list of compensations against a given order.
- GetOrderProcessHistory: Returns multiple process history perspectives.
- GetCompensationPlan: Returns a set of compensation tasks and the dependencies between them.
See the PONR_OrderID.xml file. This file is generated when a Submit Amendment transaction is called.

About Order Change Management at the Orchestration Layer

To manage changes to an orchestration order, OSM uses order compensation. OSM analyzes the required order changes and their impact on everything that has already been completed by the in-flight order including manual updates from Task web client users and order updates from automated tasks. OSM then creates a compensation plan to define the actions that need to be carried out to amend the in-flight order. After compensation has ended, the in-flight order will have incorporated the required order changes and continues executing normally. You can recognize when compensation is happening to an orchestration order when the order is in the Amending state or the Cancelling state.

Note:

If you submit a revision order that uses a different cartridge version from the one that the original base order was created with, OSM uses the original base order cartridge version to execute any required compensation tasks and not the cartridge version used to create the revision order.

Triggering amendment processing using revision orders is the most efficient way to manage changes made to in-flight orders. OSM automatically detects the revisions that must be made and changes the orchestration plan as necessary. No manual work is required to find changes that need to be made.

A revision order is sometimes called a supplemental order. This order contains all the relevant data for the order, including the updated requirements. During the amendment processing phase, OSM compares the data in the revision order with the data in the base order and makes the changes as required (a single revision order can make multiple changes to an order). This allows the base order to continue processing with, and compensating for, the customer's new order requirements provided in the revision order. The customer does not have to wait for the base order to be completed or canceled before changing it. A revision order can also be used to correct a failed order.

When you model orders and tasks, you can control the amendment processing that is allowed for the order. For example:

If the order is allowed to be amended
At which point in the order processing the order is no longer allowed to be amended (the PONR)
Who can manage revision orders in the Task web client
Which data needs to be compensated, and which does not

For more information about amendment processing and compensation, see "About Compensation and Orchestration".

About Compensation and Orchestration

OSM performs compensation on both process-based orders and orchestration orders. When compensating an order that has an orchestration plan, the compensation can change the orchestration plan.

Each orchestration order has its own unique orchestration plan, generated specifically for that order. Therefore, to manage a revision order for the base order, OSM must generate a new orchestration plan for the revision order. The orchestration plan for the revision order can be different from the orchestration plan for the base order; for example, it might include different order components, with different dependencies and different order items.

By contrast, a process-based order has a predefined process; the process is not generated when the order is created. The tasks that make up that process and the flow of those tasks in the process do not change. The data values for those tasks change as a result of a revision, and the path through the predefined process may change as a result of compensation, but the overall process remains the same.

To manage compensation for an orchestration plan, OSM needs to recognize and account for dependencies between the order components in the order that is being amended. The compensation required depends on whether components exist in one or both orders' (revision order and base) orchestration plans and on whether changes to the contents of those order components (such as different order items) exist.

Redoing an order component in an orchestration plan is performed by redoing the tasks run by the order component. In redoing order components, OSM follows the sequence of dependencies in the orchestration plan. OSM takes into account the dependencies from the revised orchestration plan, unless a successor component has previously started in the original base order, in which case the dependency is considered resolved.

OSM analyzes the order component compensation type and component dependencies to determine the sequence of component compensation. OSM performs order component compensations in the following stages:

Reverse compensation: In this stage, OSM performs only undo compensation tasks for order components. OSM performs undo tasks for order components in the reverse order of dependencies that existed between the components in the original.

For example, OSM performs undo tasks for order component B before performing any undo task for order component A if B was dependent upon A in the base order.
Forward compensation: In this stage, OSM fulfills order components that have changed (redo) or been introduced (amend do) based on the order of dependencies, which is derived after taking into account dependencies from the revised orchestration plan.

The revised orchestration plan may include new components to be completed using Amend Do and Redo compensation types.

Note:

When switching from reverse to forward compensation, OSM identifies the new order components that need to be completed using the Amend Do compensation type. These components participate in the compensation plan as compensation items. This facilitates appropriate compensation sequencing for compensation tasks of existing downstream order components or other components that require amend do compensation.

All processing not related to compensation is suspended for an orchestration plan until compensation is complete. After compensation is complete, the order is restored from the Amending state to an In Progress state and normal processing continues.

About Point of No Return

In some cases, there may be a point in the order process after which it becomes impossible or undesirable to make changes to an order. This is called a point of no return.

There are two types of points of no return in OSM.

A hard point of no return indicates that amendments to the relevant part of the order are either impossible or undesirable. In the case of a hard point of no return, a revision order is not possible. Instead, you can create a follow-on order. See "About Inter-Order Dependencies" for more information about follow-on orders.

Note:

A follow-on order is not a change to an in-flight order but is an alternative when revising the in-flight order is not possible. Follow-on orders are used to make changes to items on an order that have not yet been completed but are past the point of no return. OSM manages follow-on orders to ensure they do not run until the order items upon which they depend are completed.
A soft point of no return indicates that order amendment processing is still possible, but there are consequences for the customer. For example, you can specify to bill a customer for an extra charge if the order is revised after the soft point of no return has been reached.

You can define multiple point of no return milestones in an order's fulfillment flow. For example:

For a fixed-line service, a point of no return after provisioning.
For a broadband service, a point of no return after billing.

All soft or hard points of no return depend on the order life cycle policy conditions which control whether orders can transition from the In Progress state to the Amending state. See "Modeling Order Life-Cycle Policies" for more information. A point of no return value that the order life cycle policy evaluates is typically set at the order item level. This allows order components with varying processing durations to run, instead of stopping the entire order at the first order item with a point of no return. You can also set the point of no return to a fulfillment state which provides aggregated states for a group of order items and for the overall order. See "Modeling Fulfillment States" for more information.

Figure 10-23 shows two different point of no return scenarios.

Figure 10-23 Point of No Return for Different Services

Description of "Figure 10-23 Point of No Return for Different Services"