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

4 Understanding Orchestration

This chapter describes Oracle Communications Order and Service Management (OSM) orchestration.

Before you read this chapter, read "Order and Service Management Overview" for information about basic OSM concepts.

Overview of Orchestration

A single customer order typically includes multiple order line items that request multiple products and fulfillment actions. To process the order, some order line items need to be fulfilled before others; for example, you cannot configure a call-waiting service until the base telco service is provisioned. There are also multiple external systems that OSM must interact with. OSM uses orchestration to handle all of the fulfillment actions efficiently, taking into consideration all of the dependencies between the actions.

To manage orchestration, OSM creates a unique orchestration plan for each customer order. The orchestration plan specifies the fulfillment functions required to fulfill the order, manages the sequence of those functions, and manages dependencies between them.

To create the orchestration plan, OSM reads the requirements defined in each order line item of the customer order and identifies the processes and tasks to fulfill them. For example:

The orchestration plan includes:

There are more entities in an orchestration plan than order items and order components; such as orchestration sequences and orchestration stages, but the main purpose of the orchestration plan is to manage how order items are fulfilled.

You can view order components and their order items in the Order Management Web client. Figure 4-1 shows a list of order components and their order items:

Figure 4-1 Order Component Hierarchy

Shows a list of order components and their order items

An orchestration plan is generated for each order, based on the contents of the order. The orchestration plan for an order specifies the following:

In the following example, an orchestration plan is created to fulfill the following order items:

Billing has the following requirements:

The following example shows how order components and order items are decomposed to fulfill different services in different regions.

  1. OSM first reads the incoming customer order and creates order items from the order line items contained in the order. Figure 4-2 shows that order line items for two fixed services and handsets are derived from the order. There are different regions defined for each service and handset (Ontario and Quebec).

    Figure 4-2 Order Line Items and Order Items

    Graphic is described in surrounding text.
  2. OSM begins the orchestration process. The first step is to assign the order items to order components that are based on fulfillment functions. Figure 4-3 shows that the order items are organized into three function order components: Provisioning, Shipping, and Billing. The fixed-line services require provisioning, the handsets require shipping, and all order items require billing, so they are all included in the Billing order component.

    Figure 4-3 Function Order Components

    Graphic is described in surrounding text.
  3. The Billing order component must be decomposed further. Figure 4-4 shows two levels of decomposition:

    • Order items for the Ontario and Quebec regions are decomposed into target system order components. This sends the billing fulfillment process to the correct region, Ontario or Quebec.

    • For each region, the fixed-line service must be billed separately from the handset.

    Figure 4-4 Function Order Component Decomposed to Target and Granularity Order Components

    Graphic is described in surrounding text.

The order components specify how the order items are processed by the orchestration plan. They also specify how the order items are displayed in the Order Management Web client. In this example, an order manager can monitor the status of the different billing components to track the order item progress.

In Figure 4-4, the order components serve two primary functions:

Not all order components run OSM processes. Those order components are used only for decomposition. In the example above, order components in the first and second stages of orchestration play that role. The order components that run OSM processes are called executable order components. The final stage of decomposition creates those order components.

To model how orchestration plans are generated, you model several OSM entities in Oracle Communications Design Studio.

Figure 4-5 shows a generalized process flow for orchestration.

Figure 4-5 Orchestration Process

Graphic is described in surrounding text.

The following process flow shows how OSM uses the orchestration entities to create orchestration plans.

  1. After receiving and validating an incoming customer order, OSM creates the order according to the order specification chosen by the recognition rule. At this point, the following has been accomplished:

    • The order has been populated with the creation task data.

    • OSM has used the order item specification to identify order items from the order line items in the incoming customer order.

  2. The order specification includes a default process. For an orchestration order, the order specifies an orchestration process. (If no orchestration is required, the order runs an OSM process. See "About Tasks and Processes" for more information.) Figure 4-6 shows how an orchestration process is assigned to an order in Design Studio.

    Figure 4-6 Order Specifies the Orchestration Process

    Shows an orchestration process assigned to an order.
  3. The orchestration process specifies an orchestration sequence. Figure 4-7 shows how an orchestration sequence is specified in the orchestration process in Design Studio.

    Figure 4-7 Orchestration Process Specifies the Orchestration Sequence

    Graphic is described in surrounding text.
  4. The orchestration sequence specifies the following:

    • The order item specification to use for the order. The order item specification defines the order item properties that are used for decomposition and for displaying the order item in the Order Management Web client. See "About Order Items" for more information.

    • The order item selector that identifies the customer order line item node-sets to use as order items. See "About Creating Order Items from Customer Order Line Item Node-Sets" for more information.

    • The fulfillment mode that the order requires; for example, Deliver or Cancel. See "About Modeling Fulfillment Modes" for more information.

    • The orchestration stages that produce the order components. For example, the orchestration stages might be:

      • Produce function order components. This stage organizes order items into order components based on the fulfillment functions required for each order item. Fulfillment functions are the activities that must be performed to process the item, such as billing, shipping, provisioning, and so on.

      • Produce target system order components. This stage organizes order items into order components based on the target fulfillment systems required to perform the fulfillment functions. For example, this step might determine that certain items need to be fulfilled by a billing system called BRM_Residential and others by a BRM_Wholesale system.

      • Produce granularity order components. This stage organizes order items that need to be processed together into order components. For example, you might need to fulfill billing requirements for mobile and fixed services. You can use different order components to process the billing requirements for those services separately.

    Figure 4-8 shows how to define orchestration stages in Design Studio.

    Figure 4-8 Orchestration Sequence Specifies the Orchestration Stages

    Shows how to define orchestration stages in Design Studio
  5. Each orchestration stage produces a set of order components. Figure 4-9 shows how an orchestration stage specifies order components.

    Figure 4-9 Orchestration Stage Produces Order Components

    Shows how an orchestration stage specifies order components
  6. Based on the default orchestration process, and the orchestration sequence and stages that are defined, OSM can start the process of assigning order items to order components. The first step is to find the product specification used by each order item.

    Each order item belongs to a product class. A product class is a group of related products that share common attributes. For example, the products Broadband Light, Broadband Medium, and Broadband Ultimate would all belong to the ServiceBroadBand product class. OSM maps the product class to a product specification.

    The product specification manages the first stage of orchestration. It assigns order items to function order components in the first stage of orchestration. It also specifies the dependencies between the function order components. For example, the product specification might specify to process function order components in this order:

    1. ProvisioningFunction

    2. BillingFunction

    3. CollectionsFunction

    The product specification also specifies the fulfillment mode that the order items can be used for. See "About Mapping Order Items to Product Specifications" for more information.

    Figure 4-10 shows function order components defined in a product specification.

    Figure 4-10 Order Components Defined in Product Specification

    Shows order components defined in product specification

    Figure 4-11 shows order component dependencies defined in a product specification.

    Figure 4-11 Order Component Dependencies Defined in a Product Specification

    Graphic is described in surrounding text.

    Figure 4-12 shows the order component dependencies shown in Figure 4-11. Provisioning must occur before billing, which must occur before marketing, customer updates (SyncCustomer), and collections.

    Figure 4-12 Dependency Relationships for Order Item Dependency

    Graphic is described in surrounding text.
  7. After assigning order items to function components, OSM further decomposes the order into target system order components and granularity order components, following the specifications defined in the orchestration stages. See "About the Decomposition of Function to Target System Components" and "About the Decomposition of Target System to Granularity Components" for more information.

  8. While decomposing the order, OSM finds dependencies between order components and generates an orchestration plan. Dependencies determine the order in which order components can be processed. See "About Decomposition" for more information.

  9. After generating the orchestration plan, OSM runs it. Each executable order component runs a process. Each process includes the tasks that fulfill the order requirements.

About Orchestration Plans

An orchestration plan includes the order items, order components, and dependencies. An order-specific orchestration plan is generated for each order that requires orchestration.

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.

The orchestration plan for an order specifies the following:

  • How order items are grouped into order components for processing

  • The dependencies between the order components

In the OSM Order Management Web client, you can view graphical representations of an order's orchestration plan and dependencies. You can use this information as you model orders to validate that order decomposition and orchestration plan generation is functioning as intended. The graphical representation shows exactly how an order is fulfilled.

The Order Management Web client provides a graphical representation of the orchestration plan in two views:

  • Orchestration plan decomposition

  • Orchestration plan order item dependencies

Figure 4-13 shows three orchestration stages, represented in three columns:

  • Determine the fulfillment function

  • Determine the fulfillment system

  • Determine the processing granularity

Note:

You can model any number of orchestration stages.

At each orchestration stage, the graph shows the order components created by that stage. The final column on the right shows the order components that are run as part of the orchestration plan. Each component includes a name, which is based on the orchestration stages. Components also list their included order items.

The inset in Figure 4-13 shows details for three executable order components, as displayed in the orchestration plan decomposition.

Figure 4-13 Decomposition Tree

Shows details for three executable order components

Figure 4-14 shows the orchestration plan displayed in the Order Management Web client dependency graph. The dependency graph shows the executable order components which are the components shown in the final stage of the decomposition display. In this case, executable components are based on three orchestration stages corresponding to fulfillment function, fulfillment system, and processing granularity. The different colors represent fulfillment functions, such as InitiateBilling or FulfillBilling. The inset shows a detailed view of two order components. Even though the two fulfillment functions are targeted to the same system (BRM-VOIP), processing granularity rules defined for this order require that they take place as two separate actions.

Figure 4-14 Dependency Graph

Graphic is described in surrounding text.

Both of these representations are useful at design time and when debugging orchestration plans. For example, you can use the dependency graph to confirm that an order goes to all of the correct systems in the correct order. Use the decomposition tree to verify that decomposition happens as expected at a particular stage and that the order was decomposed into the correct components, each containing the correct order items.

About Order Items

Order items are individual products, services, and offers that need to be fulfilled as part of an order. Each item includes the action required to implement it: Add, Suspend, Delete, and so on. For example, a new order might add a wireless router; the order item created in OSM is Add Wireless Router.

When you model order items, you do not model every possible order item. Instead, you create an order item specification, which defines:

There must be one order item specification for each type of order received from the order-source system. When you model an order item specification, you can configure the following:

About Creating Order Items from Customer Order Line Item Node-Sets

To create order items from customer order line items, OSM needs to know what nodes in the incoming customer order include the data to use in order items. OSM creates orchestration control data from these nodes (see "About Order Item Control Data").

Example 4-1 shows the <salesOrderLine> node-set in an incoming customer order. You can specify these node-sets as order items by creating an XQuery in the Design Studio Sequence editor that returns every instance of <salesOrderLine> contained in the customer order (see "About Order Item Specification Order Item Property XQuery Expressions"). These node-sets produce the Broadband Bundle and the Mobile Bundle order items. The elements in these node-sets can then be specified as order item properties in the order item specification.

Example 4-1 The <salesOrderLine> element in an Incoming Customer Order

<im:salesOrderLine>
     <im:lineId>13</im:lineId>
     <im:promotionalSalesOrderLineReference>1
     </im:promotionalSalesOrderLineReference>
     <im:serviceId></im:serviceId>
     <im:requestedDeliveryDate>2001-12-31T12:00:00</im:requestedDeliveryDate>
     <im:serviceActionCode>Add</im:serviceActionCode>
     <im:itemReference>
          <im:name>Broadband Bundle</im:name>
          <im:typeCode>BUNDLE</im:typeCode>
          <im:specificationGroup></im:specificationGroup>
     </im:itemReference>
</im:salesOrderLine>
<im:salesOrderLine>
     <im:lineId>14</im:lineId>
     <im:promotionalSalesOrderLineReference>2
     </im:promotionalSalesOrderLineReference>
     <im:serviceId></im:serviceId>
     <im:requestedDeliveryDate>2001-12-31T12:00:00</im:requestedDeliveryDate>
     <im:serviceActionCode>Add</im:serviceActionCode>
     <im:itemReference>
          <im:name>Mobile Bundle</im:name>
          <im:typeCode>BUNDLE</im:typeCode>
          <im:specificationGroup></im:specificationGroup>
     </im:itemReference>
</im:salesOrderLine>

About Order Item Properties

Prior to generating an orchestration plan, OSM processes each customer order line item in the incoming customer order and turns it into an order item. The order item properties define the data that is included from these order items using XQuery expressions.

Figure 4-15 shows order item properties defined in Design Studio.

Figure 4-15 Order Item Properties in Design Studio

Shows order item properties defined in Design Studio

Figure 4-16 shows the order item created from the order item properties shown in Figure 4-15.

Figure 4-16 Order Item Displayed in the Order Management Web Client

Shows order item created from order item properties

Most order items properties must be created in Design Studio and associated to corresponding customer order element values using XQuery expressions (see "About Order Item Specification Order Item Property XQuery Expressions"). However, in some cases the order item property is not provided in the customer order. In this case, you must use an XQuery expression to derive the missing property value from the existing customer order element values (see "About Order Item Specification Order Item Property XQuery Expressions").

Example 4-2 shows an order line item. This order line item adds a Commercial Fixed Service order item. In the following example, notice that the items in bold correspond to the order item properties. However, there are order item properties, such as productSpec and region, that are not in the order line item. Instead, you specify to create those order item properties by using XQuery expressions in the order item specification.

Example 4-2 Order Line Item in an Incoming Customer Order

<im:salesOrderLine>
  <im:lineId>4</im:lineId>
  <im:parentLineReference>
    <im:parentLineId>3</im:parentLineId>
    <im:hierarchyName>default</im:hierarchyName>
  </im:parentLineReference>
  <im:rootParentLineId>2</im:rootParentLineId>
  <im:promotionalSalesOrderLineReference>1
</im:promotionalSalesOrderLineReference>
  <im:serviceId>552131313131</im:serviceId>
  <im:requestedDeliveryDate>2001-12-31T12:00:00</im:requestedDeliveryDate>
  <im:serviceActionCode>Add</im:serviceActionCode>
  <im:serviceAddress>
    <im:locationType>Street</im:locationType>
    <im:nameLocation>OLoughlin</im:nameLocation>
    <im:number>48</im:number>
    <im:city>Toronto</im:city>
  </im:serviceAddress>
  <im:itemReference>
    <im:name>Commercial Fixed Service</im:name>
    <im:typeCode>PRODUCT</im:typeCode>
    <im:primaryClassificationCode>Fixed Service Plan Class</im:primaryClassificationCode>
  </im:itemReference>
</im:salesOrderLine>

Figure 4-17 shows all of the order items derived from an order, including the order item shown in Example 4-2.

Figure 4-17 All Order Items in an Order

Shows all the order items derived from an order

In Figure 4-17, notice that order items are hierarchical. For example, the Fixed Service order item shown in Example 4-2 is part of the Fixed Bundle order item. In addition, the Fixed Service order item includes three more order items: Commercial Fixed Service, Fixed Caller ID, and Fixed Call Waiting. When you model orchestration, you ensure that the hierarchy in the incoming customer order is duplicated in the OSM order items. See "About Order Item Hierarchy" for more information.

The order item specification defines the order item properties that are required for generating the orchestration plan and the data to display in the Order Management Web client. This typically includes the display name, product class, line ID, requested delivery date, and so on. By contrast, the order item usually would not include supplementary account and customer details such as the street address or mailbox size. That type of data is defined in the task data for each task in the fulfillment data, and in the creation task data when the order is created.

Important:

Order item properties do not represent all of the data in an order. For example, they do not define creation task data. That data is captured by transformation rules. Order item properties are a subset of the data and are used for orchestration.

Figure 4-18 shows part of an order input file and how the city field is mapped to the region order item property in Design Studio. In this example, the <city> element in the XML file is used in the order item property expression.

See "About the Decomposition of Function to Target System Components" for an example of how the region order item property is used in orchestration.

Figure 4-18 Order Line and Definition in Order Item Specification

Graphic is described in surrounding text.

A single order item specification is used for generating all of the order items that can be created for an order. This ensures a consistent order item structure. Therefore:

  • Order item properties should not be product or service specific. The only product information you need to include is the product class, which is a generic value used for identifying the product specification. By not applying order items to a specific product, you can use the order item specifications for multiple products, and you can support new products and services and multiple order entry systems.

  • Order item properties should not be specific to any order entry system.

Important:

When defining order item properties, include only the data required by OSM for orchestration. Performance is impacted by the number and size of order item properties.

Figure 4-19 shows the data on an incoming customer order and the subset of data that is used for order items.

Figure 4-19 Selecting Order Item Properties from Input Data

Graphic is described in surrounding text.

The properties you define for your order items will be different from those pictured in Figure 4-19. However, this selection provides a good example of the type of order properties that are commonly configured:

  • productClass: This property retrieves the product class from the incoming customer order. OSM maps each order item to a product specification based on the item's product class (defined in the order-source system). The product specification specifies the order components in the first level of decomposition.

  • productSpec: This property stores the product specification that the order item uses. This value is obtained by mapping the productClass value in a mapping file. See "About Mapping Order Items to Product Specifications" for more information.

  • lineId: This is the line ID of the order line item in the incoming customer order. Each order line item in the incoming customer order has a unique line ID. This property is used for determining the hierarchy of the order items. See "About the Decomposition of Target System to Granularity Components" for an example of how this property is used.

  • lineItemName: This property is the display name used in OSM Web clients.

  • requestedDeliveryDate: This property is the requested completion date for the order item.

  • parentLineId: This property defines the parent of the order line item in the incoming customer order. This property is used for determining the hierarchy of the order items. See "About the Decomposition of Target System to Granularity Components" for an example of how this property is used.

  • region: This property is an example of data that can be used to manage decomposition into target system order components. See "About the Decomposition of Function to Target System Components" for more information.

  • serviceId: This property is used to display the service ID in the OSM Web clients.

  • lineItemPayload: This property stores the entire incoming customer order in OSM as an XML file. This property is typically used in a development environment as an aid to modeling.

About Order Item Hierarchy

Order items can be organized hierarchically based on the content of the original customer order. The hierarchy can include various types of order line items, such as offers, products, and bundles of products or services. For example, an order could include a Broadband-VoIP offer with a High Speed Internet bundle, an Internet Services service bundle, and a Wireless Router product item. OSM maintains the order line item hierarchy from the customer order in the order item hierarchy. Maintaining this hierarchy allows OSM to aggregate order item status from a hierarchy of order items.

Figure 4-20 shows an item hierarchy that reflects the structure of the original customer order.

Figure 4-20 Item Hierarchy

Shows an item hierarchy

The hierarchy is defined in the <lineID> and <parentLineId> elements. Figure 4-21 shows the first part of Figure 4-20, as it appears in an incoming customer order.

Figure 4-21 Item Hierarchies In an Incoming Customer Order

Shows item hierarchies in an incoming customer order

To define the order item properties that specify the hierarchy, you configure the order item hierarchy in the order item specification using an XQuery expression. See "About Order Item Specification Order Item Hierarchy XQuery Expressions" for more information.

About Mapping Order Items to Product Specifications

The first orchestration stage assigns order items to function order components, by using product specifications. You need to model how to map order items to product specifications and implement the model using an XQuery expression (see "About Mapping Product Class and Product Specification XQuery Expressions" for more information about using XQuery to map product class to product specifications).

About Modeling Product Classes

You can create product classes by importing them or by creating them manually in Design Studio.

When you model a product class, you can specify:

  • The product class that it is extended from.

  • Start and end dates. Dates can be useful when you change product offerings often, and you need to change product classes.

  • Attributes that provide structure and content to the product class definition. For example, attributes for a Mobile service product class might be the IMSI and the telephone number.

Figure 4-22 shows a product class in Design Studio.

Figure 4-22 Product Class in Design Studio

Shows a product class in Design Studio

Product classes are typically created in a master product catalog in a CRM or other order-source system. You can import product classes from the Siebel product catalog into Design Studio. This is accomplished by using an Enterprise Business Service (EBS). The EBS supports a query interface that enables modelers to specify a Siebel product class ID and retrieve its definition. Design Studio converts the product class definition into a product specification.

You can map multiple product classes to one product specification. This enables you to introduce new products in existing product classes without needing to create new product specifications or fulfillment flows.

When new products are added to the master product catalog, the corresponding product class must be imported into Design Studio and mapped to a product specification.

About Order Item Control Data

In addition to defining order item properties in the order item specification, you need to provide a storage area for the order item properties. You do so by adding control data to the order item specification Order Template tab. This definition is automatically added to the order's order template. This makes it easier to track which entity is the master of the data and enables easier refactoring and maintenance of the overall order specification. Figure 4-23 shows the order item properties in the control data in an order template.

Figure 4-23 Order Item Properties Included in the Order Template

Shows the control data in an order template

When you define the control data, note the following:

  • The name used in the control data must exactly match the spelling and case of the order item property name.

  • Make sure that the Data Dictionary properties are correct for the type of data; for example, string or number.

  • Configure each data element as a multi-instance data element.

    • Minimum = 0

    • Maximum = Unbounded

    Note:

    To define data properties, you edit the entry in the data schema, not in the order item specification.

    An instance of ControlData/OrderItem is created for each data element returned by the order item selector from the orchestration sequence (see "About Creating Order Items from Customer Order Line Item Node-Sets").

The OracleComms_OSM_CommonDataDictionary model project contains predefined base data elements for control data. Oracle recommends that you use the data schema of this model project to add the ControlData/OrderItem structure to the order item specification Order Template tab.

About Decomposition

Decomposition is the process of organizing order components into increasingly granular order components.

There are typically three stages of decomposition, which decompose order items into these types of order components:

Figure 4-24 shows a simplified decomposition process. In this example, the order includes two order items, adding a mobile service and adding a fixed service. The decomposition proceeds as follows:

  1. In the first stage of decomposition, the order items are assigned to function order components. There are two function order components: provisioning and billing. Both of the order items require provisioning and billing, so they are both included in the provisioning and billing function order components.

    Order items are assigned to function order components by using a product specification. See "About Mapping Order Items to Product Specifications" for more information.

  2. In the next stage of decomposition, the order items are assigned to target system function components. The mobile and fixed services require different provisioning systems, so there are two separate target system components for provisioning. Both order items, however, can be processed by the same billing system, so they are both included in the same billing target system order component. See "About the Decomposition of Function to Target System Components" for more information.

  3. In the final stage of decomposition, no further decomposition is required for provisioning; the order items are processed by their target systems. For billing, however, the mobile service billing and the fixed service billing need to be processed separately. In this stage of decomposition, therefore, the orchestration plan generates two bundle granularity order components: one for the mobile service billing and one for the fixed service billing. See "About the Decomposition of Target System to Granularity Components" for more information.

Figure 4-24 Order Items Decomposed into Order Components

Graphic is described in surrounding text.

Order items are often included in more than one order component. This is because order item fulfillment often requires multiple functions. For example, the top-level order item Create Mobile Service would be included in any order component that included the child order items belonging to Create Mobile Service.

Order components are usually modeled by extending order component specifications in Design Studio. For example, you can create a base order component for all function types and extend it for individual function types such as billing or collections. Figure 4-25 shows the Function order component as the base component, with extended components for specific functions.

Figure 4-25 Extending Order Component Specifications

Description of Figure 4-25 follows
Description of "Figure 4-25 Extending Order Component Specifications"

About Component IDs and Component Keys

Each order component has a component ID and a component key. The component ID is specified at design time. The component key is generated for each instance of the order component at run time. You can use customized order keys when assigning order items to order components.

By default, the component ID is the name of the component; for example, Billing Function or Billing System. The component key is a concatenation of the names of the components in the orchestration stages. For example, if the component IDs are modeled as:

  • Billing Function

  • Billing System

  • Bundle

The order keys generated at run time are:

  • BillingFunction

  • BillingFunction.BillingSystem

  • BillingFunction.BillingSystem.Bundle

You can customize how order keys are generated. See "About the Decomposition of Target System to Granularity Components" for an example of how to use customized order keys to generate granularity components. Figure 4-26 shows order component keys displayed in the Order Management Web client, in the Orchestration Plan page's Dependencies tab.

Figure 4-26 Order Component Keys Displayed in the Order Management Web Client

Shows order component keys

About the Decomposition of Order Items to Function Order Components

The following sections describe the decomposition of order items to function order components.

About Assigning Order Items to Product Specification Function Components

The first step in decomposition is to assign order items to function components. To do so, OSM uses the product class to find the product specification that the order item uses. (See "About Mapping Order Items to Product Specifications" for more information.) The product specification defines the order components to add the order item to.

Figure 4-27 shows the function order components selected in the Service.Broadband product specification. In this case, order items that use this product specification need all of the functions; billing, collections, provisioning, and so on.

Figure 4-27 Function Order Components Selected for a Service Product Specification

Shows function order components

Figure 4-28 shows the function order components selected for a non-service product specification. In this case, the order items do not need provisioning, so the provisioning function is not selected.

Figure 4-28 Function Order Components Selected for a Non-Service Product Specification

Shows function order components

Figure 4-29 shows how to use a base specification to define the same function order components as described above. In this case, the base product specification selects all of the function order components except provisioning. The service and non-service product specifications inherit the selections. The service product specification adds the provisioning function. The non-service product specification does not add it.

Figure 4-29 How to Use a Base Specification to Define Function Components

Graphic is described in surrounding text.

About the Function Components Stage

In addition to using the product specification to assign order items to function components, you model an orchestration stage, which specifies to create the function order components to create. Figure 4-30 shows the function order components created at the DetermineFulfillmentFunction orchestration stage.

Figure 4-30 Orchestration Stage that Produces Function Order Components

Shows the function order components

About Order Component Control Data

When OSM creates the order items and order components, it produces a set of control data. The control data provides information OSM requires to fulfill the order. OSM uses the control data to track the status of the entire order and to track the status of the individual order items. During fulfillment, order component transactions update this control data with system interaction responses.

Design Studio automatically generates control data for function order components provided that orchestration entities are preconfigured correctly and you use the OracleComms_OSM_CommonDataDictionary model project. If you do not use the OracleComms_OSM_CommonDataDictionary model project, you must manually model order component control data. See the Design Studio Help for information on how order component control data is automatically generated or how to manually model it.

See "About Order Template Control Data" for more information on adding function order components to the order control data.

About Product Specification Conditions for Including Order Items

You can use conditions to add order items to an order component only when the XQuery for the condition evaluates to true. For example, you might include an order item based on an XQuery that checks the action code (Add or None). This is useful in the case of an update to a service that changes some features while leaving other features unchanged. See "About Order Item Specification Condition XQuery Expressions" for more information.

Summary of Order Item to Function Components Decomposition

To summarize this example, to model the decomposition from a order items to a function component, you model the following:

  • The product specification order item property so that order items can be mapped to product specification function components.

  • Any XQuery expressions that evaluate conditions to include or exclude order items.

  • The Order control data for orchestration.

  • The orchestration stage that produces the function components

About the Decomposition of Function to Target System Components

The following sections describe the decomposition of order items from functional components to target systems.

About Decomposition Rules from Function Components to Target Systems

After the order items have been assigned to function order components, they need to be further decomposed into target system order components. To do so, you use decomposition rules.

A decomposition rule specifies a source order component and a target order component. Figure 4-31 shows a decomposition rule from the billing function component to the billing target system component.

Figure 4-31 Decomposition Rule

Graphic is described in surrounding text.

About Decomposition Rule Conditions for Choosing a Target System

You can use decomposition rules to decompose order items from one function component to multiple target system components. Figure 4-32 shows the source and target order components for two decomposition rules:

  • Provision to DSL Provisioning System - Region1

  • Provision to DSL Provisioning System - Region2

These two decomposition rules decompose the order items in the ProvisioningFunction order component into two target system order components based on Region 1 and Region 2.

Figure 4-32 Source and Target Order Components for Two Decomposition Rules

Graphic is described in surrounding text.

Each of the decomposition rules uses decomposition conditions to specify which target system to use for a particular order. The target system is selected if the XQuery expression associated with the condition evaluate to true. In this example, the XQuery expression uses the value of the region order item property to make this evaluation. If the value of region is Toronto, then OSM selects the condition and target system for Region 1. If the value of region is New York, then OSM selects the condition and target system for Region 2. See "About Order Item Specification Condition XQuery Expressions" for more information about creating an XQuery condition expression that can be used for with a decomposition rule.

About the Target Systems Stage

In addition to creating the decomposition rules that define the source and target components, you need to create an orchestration stage that produces the target system order components. Figure 4-33 shows the target system order components produced by the DetermineTargetSystem orchestration stage.

Figure 4-33 Orchestration Stage that Produces Target System Order Components

Graphic is described in surrounding text.

Summary of Configuring Target System Components Decomposition

To summarize, to configure how order items are decomposed from a function order component to a target system order component, you do the following:

  • Define an orchestration stage to produce the target system order components.

  • Create dependency rules to specify the source order components and target order components.

  • If a function order component decomposes order items to more than one target system order component, create decomposition conditions. Decomposition conditions depend on data specific to the order items, so decomposition rules typically use XQuery expressions to retrieve the data that is used for evaluating the condition.

About the Decomposition of Target System to Granularity Components

The following sections describe the decomposition of order items from target system components to granularity components.

About Decomposition Rules from Target System to Granularity Components

After order items have been decomposed into target system order components, the next step is to decompose them into the granularity order components.

Some examples of the granularity requirements are:

  • A billing system might require the entire order in the message to calculate discounts.

  • A billing system might require separate bundles for mobile billing and fixed billing, to handle different completion times (fixed billing typically has more dependencies and takes longer).

The following example shows how to decompose target system order components items into bundle granularity components. You configure the following:

  • Create a decomposition rule, which decomposes the target system order component into bundle granularity components. Figure 4-34 shows a decomposition rule that decomposes order items from the billing function to the bundle granularity order components.

    Figure 4-34 Decomposition Rule: Billing Function to Bundle

    Graphic is described in surrounding text.
  • Create customized component IDs that are used to create separate order components for each bundle. (See "About Customized Component IDs to Separate Bundled Components" for information.)

About Customized Component IDs to Separate Bundled Components

You create the customized order component by editing the bundle order component specification. Figure 4-35 shows an order component with a customized component ID.

Figure 4-35 Customized Component ID

Graphic is described in surrounding text.

In this example, you need to configure a decomposition rule and a bundle granularity order component specification to make sure that order items for a fixed service and a broadband service are decomposed into separate bundle granularity components, based on their customized component IDs. The customized component IDs result in separate instances of bundle order components, with separate component keys. This allows OSM to process the order components for the fixed service and the broadband service separately.

If you had not created customized component IDs, the component key of both order items would be BillingFunction.BillingSystem.Bundle. The order items would be processed together in the same order component.

This customization also ensures that the component ID is the same for order items within the same granularity (for example, a bundle) but not for order items at a higher granularity.

In addition, you may want to group order items into custom component IDs based on order item requested delivery date. For example, you might want an order component to process all order items with a requested delivery date that falls within the first two days of when an order start, and another order component for the next two days. You can further combine these grouping by requested delivery date within order item hierarchy groupings.

See "About Component Specification Custom Component IDs XQuery Expressions" for more information about configuring custom order component hierarchies using XQuery.

About the Granularity Components Stage

In addition to creating the decomposition rules that define the source and target components, you need to create an orchestration stage that produces the granularity order components.

Summary of Configuring Granularity Components Decomposition

To summarize this example, to model the decomposition from a target system order component to a bundle order component, you model the following:

  • The decomposition rule, which decomposes the target system order component into bundle granularity components

  • The orchestration stage that produces the bundle order component

  • The order item hierarchy that the XQuery ancestors function uses in the order item specification

  • The XQuery for the customized order component in the bundle order component specification

About Associated Order Items

Sometimes, you need to assign order items to order components that would not be assigned by their product specification. This is often the case when an interaction with an external system requires a specific context for an order item.

For example, a billing system might need to process billing-related order items in the context of a bundle, to manage the relationships between balances, discounts, and so on. Billing charges are often order line items, such as an installation service, that are included in the order outside of the service billing bundle hierarchy. However, they might need to be associated with the billing bundle to ensure that the charge is made against the correct service. In that case, you can associate the billing charges with a bundle order component.

By contrast, billing order items might be sent to the billing system in the context of a whole order. In that case, you do not need to associate the order items to a bundle, because they are already in context.

Figure 4-36 shows the associated order items, displayed with (assoc) in the orchestration plan.

Figure 4-36 Associated Order Items Displayed in the Order Management Web Client

Shows the associated order items

Important:

Associated order items are not considered as part of the decomposition and dependency calculations when OSM generates an orchestration plan. Therefore, you cannot reference associated order items in decomposition or dependency rules.

You model order item associations in product specifications. Figure 4-37 shows an order item association modeled for the Bundle order component in the Service.Mobile product specification.

Figure 4-37 Order Item Associations in a Product Specification

Graphic is described in surrounding text.

There are two ways to associate order items:

About Modeling Fulfillment Modes

The fulfillment mode is the overall purpose of the order. For example:

  • Deliver a service.

  • Qualify a service before delivering it. This ensures that a service can be fulfilled before attempting to fulfill it.

  • Cancel an entire order.

Every incoming customer order can specify a fulfillment mode.

OSM can use the fulfillment mode as part of the orchestration process. For example, if OSM receives two identical incoming customer orders with different fulfillment mode order item properties, it generates a different orchestration plan for each order. The two plans include different executable order components with different dependencies among order items.

Fulfillment modes are configured in the following places:

  • Fulfillment mode entities: These entities include no data other than a name. They provide the means to assign fulfillment modes to other entities, such as orchestration sequences and product specifications. Figure 4-38 shows a fulfillment mode specification.

    Figure 4-38 Fulfillment Mode in Design Studio

    Shows a fulfillment mode specification
  • Orchestration sequences define a single fulfillment mode using an XQuery expression based on a customer order attribute (see "About Order Sequence Fulfillment Mode XQuery Expressions").

  • Product specifications list the fulfillment modes that the associated order items can be used with.

    Figure 4-39 shows the fulfillment modes defined in a product specification. Any order item that uses this product specification can be processed in either the Cancel or Deliver fulfillment mode.

Figure 4-39 Fulfillment Modes Defined in a Product Specification

Graphic is described in surrounding text.

When a product specification includes multiple fulfillment modes, you can model a different set of order components and dependencies for each fulfillment mode. Figure 4-40 shows the order components selected in a product specification when the fulfillment mode is Deliver. Figure 4-41 shows the same product specification, with different order components selected because the fulfillment mode is Cancel.

Figure 4-40 Product Specification with Fulfillment Mode of Deliver

Graphic is described in surrounding text.

Figure 4-41 Product Specification with Fulfillment Mode of Cancel

Graphic is described in surrounding text.

About Dependencies

An orchestration plan is based on two main factors: decomposition, which derives the order components, and dependencies, which dictate when the order components are allowed to run.

Dependencies are relationships in which a condition related to one order item must be satisfied before another item can be processed successfully. For example, a piece of equipment must be shipped to a location before the action to install it at that location can be taken.

You can model the following types of dependencies:

You typically create dependencies between order items in the same order (intra-order dependencies). However, you can also create dependencies between order items in different orders (inter-order dependencies). For example, the order items in a follow-on order for VoIP provisioning might depend on the execution of the order items in the original order for DSL provisioning. See "About Inter-Order Dependencies" for more information.

A dependency requires two order components: the waiting order item and the blocking order item. The blocking order item is the order item that must complete before the waiting order item is started.

Dependencies can be based on several different factors, including:

Order items can have combinations of dependencies. For example, an order item for an installation can depend on a combination of a completion status dependency (item successfully shipped) and date dependency (wait two days after shipment to schedule installation).

Note:

You can manage dependencies during amendment processing; for example, when you submit a revision order. See "About Compensation and Orchestration" for more information.

Although dependencies exist logically between order items, they are managed by order components. In other words, if any item in a component has a dependency, the component as a whole cannot be started until the dependency is resolved. In the Order Management Web client, order items include dependency IDs to indicate items whose dependencies are managed together. See Order Management Web Client User's Guide for more information.

You can model dependencies in two ways in Design Studio:

Figure 4-42 shows order items displayed in the Order Management Web client. In this example, the billing order items for a fixed service can start immediately because they have no dependencies. The billing order items for high-speed Internet must wait until the provisioning order items have completed.

Figure 4-42 Dependencies Displayed in the Order Management Web Client

Graphic is described in surrounding text.

About Intra-Order Dependencies

The following sections describe dependencies that can be created within the same order.

Modeling an Order Item Dependency

The simplest form of dependency is an order item dependency, configured in a product specification. This type of dependency is based on function order components; for example, the billing order component cannot start until the provisioning function has completed. Figure 4-43 shows an order item dependency in Design Studio.

Figure 4-43 Order Item Dependency in Design Studio

Shows an order item dependency in Design Studio

Figure 4-44 shows the dependency relationships shown in Figure 4-43. Note the two layers of dependency: billing is dependent on provisioning, and everything else is dependent on billing.

Figure 4-44 Dependency Relationships for Order Item Dependency

Shows dependency relationships.

In addition to defining the function order components, you need to define the conditions that govern the dependency. The default condition is to wait until the final task associated with the order item has completed. Figure 4-45 shows a wait condition defined in Design Studio. In this case, the waiting order item must wait until the blocking order item task has reached the Completed state. See "About Order Item Dependency Wait Conditions" for more information.

Figure 4-45 Wait Condition in Design Studio

Shows a wait condition defined in Design Studio

About Order Item Dependency Wait Conditions

Dependency wait conditions specify the condition that the blocking order item must be in before the waiting order item can start. For example, the default wait condition is to start the waiting order item when the last task associated with the blocking order item reaches the Completed state.

You specify wait conditions in product specifications and orchestration dependencies. You can set different wait conditions for each dependency. The wait conditions can be:

  • The task state of the final task associated with the blocking order item

  • A change in the data for a specified field. See "About Order Item Dependency Wait Conditions Based on Data Changes" for more information.

  • A specified duration after the task state or data change condition has been met. You can specify a value in months, weeks, days, hours, or minutes, or you can specify an XQuery expression to determine the delay (see "About Wait Delay Duration XQuery Expressions"­). For example, you can specify to start the waiting order item two days after the blocking order item has completed.

  • A specific date and time based on the result of an XQuery expression (see "About Wait Delay Date and Time XQuery Expressions"­). For example, you can specify to start the To Component order component on a date specified in an order item property.

Figure 4-46 shows the wait condition options in a product specification in Design Studio. The orchestration dependency wait condition options are identical.

Figure 4-46 Product Specification Wait Conditions in Design Studio

Shows wait condition options in Design Studio

About Order Item Dependency Wait Conditions Based on Data Changes

You can base a dependency on a change to data. The data must be included in an order item property, and it must be in the task data of the task associated with the blocking order item.

To configure the dependency, you define the following:

  • The order item property that is evaluated. Any change to the data in the order item property triggers an evaluation of the data to determine if it matches the conditions required for the dependency.

  • An XQuery expression that evaluates the data retrieved from the blocking order item. The expression returns true or false; if true, the dependency has been met.

Figure 4-47 shows a data change dependency in Design Studio.

Figure 4-47 Data Change Dependency In Design Studio

Graphic is described in surrounding text.

In Figure 4-47:

  • The Order Item field specifies the order item specification to use.

  • The order item property that the dependency is based on is milestone.

    The Relative Path field (not used in this example) is an optional field you can use to specify a child data element in the order item properties.

  • The XQuery expression evaluates the data in the milestone property to determine if the dependency has been met (see "About Order Data Change Wait Condition XQuery Expressions" for more information).

Modeling a Product Specification Dependency

You can define dependencies across different order items by basing the dependency on the product specifications of the order items. For example, you can create a dependency that specifies to provision fixed services only after broadband services have been provisioned.

Figure 4-48 shows a dependency based on product specification. In this example, the dependency requires that fixed services be provisioned before broadband services. To configure this type of dependency, you edit the product specification of the waiting order item. In the product specification, you provide a list of waiting and blocking order components.

Figure 4-48 Dependency Based on Product Specification

Shows a dependency based on product specification

Figure 4-49 shows the dependency relationships shown in Figure 4-48. Note that fixed provisioning is the blocker for broadband provisioning and for fixed billing.

Figure 4-49 Dependency Relationships for Product Specification Dependency

Shows the dependency relationships

Modeling an Order Item Property Correlation Dependency

Using properties correlation is the most flexible way to configure dependencies. You use this method to create a dependency on two different order items that share the same order item property. As with other dependencies, you specify a blocking component (the From Component field) and a waiting component (the To Component field), but you also enter an XQuery expression to select the order item property that order items in the To Component field must share with order items in the From Component field (see "About Product Specification Order Item Dependency XQuery Expressions" for more information).

About Inferred Dependencies

OSM is able to create dependencies at run time by inferring dependencies. For example, you might create this series of dependencies:

Provisioning - Billing - Marketing

If the order item has no billing function, there is an inferred dependency between Provisioning and Marketing, even though you have not modeled that dependency. Provisioning must complete before Marketing can start.

Inferred dependencies mean that whenever A is dependent on B and B is dependent on C, A is dependent on C. This avoids the need to model every dependency that might be possible.

Figure 4-50 shows a sample dependency configuration. Figure 4-51 shows the run-time view of the same configuration when there is no billing function. In this case, the Order Management Web client shows dependencies from provisioning to marketing, synchronize customer, and collections.

Figure 4-50 Dependency Relationship

Shows a sample dependency configuration

Figure 4-51 Inferred Dependencies at Run Time

Shows the run-time view

Inferred dependencies are supported within a product specification, but they are not supported across product specifications. For example, in Figure 4-52, OSM does not infer a dependency from ProvisioningFunction(Service.Fixed) to BillingFunction(Service.Broadband). You must specifically model that dependency.

Figure 4-52 Product Specification Dependencies

Shows product specification dependencies.

About Inter-Order Dependencies

An inter-order dependency is a dependency between order items in different orders. You typically configure this type of dependency to manage changes to an order when that order has passed the point of no return and cannot be amended. However, you can also use inter-order dependencies for other purposes, such as managing fulfillment functions on different systems, load balancing, and so on.

When using inter-order dependencies, the blocking order is the base order, and the waiting order is a follow-on order. A typical scenario is:

  1. A customer has ordered a broadband service.

  2. The next day, while the order is still in-flight but past the point of no return, the customer requests a change to the service bandwidth.

  3. Because a revision to the base order cannot be submitted, the customer service representative creates a follow-on order.

  4. The follow-on order is submitted to OSM; however, it does not begin processing until the base order has completed.

Here are some important points to know about inter-order dependencies:

  • Inter-order dependencies are based on order items. After the base order completes the blocking order item, the follow-on order can start, even though the base order is still in-flight.

  • Inter-order dependencies are sometimes used to manage technical dependencies when a specific fulfillment requirement cannot be handled by a revision. However, they can also be based on business reasons, when it is simpler or more efficient to use a follow-on order than to model revisions.

  • A follow-on order does not perform amendment processing on the base order. A follow-on order can be used to add, modify, or cancel services, similar to any order. The key feature is that a follow-on order has a dependency on another order.

You must model the inter-order dependencies into both the base order and the follow-on order.

  • The follow-on order must be able to find the base order and be able to recognize if the blocking order item has completed.

  • The base order must contain a reference to allow the follow-on order to find it.

To configure an inter-order dependency, you use the Order Item Dependencies tab, as shown in Figure 4-53. The configuration typically consists of the name of the dependency and its XQuery or data instance (see "About Order Item Inter Order Dependency XQuery Expressions" for more information about inter order item XQuery expressions).

Figure 4-53 Order Item Dependencies Tab

Shows order item dependencies tab.

You can create inter-order dependencies that involve order item hierarchies. For example, you can specify that the blocking order item include all of the order items in its hierarchy. To do so, you select the child completion dependency when specifying an order item hierarchy (see Figure 4-54). For more information about order item hierarchies, see "About Order Item Hierarchy").

Figure 4-54 Use for Child Completion Dependency Selected in Design Studio

Shows Use for Child Completion Dependency option.

About Modeling Orchestration Dependencies

You use orchestration dependencies to create dependencies between order components that are not based on product specifications. For example, if you need to define a generic dependency or want to model one without having to modify a product specification, you can use an orchestration dependency specification.

As with dependencies defined in product specifications, you can specify wait conditions and the type of order item dependency (for example, order item, product specification, and property correlation).

Figure 4-55 shows an orchestration dependency in Design Studio.

Figure 4-55 Orchestration Dependency in Design Studio

Shows an orchestration dependency in Design Studio

Modeling Fulfillment States

In OSM, you use fulfillment states to provide an aggregated status of order components. Fulfillment state functionality, which is an optional part of the orchestration configuration, provides the ability to compose the statuses received from external systems into normalized statuses for the order components, then into individual statuses for order items, and ultimately to a single status per order. Fulfillment state values are available in the Order Management Web client.

When OSM sends requests to external fulfillment systems, the external fulfillment systems respond with the status of the request; for example, Completed or Failed. Some fulfillment systems send multiple interim status update messages to indicate progress before sending a final completion response. Both interim and final statuses are referred to as external fulfillment states in OSM.

Each external system will have its own set of values to indicate status. For example, successful processing might be indicated by Complete in one external system and OK in another. A single order may require OSM to interact with many different external systems, so there is a need to normalize the incoming statuses into a common set of values. These values are then used as inputs to user-defined composition rules, which determine a composite fulfillment state for an order item. Using the order item hierarchy and further composition rules, OSM determines the fulfillment state for the entire order. This allows these common statuses to be sent to an upstream system, which would not be able to parse all of the individual statuses returned by the external systems. Fulfillment states can also be used to set a point of no return.

At a high level, configuration of fulfillment state management has the following main steps:

  1. Define external fulfillment states for order components: An external fulfillment state is available on that component and on any order component that extends that order component.

  2. Create and configure fulfillment state maps: Fulfillment state maps provide the evaluation and normalization of the external system's states into mapped fulfillment states. Fulfillment state maps also provide the ability to define common fulfillment states that are used for mapping and composition rule sets. See "Modeling Fulfillment State Maps" for more information.

  3. Create and configure order item fulfillment state composition rule sets and order fulfillment state composition rule sets: These entities compose the mapped fulfillment states from the previous step into composite fulfillment states that reflect the state of entire order items or orders. See "Modeling Order and Order Item Fulfillment State Composition Rule Sets" for more information.

At run time, OSM maps the external fulfillment states 1:1 to mapped fulfillment states on an order item. Composite fulfillment states are composed using the set of input fulfillment states that are available to them:

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 addition to providing order item and order processing state information to upstream systems, fulfillment states may also be used to restrict processing of order amendments from the upstream system. This functionality is provided by point-of-no-return processing, which is based on fulfillment states. See "About Point of No Return" for more information.

Figure 4-56 depicts a fulfillment state mapping scenario.

Figure 4-56 Simple Fulfillment State Scenario

Graphic is described in surrounding text.

In the figure, OSM receives the external fulfillment states (for example, Completed and Success) and uses fulfillment state maps and composition rules to translate those states into a value that the CRM system uses, such as SuccessfulCompletion. In some cases, the external fulfillment state that indicates a completed order may not be obvious. For example, if the task sent to a billing system is supposed to start the billing, the billing system might indicate a completed order by sending the status Started.

Figure 4-57 shows a more detailed depiction of fulfillment state processing for a small part of a sample implementation.

Figure 4-57 Fulfillment State Composition

Graphic is described in surrounding text.

In the figure:

  1. The external billing system sends a status of OK, which is used directly as the external fulfillment state for OrderComponent_Billing.

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

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

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

  5. The order item fulfillment state composition rule set for the OrderItem_VoIP order item then looks 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.

  6. A similar process is followed for OrderItem_Mobile, which sets the status to Failed because a partial completion in that order item is considered a failure.

  7. The order fulfillment state composition rule set for the order then takes the composite fulfillment state of the highest-level parent order items (in this case, all of the 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 case customer needs dictate that because there is at least part of the order that is ready for customer use (VoIP) the composite fulfillment state is set to Part_Success.

About Modeling Fulfillment State Management

To model fulfillment states, start by defining external fulfillment states in order components. These external fulfillment states could match the status values returned from an external system, or the automation could transform status values before putting them on the order, in which case the external fulfillment state will match the transformed value.

After defining the external fulfillment states, create fulfillment state mappings in a fulfillment state map and composition rules for either the order, the order item, or both.

Modeling Fulfillment State Maps

Fulfillment state maps are containers for 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 work space.

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. (For more information about composition rules, see "Modeling Order and Order Item 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 know how the common fulfillment state will be used when you configure it. The same common fulfillment state can be used for both purposes at the same time.

Figure 4-58 Detail from Fulfillment State Map Editor States Tab

Graphic is described in surrounding text.

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. However, each mapping must specify a single product specification, order item, and orchestration sequence, with a single set of orchestration stage and order component combinations. Wild cards cannot be used, which may lead to a large number of mappings.

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

  1. Product specification: The product specification value restricts the fulfillment state mapping to apply only to order components defined on orchestration plans associated with the specified product specification. For example, the fulfillment state mappings might be very different between mobile and IP services.

  2. Order item: The selected value restricts the fulfillment state mapping to apply only to order components responsible for processing the specified order item.

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

  4. 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 state facilitates maintenance of the solution because your decomposition rules may change over time.

  5. Order component: One order component must be specified for each specified orchestration stage. You should ensure that your mappings handle all of the order components you are using.

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 product specification 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 Softphone.

    Figure 4-59 Detail from Fulfillment State Map Editor Mappings Tab

    Graphic is described in surrounding text.
  • 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 Order and Order Item Fulfillment State Composition Rule Sets

Orders contain one or more order items. Order items can in turn contain other order items using the order item hierarchy. See "About Order Item Hierarchy" for more information. An order item may be fulfilled by one or more order component specifications.

OSM assigns a fulfillment state for order items that are directly fulfilled by order components. This represents the status of the order item as it was fulfilled by a particular order component. This is referred to as a mapped fulfillment state because it is generated by fulfillment state maps. There is also a fulfillment state assigned to the order item as a whole that takes into account all of the mapped fulfillment states for that order item. This is referred to as a composite fulfillment state because it is generated by order item fulfillment state composition rules. In addition, fulfillment state management maintains a fulfillment state value for the order as a whole, which is also referred to as a composite fulfillment state, and is generated by order fulfillment state composition rules.

Common Features of Order and Order Item Fulfillment State Composition Rule Sets

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

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

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

Figure 4-60 Detail from Order Fulfillment State Composition Rule Set Editor

Graphic is described in surrounding text.

You use order item fulfillment state composition rules to specify the fulfillment state for the 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.

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 4-61 Fulfillment States Section of Condition Details Subtab

Graphic is described in surrounding text.

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, you can set 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

Order fulfillment state composition rules determine the fulfillment state of the order based on the composite fulfillment states of the highest-level parent order items.

In addition to the common fulfillment state-related criteria discussed above, 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.

Decomposition XQuery Expressions

This section includes information about Orchestration XQueries related to order decomposition.

About Orchestration Sequence XQuery Expressions

The orchestration sequence editor provides the following areas to define XQuery expressions related to order decomposition:

About Order Sequence Order Item Selector XQuery Expressions

This section refers to the Design Studio OSM Orchestration Sequence editor, Order Item Selector XQuery field.

The Orchestration Sequence editor Order Item Selector XQuery expression specifies which node-set to use from the customer order as order items and has the following characteristics:

  • Context: The input document for the Order Item Selector XQuery is the customer order. See "How Incoming Customer Orders are Structured" for more information about typical customer order structures.

  • Prolog: You can declare the customer order namespace in the XQuery prolog.

  • Body: The XQuery body must specify the customer order node-sets that OSM then uses as order items.

Figure 4-62 shows an order item selector XQuery expression in Design Studio. In this case, the <salesOrderLine> node-set is specified. OSM can now use the data in the <salesOrderLine> node-set in the incoming customer order in the order items. There can only be one node-set selected per sequence.

Figure 4-62 Order Item Selector

Shows an order item selector in Design Studio

About Order Sequence Fulfillment Mode XQuery Expressions

This section refers to the Design Studio OSM Orchestration Sequence editor, Fulfillment Mode Expression XQuery field.

The orchestration sequence editor Fulfillment Mode Expression XQuery expression specifies the fulfillment mode for the orchestration sequence from a customer order element and has the following characteristics:

  • Context: The input document for the Fulfillment Mode Expression XQuery is the customer order. See "How Incoming Customer Orders are Structured" for more information about typical customer order structures.

  • Prolog: The input document for the Fulfillment Mode Expression XQuery is the incoming customer order. You must declare the customer order namespace in the XQuery prolog.

  • Body: The XQuery body must specify the fulfillment mode.

Typically, the fulfillment mode is specified in the order header. For example:

<im:FulfillmentModeCode>Deliver</im:FulfillmentModeCode>

Figure 4-63 shows a hard coded fulfillment mode defined in an orchestration sequence, although normally you would derive the fulfillment mode from a customer order element.

Figure 4-63 Fulfillment Mode Defined in an Orchestration Sequence

Graphic is described in the surrounding text.

In the following example, the XQuery looks in the incoming customer order (SalesOrder) for the <FulfillmentModeCode> element. It returns the text contained in that element.

declare namespace
im="http://xmlns.oracle.com/InputMessage";
<osm:fulfillmentMode name="{fn:normalize-space(.//im:SalesOrder/im:DataArea/im:FulfillmentModeCode/text())}"

This is the XML in the incoming customer order:

<im:FulfillmentModeCode>Deliver</im:FulfillmentModeCode>

In this case, the XQuery returns Deliver.

About Order Item Specification XQuery Expressions

The Order Item Specification editor provides the following areas to define XQuery expressions related to order decomposition:

About Order Item Specification Order Item Property XQuery Expressions

This section refers to the Design Studio OSM Order Item Specification editor, Order Item Properties tab, Property Expression XQuery field.

You can define order item properties in the Order Item Specification editor based on the input context using XQuery expressions that have the following characteristics:

  • Context: The Property Expression XQuery input document is a node from the node-set returned by the order item selector (see "About Order Sequence Order Item Selector XQuery Expressions"). OSM runs every order item Property Expression XQuery against each node (starting with the first and ending with the last node) in the node-set returned by the order item selector.

  • Prolog: You can declare the following variables within the prolog to access additional context information:

    • The $inputDoc variable can be declared in the prolog of an OSM XQuery to provide access to the original input customer order. This external function can be useful if you need to generate order item properties based on elements outside of the order item node-set defined in the order item selector. The format for declaring this variable in the XQuery prolog is:

      declare variable $inputDoc as document-node() external;
      

      You can then access this variable within the XQuery body. For example, the following XQuery body uses $inputDoc to define the ItemReferenceName value:

      let $inputOrderData:= $inputDoc/GetOrder.Response/_root
      fn:normalize-space(cso:ItemReferenceName/text())
      

      See "How Incoming Customer Orders are Structured" for more information about typical customer order structure.

    • The $salesOrderLines variable can be used in an OSM XQuery to provide access to original order item node-set before it is selected by the orchestration sequence's order item selector. This can be useful if the order item selector XQuery changes the selected order item node-set (for example, by rearranging the order of the elements). The format for declaring this variable in the XQuery prolog is:

      declare variable $salesOrderLines as document-node() external;
      

      You can access this variable within the XQuery body. See "How Incoming Customer Orders are Structured" for more information about typical customer order structure.

  • Body: The XQuery body must specify the order item element that provides the values for each order item property you define.

After these XQueries have run against an order item, the order item and the order item properties become internally accessible as an XQuery context for other OSM entities. For example,

<osm:orderItem 
 xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="1288881040699">
 <osm:name>Commercial Fixed Service [Add]</osm:name>
 <osm:orderItemSpec xmlns="http://xmlns.oracle.com/communications/ordermanagement/model">
  <osm:name>CustomerOrderItemSpecification</osm:name>
  <osm:namespace>http://oracle.communications.ordermanagement.unsupported.centralom</osm:namespace>
 </osm:orderItemSpec>
 <osm:productSpec xmlns="http://xmlns.oracle.com/communications/ordermanagement/model">
  <osm:name>Service.Fixed</osm:name>
  <osm:namespace>http://oracle.communications.ordermanagement.unsupported.centralom</osm:namespace>
 </osm:productSpec>
 <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
  <im:typeCode>PRODUCT</im:typeCode>
  <im:parentLineId>3</im:parentLineId>
  <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
  <im:lineItemName>Commercial Fixed Service [Add]</im:lineItemName>
  <im:lineId>4</im:lineId>
  <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
  <im:productClass>Fixed Service Plan Class</im:productClass>
  <im:serviceId>552131313131</im:serviceId>
  <im:productSpec>Service.Fixed</im:productSpec>
  <im:lineItemPayload> [34 lines]
  <im:region>Sao Paulo</im:region>
 <osm:properties>
</osm:orderItem>

The following examples show some ways to map data in an incoming customer order to an order item property. The current context is a single node from salesOrderLines, which is one of the nodes returned by executing the orchestration sequence order item selector against the input message (see "About Order Sequence Order Item Selector XQuery Expressions").

  • Order management personnel need to know what the requested delivery date is for order items. Adding the date to the order item allows the order management personnel to see it in the OSM Web clients. In addition, OSM needs the requested delivery date to calculate the order start date.

    To retrieve the requested delivery data for an order item, OSM looks in the incoming customer order for the <requestedDeliveryDate> element:

    <im:requestedDeliveryDate>2001-12-31T12:00:00</im:requestedDeliveryDate>
    

    The definition of the requestedDeliveryDate order item property includes the following XQuery, which returns the text of the <requestedDeliveryDate> element:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
          fn:normalize-space(im:requestedDeliveryDate/text())
    
  • Order management personnel need to identify order items in the OSM Web clients. The lineItemName order item property includes the following XQuery:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
          fn:normalize-space(fn:concat(im:itemReference/im:name/text(),' [',im:serviceActionCode/text(),']'))
    

    This XQuery looks for two elements, <name> and <serviceActionCode>:

    <im:name>Fixed Caller ID</im:name>
    <im:serviceActionCode>Add</im:serviceActionCode>
    

    It then concatenates the text retrieved from the two elements to form the order item name, in this case Fixed Caller ID [Add].

  • Order management personnel need to identify the product class from the customer order so that order items can be mapped to product specifications (see "About Mapping Product Class and Product Specification XQuery Expressions"). The following example shows the product class data in the message, contained in the <primaryClassificationCode> element:

    <im:primaryClassificationCode>Mobile Service Feature Class
    </im:primaryClassificationCode>
    

    The productClass order item property uses the following XQuery expression to get the data:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
          fn:normalize-space(im:itemReference/im:primaryClassificationCode/text())
    

About Mapping Product Class and Product Specification XQuery Expressions

The order item property productSpec must map to an existing OSM product specification entity. The value could be contained in a customer order, but more often, it is derived from other customer order parameter. This property is mandatory.

The construction of the productSpec order item property follows the same rules as other order item property XQuery expressions. See "About Order Item Specification Order Item Property XQuery Expressions" for more information about the XQuery context, prolog, and body.

The following describes a common scenario for deriving product specifications from product class data contained in an order. In other scenarios, the mapping from product class to product specification might be simpler; or, there might be cases where some order line items have no product class, in which case the product class can be derived from the context of the order item.

You typically create product classes in your OSM system by importing them. (See "About Modeling Product Classes" for more information.) When you import product classes, Design Studio creates the productClassMapping.xml file in the resources/productSpecMapping folder of the cartridge project. This file contains product class to product specification mappings.

You can retrieve this mapping data from the productClassMapping.xml file by creating a data instance provider that can be referenced from an XQuery expression body using a data instance behavior (see "Using the Data Instance Behavior to Retrieve and Store Data").

For example, the following XQuery creates the $productClassMap variable that references the data instance that points to the productClassMapping.xml file:

let $productClassMap := vf:instance('dataInstace1')

The following code creates a variable that references the product class value from the customer order. For example:

let $productClassName  := fn:normalize-space(im:itemReference/im:primaryClassificationCode/text())

You can now create an expression that matches the product class from the order with the product class contained in the productClassMapping.xml file and returns the product specification associated with it or else defaults to the Non.Service.Offer product specification. For example:

     return
     if ($productClassName != '')
     then
     fn:normalize-space($productClassMap/productClass
     [fn:lower-case(@name)=fn:lower-case($productClassName)]/productSpec/text())
     else
 'Non.Service.Offer'

In the following example, OSM retrieves the product class Mobile Service Feature Class from the incoming customer order. OSM uses the productSpec order item property to map the product class to a product specification.

The productSpec order item property includes the following XQuery expression:

declare namespace im="http://xmlns.oracle.com/InputMessage";
(:    Use the ProductClassMap data instance behavior to retrieve the data in the productClassMapping.xml file:     :)
     let $productClassMap := vf:instance('ProductClassMap')
     let $productClassName  := 
     fn:normalize-space(im:itemReference/im:primaryClassificationCode/text())
     return
     if ($productClassName != '')
     then
     fn:normalize-space($productClassMap/productClass
     [fn:lower-case(@name)=fn:lower-case($productClassName)]/productSpec/text())
     else
     'Non.Service.Offer'

The productClassMapping.xml file includes the <productClass> element, that maps the Mobile Service Feature Class product class to the Service.Mobile product specification:

<productClass name="Mobile Service Feature Class" 
     cartridge="OsmCentralOMExample-ProductClasses">
     productSpec>Service.Mobile</productSpec>
</productClass>

To summarize, to map an order line item in an incoming customer order to a product specification, you configure the following:

  • In the order item specification:

    • The productClass order item property, that retrieves the product class from the incoming customer order.

    • The productSpec order item property, that maps the product class to the product specification. To do so, OSM uses the ProductClassMap data instance behavior.

  • The ProductClassMap data instance behavior (and the data provider that supports it), that retrieves data from the productClassMapping.xml file.

  • The productClassMapping.xml file used by the ProductClassMap data instance behavior, that maps product classes to product specifications.

When you update your product catalog, you might need to add new product specifications. In that case, you need to:

  • Create new product specifications and product classes, if necessary.

  • Add mappings to the productClassMapping.xml file.

You do not need to change the order item specification or the data instance behavior.

About Order Item Specification Order Item Hierarchy XQuery Expressions

This section refers to the Design Studio OSM Order Item Specification editor, Order Item Hierarchies tab, Key Expression and Parent Key Expression sub tab XQuery fields.

The order item specification editor Order Item Hierarchies Key Expression and Parent Key Expression XQueries specifies the relative hierarchy of order items, in the same order or between different orders, based on an order item value, such as lineId and parentLineId and has the following characteristics:

  • Context: The Key Expression and Parent Key Expression XQuery input document is the order item. Specifically order item properties that indicate the relative hierarchy, such as order item lineId and parentLineID properties. For example:

    <osm:orderItem 
     xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="1288881040699">
    .....
     <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
      <im:typeCode>PRODUCT</im:typeCode>
      <im:parentLineId>3</im:parentLineId>
      <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
      <im:lineItemName>Commercial Fixed Service [Add]</im:lineItemName>
      <im:lineId>4</im:lineId>
      <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
      <im:productClass>Fixed Service Plan Class</im:productClass>
      <im:serviceId>552131313131</im:serviceId>
      <im:productSpec>Service.Fixed</im:productSpec>
      <im:lineItemPayload> [34 lines]
      <im:region>Sao Paulo</im:region>
     <osm:properties>
    </osm:orderItem>
    
  • Prolog: You can declare the order item specification namespace and the OSM namespace in the XQuery prolog. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
    declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
    

    You can declare the OrchestrationXQueryFunctions class in the prolog to use the ancestors method that returns the current node and all ancestors of the current node based on the specified hierarchy definition. This method can be useful when creating dependencies between order items based on hierarchy. For example:

    declare namespace osmfn = "java:oracle.communications.ordermanagement.orchestration.generation.OrchestrationXQueryFunctions";
    

    For more information about the OrchestrationXQueryFunctions class, install the OSM SDK and extract the OSM_home/SDK/osm7.x.y.z-javadocs.zip OSM Java docs (where OSM_home is the directory in which the OSM software is installed and x.y.z are the software release, patch, and build numbers). See OSM Installation Guide for more information about installing the OSM SDK.

    See "About the Decomposition of Target System to Granularity Components" for an example of how the ancestors method is used.

  • Body: The XQuery body must specify an order item property defined in the order item specification.

    For example, for the Key Expression, you can identify a unique key for each order item, typically the order item line ID:

    fn:normalize-space(osm:properties/im:LineId/text())
    

    For example, for the Parent Key Expression, you can identify a parent order line item, typically the line ID for the parent order line item:

    fn:normalize-space(osm:properties/im:parentLineId/text())
    

Figure 4-64 shows an example of an order item hierarchy.

Figure 4-64 Order Item Hierarchy in Design Studio

Shows an example of an order item hierarchy in Design Studio

In the following example, the key expression uses the parent order line item's <lineId> element from the order item property customer order:

declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
fn:normalize-space(osm:properties/im:lineId/text())

The parent key expression uses the child order line item's <parentLineId> element from the incoming customer order:

declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
fn:normalize-space(osm:properties/im:parentLineId/text())

About Order Item Specification Condition XQuery Expressions

This section refers to the Design Studio OSM Order Item Specification editor, Orchestration Conditions tab, Condition Expression sub tab XQuery field.

The order item specification editor Condition Expression XQuery specifies an order item property value as a condition that you can then use in an Order Decomposition Rule or in a Product Specification to determine whether an order item gets included in an order component. The XQuery for the condition has the following characteristics:

  • Context: The Condition Expression XQuery input document is the order item properties you want to use as conditions. For example, the following order item contains the region and the ServiceActionCode order item properties, that could be associated to conditions:

    <osm:orderItem 
     xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="1288881040699">
    .....
     <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
      <im:typeCode>PRODUCT</im:typeCode>
      <im:parentLineId>3</im:parentLineId>
      <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
      <im:lineItemName>Commercial Fixed Service [Add]</im:lineItemName>
      <im:lineId>4</im:lineId>
      <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
      <im:productClass>Fixed Service Plan Class</im:productClass>
      <im:serviceId>552131313131</im:serviceId>
      <im:productSpec>Service.Fixed</im:productSpec>
      <im:lineItemPayload> [34 lines]
      <im:region>Sao Paulo</im:region>
     <osm:properties>
    </osm:orderItem>
    

    See "About Product Specification Order Component Condition XQuery Expressions" for a description of the XQuery condition based on the ServiceActionCode. See "About Decomposition Rule Condition XQuery Expressions" for a description of the XQuery condition based on the region.

  • Prolog: You can declare the order item specification namespace and the OSM namespace in the XQuery prolog. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
    declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
    
  • Body: The XQuery body must evaluate an order item property defined in the order item specification. These order item properties are available from the OSM namespace using the properties element. For example, the following expression evaluates to true if the value of region is anything other than Sao Paulo and the order item gets included in the order component. If the region were set to Sao Paulo, then the order item would not be included in the order component.

    fn:not(fn:normalize-space(osm:properties/im:region/text())='Sao Paulo')
    

    Another condition could be created that would only evaluate to true if the value of region was set to Sao Paulo. In this case, the order item would only be included in the order component if the region were set to Sao Paulo.

About Product Specification Order Component XQuery Expressions

The product specification editor provides the following areas to define XQuery expressions related to order decomposition:

Note:

The XQuery expressions discussed in this chapter also apply to the Orchestration Dependency editor.

About Product Specification Order Component Condition XQuery Expressions

This section refers to the Design Studio OSM Product Specification editor, Orchestration Plan tab, Order Components sub tab, Conditions sub tab XQuery field.

The Product Specification editor Component Condition Expression XQuery determines whether to include or exclude an order item from an order component. You can create a new specification from the Product Specification editor or select from conditions created in the Order Item Specification. See "About Order Item Specification Condition XQuery Expressions" for more information about the context, prolog, and body of condition XQuery expressions.

Figure 4-65 shows an order component condition in Design Studio.

Figure 4-65 Order Component Condition

Shows an order component condition in Design Studio

The Example 4-3 XQuery expression only evaluates to true if the value of ServiceActionCode is not NONE or UPDATE. For example, if the value of ServiceActionCode were ADD, then the order item would be included in the order component.

Example 4-3 Order Component Condition

fn:boolean
(
(osm:properties/im:ServiceActionCode/text()!="NONE" and
osm:properties/im:ServiceActionCode/text()!="UPDATE") or
(

About Associating Order Items Using Property Correlations XQuery Expressions

This section refers to the Design Studio OSM Product Specification editor, Orchestration Plan tab, Order Components sub tab, Order Item Association sub tab, Property Correlation XQuery field.

The Product Specification editor Order Item Association XQuery assigns order items to order components that are not assigned by their product specification. These order item associations are typically required when external systems need a specific context for an order item and includes the following characteristics:

  • Context: The Order Item Association XQuery input documents are multiple order items in the order after decomposition contained in the fromOrderComponent element and the entire set of order items included in the order contained in the toOrderComponent element. You can make an XQuery association based on the contents of these order items that create an association between the unique order item IDs. For example:

    <fromOrderComponent xmlns="">
     <osm:orderItem 
     xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="1234">
     <osm:name>Speed By Demand [Add]</osm:name>
    .....
      <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
       <im:typeCode>PRODUCT</im:typeCode>
       <im:parentLineId>3</im:parentLineId>
       <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
       <im:lineItemName>Commercial Fixed Service [Add]</im:lineItemName>
       <im:lineId>4</im:lineId>
       <im:SiteID>10</im:SiteID>
       <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
       <im:productClass>Speed by Demand class</im:productClass>
       <im:serviceId>552131313131</im:serviceId>
       <im:productSpec>Service.Fixed</im:productSpec>
       <im:lineItemPayload> [34 lines]
       <mi:region>Sao Paulo</im:region>
      <osm:properties>
     </osm:orderItem>
     <osm:orderItem [37 lines] 
     <osm:orderItem [42 lines]
     <osm:orderItem [57 lines]
     <osm:orderItem [57 lines]
    </fromOrderComponent>
    <toOrderComponent xmlns="">
     <osm:orderItem [35 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [42 lines]
     <osm:orderItem 
     xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="5678">
     <osm:name>Broadband Bundle [Add]</osm:name>
    .....
      <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
       <im:typeCode>PRODUCT</im:typeCode>
       <im:parentLineId>3</im:parentLineId>
       <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
       <im:lineItemName>Broadband Bundle [Add]</im:lineItemName>
       <im:lineId>4</im:lineId>
       <im:SiteID>10</im:SiteID>
       <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
       <im:productClass>Broadband Bundle Class</im:productClass>
       <im:serviceId>1112223333</im:serviceId>
       <im:productSpec>Broadband.Bundle</im:productSpec>
       <im:lineItemPayload> [34 lines]
       <im:region>Sao Paulo</im:region>
      <osm:properties>
     <osm:orderItem [57 lines]
     <osm:orderItem [57 lines]
     <osm:orderItem [42 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [57 lines]
    </toOrderComponent>
    
  • Prolog: You can declare the order item namespace and the OSM namespace in the XQuery prolog. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
    declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
    
  • Body: The XQuery body must specify a dependency between the order item and the associated order item using something similar to the following syntax:

    let $fromItem := osm:fromOrderComponent/osm:orderItem[osm:name/text()="Speed By Demand [Add]"]
    let $toItem := osm:toOrderComponent/osm:orderItem[osm:name/text()="Broadband Bundle [Add]" and osm:properties/im:SiteID/text() = $fromItem/osm:properties/im:SiteID/text()]
    return
    <osm:dependency fromOrderItemId='{$fromItem/@id}' toOrderItemID='{$toItem/@id}'/> 
    

    where

    • osm:fromOrderComponent: Returns the set of order items included in the order component after the decomposition phase.

    • osm:toOrderComponent: Returns the entire set of order items included in the order.

    • osm:orderItem: These are the order items in the fromOrderComponent or toOrderComponent categories.

    • osm:dependency fromOrderItemId='{$fromItem/@id}: The output of the XQuery specifying the source order item ID for the association.

    • toItem='{$childOrderItem/@id}'/>: The output of the XQuery specifying the target order item ID for the association.

    Given the sample provided in the context bullet, this XQuery would return the following association:

    <osm:dependency fromOrderItemId='1234' toOrderItemId='5678'/> 
    

Example 4-4 shows an XQuery that associates all child order items with their parent items. (See "About Order Item Hierarchy" for more information.) The output of the XQuery expression returns a node-set of <osm:dependency fromOrderItemId='{$fromOrderItem/@id}' toOrderItemId=' {$toOrderItem/@id}'/> where item IDs are the @id attribute of the order item.

Example 4-4 Order Item Association Using Property Correlation

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace prop="http://oracle.communications.ordermanagement.unsupported.centralom";
(:   $fromOrderItemList contains all order items in the selected order component:   :)
for $fromOrderItem in $fromOrderItemList
let $fromOrderItemList := osm:fromOrderComponent/osm:orderItem
(:    $childOrderItems contains all children for the current $fromOrderItem:    :)
let $childOrderItems := osm:toOrderComponent/osm:orderItem/osm:properties
      [prop:ParentLineID/text() = $fromOrderItem/osm:properties/prop:LineID/text()]
(:    Returns the association between all parents and their children:    :)
for $childOrderItem in $childOrderItems
return
  <osm:dependency fromOrderItemId='{$fromOrderItem/@id}' toOrderItemId='{$childOrderItem/@id}'/> 

About Decomposition Rule Condition XQuery Expressions

This section refers to the Design Studio OSM Decomposition Rule editor, Conditions tab, Conditions Details sub tab XQuery field.

To associate a condition with a decomposition rule, you can create the condition in the order item specification and select them in the decomposition rule, or you can create them directly in the decomposition rule. See "About Order Item Specification Condition XQuery Expressions" for more information about the context, prolog, and body of condition XQuery expressions.

The following is an example of two decomposition rules, each having a condition set that determines whether an order item is included in the target order component or not. In this example:

  • The decomposition rule that targets the target system order component for region 1 has the following decomposition condition:

    isRegion1
    
  • The decomposition rule that targets the a target system order component for region 2 has the following decomposition condition:

    isOtherRegion
    

The XQuery for the isRegion1 decomposition rule condition is:

declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
fn:normalize-space(osm:properties/im:region/text())='Toronto')

This condition specifies the value of the region order item property. If the value is Toronto, the decomposition rule condition is true, and the order item is included in the region 1 target system order component.

The XQuery for the isOtherRegion decomposition rule condition is:

declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";fn:not(fn:normalize-space(osm:properties/im:region/text())='Toronto')

This condition also specifies the value of the region order item property, but evaluates to true only if the value is not Toronto. All order items that have any other value are included in the region 2 target system order component.

The following example includes a variation on the isRegion1 decomposition rule that specifies that all the order items from the source order component to the target order component that have at least one order item with a region property of Toronto are included in the order component. Otherwise, if the condition evaluates to false then none of the order items in fromOrderComponent are included in the resulting order component.

declare namespace im="http://oracle.communications.centralom";
declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
fn:exists(osm:fromOrderComponent/osm:orderItem[fn:normalize-space(osm:properties/im:Region/text())='Toronto'])

For some functions, there is only one target system in the topology. For example, if you have only one collections system in the topology, you will have one dependency rule that uses a simple mapping from the source collections function order component to the collections target system order component, and no decomposition condition is necessary.

About Component Specification Custom Component IDs XQuery Expressions

This section refers to the Design Studio OSM Order Component Specification editor, Component ID tab XQuery field.

The Component Specification editor Component ID XQuery can be used to create a custom component ID for an order component. These custom component IDs are typically required when the default component IDs are not sufficiently specific (see "About Component IDs and Component Keys" for more information about the default component ID). The Component ID XQuery includes the following characteristics:

  • Context: The Component ID XQuery input document is the order item and the order item properties you want to use to create a custom component ID with. For example, the following order item contains the SiteID and requestedDeliveryDate order item properties. In a simple scenario, you can use this element to group all order items that share the same SiteID value and further delineate groups based on requestedDeliveryDate date range.

    <osm:orderItem 
     xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="1288881040699">
    .....
     <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
      <im:typeCode>Bundle</im:typeCode>
      <im:parentLineId>3</im:parentLineId>
      <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
      <im:lineItemName>Commercial Fixed Service [Add]</im:lineItemName>
      <im:lineId>4</im:lineId>
      <im:SiteID>10</im:SiteID>
      <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
      <im:productClass>Fixed Service Plan Class</im:productClass>
      <im:serviceId>552131313131</im:serviceId>
      <im:productSpec>Service.Fixed</im:productSpec>
      <im:lineItemPayload> [34 lines]
      <im:region>Sao Paulo</im:region>
     <osm:properties>
    </osm:orderItem>
    
  • Prolog: You can declare the order item namespace and the OSM namespace in the XQuery prolog. In more complicated XQueries, you can also use the OrchestrationXQueryFunctions OSM Java package to specify component IDs based on order item hierarchies, order item requested delivery date, order component duration, order component minimum duration separation, or a combination of some or all of them. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
    declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
    declare namespace osmfn = "java:oracle.communications.ordermanagement.orchestration.generation.OrchestrationXQueryFunctions";
    

    For more information about the OrchestrationXQueryFunctions class, install the OSM SDK and extract the OSM_home/SDK/osm7.x.y.z-javadocs.zip OSM Java docs (where OSM_home is the directory in which the OSM software is installed and x.y.z are the software release, patch, and build numbers). See OSM Installation Guide for more information about installing the OSM SDK. For more information about how the OrchestrationXQueryFunctions are used in custom Component ID XQueries, see:

  • Body: The body must return a string. Every order item that ends with the same string gets included in the order component. For example, if you wanted to group all order items based on the SiteID value, you could specify the following XQuery:

    return osm:properties/im:SiteID/text() 
    

The following sections describe more complicated custom group ID generation scenarios that use Orchestration XQueryFunction OSM Java package methods.

Custom Order Component IDs Based on Hierarchy

A more common scenario where custom order component IDs can be used is when there is a need for additional groupings of order components at the granularity level. For example, three levels of decomposition from Function, System, to Bundle, results in the following component IDs:

  • BillingFunction

  • BillingFunction.BillingSystem

  • BillingFunction.BillingSystem.Bundle

If you had order items in the Bundle order components that were part of different bundles that go to different the billing system, you would need to separate each order item bundle into different bundle order component. A component ID for such a scenario could look like this:

  • For billing system 1: BillingFunction.BillingSystem.Bundle.2/BundleGranularity

  • For billing system 2: BillingFunction.BillingSystem.Bundle.6/BundleGranularity

To create custom component IDs for this scenario, you could use the following order item properties:

  • typeCode: This property specifies if the order line item is an offer, bundle, or product. This element also defines the product hierarchy of the order line items. For example:

    OFFER
       BUNDLE
          PRODUCT
    
  • lineId and parentLineId: These properties specify the hierarchical relationship between the bundle and product order line items. You can create separate component IDs for every order item bundle and associate all product order items with their corresponding bundle component ID. To identify all ancestor order items that may be a bundle, you can use the XQuery ancestors function, as explained later.

For example, the following four order items include two bundles and two associated products ("Order Item 1 - Fixed Bundle" with "Order Item 2 - Fixed Caller ID" and "Order Item 3 - BroadBand Bundle" with "Order Item 4 - BroadBand Service"):

Example 4-5 Order Item 1 - Fixed Bundle

<osm:orderItem 
 xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="1234">
 <osm:name>FIXED BUNDLE - BUNDLE</osm:name>
.....
 <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
  <im:typeCode>BUNDLE</im:typeCode>
  <im:parentLineId>1</im:parentLineId>
  <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
  <im:lineItemName>Fixed Bundle</im:lineItemName>
  <im:lineId>2</im:lineId>
  <im:SiteID>5</im:SiteID>
  <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
  <im:productClass>Fixed Bundle Class</im:productClass>
  <im:serviceId>552131313131</im:serviceId>
  <im:productSpec>Service.Fixed</im:productSpec>
  <im:lineItemPayload> [34 lines]
  <im:region>Sao Paulo</im:region>
 <osm:properties>
</osm:orderItem>

Example 4-6 Order Item 2 - Fixed Caller ID

<osm:orderItem 
 xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="56789">
 <osm:name>FIXED CALLER ID - PRODUCT</osm:name>
.....
 <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
  <im:typeCode>PRODUCT</im:typeCode>
  <im:parentLineId>2</im:parentLineId>
  <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
  <im:lineItemName>Commercial Fixed Service [Add]</im:lineItemName>
  <im:lineId>5</im:lineId>
  <im:SiteID>7</im:SiteID>
  <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
  <im:productClass>Fixed Bundle Class</im:productClass>
  <im:serviceId>552131313131</im:serviceId>
  <im:productSpec>Service.Fixed</im:productSpec>
  <im:lineItemPayload> [34 lines]
  <im:region>Sao Paulo</im:region>
 <osm:properties>
</osm:orderItem>

Example 4-7 Order Item 3 - BroadBand Bundle

<osm:orderItem 
 xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="10111213">
 <osm:name>BroadBand BUNDLE - BUNDLE</osm:name>
.....
 <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
  <im:typeCode>BUNDLE</im:typeCode>
  <im:parentLineId>1</im:parentLineId>
  <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
  <im:lineItemName>Broadband Bundle</im:lineItemName>
  <im:lineId>6</im:lineId>
  <im:SiteID>5</im:SiteID>
  <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
  <im:productClass>Broadband Bundle Class</im:productClass>
  <im:serviceId>552131313131</im:serviceId>
  <im:productSpec>Service.Broadband</im:productSpec>
  <im:lineItemPayload> [34 lines]
  <im:region>Sao Paulo</im:region>
 <osm:properties>
</osm:orderItem>

Example 4-8 Order Item 4 - BroadBand Service

<osm:orderItem 
 xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="14151617">
 <osm:name>BroadBand Service - PRODUCT</osm:name>
.....
 <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
  <im:typeCode>PRODUCT</im:typeCode>
  <im:parentLineId>6</im:parentLineId>
  <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
  <im:lineItemName>Fixed Bundle</im:lineItemName>
  <im:lineId>7</im:lineId>
  <im:SiteID>5</im:SiteID>
  <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
  <im:productClass>Broadband Bundle Class</im:productClass>
  <im:serviceId>552131313131</im:serviceId>
  <im:productSpec>Service.Broadband</im:productSpec>
  <im:lineItemPayload> [34 lines]
  <im:region>Sao Paulo</im:region>
 <osm:properties>
</osm:orderItem>

These order items have the following characteristics:

  • "Order Item 1 - Fixed Bundle" includes:

    • typeCode: BUNDLE

    • lineId: 2

    • parentLineId: 1 (for example, an order item with an OFFER typeCode. This order item is not specified in this example).

  • "Order Item 2 - Fixed Caller ID" includes:

    • typeCode: PRODUCT

    • lineId: 3

    • parentLineId: 2 (This matches the lineID of order item 1 indicating that order item 1 is the parent of order item 2).

  • "Order Item 3 - BroadBand Bundle" includes:

    • typeCode: BUNDLE

    • lineId: 6

    • parentLineId: 1 (This indicates that both order item 1 and order item 3 share the same parent).

  • "Order Item 4 - BroadBand Service" includes:

    • typeCode: PRODUCT

    • lineId: 7

    • parentLineId: 6 (This matches the lineID of order item 3 indicating that order item 3 is the parent of order item 4).

The customer order includes two bundles with two products. The hierarchy is:

Fixed Bundle - order item 2
     Fixed Caller ID - order item 5
Broadband Bundle - order item 6
     BroadBand Service - order item 7

To create the separate customized component IDs for the bundle order items 1 and 3, and include all their corresponding children order items you need to:

  • Return a separate component ID for each BUNDLE typeCode. This causes BUNDLE order components to be generated.

  • Ensure that the PRODUCT typeCode for that bundle are included in its parent order item.

To do so, the XQuery uses the ancestors function to find whether the order item has a BUNDLE typeCode or has a BUNDLE typeCode in one of its parent order items. If the order item is a bundle, then a OSM creates a component ID for the bundle. If the order item has a bundle in one of its parent order items, then OSM includes the order item in its parent order item component ID. Example 4-9 shows an XQuery that does this.

Example 4-9 XQuery for Custom Component ID

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace prop="http://oracle.communications.ordermanagement.unsupported.centralom";
declare namespace osmfn = "java:oracle.communications.ordermanagement.orchestration.generation.OrchestrationXQueryFunctions";
(:    The following part of the XQuery identifies the order line hierarchy definition and retrieve all of the predecessor order line items in the bundle:   :)
let $ancestors := osmfn:ancestors("CustomerOrderItemSpecification","default","http://oracle.communications.ordermanagement.unsupported.centralom")

(:   The following part of the XQuery finds the BUNDLE order item and generates an ID based on the bundle order item lineID:     :)
   return
   if (fn:exists($ancestors[osm:properties/prop:typeCode='BUNDLE']))
      then (
               concat($ancestors[osm:properties/prop:typeCode=('BUNDLE')]
               [1]/osm:properties/prop:lineId/text(),'/BundleGranularity')
           )
      else (
              'ALL_OFFERS_AND_NON_SERVICE_BILLING/BundleGranularity'
)

This XQuery finds the child order line items, finds their parent order line items, and creates a bundle order component for each of the bundle lines. The component keys are:

  • BillingFunction.BillingSystem.Bundle.2/BundleGranularity

  • BillingFunction.BillingSystem.Bundle.6/BundleGranularity

In another example, there is one offer with two bundles and two products in each bundle. Table 4-1 shows the hierarchy of bundles and products. The component keys use the line IDs of the two bundle items.

Table 4-1 Example Bundle and Product Hierarchy

Line Number Line Name Line typeCode Parent Line ID Value to Use in Component Key

1

Triple Play

OFFER

-

-

2

Fixed Bundle

BUNDLE

1

2

2.1

Fixed Service

PRODUCT

2

2

2.2

Call Forwarding

PRODUCT

2

2

5

Broadband Bundle

BUNDLE

1

5

5.1

Broadband Service

PRODUCT

5

5

5.2

High-Speed Internet

PRODUCT

5

5


Custom Component ID Based on Requested Delivery Date and Duration

In some scenarios, you may want to create custom Order Component IDs based on order item requested delivery date and duration. For example, the following custom component ID XQuery creates order component grouping based on the order item requested delivery dates:

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace prop="http://oracle.communications.ordermanagement.unsupported.centralom";
declare namespace osmfn = "java:oracle.communications.ordermanagement.orchestration.generation.OrchestrationXQueryFunctions";
let $groupDuration := "P2D"
return
osmfn: getGroupIdByDateTime ($groupDuration)

The XQuery creates a new order component for an order item based on the order item's requested delivery date and includes all order items within this group that fall within two days of the first order item's requested delivery date in the group. The XQuery does the same thing for all other order items within the order.

Table 4-2 shows how five order items would be grouped given a custom Order Component ID XQuery that creates a new component IDs.

Note:

The group ID names are static with the first order component always called Group1 and the next Group2, and so on.

Table 4-2 Custom Component ID by Requested Delivery Date and Duration

Order Item Requested Delivery Date Group ID

A

June 9, 2014

Group1

B

June 10, 2014

Group1

C

June 11, 2014

Group2

D

June 12, 2014

Group2

E

June 12, 2014

Group3


For more information about the context, prolog, and body of this XQuery and the OrchestrationXQueryFunctions package functions, see "About Component Specification Custom Component IDs XQuery Expressions".

Custom Component ID by Duration and Minimum Separation Duration

You can specify a minimum duration separation value for order items that fall very close to a custom Order ID grouping based on order item requested delivery date and duration. For example, the following XQuery is identical to the one that generated the group IDs listed in Table 4-2, but adds a minimum separation value of one day:

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace prop="http://oracle.communications.ordermanagement.unsupported.centralom";
declare namespace osmfn = "java:oracle.communications.ordermanagement.orchestration.generation.OrchestrationXQueryFunctions";
let $groupDuration := "P2D"
let $minSeparationDuration := "P1D"
return
osmfn: getGroupIdByDateTime ($groupDuration, $minSeparationDuration)

All order item requested delivery dates that fall within one day of a two day grouping, would be included in the two day grouping.

Table 4-3 shows how the five order items would be grouped given a one day minimum separation duration.

Table 4-3 Custom Component ID with a Minimum Separation Duration

Order Item Requested Delivery Date Group ID

A

June 9, 2014

Group1

B

June 10, 2014

Group1

C

June 11, 2014

Group1

D

June 12, 2014

Group2

E

June 12, 2014

Group2


For more information about the context, prolog, and body of this XQuery and the OrchestrationXQueryFunctions package functions, see "About Component Specification Custom Component IDs XQuery Expressions".

Combining Order Item Hierarchy with Duration Based Groupings

You can combine the function to create custom Component IDs based on order item requested delivery date, duration, and minimum duration separation, or a combination of these functions with order component ID generation based on order item hierarchy. The following example creates separate component IDs for order items that, although they have the same requested delivery date, are part of different order item hierarchical groupings:

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace prop="http://oracle.communications.ordermanagement.unsupported.centralom";
declare namespace osmfn = "java:oracle.communications.ordermanagement.orchestration.generation.OrchestrationXQueryFunctions";
let $groupDuration := "P2D"
let $minSeparationDuration := "P1D"
return
osmfn: getGroupIdByDateTime ($groupDuration, $minSeparationDuration)
let $rootAncestorID := osmfn:ancestors("eboLineItem", "default", "http://xmlns.oracle.com/communications/ordermanagement")[fn:last()]/osm:properties/prop:BaseLineId/text()
return fn:concat($rootAncestorId, '/', $groupId)

Table 4-4 shows how five hierarchically divided order items would be grouped given a one day minimum separation duration.

Table 4-4 Custom Component ID with a Minimum Separation Duration

Order Item Requested Delivery Date Group ID Component ID

A.1

June 9, 2014

Group1

A/Group1

A.1.1

June 11, 2014

Group1

A/Group1

A1.2

June 19, 2014

Group2

A/Group2

A.1.3

June 20, 2014

Group2

A/Group2

B.1

June 9, 2014

Group1

B/Group1

B.1.1

June 11, 2014

Group1

B/Group1

B.1.2

June 12, 2014

Group1

B/Group2


For more information about the context, prolog, and body of this XQuery and the OrchestrationXQueryFunctions package functions, see "About Component Specification Custom Component IDs XQuery Expressions".

Dependency XQuery Expressions

This section includes information about Orchestration XQueries related to orchestration dependencies.

About Product Specification Order Item Dependency XQuery Expressions

This section refers to the Design Studio OSM Product Specification editor, Dependencies tab, Order Item Dependency sub tab, Property Correlation XQuery field.

The Property Correlation XQuery can be used to create dependencies between different order items using order item properties. The Property Correlation XQuery has the same context, prolog, and body structure as the Product Specification editor, Order Components, Order Item Association XQuery field. See "About Associating Order Items Using Property Correlations XQuery Expressions" for more information.

Example 4-10 shows a dependency that requires provisioning of an Internet service before shipping a modem. This involves two order items: provision Internet service and ship modem. The correlating property is the order item ID.

Example 4-10 Properties Correlation Dependency

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
declare namespace im="http://sample.broadband";
let $bbProvision := osm:fromOrderComponent/osm:orderItem[osm:name="Internet Service"]
let $bbModem := osm:toOrderComponent/osm:orderItem[osm:name/text()='Broadband Modem' 
   and osm:properties/im:SiteID/text() = $bbProvision/osm:properties/im:SiteID/text()]
return
   <osm:dependency fromOrderItemId='{$bbProvision/@id}' toOrderItemId='{$bbModem/@id}'/> 

In this example:

  • $bbProvision contains the broadband service order item in the blocking Provision order component.

  • $bbModem is the broadband modem in the waiting Ship order component.

  • The XQuery returns a dependency from the Internet Service order item to its associated Broadband Modem order item, identified by $bbProvision/@id and $bbModem/@id.

If the order item IDs are:

  • $bbProvision/@id = 1301589468772

  • $bbModem/@id = 1301589468785

Then the XQuery returns the following:

<osm:dependency fromOrderItemId='1301589468772' toOrderItemId='1301589468785'/>

About Wait Delay Duration XQuery Expressions

This section refers to the Design Studio OSM Product Specification editor, Orchestration Plan tab, Dependencies sub tab, Wait Condition sub tab, Wait Delay, Duration XQuery field.

The wait delay duration XQuery expression specifies the duration of delay, based on an order item property, before starting a waiting order component after all dependencies have been resolved.

  • Context: The Duration XQuery input document is the entire set of order items included in the order contained in the toOrderComponent element. You can return the value of requestedDeliveryDate to help determine the wait delay duration. For example:

    <toOrderComponent xmlns="">
     <osm:orderItem [35 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [42 lines]
     <osm:orderItem 
     xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="5678">
     <osm:name>Broadband Bundle [Add]</osm:name>
    .....
      <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
       <im:typeCode>PRODUCT</im:typeCode>
       <im:parentLineId>3</im:parentLineId>
       <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
       <im:lineItemName>Broadband Bundle [Add]</im:lineItemName>
       <im:lineId>4</im:lineId>
       <im:SiteID>10</im:SiteID>
       <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
       <im:productClass>Broadband Bundle Class</im:productClass>
       <im:serviceId>1112223333</im:serviceId>
       <im:productSpec>Broadband.Bundle</im:productSpec>
       <im:lineItemPayload> [34 lines]
       <im:region>Sao Paulo</im:region>
      <osm:properties>
     <osm:orderItem [57 lines]
     <osm:orderItem [57 lines]
     <osm:orderItem [42 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [57 lines]
    </toOrderComponent>
    
  • Prolog: You can declare the order item namespace and the OSM namespace in the XQuery prolog. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
    declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
    
  • Body: The XQuery body returns a duration value based on the requestedDeliveryDate order item property:

    let $mydate := osm:toOrderComponent[1]/osm:orderItem[1]/osm:properties[1]/*[namespace-uri()='http://oracle.communications.ordermanagement.unsupported.centralom' and local-name()='requestedDeliveryDate'][1]/text() 
    return  
    if (fn:current-dateTime()- xs:dateTime($mydate) < xs:dayTimeDuration('PT10H'))  then 
        'PT10H' 
    else 
        'PT10M'
    return
    

    where

    • osm:toOrderComponent: Provides the entire set of order items included in the order.

    • osm:orderItem: These are the order items in the toOrderComponent category. The remainder of this expression identifies the namespace of the order item specification and returns the value of the requestedDeliveryDate element.

    • The if statement checks to see if the value of the requestedDeliveryDate is less than the hard coded dayTimeDuration value. These values conform to the XSD duration data type.

    • The then statement returns 10 hours if the if statement evaluates to true.

    • The else statement return 10 months if the if statement evaluates to false.

Example 4-11 shows the sample XQuery to return a duration value.

Example 4-11 Wait Delay Duration Expression

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model"; 
declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom"; 
 
let $mydate := osm:toOrderComponent[1]/osm:orderItem[1]/osm:properties[1]/*[namespace-uri()='http://oracle.communications.ordermanagement.unsupported.centralom' and local-name()='requestedDeliveryDate'][1]/text() 
return  
if (fn:current-dateTime()- xs:dateTime($mydate) < xs:dayTimeDuration('PT10H'))  then 
    'PT10H' 
else 
    'PT10M'

About Wait Delay Date and Time XQuery Expressions

This section refers to the Design Studio OSM Product Specification editor, Orchestration Plan tab, Dependencies sub tab, Wait Condition sub tab, Wait Delay, Date Time Expression XQuery field.

The wait delay date time XQuery expression specifies the date and time, based on an order item property, for starting a waiting order component after all dependencies have been resolved.

  • Context: The Date Time Expression XQuery input document is the entire set of order items included in the order contained in the toOrderComponent element. You can use the requestedDeliveryDate order item property to determine the date and time that the XQuery should start after all blocking items have resolved. For example:

    <toOrderComponent xmlns="">
     <osm:orderItem [35 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [42 lines]
     <osm:orderItem 
     xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model" id="5678">
     <osm:name>Broadband Bundle [Add]</osm:name>
    .....
      <osm:properties xmlns:im="http://oracle.communications.ordermanagement.unsupported. centralom">
       <im:typeCode>PRODUCT</im:typeCode>
       <im:parentLineId>3</im:parentLineId>
       <im:requestedDeliveryDate>2013-06-31T12:00:00</im:requestedDeliveryDate>
       <im:lineItemName>Broadband Bundle [Add]</im:lineItemName>
       <im:lineId>4</im:lineId>
       <im:SiteID>10</im:SiteID>
       <im:ServiceActionCode>UPDATE</im:ServiceActionCode>
       <im:productClass>Broadband Bundle Class</im:productClass>
       <im:serviceId>1112223333</im:serviceId>
       <im:productSpec>Broadband.Bundle</im:productSpec>
       <im:lineItemPayload> [34 lines]
       <im:region>Sao Paulo</im:region>
      <osm:properties>
     <osm:orderItem [57 lines]
     <osm:orderItem [57 lines]
     <osm:orderItem [42 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [37 lines]
     <osm:orderItem [57 lines]
    </toOrderComponent>
    
  • Prolog: You can declare the order item namespace and the OSM namespace in the XQuery prolog. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
    declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom";
    
  • Body: The XQuery body returns a date and time value based on the requestedDeliveryDate order item property:

    osm:toOrderComponent[1]/osm:orderItem[1]/osm:properties[1]/*[namespace-uri()='http://oracle.communications.ordermanagement.unsupported.centralom' and local-name()='requestedDeliveryDate'][1]/text() 
    

    osm:toOrderComponent: returns the entire set of order items included in the order and returns the requested delivery date of all order items for the wait delay date and time.

Example 4-12 shows the sample XQuery to return a date time value.

Example 4-12 Wait Delay Date Time Expression

declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model"; 
declare namespace im="http://oracle.communications.ordermanagement.unsupported.centralom"; 
 
osm:toOrderComponent[1]/osm:orderItem[1]/osm:properties[1]/*[namespace-uri()='http://oracle.communications.ordermanagement.unsupported.centralom' and local-name()='requestedDeliveryDate'][1]/text() 

About Order Data Change Wait Condition XQuery Expressions

The wait for condition data change notification XQuery expression specifies a value that must exist in order item property (typically a blocking order item property) before a waiting order item starts.

This section refers to the Design Studio OSM Product Specification editor, Orchestration Plan tab, Dependencies sub tab, Wait Condition sub tab, Wait For Condition, Data Change Notification XQuery field.

  • Context: The Data Change Notification XQuery input document is the task view task data that was changed using an update order transaction.

  • Prolog: You can declare the $blockingIndexes variable in the XQuery prolog that contains an index of data element for all blocking order items. For example:

    declare variable $blockingIndexes as xs:integer* external;
    
  • Body: The XQuery body return a specific value and will wait until all blocking order items have the corresponding value and the XQuery returns true.

Example 4-13 shows the XQuery that evaluates the data change. The dependency is met when all blocking order items have reached a state of PROVISION STARTED.

Example 4-13 XQuery for Data Change Dependency: All Blocking Order Items Must Be Complete

(:   The $blockingIndexes variable contains data element indexes for all blocking order items:   :)
declare variable $blockingIndexes as xs:integer* external;
(:   Specify "PROVISION STARTED" as the data value that must be met:   :)
let $expectedMilestoneCode := "PROVISION STARTED"
(:   $milestoneValues contains a set of milestones for all blocking order items:   :)
let $milestoneValues := 
     /GetOrder.Response/_root/ControlData/Functions/ProvisioningFunction/orderItem/orderItemRef[
     fn:index-of($blockingIndexes, xs:integer(@referencedIndex)) !=
     0]/milestone[text() eq $expectedMilestoneCode]
(:   Return true only if all the milestones in ProvisioningFunction/orderItem/orderItemRef are PROVISION STARTED:   :)
return fn:count($milestoneValues) eq fn:count($blockingIndexes)

Example 4-14 shows a different example. The following example returns true when at least one blocking item is completed.

Example 4-14 XQuery for Data Change Dependency: At Least One Blocking Order Item Must Be Complete

declare namespace oms="urn:com:metasolv:oms:xmlapi:1";
declare variable $blockingIndexes as xs:integer* external;
let $component := //ControlData/Functions/NetworkProvisionFunction
let $lineItem := $component/orderItem/orderItemRef[fn:index-of($blockingIndexes, xs:integer(@referencedIndex)) != 0]
return
     if (fn:exists($lineItem))
     then
        let $statusValue := $lineItem/OrderItemStatus/text() = "completed"
        return
        if (fn:count($statusValue)>0) 
        then 
            fn:true()
        else 
            fn:false()
     else 
        fn:false() 

About Order Item Inter Order Dependency XQuery Expressions

This section refers to the Design Studio OSM Order Item Specification editor, Order Item Dependency tab, Order Item Selector XQuery field.

This XQuery expression creates dependencies between order items across orders.

  • Context: The Order Item Selector XQuery input document is typically an order item on a follow-on order (the waiting order).

  • Prolog: You can declare the OSM namespace, the cartridge namespace for the target order, and the namespace of the task that contains the data you want to query. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement";
    declare namespace im="CommunicationsSalesOrderFulfillmentPIP";
    declare namespace osmc="urn:oracle:names:ordermanagement:cartridge: CommunicationsSalesOrderFulfillmentPIP:1.0.0:view:CommunicationsSalesOrderQueryTask";
    
  • Body: The XQuery body returns the order ID of the target order and the order item property:

     <osm:dependency fromOrderId="{$parentOrderId}" fromOrderItemId="{$parentOrderItemId}"/>
    

    where

    • <osm:dependency fromOrderId: Returns the target order ID.

    • fromOrderItemId: Returns the target order item property value that controls the dependency.

Example 4-15 shows an XQuery for an inter-order dependency.

Example 4-15 Inter-Order Dependency XQuery

declare namespace ord="http://xmlns.oracle.com/communications/ordermanagement";
declare namespace im="CommunicationsSalesOrderFulfillmentPIP";
declare namespace
osmc="urn:oracle:names:ordermanagement:cartridge:
     CommunicationsSalesOrderFulfillmentPIP:1.0.0:view:CommunicationsSalesOrderQueryTask";
let $dependingLineId := fn:normalize-space(osm:properties/im:DependingSalesOrderBaseLineId)
return
     if(fn:not($dependingLineId = ''))
     then
(:   Use the data instance behavior "findOrder" to find the base order:   :)
     let $parentOrderId
           :=fn:normalize-space(vf:instance("findOrder")/ord:Order[last()]
              /ord:Amendments/ord:AmendedOrderSummary/ord:Id/text())
(:   Use the data instance behavior "getOrder" to find the associated order item ID in the base order:   :)
     let $parentOrderItemId :=
          fn:normalize-space(vf:instance("getOrder")/ord:Data/
          osmc:_root/osmc:ControlData/osmc:OrderItem[osmc:BaseLineId=$dependingLineId]/@index)
return
     if(fn:not($parentOrderId = '') and fn:not($parentOrderItemId = ''))
     then
(:   Return the dependency:   :)
     <osm:dependency fromOrderId="{$parentOrderId}" fromOrderItemId="{$parentOrderItemId}"/>
else()
else()