4 Modeling Order Recognition

This chapter describes how to model order recognition rules to receive incoming orders from external systems in an Oracle Communications Order and Service Management (OSM) solution.

About Sending Orders to OSM and Order Recognition

This section describes the order capture and submission process and how OSM recognizes and resolves various incoming orders from CRM systems to specific order types.

The following process flow is for a new order:

1. The order data is captured in a CRM system; for example, as a Siebel order. There are several order types that OSM can process (see "About Order Types" for more information). Before submitting the order to OSM, the CRM system usually performs validations, such as validating customer information from its customer database. For some orders, the order may require technical qualification, such as validating that the network has enough capacity to offer the purchased products.

2. The CRM system sends the customer order to OSM by using the OSM CreateOrder Web Service operation. The CreateOrder operation contains order data that is in the XML format of the order-source system, which is different from the OSM order format (see "Modeling OSM Data").

   The OSM Web Service API is the primary API for external clients that you can use to communicate with OSM (see OSM Developer's Guide for more information).

   Note:

   A single OSM instance can receive orders from multiple order-source systems.

3. The OSM order request processor receives the customer order and evaluates the order against order recognition rules until the order request processor finds an order recognition rule that matches the incoming customer order. Then the order request processor uses the order recognition rules to transform the requests to the OSM internal order format before creating the order.

4. After OSM has recognized and validated the incoming customer order, internally, the OSM recognition rule calls the CreateOrderBySpecification web service operation. This operation does the following:

   • Creates the order in OSM

   • Sets the order priority

   • Populates the data in the creation task

   Note:

   You can also send a CreateOrderBySpecification operation directly from external client systems in the OSM native XML format that would bypass the order recognition and transformation functionality. 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.

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

• Configure your order-source system to output orders in XML format (see "Modeling OSM Data").

• Do the following in Design Studio:

  • Populate the Data Dictionary with the data elements that the order needs. See "Modeling OSM Data" for more information.

  • Create recognition rules to recognize, validate, and transform the data.

  • Create order specifications for the types of orders you need to create in OSM. See "Modeling Orders and Permissions" for more information.

Incoming orders can use the process layer or the orchestration layer. See "Modeling Orders and Permissions" for more information.

Note:

An order can be created without recognition rules and without an orchestration plan. This is common when the order has a limited set of tasks that do not have dependencies; for example, an order that only manages service activation.

Modeling Order Recognition Rules

You model order recognition rules to accept, evaluate, and transform OSM Web Service API CreateOrder requests. The content of every CreateOrder request must match a specific order recognition rule that associates the incoming order with a target OSM order specification. If you have more than one version of the target order specification, you can target a specific version of the order specification.

During order recognition, OSM reviews 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. OSM evaluates each order based on how high the relevancy of a particular order recognition rule is. For example, a recognition rule with a relevancy of 12 evaluates first, then the rule with the relevancy of 11, then 10, and so on. An order recognition rules with a 0 relevancy should be modeled as a catch-all recognition rule. See "Modeling a Catch-All Recognition Rule" for more information.

Validating Incoming Order Data

You can model a validation rule to valid any number of things in the order data. For example, you can ensure that:

• All mandatory fields are populated on the incoming order.

• Valid characters (numeric or alphanumeric) are used for fields.

• The order has a valid status code, such as Open.

Transforming Order Data

OSM provides the following transformation rules in an order recognition rule:

• order priority rules: define the priority of the order in relation to others.

• order reference rules: define the order reference number.

• order data rules: add to or modify incoming customer order data.

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:

• Could not set order priority.

• Could not set order header reference.

• Could not create order data.

• Could not store incoming message. Message stored as attachment.

Modeling the Order Data Rule to Populate the Creation Task

An internal transformation rule always stores the raw XML input message in an XML data field as part of the order data (see "Adding the Input Message to an Order Recognition Rule" and "Adding the Input Message to the Order Template"). However, that data does not populate the fields in the creation task.

You can use an order data rule to modify data in the order. For example, you can concatenate the area code and phone number into a single data element.

You can retrieve data from external systems if it does not exist on the incoming customer order using a data instance behavior associated with the order data rule (see "Evaluating Data Instance Behaviors"). For example, the incoming customer order might have a customer address, but you need to add the geographic region to the order, which is not in the input data. You can use a web service operation, or an SQL call to an external system, to look up the region, based on the customer's address. You can then add the region code to the order.

When modeling a creation task, create a manual task, even if the order is intended to be processed automatically. Using manual tasks as creation tasks ensures that task behaviors are supported at run time if you manually create an order. This can be useful for testing purposes.

Modeling Order Priority

The order priority range specifies the acceptable range of numeric priority (between 0 and 9) that orders of a single type may use. For example, this could allow you to configure a fixed-line order type with a lower range (0 to 4) and a mobile order type with a higher priority range (5 to 9), ensuring that mobile orders are prioritized higher than fixed-line orders.

You create an order priority range by specifying a minimum and maximum priority for the order. OSM rounds priority values up or down to ensure they conform to the order priority range. For example, if you specify a priority range of 5 to 7 and an order is created with a priority of less than 5, the system assumes the intent is to provide the lowest priority allowed for the order, and the priority value of the order is set to 5. Similarly, if a priority higher than 7 is provided for another order of the same type, the system assumes the intent is to provide the highest priority allowed for the order, and the priority value of the order is set to 7.

Table 4-1 shows examples of how the order priority is set by using the order priority from the recognition rule, and the order priority range from the order specification.

Table 4-1 Order Priority Examples

Order Priority Range	Recognition Rule Order Priority 1	Recognition Rule Order Priority 5	Recognition Rule Order Priority 9
Order Priority Range 1 - 3	Priority = 1	Priority = 3	Priority = 3
Order Priority Range 3 - 5	Priority = 3	Priority = 5	Priority = 5
Order Priority Range 5 - 9	Priority = 5	Priority = 5	Priority = 9

You can set the order priority range in the Design Studio Order editor Details tab.

The order priority value is also considered when an order's tasks are run, so that automated tasks are run according to order priority. This requires that Java Messaging Service (JMS) message priority settings are configured for the JMS queues. For information about configuring JMS message priority on JMS queue, see "Configuring JMS Message Priority on JMS Queue".

You can change the order priority of an in-flight order by using the Order Management web client. You can specify permissions for which roles can change the priority. See the discussion of changing order priority in OSM Order Management Web Client User's Guide.

The automation plug-ins are executed using JMS. For internal plug-ins, OSM relays Order Priority into JMSPriority and thus ensures Order Priority to take effect during the execution of plug-ins.

For external plug-ins, for Order-Priority to take effect during the execution, the external system needs to update JMSPriority in the JMS message response with the one received in the JMS message request.

Note:

This is an optional activity and is relevant only when the execution of external plug-ins needs to acknowledge Order-Priority.

Configuring JMS Message Priority on JMS Queue

As messages arrive on a specific destination, by default, they are sorted in FIFO (first-in, first-out) order, which sorts the messages in the ascending order based on each message's unique JMSMessageID. However, you can use a destination key to configure a different sorting scheme based on other message properties such as JMSPriority and JMSCorrelationID for a destination. In traditional OSM, the OSM installer creates the osmDescendingPriorityDestinationKey destination key with JMSPriority as the Property and Descending as the Sort order. OSM cloud native comes configured with osmDescendingPriorityDestionationKey.

To configure JMS Message priority on JMS queue, do the following:

• Create a JMS Destination Key. See "Creating a JMS Destination Key (Traditional OSM Only)"

• Configure a destination key for a JMS resource. See "Configuring Destination Key for a JMS resource (Traditional OSM Only)".

Creating a JMS Destination Key (Traditional OSM Only)

To create a JMS Destination Key:

1. In the WebLogic Administration Console, expand Services > Messaging > JMS Modules.

2. In the JMS Modules table, click the JMS module that contains the configured resource.

3. In the Summary of resources table, click the New button to create a destination key.

4. Select Destination Sort Key and then click Next.

5. Enter a meaningful name for the key and click OK.

6. In the Summary of resources table, select the newly created JMS destination key.

7. Select the Sort key field and specify a message property name or the name of a message header field on which to sort messages.

8. Save the changes.

Configuring Destination Key for a JMS resource (Traditional OSM Only)

To configure destination key for a JMS resource:

1. In the WebLogic Administration Console, expand Services > Messaging > JMS Modules.

2. In the JMS Modules table, click the JMS module that contains the configured resource.

3. In the Summary of Resources table for the selected JMS module, select the JMS resource that you want to edit.

4. Move the selected destination key from the Available list to the Chosen list. The keys are ordered from most significant to least significant. If more than one key is specified, a key based on the JMSMessageID can only be the last key in the list. If JMSMessageID is not defined in the key, it is implicitly assumed to be the last key and is set as "Ascending" (FIFO) for the sort order).

5. Save the changes and restart the WebLogic server.

Creating and Configuring JMS Destination Key in OSM Cloud Native

You will need to provide the WDT for your OSM instance to provide the appropriate configuration for a new JMS Destination Key. See "Extending the WebLogic Server Deploy Tooling (WDT) Model" in OSM Cloud Native Deployment Guide for further details.

Modeling the Order Reference Number

The order reference number is an alphanumeric value supplied by the order-source system. It is usually unique, but it does not have to be unique. When OSM creates the order, OSM gives the order an OSM order ID. The original order reference number is stored as well, so the order reference number is associated with the OSM order ID.

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

Common Order Recognition 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 "Modeling a Catch-All Recognition Rule" for more information.