6 Modeling the Order Transformation Manager

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

Understanding the Order Transformation Manager

The order transformation manager provides users with the ability to transform order items. For example, you can use the order transformation manager to transform customer-focused order items (what the customer bought) to service-focused order items (the services that equate to what the customer bought). It enables you to set up guidelines for order transformation that do not need to be changed due to product changes. Instead of writing a lengthy XQuery, users can model the order transformation in Oracle Communications Design Studio. The order transformation manager also provides visibility in the Order Management web client into service processing, making it easier to see how customer services are being transformed into the services being processed by OSM. In addition, the order transformation manager enables you to propagate data upstream and assists in status consolidation.

Order Transformation Manager in Runtime

In runtime, when the order transformation manager is triggered, OSM initiates the following process for each domain that has order items associated with it:

  1. The appropriate transformation sequence is accessed to determine the appropriate transformation stages.

  2. The transformation stages are executed in order. For each transformation stage:

    1. The stage condition is evaluated to determine whether the stage should be run. If not, OSM moves to the next stage.

    2. The list of source order items is gathered: both context order items (the order items to be transformed) and related order items (order items that might contribute data to the transformed order items).

    3. The list of mapping rules that apply to the named relationships for the transformation stage is gathered.

    4. The mapping rules are processed, creating transformed order items and mapping parameters to them.

  3. The transformed order items are processed in the same way as original order items, for example being processed by order components.

The Order Transformation Manager and the Conceptual Model

Entities are realized into the OSM cartridges by different means. Following is a description of how the different entities are realized into OSM or referenced by OSM.

  • Provider Functions: Provider functions in the conceptual model are realized into OSM as transformation managers.

  • Named Relationships: These entities are realized into OSM when they are referenced by OSM entities, such as mapping rules.

  • Domains: Domains are referenced in OSM by transformation managers and mapping rules.

  • Products and Customer-Facing Services: These entities are realized into OSM when they are included in relationships that are used by the order transformation manager and when their parameters are mapped to OSM order items using order item parameter bindings.

Figure 6-1 depicts general relationships between conceptual model entities and OSM entities that are used by the order transformation manager.

Figure 6-1 Relationships Between Conceptual Model Entities and OSM Entities

Surrounding text describes Figure 6-1 .

OSM Entities Used in the Order Transformation Manager

The order transformation manager uses several entities in Design Studio for OSM.

  • Transformation manager: The transformation manager entity enables you to select the transformation sequences for the service domains within a provider function. This entity is the entry into the order transformation functionality.

  • Transformation sequence: The transformation sequence enables you to define the transformation stages and the logic to be used at each transformation stage. Transformation stages define the source and target order items and the relationship between them for each step of the transformation.

  • Order item specifications: You must define an original (source) order item specification that defines the structure of the incoming order items and a transformed (target) order item specification that defines the structure of the output of the order transformation for the order transformation manager. If the same structure is used for both, the same order item specification can be defined for both original and transformed order items. See "About Order Items" for more information about configuring and using order items.

  • Mapping rules: Mapping rules define the way that original order items are transformed into transformed order items. You use mapping rules to define how transformed order items are generated and how their parameters and properties are populated. The data elements you can use as a source for the mappings are the parameters on the original order item in addition to the parameters on the actions defined for the order item. There are many different ways to generate the parameters and properties for the transformed order items. These methods include:

    • You can map parameters from the source order item to the target order item. You can copy the value from the source to the target, transform the value of the source parameter or property to a value on the target based on pre-defined value mappings or on the units of measure for each, and you can write XQuery expressions to do the value transformation.

    • You can map order item instances from the source order item to parameters or properties on the target order item. You can either set up a specific value to use on the transformed order item based on the presence of the source order item, or you can use XQuery to determine the value for the parameter or property on the transformed order item.

    For more information about mapping rule types, see the Modeling OSM Orchestration Help.

    Mapping rules also enable you to map actions for the transformed order item either using the actions defined in the named relationship or defining the actions specifically for the mapping rule, based on the input, output, and current actions of the order items.

  • Order Item Parameter Bindings: The order item parameter bindings enable you to bind the parameters from a conceptual model entity to parameters on an order item. They also enable you to determine the mapping between the parameters on the conceptual model entity and the properties on an order item. In addition, they enable you to transform the parameters from the customer order line before they are added to the conceptual model entity. One use for this would be to transform name/value-pair-type parameters from the incoming order into more strongly typed parameters on the conceptual model entity.

  • Transformation Tasks: If you want to call the order transformation manager from a process instead of before the orchestration plan is generated, you do this using a transformation task. See "Calling the Order Transformation Manager" for more information. The transformation task is very much like an automated task, except that by default it has an appropriate automation plug-in defined for it and provides the ability to define the transformation manager to call.

Calling the Order Transformation Manager

There are two methods for calling the order transformation manager:

  • If you want the order transformation manager to run before the orchestration plan is generated, select Invoke Order Transformation Manager in the Orchestration Process and select a provider function. This is the recommended practice, as it causes the order transformation manager to be run in the context of the whole order and with one call.

  • If you want to call the order transformation manager at a different place in the order process, you can include a transformation task in an OSM process. The transformation task calls a specific transformation manager that you define in the task. This option provides flexibility in the following ways:

    • It enables you to call the order transformation manager multiple times in the process flow for different provider functions. You should not call the order transformation manager more than once for the same provider function.

    • It provides the option not to persist the results of the transformation to the order template. This is useful if the order transformation manager results are transient or going to be passed through directly to a southbound system. Additionally, this gives the user the flexibility to format any results that are going to be persisted in whichever structure they want.

    • It provides the ability to filter the order items passed into the order transformation manager. This enables a user to ensure that the order transformation manager only processes relevant order items.

The order transformation manager works the same regardless of the way it is called.

Using the Distributed Order Template with the Order Transformation Manager

When you are using the order transformation manager, you must use the distributed order template for the order item specification that contains transformed order items. For the order item specification that contains original order items, using the distributed order template is optional. See "About Using a Distributed Order Template" for general information about the distributed order template.

The distributed order template uses namespaces to determine the data structure that should be used. For transformed order items, the namespace depends on the source of the data for the transformed order item. Data that is defined in the order item specification itself will use the namespace for the order item specification, the same way that data would be referenced for an input order item. Following is an example of an XQuery reference to the lineItemID property on the OutputOrderItem order item with the namespace http://ex_output.com:

/ControlData/OrderItem[@type='{http://ex_output.com}OutputOrderItem']/lineItemID

Data that has been derived from a common model entity, for example an action, will use a different format. In the following situation:

  • Order item namespace: http://ex_output.com

  • Order item name: OutputOrderItem

  • Name of the parameter assigned as the Dynamic Parameter Property in the order item specification: dynamicParams

  • Conceptual model cartridge name: Model_Broadband

  • Conceptual model cartridge version: 1.0.0.0.0

  • Conceptual model entity (in this case an Action) name: SA_Add_Internet

  • Parameter name on SA_Add_Internet: serviceLevel

The reference would look like this:

/ControlData/OrderItem[@type='{http://ex_output.com}OutputOrderItem']/dynamicParams[@type='{Model_Broadband/1.0.0.0.0}SA_Add_InternetType']/serviceLevel

The parameters from the conceptual model entity are contained in the dynamicParams element on the transformed order item. The type for the parameters contained in the conceptual model entity has the string "Type" appended to the name of the entity. Thus, the type contains SA_Add_InternetType rather than just SA_Add_Internet.

Modeling OTM With Calculate Service Order

Calculate Service Order is a specific provider function that is delivered via design patterns in Design Studio. The Calculate Service Order provider function is the functional module that transforms customer orders into service orders.

Using Calculate Service Order has two parts. First, you must run the relevant design patterns to set up the framework, and then you must configure the other required entities that are specific to your implementation.

Calculate Service Order Design Patterns

Calculate Service Order includes two design patterns:

  • The Design Studio core software contains a design pattern (Common Model Base Data) that sets up the base data for the conceptual model. The following entities that are created in the conceptual model support Calculate Service Order:

    For more general information about these entities, see the information about designing solutions in Design Studio Concepts.

  • Design Studio for OSM contains a design pattern (Calculate Service Order) that contains OSM entities to support Calculate Service Order:

About the Calculate Service Order Provider Function

The Calculate Service Order provider function is a logical entity that groups all the metadata required to perform the transformation. It also provides the ability to determine what types of entities and relationships can be used in the transformation and the method used to realize the provider function into OSM.

The Calculate Service Order provider function defines the following associations:

  • The input (Product) and output (Customer Facing Service and Resource) conceptual model entities

  • The relationship types (Primary and Auxiliary)

About Calculate Service Order Relationship Types

Calculate Service Order also contains the definitions of the following relationship types:

  • Primary: In this relationship type, transformed order items are created from original order items. Action codes are normally transferred to the target without being changed, or you can define rules to change the action types.

  • Auxiliary: In this relationship type, transformed order items are enriched, but no new transformed order items are created. Action codes are translated based on the action type of the source item combined with the current action type of the target item. If the target action type is None, the source action type will be transferred to the target without being changed. If the source and target action types are both defined to something other than None, the action code of the target is changed to Modify. Otherwise, the target action code is unchanged.

These action types are the default for the relationship type. In a mapping rule, you can either use the default from the relationship type or you can define specific rules for a named relationship to be used for the mapping rule.

About the Calculate Service Order Transformation Sequence

The transformation sequence (CalculateServiceOrder) that is created by the OSM design pattern for Calculate Service Order contains the following transformation stages. These stages process order items based on an order item hierarchy. See "Modeling Order Item Hierarchies" for more information about the way order items can be arranged in hierarchies. You can edit these stages using Design Studio, if you need the transformation to work differently.

  1. ProcessPrimaryRelationships: This stage creates transformed order items from original order items. Parameters from the original order item are also mapped to parameters on the transformed order item.

  2. ProcessDescendantItems: This stage looks at child order items of the original order items and uses them to provide auxiliary data on the transformed order items. This can happen in two ways: the child order item itself may map to a data element on the transformed order item, or parameters from the child order item may map to parameters on the transformed order item. The child order items considered in this stage are not only the immediate children of the original order item, but also their children, to the bottom of the order item hierarchy.

  3. ProcessSiblingItems: This stage is similar to the ProcessDescendantItems stage, except that the order items that are contributing data to the transformed order item are the siblings, rather than the descendants, of the original order item. As in the ProcessDescendantItems stage, the order items can provide auxiliary data by the sibling order item mapping to a data element on the transformed order item, or by parameters from the sibling order item mapping to parameters on the transformed order item.

  4. ProcessAncestorItems: This stage is also similar to the ProcessDescendantItems stage. In this stage, the order items considered are the parent order items instead of the children. As in the ProcessDescendantItems stage, the order items can provide auxiliary data by the parent order item mapping to a data element on the transformed order item, or by parameters from the parent order item mapping to parameters on the transformed order item. The parent order items considered in this stage are not only the immediate parents of the original order item, but also their parents, to the top of the order item hierarchy.

User-Created Entities for Calculate Service Order

In addition to the entities created by the design patterns, you must also create entities with information specific to your implementation. Some of these entities are in the conceptual model, and some are in OSM.

In the conceptual model, you will need to model at least some of the following:

  • Products

  • Customer Facing Services

  • Resources

  • Resource Facing Services

  • Actions

  • Action Codes

  • Data elements

In OSM, you will need to model all of the following:

  • Order item specifications for the original (source) and transformed (target) order items

  • Transformation manager

  • Mapping rules

  • Order item parameter bindings: OSM has a design pattern to facilitate creating these bindings

Modeling OTM Without Calculate Service Order

If the supplied Calculate Service Order order transformation does not transform the order items the way you need, to such an extent that you do not think that editing the supplied entities would work for your situation, you have the option of configuring the order transformation manager from scratch instead.

To configure the order transformation manager if you are not using Calculate Service Order:

  1. Model conceptual model entities. For more information about modeling these entities, see the Design Studio Platform Help.

    1. Create a provider function.

    2. Create relationship types.

    3. Create one or more functional areas.

    4. Create a domain in the conceptual model.

    5. Model customer-facing services in the conceptual model.

    6. Model products in the conceptual model.

    7. Model named relationships in the conceptual model.

    8. Add the products to the domain in the conceptual model.

    9. Model a provider function in the conceptual model.

    10. Model data in the conceptual model, including keys for conceptual model entities.

  2. Model the order item specifications for the original and transformed order items:

    1. Model the order item recognition. This is usually a parameter on the customer order line item, such as Fulfillment Item Code.

    2. Model order item properties, including a property for order item recognition, a property to contain dynamic parameters created by the order item parameter binding, and properties for the order item ID and action.

  3. Model order item parameter bindings to create typed and named parameters from parameters that may have been in name/value pairs in the incoming customer order line item.

  4. Model mapping rules. These rules create order items and order item parameters on transformed order items based on original order items (that is, the order items and parameters from the customer order). The following types of mappings are available:

    • Entity-to-entity mapping: This creates a new transformed order item from an original order item. For example, you can use this to create a transformed order item representing a line from an original order item representing a major service.

    • Attribute-to-attribute mapping: This type of mapping creates new parameters on the transformed order item based on parameters on the original order item.

    • Entity-to-attribute mapping: This type of mapping creates new parameters on the transformed order item based on the presence of particular original order items. For example, an original order item representing a feature might be mapped to a parameter for that feature on an order item representing a new line.

  5. Model a transformation sequence. This involves modeling a series of transformation stages. Each transformation stage includes the following steps:

    1. Identify context order items for the transformation stage. These nodes are the original order items that will be available for transformation. You can select these nodes either by selecting an order item property that the original order items will have in common or by defining an XQuery expression to select them.

    2. Identify related order items for the transformation stage. These order items will be able to contribute data to the transformed order items. You can select these nodes either by their relation to the context order items (parent, sibling, child) or using an XQuery expression. The relationships between the order items will be based on the physical order item hierarchy defined in the order item specification.

    3. Select the relationship and relationship type that will be available to the transformation stage. For example, the transformation stage may be set up to include a Primary relationship between the Broadband product and the BroadbandInternetAccess customer-facing service.

    4. Determine whether the stage should be conditional, and if so, write a condition for it.

  6. Create a transformation manager that links the service domains and transformation sequences that you have created.