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

3 About Receiving and Creating OSM Orders

This chapter describes how Oracle Communications Order and Service Management (OSM) processes an order when it is received from an order-source system and how it creates an OSM order.

Before reading this chapter, read "Order and Service Management Overview" for more information.

About Receiving and Creating Orders in OSM

The typical process for receiving orders in OSM using the CreateOrder Web services operation is as follows:

  1. The order data is captured in a CRM system; for example, as a Seibel order.

  2. The CRM system sends the order to OSM by using the OSM CreateOrder Web services operation.

    The CreateOrder operation receives orders that are in the XML format of the order-source system, which is different from the OSM order format. The CreateOrder operation can recognize external order formats, and it uses a recognition rule to transform the requests to the OSM internal order format before creating the order.

    You can use Java Message Service (JMS) or HTTP or HTTPS to send orders to OSM. Use JMS on production systems, because it provides quality-of-service guarantees not available from HTTP or HTTPS. Use HTTP or HTTPS on development and test systems.

    Note:

    A single OSM instance can receive orders from multiple order-source systems.
  3. After OSM has recognized and validated the incoming customer order, the OSM recognition rule calls the CreateOrderBySpecification Web services operation. This operation does the following:

    • Creates the order in OSM

    • Sets the order priority

    • Populates the data in the creation task

    The CreateOrderBySpecification operation receives orders from systems that can provide order requests in the OSM native XML format. The CreateOrderBySpecification operation references an order specification that you define in Oracle Communications Design Studio, and the order details must conform to that order specification.

    The CreateOrderBySpecification Web services operation is typically used for sending an order to an instance of OSM running in the service order management role. In that case, OSM creates the order and begins processing it.

  4. If the order is created successfully, and the default order process is an orchestration process, OSM begins generating the orchestration plan. If the default process is a workflow process or a workstream process, OSM begins processing the tasks in the default process.

    If OSM is unable to create the order by using the CreateOrderBySpecification operation, the in-bound order is handled in one of two ways:

    • If the order type is not valid, a failed order is created with the in-bound order attached.

    • If the order type and source are valid, the in-bound order is put on the JMS redelivery queue. OSM attempts to receive the order again, up to the receive limit configured for the queue. When that limit is reached, the failed message is moved to an error queue.

To receive and create orders, you need to do the following:

How Incoming Customer Orders are Structured

When received by OSM, the incoming customer order typically consist of these sections:

Figure 3-1 shows part of a customer order, received from a CRM system.

Figure 3-1 Example of a Customer Order

Description of Figure 3-1 follows
Description of "Figure 3-1 Example of a Customer Order"

Figure 3-2 shows one of the order line items. Included in this order line item are the requested delivery date and the action to take (Add).

Figure 3-2 Example Order Line Item in a Customer Order

Shows one of the order line items.

The AIA Order-to Activate solution uses three sections, an AIA header, an order header, and order line items.

Understanding Order Recognition

Order recognition is the process of determining the type of an incoming customer order so it can be mapped to an order type in OSM. Recognition rules allow OSM to accept any input message structure.

During order recognition, OSM steps through a prioritized list of recognition rules to determine which rule applies to the in-bound order. Each recognition rule is associated with an order specification. The first rule that evaluates to true determines the order specification to use for the incoming customer order and which validations and transformations are required, if any. Rules are evaluated in an order based on a property called relevancy, which is defined as part of the recognition rule specification in Design Studio.

Order recognition rules use XQuery expressions to match incoming customer orders. See "About Recognition Rule XQuery Expressions" for information about creating order recognition XQuery expressions.

About Recognition Rule Relevancy

Relevancy determines the order in which the OSM server evaluates the order recognition rules at run time. OSM evaluates a rule with a higher relevance before it evaluates a rule with a lower relevance. For example, OSM evaluates a rule with a relevancy value of 2 before it evaluates a rule with a relevancy value of 1. At run time, OSM uses the first order recognition rule that evaluates to true.

Recognition Rule Errors

There are two possible errors during order recognition:

  • A recognition rule fails to run; for example, because of bad syntax. Evaluation of other rules continues.

  • The in-bound order is not recognized. If all recognition rules run and fail to find a match, then no OSM order can be created. This failure generates fallout, which you can view and manage as an order failure in the Order Management Web client.

    To avoid this kind of failure, you can create a lowest-relevancy catch-all rule that recognizes any in-bound order and maps it to a default order specification. See "Creating a Catch-All Recognition Rule" for more information.

Creating a Catch-All Recognition Rule

An order that fails to be recognized by any recognition rule is rejected by OSM, and an error is returned by the Web services operation to the order-source system. To make sure that all orders are entered into OSM, create a catch-all recognition rule that accepts all incoming customer orders.

To configure this recognition rule:

  • Set the relevancy to 0, and set the relevancy for all other recognition rules higher than 0, so they are processed first.

  • Include the following recognition rule XQuery:

    fn:true()
    
  • Select the Fail Order check box, and enter a reason. For example:

    No valid recognition rule found.
    

Using this lowest-level recognition rule, an invalid order is recognized and then fails during validation. It then transitions to the Failed state and is kept by OSM.

Understanding Order Validation

When an incoming customer order is recognized, OSM checks the order using a validation rule XQuery defined in the order recognition rule. The validation step ensures that the order is syntactically correct.

For example, a validation rule can determine that:

See "About Validation Rule XQuery Expressions" for information about creating validation rule XQueries.

Understanding Order Transformation

Incoming customer orders might come from multiple order-source systems. Data is often represented differently in different systems; for example, telephone number formats might include varying numbers of digits. You can use transformation rules to normalize data and to make it usable in OSM and in external systems. For example, you might use transformation rules to add information to the customer order data or to transform the generic order items and their attributes into specific attributes of an order required in an external system.

In addition, you use transformation rules to add data and properties to an order when it is created. This includes:

You use XQuery expressions to define transformation rules. Figure 3-3 shows the Transformation tab in the Design Studio Recognition Rule editor.

Figure 3-3 Transformation Tab in Design Studio Recognition Rule Editor

Shows Transformation tab in Recognition Rule editor.

At run time, the OSM server always runs all transformation rules, regardless of the failure of any transformation rule. Running all transformation rules ensures that the order is populated with all available data.

If a transformation rule fails, the order is populated with whatever data is available, and the order is placed in a Failed state with reasons corresponding to the type of transformation rule that failed:

Adding the Input Message to the Order Template

OSM can add the input message to the order template automatically. To do so, you specify the data structure of the incoming customer order in the order's recognition rule. You can select from the Data Dictionary a previously imported XML structure, or a data element from a previously imported XML structure. At run time, when a recognition rule evaluates to true, OSM adds this input message to the order template (as an XML data type) to contain the incoming customer order. Figure 3-4 shows an input message specified in a recognition rule.

Figure 3-4 Input Message Specified in a Recognition Rule

Shows an input message specified in a recognition rule.

The order uses the XML data type. Figure 3-5 shows the order in the order template.

Figure 3-5 Incoming Customer Order Added to the Order Template

Shows the order in the order template

Modeling Recognition Rules

When you define recognition rules in Design Studio, you configure the following attributes:

You can create the following recognition, validation, and transformation rules:

Order Recognition Rule XQuery Expressions

The following sections provide reference information about order recognition rule XQueries.

About Recognition Rule XQuery Expressions

This section refers to the Design Studio OSM Order Recognition Rule editor, Recognition tab, Recognition Rule XQuery field.

The Order Recognition Rule editor Recognition Rule XQuery expression specifies a customer order and associates it with an OSM target order type. The XQuery has the following characteristics:

  • Context: The input document for the Recognition Rule 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 namespace for the customer order if you want to use the contents of the order as part of the recognition rule or you can omit the declaration if you only want to check the incoming customer order namespace. For example:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
    
  • Body: You must match the namespace you want to select for order processing with the namespace of the incoming customer order. For example, the following expression retrieves the namespace URI from the incoming customer order (fn:namespace-uri(.)) and compares it with this URI: 'http://xmlns.oracle.com/InputMessage':

    fn:namespace-uri(.) = 'http://xmlns.oracle.com/InputMessage'
    

    If you have declared a namespace in the prolog, you can also check to see if specific values exist in the order. For example, you can use the fn:exists function to check that an element exists. Or you can use a comparison expression such as = (equal to) or != (not equal to) to compare a value in the customer order with a value in the XQuery.

Tip:

Recognition rules are global entities within OSM, meaning that they could apply to any CreateOrder operation. An incoming customer order could be recognized by a recognition rule deployed in the system that you did not intend to be matched if you are not careful with the relevancy settings and the recognition rule. For more information about relevancy, see "About Recognition Rule Relevancy".

For example, in a simple scenario, the XQuery is based on a namespace:

fn:namespace-uri(.) = 'http://xmlns.oracle.com/InputMessage'

The input message XML file includes the following line, which matches the namespace specified in the recognition rule:

<im:order xmlns:im="http://xmlns.oracle.com/InputMessage"

The XQuery expression returns a Boolean expression, for example, fn:true() or fn:false()

The following example searches in a specific type of order:

fn:namespace-uri(.) = 'http://xmlns.oracle.com/communications/sce/dictionary/CentralOMManagedServices-Orchestration/CustomerSalesOrder'

Figure 3-6 shows a recognition rule in Design Studio. The recognition rule is based on a namespace, and the target order is OSMCentralOMExampleOrder.

Figure 3-6 Recognition Rule in Design Studio

Shows a recognition rule in Design Studio.

In a more complicated scenario, you might create an XQuery expression that looks for a specific namespace and also interrogates the data within the incoming customer order. Example 3-1 shows a recognition rule that recognizes an order based on the following criteria:

  • Namespace

  • Value of the typeCode data element in the incoming customer order. In this case, the value must be OSM-BDB. This indicates an OSM business-to-business order.

  • The value of the FulfillmentModeCode data element in the incoming customer order. In this case, the value can be DELIVER, CANCEL, or TSQ.

Example 3-1 Recognition Rule for Broadband Service

declare namespace provord=";http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/ProvisioningOrder/V1";;
declare namespace corecom=";http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2";;
fn:namespace-uri(.) = 'http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/ProvisioningOrder/V1'
and
fn:exists(../provord:ProcessProvisioningOrderEBM/provord:DataArea/provord:ProcessProvisioningOrder/corecom:Identification/corecom:BusinessComponentID)
and
../provord:ProcessProvisioningOrderEBM/provord:DataArea/provord:ProcessProvisioningOrder/provord:TypeCode/text() = 'OSM-BDB'
and
(
../provord:ProcessProvisioningOrderEBM/provord:DataArea/provord:ProcessProvisioningOrder/provord:FulfillmentModeCode/text() = 'DELIVER'
or
../provord:ProcessProvisioningOrderEBM/provord:DataArea/provord:ProcessProvisioningOrder/provord:FulfillmentModeCode/text() = 'CANCEL'
or
../provord:ProcessProvisioningOrderEBM/provord:DataArea/provord:ProcessProvisioningOrder/provord:FulfillmentModeCode/text() = 'TSQ'
)

See "Understanding Order Recognition" for more information about order recognition rules.

About Validation Rule XQuery Expressions

This section refers to the Design Studio OSM Order Recognition Rule editor, Recognition tab, Validation Rule XQuery field.

The Order Recognition Rule editor Validation Rule XQuery expression specifies nodes in the incoming customer order that must evaluate to true to accept the customer order into the system. The XQuery has the following characteristics:

  • Context: The input document for the Validation Rule 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 Validation Rule XQuery is the customer order. You can declare the customer order namespace in the XQuery prolog. For example:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
    
  • Body: The validation rule must specify customer order parameters or parameter values to evaluate to true for the validation to be successful. If the validation fails, the expression should return an error message.

    In addition, if the Validation Rule fails, OSM automatically creates the order and sets the order state to Failed. The inbound message and validation failure output are attached to the order for reference. You can display and manage the order failure in the Order Management Web client.

The following sample XQuery checks for the existence of a sender ID:

if (fn:exists(./header/c:Sender/c:ID) and ./header/c:Sender/c:ID != '')
  then (true())
     else concat("SEVERE", "Message Header should contain Sender ID", header/Sender/ID")

The following sample XQuery checks for correct values in the typeCode data element in the incoming customer order:

if (fn:exists($orderLine/im:ItemReference/im:TypeCode) 
    and 
    $orderLine/im:ItemReference/im:TypeCode != '') 
then 
    (
    if ($orderLine/im:ItemReference/im:TypeCode = "PRODUCT" or 
        $orderLine/im:ItemReference/im:TypeCode = "OFFER" or 
        $orderLine/im:ItemReference/im:TypeCode = "BUNDLE") then ()
    else
       local:reportIssue("ERROR", "Product Type should be one of: PRODUCT, OFFER, BUNDLE", 
             $lineNum, "ProcessProvisioningOrderEBM/DataArea/ProcessProvisioningOrder/
                        ProvisioningOrderLine/ItemReference/TypeCode")
)

Given this XQuery sample, the following part of a customer order would evaluate to true because the typeCode element value is BUNDLE.

<!-- FIXED BUNDLE - BUNDLE -->
<im:salesOrderLine>
          <im:lineId>2</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>Fixed Bundle</im:name>
                                        <im:typeCode>BUNDLE</im:typeCode>
                                        <im:specificationGroup />
        </im:itemReference>
</im:salesOrderLine>

See "Understanding Order Validation" for more information about validation rules.

About Order Priority XQuery Expressions

This section refers to the Design Studio OSM Order Recognition Rule editor, Transformation tab, Order Priority XQuery field.

The Order Recognition Rule editor Order Priority XQuery expression specifies an element value in the incoming customer order that identifies the order priority. The XQuery has the following characteristics:

  • Context: The input document for the Order Priority 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. For example:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
    
  • Body: The Order Priority body must specify the node that contains the order priority value.

See "About Specifying the Order Priority" for more information about creating order priority XQuery expressions in the order recognition rule and about creating order priority ranges for an order type.

About Order Reference XQuery Expressions

This section refers to the Design Studio OSM Order Recognition Rule editor, Transformation tab, Order Reference XQuery field.

The Order Recognition Rule editor Order Reference XQuery expression specifies an element value in the incoming customer order that identifies the order reference. The XQuery has the following characteristics:

  • Context: The input document for the Order Reference 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. For example:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
    
  • Body: The Order Reference body must specify the node that contains the order reference value.

The following example shows a transformation rule XQuery expression that retrieves the order reference number (as a string) from the numSalesOrder field in the incoming customer order:

declare namespace im="http://xmlns.oracle.com/InputMessage";
let $order := ../im:order
return
$order/im:numSalesOrder/text()

See "Understanding Order Transformation" for more information about order reference.

About Order Data Rule XQuery Expressions

This section refers to the Design Studio OSM Order Recognition Rule editor, Transformation tab, Order Data Rule XQuery field.

The Order Recognition Rule editor Order Data Rule XQuery expression specifies nodes in the incoming customer order that must be used in the creation task. The XQuery has the following characteristics:

  • Context: The input document for the Order Data Rule 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. For example:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
    
  • Body: The Order Data Rule body must map the customer order element values to the corresponding creation task Task Data values.

    Figure 3-7 shows the data defined in the creation task in Design Studio.

    Figure 3-7 Creation Task Data

    Shows data defined in the creation task in Design Studio

    The following example shows the same fields in the incoming customer order:

    <im:customerAddress>
         <im:locationType>Street</im:locationType>
         <im:nameLocation>Jangadeiros</im:nameLocation>
         <im:number>48</im:number>
         <im:typeCompl>floor</im:typeCompl>
         <im:numCompl>6</im:numCompl>
         <im:district>Ipanema</im:district>
         <im:codeLocation>5000</im:codeLocation>
         <im:city>Rio de Janeiro</im:city>
         <im:state>RJ</im:state>
         <im:referencePoint>Gen. Osorio Square</im:referencePoint>
         <im:areaCode>22420-010</im:areaCode>
         <im:typeAddress>Building</im:typeAddress>
    </im:customerAddress>
    

    The following XQuery expression specifies a variable for the location of the customerAddress node in the customer order that can then be used to map customerAddress child element values to CustomerDetails task data elements:

    let $details := $customer/mes:customerAddress
    

    The following XQuery expression performs this mapping:

    return<_root>
    <CustomerDetails>
         <locationType>{$details/im:locationType/text()}</locationType>
         <nameLocation>{$details/im:nameLocation/text()}</nameLocation>
         <number>{$details/im:number/text()}</number>
         <typeCompl>{$details/im:typeCompl/text()}</typeCompl>
         <numCompl>{$details/im:numCompl/text()}</numCompl>
         <district>{$details/im:district/text()}</district>
         <codeLocation>{$details/im:codeLocation/text()}</codeLocation>
         <city>{$details/im:city/text()}</city>
         <state>{$details/im:state/text()}</state>
         <referencePoint>{$details/im:referencePoint/text()}</referencePoint>
         <areaCode>{$details/im:areaCode/text()}</areaCode>
         <typeAddress>{$details/im:typeAddress/text()}</typeAddress>
    </CustomerDetails>
    </_root>
    

In the following example, the XQuery expression returns the <_root> portion of the order. The ControlData portion of the order is populated by the system during the generation of the orchestration plan.

declare namespace cso="http://xmlns.oracle.com/communications/sce/dictionary/CentralOMManagedServices-Orchestration/CustomerSalesOrder";
let $customer :=  //cso:CustomerAccount
return
<_root>
<OrderHeader>
<AccountIdentifier>{$customer/cso:AccountID/text()}</AccountIdentifier>
</OrderHeader>
</_root>

See "Understanding Order Transformation" for more information about order reference.