Modeling Fulfillment States and Processing States

12 Modeling Fulfillment States and Processing States

This chapter describes how to model fulfillment states and processing states in an Oracle Communications Order and Service Management (OSM) solution.

About Fulfillment States, and Processing States

You can associate the predefined order component order item (OCOI) processing states to messages from external fulfillment systems or to events that occur within OSM to generate an aggregate order item processing state as an order processes. OSM then uses these OCOI processing states to calculate You can also define fulfillment states for orders and order items to report on different business scenarios.

Table 12-1 compares processing states with fulfillment states.

Table 12-1 Comparing Processing States with Fulfillment States

Features	Processing States	Fulfillment States
Auto-configured and predefined	Yes	No
Manually configured and defined	No	Yes
Tracked as normal, warnings, or failures counts in the Order Management web client Order tab, Summary subtab.	Yes	No
Tracked as warning or failure counts in the Order Management web client Order Items tab.	Yes	No
Failure states in the Order Management web client can be traced: From the order item To the order components processing the order item To the tasks processing the order items in each order component. Identifying when a task generates a failure state is easier when the task also transitions to a fallout execution mode.	Yes	Yes
Updated for each order item in the Order Management web client Order Items tab.	Yes	Yes
States reflected up the order item hierarchy	Yes	Yes
States reflected on orders based on order item hierarchy states	No	Yes

Modeling Fulfillment States

Figure 12-1 is a detailed depiction of fulfillment state processing for a small part of a sample implementation. It shows the way multiple external responses can be translated into a single fulfillment state for the order.

Figure 12-1 Fulfillment State Composition

Description of "Figure 12-1 Fulfillment State Composition"

At run time, OSM maps the external fulfillment states to mapped fulfillment states on an order item. Order item fulfillment states are composed using the immediate children of the order item, and order fulfillment states are composed using the root-level order items.

Whenever one of the input fulfillment states for an order item changes, the fulfillment state of that order item (and all of its parents, including the order) is recalculated. For example, if the mapped fulfillment state of "leaf" order item A changes, the composite fulfillment state of order item A is recalculated. If the composite fulfillment state for order item A changes and it has a parent, order item B, order item B's fulfillment state is recalculated as well. If the composite fulfillment state of order item A does not change, the fulfillment state for order item B is not recalculated.

In the figure:

The external billing system sends a status of OK, which is used directly as the external fulfillment state for OrderComponent_Billing.
The external fulfillment state of OK is mapped to Complete for both the order items that are fulfilled by that order component (OrderItem_VoIP and OrderItem_Mobile) using the fulfillment state mappings.
The activation system has sent a complex message indicating the statuses of different parts of the fulfillment request. That message is translated by the custom code in the automation to the external fulfillment state of MOBILE_FAIL.
The fulfillment state mappings are configured to map MOBILE_FAIL for this order component to mean that OrderItem_Mobile has failed and OrderItem_VoIP has succeeded.
The fulfillment state composition rules for the OrderItem_VoIP order item then look at the mapped fulfillment states for OrderItem_VoIP for each order component (OrderComponent_Billing and OrderComponent_Activation) that fulfills that order item. Because the mapped fulfillment states for both of the order components are Complete, the composite fulfillment state for the order item is also set to Completed.
The fulfillment state composition rules for the OrderItem_Mobile order item then look at the mapped fulfillment states for OrderItem_Mobile for each order component (OrderComponent_Billing and OrderComponent_Activation) that fulfills that order item. Because the mapped fulfillment states for one of the order items is Complete and for the other order item is Fail, the composite fulfillment state for the order item is set to Failed.
The fulfillment state composition rules for the order then take the composite fulfillment state of the highest-level parent order items to determine the fulfillment state of the order. In many cases, the failure of any part of an order might be configured as a failure of the order as a whole. However in this example, fulfillment states have been configured that, because part of the order (VoIP) is ready for customer use, the composite fulfillment state is set to Part_Success.

Defining Fulfillment States

Fulfillment states are configured in Oracle Communications Design Studio. At a high level, configuration of fulfillment state management has the following main steps:

Define external fulfillment states for order components: Create a list of values for the order component that matches the statuses returned by the external systems or automations. An external fulfillment state is available on the order component where it is defined and on any order component that extends that order component. See "Modeling External Fulfillment States" for more information.
Create and configure fulfillment state maps: Create one or more lists of values for the common fulfillment states and create mappings to translate external fulfillment states into mapped fulfillment states. Common fulfillment states are used as mapped fulfillment states and as composite fulfillment states. Fulfillment state mappings provide the evaluation and normalization of the external system's states into mapped fulfillment states. Common fulfillment states and fulfillment state mappings are available for the entire workspace. See "Modeling Fulfillment State Maps" for more information.
Create and configure order item fulfillment state composition rule sets and order fulfillment state composition rule sets: Create the composition rule sets to determine the fulfillment state of an order or order item from the fulfillment state of its child items. Composition rule sets are based on the order item and order hierarchy, and compose fulfillment states into composite fulfillment states that reflect the state of entire order items or orders. See "Modeling Fulfillment State Composition Rule Sets" for more information.

The external fulfillment states, order item fulfillment states, and order fulfilment are stored in the ControlData for the order. See "Modeling Data for Fulfillment States" for more information. Mapped fulfillment states are not stored on the order.

Modeling External Fulfillment States

External fulfillment states consist of a list of responses expected by an order component and any order components that extend the order component. When an external fulfillment state is defined, it can be used in a fulfillment state mapping.

Modeling Fulfillment State Maps

You use fulfillment state maps to configure common fulfillment states and fulfillment state mappings. Fulfillment state mappings are the entities that contain the actual mapping information, and fulfillment state maps are containers for the information. Functionally, it does not matter whether you have one or many fulfillment state maps. Each common fulfillment state is available to all of the fulfillment state mappings, regardless of which fulfillment state map it is configured in. This means that each common fulfillment state needs to be unique in the workspace. There are optional default common fulfillment states that can be used. See Design Studio Modeling OSM Orchestration Help for more information about the default states.

Common fulfillment states have two functions:

They are used as the result of the fulfillment state mappings. When they are used this way, they are referred to as mapped fulfillment states.
They are used as the result of the composition rules. When they are used this way, they are referred to as composite fulfillment states. If these fulfillment states are to be sent to an upstream system, you configure these values to match what the upstream system expects. (For more information about composition rules, see "Modeling Fulfillment State Composition Rule Sets".)

Common fulfillment states, used as either mapped or composite fulfillment states, are configured in a single list in the States tab of the Fulfillment State Map editor. You do not need to assign the common fulfillment state as either a mapped fulfillment state or a composite fulfillment state when you configure it. The same common fulfillment state can be used for both purposes at the same time. Figure 12-2 shows the common fulfillment states configured in a fulfillment state map.

Figure 12-2 Detail from Fulfillment State Map Editor States Tab

Description of "Figure 12-2 Detail from Fulfillment State Map Editor States Tab"

After the fulfillment states have been created, you create the mappings in the Mappings tab of the Fulfillment State Map editor.

A fulfillment state mapping maps an external fulfillment state to a common fulfillment state. When defining a fulfillment state mapping, you must define when that particular mapping will be used. Each mapping must specify a single fulfillment pattern, order item, and orchestration sequence, with a single set of orchestration stage and order component combinations. There may be a large number of mappings because wild cards cannot be used.

These criteria are defined in Design Studio and should be specified in the order given. Some of the entries later on the list cannot be set until the earlier ones have been entered.

Fulfillment pattern: The fulfillment pattern value restricts the fulfillment state mapping to apply only to order components defined on orchestration plans associated with the specified fulfillment pattern. For example, the fulfillment state mappings might be very different between mobile and IP services.
Order item: The selected value restricts the fulfillment state mapping to apply only to order components responsible for processing the specified order item.
Orchestration sequence: The available orchestration sequences are those related to the specified order item. The selected value restricts the orchestration stages to which the mapping can apply.
Orchestration stage: One or more orchestration stages must be specified for the mapping. Any of the orchestration stages in the orchestration sequence can be specified. Use only one orchestration stage per mapping, if possible. Using only one orchestration stage facilitates maintenance of the solution because your decomposition rules may change over time.
Order component: One order component must be specified for each specified orchestration stage.

You can further restrict the application of the mapping by specifying any of the following:

Fulfillment mode: If specified, the fulfillment mode value, combined with the fulfillment state mapping's fulfillment pattern value, determines the orchestration plan to which the fulfillment state mapping applies. The fulfillment state mapping is evaluated for order components associated only with the identified orchestration plan. The fulfillment state mapping returned for an item with Cancel fulfillment mode could be very different than that for an item with Deliver fulfillment mode.
Properties/property value combinations: After the order item is selected, one or more order item property value criteria values may be specified. The set of order item properties available for selection are those properties that are defined on the fulfillment state mapping's selected order item specification. For example, you might have a property called LineType and have different mappings based on whether the value was VoIP Phone or soft phone.
Current Fulfillment State: If a current fulfillment state is specified, the fulfillment state mapping is evaluated only for those order components where the current fulfillment state of the item on the component matches the specified value. This current fulfillment state is taken from the list of common fulfillment states, meaning that it is the target fulfillment state of another fulfillment state mapping or the result of composition rules. You might use this to set a mapped fulfillment state of Failed if that is the current state; if the current state is In_Progress, the new state might be Complete.

Modeling Fulfillment State Composition Rule Sets

Orders contain one or more order items. Order items can in turn be fulfilled by one or more order components and also contain other order items using the order item hierarchy. See "Modeling Order Item Hierarchies" for more information.

There is a fulfillment state assigned to the order and order item as a whole that takes into account all of the fulfillment states of its immediate children. This is referred to as a composite fulfillment state.

Fulfillment state composition rules for the order item are defined in order item fulfillment state composition rule sets. These rules aggregate the mapped fulfillment states for any order components that fulfill the order item and also the fulfillment states of any child order items of the order item.

Fulfillment state composition rules for the order are defined in order composition rule sets. These rule sets aggregate the composite fulfillment states of the root-level order items.

Note:

To use fulfillment states, you must configure composition rule sets both for orders and for order items.

The configuration processes for order fulfillment state composition rule sets and order item fulfillment state rule sets are similar.

A fulfillment state composition rule set contains rules, which in turn contain conditions, as shown in Figure 12-3.

Figure 12-3 Detail from Order Fulfillment State Composition Rule Set Editor

Description of "Figure 12-3 Detail from Order Fulfillment State Composition Rule Set Editor"

You use composition rules to specify the fulfillment state for the order or order item when all of the conditions are met (logical AND). If there are separate situations that can result in the same fulfillment state (logical OR), create separate rules that evaluate to the same fulfillment state.

For example, say that you have one condition that specifies that all of the input fulfillment states must be FAILED, and another condition that specifies that all of the input fulfillment states must be CANCELLED. Both of these conditions should result in a fulfillment state of NOT_DONE. You also have another condition that allows a mixture of FAILED and CANCELLED states that should result in a fulfillment state of CHECK_STATUS. In this case you would need three separate rules. The last condition requires its own rule because it results in a different fulfillment state. The other two conditions each require their own separate rule because it would never be possible for both of those conditions to be met at the same time.

The fulfillment state condition based on the input fulfillment states is the same for both order item composition rule sets and order composition rule sets. It allows the inclusion (or exclusion) of one or more fulfillment states according to whether any, all, or none of the input fulfillment states are in a selected list of fulfillment states. Figure 12-4 shows the details for a condition.

Figure 12-4 Fulfillment States Section of Condition Details Subtab

Description of "Figure 12-4 Fulfillment States Section of Condition Details Subtab"

The fulfillment states selected in the condition are constrained by a conjunction that must be true for the condition to evaluate to true. The available conjunctions are:

Any: The condition requires at least one of the input fulfillment states to match one of the selected fulfillment states.
All: The condition requires all of the input fulfillment states to match the selected fulfillment states.
None: The condition requires that none of the input fulfillment states match any of the selected fulfillment states.

The list of fulfillment states that can be assigned as mapped fulfillment states and the list that can be assigned as composite fulfillment states is the same list. The common fulfillment states created in the Fulfillment State Map editor States tab apply to both the mapped and composite fulfillment states. Therefore, when you are generating a composite fulfillment state, the list of fulfillment states that you can choose in this condition is the list of common fulfillment states. (See "Modeling Fulfillment State Maps" for more information about this list.)

Order Item Fulfillment State Composition Rule Sets

In addition to the fulfillment state conditions discussed above, in order item fulfillment state composition rule sets you can set order item property values that must be present for the composition rule to evaluate to true. If both Any/All/None and property values are defined, both must be true for the composition rule to evaluate to true.

Order Fulfillment State Composition Rule Sets

In addition to the common fulfillment state-related criteria discussed above, in order fulfillment state composition rule sets you can also specify an XQuery expression that must evaluate to true for the condition as a whole to evaluate to true. For example:

/GetOrder.Response/_root/OrderHeader/AccountIdentifier > 0

This XQuery expression provides the same functionality available to XQuery expressions exposed elsewhere in Design Studio, including access to order data, access to behavior instances, and external configuration.

Modeling Processing States

Order item processing states are a predefined set of states that an order item can enter that derive from a predefined sets of OCOI processing states. Because OSM can process an order item in more than one order component, OSM then aggregates the OCOI values returned from external systems in each order component to determine the overall processing state of the effected order item. You can apply OCOI processing states based on values in response messages from external systems that OSM receives in automated task automation plug-ins or based on direct operator input in manual tasks.

In addition, because order items can be arranged hierarchically, when a child order item processing states changes, OSM also evaluates whether the parent order item should change, and in the same way, if the parent order item is itself the child of another parent order item, OSM evaluates the parent order item when its child order item changes. This process continues up the hierarchy.

The following example shows the Brilliant BroadBand offer and all its descendant order items including their processing states.

Brilliant BroadBand [Add]          InProgressWithFailures
  BroadBand Service [Add]          InProgressWithFailures
     Basic Internet Access [Add]   In Progress
     Internet Media Service [Add]  InProgressWithFailures
       Content on Demand [Add]     InProgressWithFailures <--A1=Failed OCOI
       Video on Demand [Add]       Not Started         
     E-Mail Service [Add]          In Progress
     Internet 100% TBO [Add]       In Progress
     Firewall [Add]                In Progress
  Customer Broadband Model         In Progress
  Wireless Router                  In Progress
  Broadband Installation Fee       In Progress
  Broadband Activation Fee         In Progress

As this order progresses, one of the order components processing the Content on Demand order item receives a response message at automation plug-in instance A1. Based on a value within the response message, the A1 updates the automation task data with a Failed OCOI processing state. This change automatically causes OSM to evaluate all other order components involved in processing the Content on Demand order item and based on this evaluation, assigns the Content on Demand order item with the InProgressWithFailures order item processing state.

For more information about OCOI processing states and how OSM aggregates OCOI processing states, see "Order Component Order Item Processing States".

The change in the processing state of the Content on Demand order item causes OSM to evaluate whether Content on Demand's parent order item, Internet Media Service, also requires an order item processing state change. OSM determines the processing state of the Internet Media Service order item based on its children order items: Content on Demand and Video on Demand. When OSM determines that the Internet Media Service order item also requires an order item processing state change, this causes OSM to further evaluate BroadBand Service and its children (Basic Internet Access, Internet Media Service, E-mail Service, and so on). Likewise, a change in the Broadband Service order item also causes OSM to evaluate Brilliant Broadband based on the processing states of all of its children.

For more information about order item processing states and how OSM aggregates order item processing state changes across an order item hierarchy, see "Order Item Processing States".

Order Component Order Item Processing States

You can apply OCOI processing states from automated or manual tasks that fall into the normal, warning, or failed categories. These categories impact the overall processing state of an order item (see "Order Item Processing States" for more information about these categories).

Table 12-2 shows the OCOI processing states and the categories they are included in.

Table 12-2 OCOI Processing States

OCOI Processing State	Category	Description
NotStarted	Normal	Apply the NotStarted OCOI processing state to order items that have not begun processing in an order component. For example, you could create an automated task in the first order component that OSM runs for an order that updates all order items being processed on an order with the NotStarted OCOI processing state.
InProgress	Normal	Apply the InProgress OCOI processing state when the first task in an order component process begins or when tasks within a process resume normal processing, for example, after resolving a failure in a task.
Completed	Normal	Apply the Completed OCOI processing state to indicate that the final task has completed successfully within the order component process. For example, in an automation plug-in, you can update the Completed OCOI processing state in conjunction with the completeTaskOnExit method that completes the final task of the order component process.
Failed	Failure	Apply the failed OCOI processing state to indicate that a failure has occurred in order processing and fallout intervention is required to correct the error. For example, the Failed OCOI processing state could be used in conjunction with the failTaskOnExit method that transitions the task state to the failed-Do execution mode so that an operator can manually troubleshoot the task. A failed OCOI Processing state causes the Failure count to increase by one.
FailedContinue	Warning	Apply the FailedContinue OCOI processing state to indicate a failure condition that does not require fallout intervention to correct the error. The FailedContinue OCOI Processing state causes the Warning count to increase by one.
Undoing	Normal	Apply the Undoing OCOI processing state the entire OCOI is being undone as a result of a revision order or as a result of a fallout exception that triggers order amendment.
UndoCompleted	Normal	Apply the UndoCompleted OCOI processing state when the OCOI is undone.
UndoFailedContinue	Warning	Apply the UndoFailedContinue OCOI processing state to indicate a failure condition that does not require fallout intervention to correct the error. The FailedContinue OCOI Processing state causes the Warning count to increase by one.
UndoFailed	Failure	Apply the UndoFailed OCOI processing state to indicate that a failure has occurred in order processing while undoing the OCOI and fallout intervention is required to correct the error. For example, the UndoFailed OCOI processing state could be used during compensation in conjunction with the failTaskOnExit method that transitions the task state to the failed-Redo execution mode so that an operator can manually troubleshoot the task. An UndoFailed OCOI Processing state causes the Failure count to increase by one.
DownstreamCorrectionRequired	Warning	The downstream system returns a message to an OSM automated task that the downstream system has experienced a failure and is currently working to resolve the problem. This OCOI processing state remains until another response message returns from the downstream system indicating that the problem has been resolved causing the manual or automated task to update the OCOI processing state to Completed or InProgress.
None	Normal	OSM assigns this state automatically if no OCOI processing state has been assigned. You cannot directly use this processing state.

You must write automation plug-in code to map status response values to order component order item processing states. OSM stores order component order item processing state values in the ControlData element. See "About ControlData for Order Component Order Item Processing States" for more information.

Order Item Processing States

OSM evaluates order item processing states differently depending on order item processing directions. If an order item is being fulfilled by OSM, then the order item is operating in the forward direction. If an order item has been removed, for example, in a revision order or because the order itself has been canceled, then the order item is operating in reverse direction.

Description of order_item_process_states.gif follows

Description of the illustration order_item_process_states.gif

OSM keeps an overall count of the following processing state categories:

Normal: An order item has a normal category order item processing state when all OCOI processing states from order components processing the order item belong to the normal category or when all the descendant order items of a parent order item belong to a normal category. See Table 12-2 for OCOI processing state categories. The normal count increments by 1 when an order item is processing normally.
Warning: An order item has a warning category order item processing state when one or more OCOI processing states from order components processing the order item belong to the warning category or when one or more of the descendant order items of a parent order item belong to a warning category. See Table 12-2 for OCOI processing state categories. The warning count increments by 1 when an order item contains warnings.
Failure: An order item has a Failure category order item processing state when one or more OCOI processing states from order components processing the order item belong to the failure category or when one or more of the descendant order items of a parent order item belong to a failure category. See Table 12-2 for OCOI processing state categories. The warning count increments by 1 when an order item contains failures.

Table 12-3 shows order item processing states, and the direction and categories they are included in.

Table 12-3 Order Item Processing States

Order Item Processing State	Direction	Category	Description
NotStarted	Forward	Normal	The order item has not begun to process in any order component.
InProgress	Forward	Normal	The order item has begun processing in one or more order components.
InProgressWithWarnings	Forward	Warning	The order item has begun processing within one or more order components, however, one or more of the order components or descendant order items have a processing state from the Warning category.
InProgressWithFailures	Forward	Failure	The order item has begun processing within one or more order components, however, one or more of the order components or descendant order items have a processing state from the Failure category.
Completed	Forward	Normal	The order components processing the order item have completed all tasks associated with the order item. All order components processing the order item or all descendant order items or an order item have updated their processing states to Completed.
CompletedWithWarnings	Forward	Warning	The order components processing the order item have completed all tasks associated with the order item; however, one or more of the order components processing the order item or descendant order items have a processing state from the Warning category.
PartiallyFailed	Forward	Failure	All order components processing the order item or descendant order items have returned processing state results, however, one or more have a processing state from the Failure category.
Undoing	Reverse	Normal	The order item has begun processing in the reverse direction in one or more order components.
UndoingWithFailures	Reverse	Failure	The order item has begun processing in the reverse direction within one or more order components, however, one or more of the order components have an OCOI processing state from the Failure category.
UndoingWithWarnings	Reverse	Warning	The order item has begun processing in the reverse direction within one or more order components, however, one or more of the order components have an OCOI processing state from the Warning category.
UndoFailed	Reverse	Failure	One or more order components processing the order item in reverse direction has a failed task that requires fallout intervention to correct.
UndoCompleted	Reverse	Normal	The order components processing the order item in reverse direction have completed all tasks associated with the order item.
UndoCompleteWithWarnings	Reverse	Warning	The order components processing the order item in the reverse direction have completed all tasks associated with the order item; however, one or more of the order components processing the order item or descendant order items have a processing state from the Warning category.
None	Reverse	Normal	OSM assigns this state automatically if no OCOI processing state has been assigned. You cannot directly use this processing state.

OSM stores order item processing state values in the ControlData element. See "About ControlData for Order Item Processing States" for more information.