Skip Headers
Oracle® Communications Order and Service Management Concepts
Release 7.2.2

E35415-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

7 Managing Changes to Orders

This chapter describes how Oracle Communications Order and Service Management (OSM) manages changes to in-flight orders.

About Managing Changes to Orders

Any order that is not in a closed state (Completed or Aborted) is an in-flight order. An in-flight order still has the potential for further work to be performed on it.

There are many scenarios that require changes to an in-flight order. The most common scenarios are:

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. The revision order changes the base order in OSM, so only one order needs to be managed, even when there are multiple revisions to the same order.

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

About Update Order Transactions

In addition to revision orders, you can update order data in the following ways:

  • Manually, by sending an Web Service update order from a CRM. See OSM Developer's Guide for more information about Web Service update orders.

  • Manually, by sending an XML API update order from a CRM. See OSM XML API Developer's Guide for more information.

  • Manually, by opening and editing an order using the Task Web client order query. See OSM Task Web Client User's Guide for more information.

  • Automatically, by configuring an automated task automator to send a Web Service or XML API update order. See OSM Developer's Guide for more information about update orders and using automations.

Update orders can:

  • Update a complete order. The existing order is updated (elements added, changed, or deleted) to match the supplied order. Order level order updates are typically sent in the context of order level notification, jeopardy, or event automation automators. See "About Using Notifications to Run Automation Plug-Ins" for more information about update order transactions used in the context of jeopardies, notifications, and events.

  • Update nodes in an order. Elements can be added or changed. Deletes are not performed using the update node functionality. The nodes are supplied in the format of the existing order and are typically sent as part of task level automation automators.

  • Add, delete, or change element data values that are typically sent as part of task level automation automators.

You can manually send an update order when the order is in the Not Started state before any tasks are completed. You can also manually send an update order when the order is in the In Progress state. In this scenario, amendment processing can be triggered if a revision order does not match the data manually provided in the update order. Conflicts between manually updated data and revision order data can be avoided if the data is marked as not significant.

Update orders sent by automated task automators are configured as part of normal order processing. The changes from these order updates normally only change task data for a specific automated task. However, amendment processing can be triggered if a revision order does not match the data automatically provided in the update order. Conflicts between automatically updated data and revision order data can be avoided if the data is marked as not significant.

About Amendment Processing

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:

  1. 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 services operation or the CreateOrderBySpecification Web services 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.
  2. OSM receives the revision order. OSM checks to see if the base order is amendable. You enable this 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.
  3. 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.

  4. 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 "About OSM Order Life-Cycle Management" for more information.

    • OSM checks to see if the base order has not passed the point of no return. The point of no return 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 "About 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.

  5. 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 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 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 allows 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.

  6. After determining that amendment processing is needed, OSM transitions the order to the Amending state.

    Note:

    OSM queues orders that need amending. This means it is possible that multiple revisions are submitted and queued for the same order while the order is in the queue. If amending the order is allowed, OSM chooses the latest version of the amendments in queue by looking at the optional version identifier (if configured) or by the date and time in which they were received if there is no configured version identifier.

    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 "About Compensation" 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.

  7. 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.

  8. 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 7-1 shows a simplified amendment processing flow.

Figure 7-1 Amendment Processing

Graphic is described in surrounding text.

A simple example of a revision order is as follows:

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

    Figure 7-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 7-2 Amendment Order Example

    Graphic is described in surrounding text.
  2. OSM verifies that the 3 MBps service is available and transitions to the next task, Assign_Port.

  3. 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 5MBps and submits the order to OSM.

  4. OSM receives the incoming customer order, and detects that it is a revision to an in-flight order.

  5. 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.

  6. The value set by the Verify_ADSL_Service_Availability task is changed.

    Figure 7-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, or Amend Do. (See "About Task Execution Modes" for more information.)

    Figure 7-3 Amendment Displayed in the Task Web Client

    Shows order displayed in Task Web client.
  7. 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.

  8. After verifying that the revised bandwidth is available, the base order continues processing.

You can monitor revisions in the Web clients. Figure 7-4 shows a revision order (Order 316) and the base order that it revised (Order 315).

Figure 7-4 Revision Order and the Base Order it Amended

Shows a revision order and its base order.

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:

  1. 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.

  2. The Task Web client displays the revision order.

  3. You can then change the data required for the revision and submit the revision order.

    Important:

    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. Figure 7-5 shows an order key defined in Oracle Communications Design Studio. The expression is the path to the data in the order template.

Figure 7-5 Order Key Defined in Design Studio

Shows an order key defined in Design Studio

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

Order key values should not be modified after an order is submitted.

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:

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

Figure 7-6 shows the version specified in an order.

Figure 7-6 Revision Version Data Element Specified in an Order

Shows the version specified in an order.

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:

  1. Checks permissions to allow or postpone the processing of the revision.

  2. Checks if a grace period is set to allow all order activity to settle. If so, it waits for the grace period to end.

  3. 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. Figure 7-7 shows the life-cycle policy for the Process Amendment transition. In this case, it returns true, so it is always allowed to transition.

Figure 7-7 Order Life-Cycle Policy for the Process Amendment Transition

Graphic is described in surrounding text.

See "About Managing Order States and Transitions" for more information about transactions.

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

  1. 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.

  2. 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:

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 "About Modeling Life-Cycle Policies" for more information. See "OSM Order States and Transactions" for information about order states.

About Compensation

To manage changes to an 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 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.

When you model OSM entities such as order specifications and tasks, aspects of your model affect compensation, including the following:

You can model compensation in the following entities:

You cannot configure compensation for timer delays or event delays in processes.

About Order 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.

During the compensation analysis, OSM compares the contemporary order perspective with the historical order perspective. The data in the contemporary order perspective can be the data provided in the current revision order and may also include compensation changes made up that point. The data in the historical order perspective is the last data that had been processed on each task.

In 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".

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.

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.

  • By comparing order data keys in the Order Template editor for specific data elements. 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. For example, the data structure in Figure 7-8 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 7-8 Order Data Key Defined in Design Studio

Shows an order data key defined in Design Studio.

You could also make every instance of specification unique by setting a key on specification that points to the name child node. For expression for this key would be:

./name

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.

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.

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

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

Figure 7-9 Data Significance Inheritance

Graphic is described in surrounding text.

Figure 7-10 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 7-10 Data Significance Specified in the Data Dictionary

Graphic is described in surrounding text.

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

Figure 7-11 Data Significance Specified in the Order Template

Shows data significance specified in order template.

Figure 7-12 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 7-12 Data Significance Specified in the Task Data

Shows data significance specified in 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 4: 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.

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

Table 7-1 Compensation Types

Base Order Component Revision Order Component Compensation Type

Exists

Does not exist

Undo

Does not exist

Exists

Do (run after compensation is complete) or Amend Do (while the order is in the Amending state.

Exists

Exists, no changes found

No compensation required

Exists

Exists, changes found

Redo


Modeling Compensation for Tasks

To perform compensation, OSM must identify the tasks that need to be compensated and then do or undo them in the appropriate sequence.

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 are not compensated. This is because OSM cannot determine what work has been accomplished. For example, an automated task might have sent a request to an external system, but a response has not been received yet. If those tasks have not completed before the grace period expires, they would be started again after the compensation has completed and the order resumes to the In Progress state.

In the Design Studio Task Editor Compensation tab (see Figure 7-13), 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 modelling amendment processing compensation strategies, see "About Task Compensation Strategy XQuery Expressions".

Figure 7-13 Task Compensation Options

Shows task compensation options.

As shown in Figure 7-13, 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 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.

  • 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 7-14 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 7-14 Process with Two Paths

    Graphic is described in surrounding text.

    The two 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.

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 extract the OSM_Home/SDK/osm7.2.x-javadocs.zip OSM Java docs (where x is the software build numbers).

  • 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.

Figure 7-15 shows rule properties in Design Studio.

Figure 7-15 Rule Properties

Shows rule properties in Design Studio.

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.

Figure 7-16 shows compensation for the sender automation plug-in for an automated task.

Figure 7-16 Compensation Specified in an Automated Task

Shows compensation specified in automated task.

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.

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.

Compensation Considerations for Tasks and Processes

You can plan for compensation when designing tasks. When an order amendment is received, tasks should be undone and redone only if the order change requires it. For example, a provisioning system task might have a data element that contains the full customer name. You might include this information in the task, even if it is not something that needs to be sent to another system. However, a change to this data element would not require any action in OSM for the provisioning system. The same data element might, however, be significant in a task for a billing system. So, when designing tasks it is important to ensure that the correct data for the task has been marked as significant. This optimizes the calculation of the deltas for each task, and ensures that only the necessary tasks are compensated.

When modeling processes, you can use subprocesses to control the scope of compensation. For example; Figure 7-17 shows a process that includes only tasks, with no subprocesses.

Figure 7-17 Process Example with No Subprocesses

Shows a process example with no subprocesses.

In this figure, there is a choice between two possible flows: one through Task_2_1 and the other through Task_2_2, depending on the exit status of Task_1.

Assume this flow has completed Task_1, Task_2_2, Task_3, and Task_4 and has reached Task_Final when a revision is received. The revision indicates that the process now should go through Task_2_1 instead of Task_2_2.

In this scenario, the compensation plan undoes Task_4, then undoes Task_3 and then undoes Task_2_2, before re-processing with the correct data.

Now consider the following flow, which is modified so that Task_1, Task_2_1, Task_2_2, and Task_3 are now contained in a subprocess.

Assume that the same processing has taken place as before. Task_1, Task_2_2, and Task_3 are run in the subprocess, and Task_4 is run in the main process, which reaches Task_Final when a revision is received. With this configuration, the compensation for SubProc1 takes place before the compensation for Task_4. Task_4 does not need compensation, because the compensation is isolated in the subprocess.

Figure 7-18 Process Example with Subprocess

Shows a process example with subprocesses

Compensation Examples

The following examples show different compensation scenarios.

Example 1: Changing a Service Request

In this example of a process-based order, 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.

The tasks that might be affected by this change are:

  • Assign_Port

  • Activate_DSLAM

  • Add_Capacity

In this example, there are three possible scenarios:

  • The existing port supports 3MBps and 5MBps. In this case, the only compensation needed is to redo the Assign_Port task. Redoing the Assign_Port task causes the same port number to be assigned, which is the same outcome as before. Therefore, no further compensation is required.

  • The existing port does not support 5MBps. In this case, the compensation requires:

    • Redo the Assign_Port task that assigns a different port. This task needs to be redone because the bandwidth data element is part of the Assign_Port task data input.

    • Redo the Activate_DSLAM task to activate the new port number on the DSLAM. This task needs to be redone because the port ID as a derived data change is input on the Activate_DSLAM task data.

    In this scenario, the second compensation requirement is derived from the first. The original amendment directly affected only the Assign_Port task, but circumstances required a second compensation action.

  • There is no available port that supports 5MBps. In this case the compensation requires:

    • Redo the Assign_Port task. This results in a port_unavailable exit status for the task.

    • Undo the Activate_DSLAM task. This removes the configuration of the previous port ID on the DSLAM. In this case, the path chosen in the process has changed as a result of a different exit status from the Assign_Port task. OSM undoes the previous path (in this case, just as far as the Activate_DSLAM task), and proceeds down the other path (to the Add_Capacity task). The compensation is complete and the order returns to the In Progress state.

    • Perform the Add_Capacity task in normal Do mode, because the order is back to the In Progress state.

Example 2: Compensation During Provisioning

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

  1. The base order requires provisioning, billing, and customer account order components (sync customer).

  2. 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.

  3. 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 7-19 Example of Compensation that Occurs During Provisioning

Graphic is described in surrounding text.

Example 3: Compensation During Billing

Figure 7-20 shows a compensation scenario for billing:

  1. The base order includes provisioning order components for a fixed-line service and a cable broadband service.

  2. 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.

  3. 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 7-20 Compensation for Removing a Service

Graphic is described in surrounding text.

Example 4: Amend Do Compensation

Figure 7-21 shows a scenario for Amend Do compensation:

  1. The base order includes provisioning order components for a broadband service.

  2. A revision order is submitted while billing order components are being processed. The revision order adds a fixed-line service.

  3. 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 7-21 Compensation for Adding a Service

Graphic is described in surrounding text.

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 7-22 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 7-22 Orchestration Change Due to Revision: Change Service Attribute

Graphic is described in surrounding text.

Figure 7-23 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 7-23 Orchestration Change Due to Revision: Remove Service From Order

Graphic is described in surrounding text.

Figure 7-24 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 7-24 Orchestration Change Due to Revision: Add Service to Order

Graphic is described in surrounding text.

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 point of no return in OSM.

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

A point of no return 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.

Figure 7-25 shows two different point of no return scenarios.

Figure 7-25 Point of No Return for Different Services

Shows two point-of-no-return scenarios.

Product Specification 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 product specification using fulfillment states. The second is to write an expression in the order life-cycle policy.

When you use the product specification 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.

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 product specification. See "Modeling Fulfillment States" for more information.

  • Define a point of no return value list in the product specification. 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 product specification extended by your product specification 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. Figure 7-26 shows part of a point of no return expression defined in Design Studio.

Figure 7-26 Point of No Return Expression

Shows part of a point-of-no-return expression.

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:

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 services 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.