A XQuery Examples

You use XQuery expressions in various locations to implement key aspects of the Oracle Communications Order and Service Management (OSM) orchestration functionality. For information about these XQuery expressions, refer to the following topics:

General XQuery Information

This topic contains general or reference information about XQuery that applies the same in different situations.

When working with XQuery expressions, see the following topics:

About Creating XQuery Expressions with Design Studio

In general, the way you enter XQuery information into editors in Oracle Communications Design Studio is the same, regardless of the editor. The XQuery control in Oracle Communications Design Studio generally has three tabs: XQuery, Instances, and Information. Following are general instructions for entering XQuery information into each of these tabs in Design Studio.

Using the XQuery Tab

The XQuery tab allows you to configure XQuery-based rules or elements, or identify the source of the XQuery-based rules or elements. Select one of the following options:

  • Select None if the XQuery configuration is optional and not configured. When you select this option, Design Studio disables the remaining options in the subtabs.

  • Select Expression and enter the XQuery expression in the corresponding text box. Click Edit to open the Edit XQuery dialog box, which displays the configured XQuery expression in a larger and resizable text box. You can edit the expression in the Edit XQuery dialog box and click OK to save your changes, or click Cancel to dismiss the dialog box without saving the changes.

    Note:

    Design Studio provides XQuery validation on basic syntax and semantics, and denotes errors with Problem markers.
  • Select File to denote that the XQuery configuration is located in a file saved to the project resources directory. This option enables you to write your XQuery expressions using any XQuery editing application you have installed in your Eclipse environment. See the Eclipse online Help topic Associating editors with file types for more information.

    Click Select to open the Select XQuery File dialog box, which displays all XQuery files contained in the project resources directory. Select the appropriate XQuery file and click OK.

  • Select URI to denote that the XQuery configuration is located in a remote URI location. For example, you might enter:

    http://osm_server/AIARecognitionRule.xqy

Click Properties to open the Properties view, where you can define the following information for the XQuery:

  • Annotation: The optional XML annotation element allows you to provide information about the XQuery. Enter information (for example, HTML-formatted information) for external systems into the Annotation <appinfo> field. Enter information for human users into the Annotation <documentation> field.

  • Language: When you work with multiple languages, you can select a different language for displaying the description and annotation. For more information, see "Defining Language Preferences" in Modeling OSM Processes Help.

Using the Instances Tab

You can define a Data Instance behavior to obtain data that is not included in the order data and make that data available to the rule. Click Add to add a Data Instance behavior. Select the Data Instance behavior and click Properties to configure the Data Instance behavior.

For more information, see "Defining Data Instance Behavior Properties" in Modeling OSM Processes Help.

Using the Information Tab

Use this tab if you want to describe the intended use of the rule. For example, you might describe the functionality of a complex rule or provide instructions on its use.

OSM XQuery Functions

OSM-specific XQuery functions are available to you when writing XQuery expressions. These XQuery functions are contained in classes that you can declare in the prolog of your XQuery expression.

To see specifics about the functions available, install the OSM SDK and extract the OSM Javadocs from the OSM_home/SDK/osm7.w.x.y.z-javadocs.zip file (where OSM_home is the directory in which the OSM software is installed and w.x.y.z represents the specific version numbers for OSM). See OSM Installation Guide for more information about installing the OSM SDK.

The specific classes that contain XQuery functions you might use are:

  • OrchestrationXQueryFunctions: This class contains XQuery functions that are used in OSM Orchestration. To declare this class, put the following declaration in the prolog of your XQuery expression:

    declare namespace osmfn = "java:oracle.communications.ordermanagement.orchestration.generation.OrchestrationXQueryFunctions";
    
  • XQueryFunctions: This class contains XQuery functions that are used in the order transformation manager. To declare this class, put the following declaration in the prolog of your XQuery expression:

    declare namespace otmfn = ”java:oracle.communications.ordermanagement.orchestration.transformation.XQueryFunctions.”;
    

Referencing Items from a Distributed Order Template in XQuery Expressions

The distributed order template is an option you can set on an order item specification to modify the method used to store order item data. For more general information about the distributed order template, see OSM Concepts.

When using a distributed order template, any XQuery expressions that reference order item data must be in a particular format.

For any order item that is not a transformed order item, you must include the namespace of the order item specification. Following is an example of an XQuery reference to the lineItemID property on the InputOrderItem order item with the namespace http://ex_input.com:

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

For transformed order items, the format 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 name: OutputOrderItem

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

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

  • Conceptual model cartridge name: Model_Broadband

  • Conceptual model cartridge version: 1.0.0.0.0

  • 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

Note that 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.

Order Recognition Rule XQuery Expressions

The following topics provide reference information about order recognition rule XQuery expressions:

About Recognition Rule XQuery Expressions

This topic describes how to use the Order Recognition Rule editor Recognition Rule area XQuery tab to write an expression that 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. For more information about typical customer order structures, see OSM Concepts.

  • 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 can apply to any CreateOrder operation. Configure the relevancy settings and the recognition rule carefully to avoid having an incoming customer order recognized by a recognition rule that you do not intend. For more information about relevancy, see OSM Concepts.

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'

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. The following example 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.

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'
)

For more information about order recognition rules see OSM Concepts.

About Validation Rule XQuery Expressions

This topic describes how to use the Order Recognition Rule editor Validation Rule area XQuery tab to write an expression that 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. For more information about typical customer order structures, see OSM Concepts.

  • 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>

For more information about validation rules see OSM Concepts.

About Order Priority XQuery Expressions

This topic describes how to use the Order Recognition Rule editor Order Priority area XQuery tab to write an expression that 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. For more information about typical customer order structures, see OSM Concepts.

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

For more information about creating order priority XQuery expressions in the order recognition rule and about creating order priority ranges for an order type, see OSM Concepts.

About Order Reference XQuery Expressions

This topic describes how to use the Order Recognition Rule editor Order Reference area XQuery tab to write an expression that 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. For more information about typical customer order structures, see OSM Concepts.

  • 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()

For more information about order reference, see OSM Concepts.

About Order Data Rule XQuery Expressions

This topic describes how to use the Order Recognition Rule editor Order Data Rule area XQuery tab to write an expression that 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. For more information about typical customer order structures, see OSM Concepts.

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

    The following example shows the fields in an 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>
    

    Following is a sample order data in a creation task. In the example, the following data is contained in a CustomerDetails element:

    • locationType

    • nameLocation

    • number

    • typeCompl

    • numCompl

    • district

    • codeLocation

    • city

    • state

    • referencePoint

    • areaCode

    • typeAddress

    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>

For more information about order data rules, see OSM Concepts.

Decomposition XQuery Expressions

This topic includes information about order recognition rule XQuery expressions 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 topic describes how to use the Orchestration Sequence editor Order Item Selector area XQuery tab to write an expression that 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. For more information about typical customer order structures, see OSM Concepts.

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

The following example shows an order item selector XQuery where 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.

declare namespace im="http://xmlns.oracle.com/InputMessage";
.//im:salesOrderLine

About Order Sequence Fulfillment Mode XQuery Expressions

This topic describes how to use the Orchestration Sequence editor Fulfillment Mode area XQuery tab to write an expression that 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 area XQuery is the customer order. For more information about typical customer order structures, see OSM Concepts.

  • Prolog: The input document for the Fulfillment Mode Expression area 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>

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 topic describes how to use the Order Item Specification editor, Order Item Properties tab, Property Expression area, XQuery tab to write an expression that specifies order item properties based on the input context. These expressions have the following characteristics:

  • Context: The Property Expression area 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 area 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())
      

      For more information about typical customer order structures, see OSM Concepts.

    • 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. For more information about typical customer order structures, see OSM Concepts.

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

After these XQuery expressions 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:productSpec>Fixed Service Plan Class</im:productSpec>
      <im:serviceId>552131313131</im:serviceId>
      <im:fulfillPatt>Service.Fixed</im:fulfillPatt>
      <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 products or product specification from the customer order so that order items can be mapped to fulfillment patterns (see "About XQuery Expressions for Mapping Product Specifications and Fulfillment Patterns"). The following example shows the product specification 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 XQuery Expressions for Mapping Product Specifications and Fulfillment Patterns

The order item property specified in the Fulfillment Pattern Mapping Property field for the order item must map to an existing OSM fulfillment pattern 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 fulfillment pattern mapping 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 fulfillment patterns from product or product specification data contained in an order. In other scenarios, the mapping from product or product specification to fulfillment pattern might be simpler; or, there might be cases where some order line items have no product specification, in which case the product specification can be derived from the context of the order item.

You typically create conceptual model products in your OSM system by importing them. (See OSM Concepts for more information.) When you import products, Design Studio creates the productClassMapping.xml and productSpecMapping.xml files. These files contain mappings between conceptual model products and OSM product specifications and fulfillment patterns. The productClassMapping.xml file is provided for backward compatibility, so in this topic it is assumed that you are using the productSpecMapping.xml file. These files are created in one of the following directories:

  • If you have specified a value for the Product Specification Mapping Folder field of the Orchestration Preferences in Eclipse, it will create the two files in the directory specified.

  • If no value is specified for that field, OSM will create the productClassMapping.xml file in the resources/productClassMapping directory and the productSpecMapping.xml file in the resources/productSpecMapping directory.

You can retrieve this mapping data from one of these files by creating a data instance provider that can be referenced from an XQuery expression body using a data instance behavior.

Note:

The element names are not the same between the productClassMapping.xml and productSpecMapping.xml files. Ensure that you are using the correct element names for the file you are referencing. The names in this topic are correct for the productSpecMapping.xml file.

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

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

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

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

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

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

In the following example, OSM retrieves the product specification Mobile Service Feature Class from the incoming customer order. OSM uses the order item property specified in the Fulfillment Pattern Mapping Property field for the order item to map the product specification to a fulfillment pattern.

The order item property specified in the Fulfillment Pattern Mapping Property field for the order item includes the following XQuery expression:

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

The productSpecMapping.xml file includes the <productSpec> element, that maps the Mobile Service Feature Class product specification to the Service.Mobile fulfillment pattern:

<productSpec name="Mobile Service Feature Class" 
        cartridge="OsmCentralOMExample-ProductSpecs">
    <fulfillmentPattern>Service.Mobile</fulfillmentPattern>
</productSpec>

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

  • In the order item specification:

    • A property that retrieves the conceptual model product or the OSM product specification from the incoming customer order.

    • The order item property specified in the Fulfillment Pattern Mapping Property field, that maps the product or product specification to the fulfillment pattern. To do so, OSM uses the ProductClassMap data instance behavior.

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

  • The productSpecMapping.xml file used by the ProductClassMap data instance behavior, that maps products and product specifications to fulfillment patterns.

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

  • Create new fulfillment patterns and conceptual model products, if necessary.

  • Add mappings to the productSpecMapping.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 topic describes how to use the Order Item Specification editor Order Item Hierarchies tab, Key Expression and Parent Key Expression areas, XQuery subtabs to write expressions that specify 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 area 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";
    

    See "OSM XQuery Functions" for more information about the OrchestrationXQueryFunctions class. See OSM Concepts 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())
    

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 topic describes how to use the Order Item Specification editor Orchestration Conditions tab, Condition Expression area, XQuery subtab to write expressions that specifies an order item property value as a condition that you can then use in an order decomposition rule or in a fulfillment pattern 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 area 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 with 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 Fulfillment Pattern 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 Fulfillment Pattern Order Component XQuery Expressions

The Fulfillment Pattern 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 Fulfillment Pattern Order Component Condition XQuery Expressions

This topic describes how to use the Fulfillment Pattern editor, Orchestration Plan tab, Order Components subtab, Conditions subtab XQuery subtab to write an expression that specifies whether to include or exclude an order item from an order component. You can create a new fulfillment pattern from the Fulfillment Pattern 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.

The following example 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.

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 topic describes how to use the Fulfillment Pattern editor, Orchestration Plan tab, Order Components subtab, Order Item Association subtab, Property Correlation selection, XQuery subtab to write an expression that associates order items to order components that are not assigned by their fulfillment pattern. 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 subtab 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>
       <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'/> 
    

The following example shows an XQuery that associates all child order items with their parent items. (See OSM Concepts 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.

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 topic describes how to use the Decomposition Rule editor, Conditions tab, Conditions Details subtab, XQuery subtab to write an expression that associates 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 ID XQuery Expressions

This topic describes how to use the Order Component Specification editor, Component ID tab, Component ID area, XQuery subtab to write an expression that specifies 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 OSM Concepts for more information about the default component ID). The Component ID XQuery includes the following characteristics:

  • Context: The Component ID tab 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 XQuery expressions, 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";
    

    See "OSM XQuery Functions" for more information about the OrchestrationXQueryFunctions class.

  • 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 topics describe OSM Java package methods.

For more information about how the OrchestrationXQueryFunctions are used in custom Component ID XQuery expressions and for more complicated custom group ID generation scenarios that use Orchestration XQueryFunction, see the following topics:

Custom Order Component IDs Based on Hierarchy

A more common scenario where custom order component IDs can be used is when you need 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. These order items have the following characteristics:

  • Order Item 1 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).

    <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>
    
  • Order Item 2 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).

    <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>
    
  • Order Item 3 includes:

    • typeCode: BUNDLE

    • lineId: 6

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

    <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>
    
  • Order Item 4 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).

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

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. The following example shows an XQuery that does this.

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. The following table shows the hierarchy of bundles and products. The component keys use the line IDs of the two bundle items.

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

The following table 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.
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

See "About Component Specification Custom Component ID XQuery Expressions" for more information about the context, prolog, and body of this XQuery. See "OSM XQuery Functions" for more information about the OrchestrationXQueryFunctions class.

Custom Component IDs 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 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.

The following table shows how the five order items would be grouped given a one day 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

See "About Component Specification Custom Component ID XQuery Expressions" for more information about the context, prolog, and body of this XQuery. See "OSM XQuery Functions" for more information about the OrchestrationXQueryFunctions class.

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)

The following table shows how five hierarchically divided order items would be grouped given a one day 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

See "About Component Specification Custom Component ID XQuery Expressions" for more information about the context, prolog, and body of this XQuery. See "OSM XQuery Functions" for more information about the OrchestrationXQueryFunctions class.

About Component Specification Duration XQuery Expressions

This topic applies to the Order Component editor, Duration tab, Duration Expression area, XQuery subtab.

  • Context: There is no input document for this expression.

  • Prolog: There is no prolog required for this expression.

  • Body: The XQuery body returns a duration value based on the XQuery you enter:

    PyYmMdDThHmMsS
    

    where

    • P begins the expression.

    • yY specifies the year.

    • mM specifies the month.

    • dD specifies the day.

    • T separates the parts of the expression indicating the date from the parts of the expression indicating the time.

    • hH specifies the hour.

    • mM specifies the minutes.

    • sS specifies the seconds.

The following example is a hard-coded duration expression for seven hours:

PT7H0M0S

For more information about how OSM uses these fields to calculate order component durations, see OSM Concepts.

About Fulfillment Pattern Duration XQuery Expressions

This topic applies to the Fulfillment Pattern editor, Orchestration Plan tab, Duration subtab, Duration Expression area, XQuery subtab. The functionality for this tab has been deprecated and is displayed to provide backward compatibility with older cartridges.

For the recommended functionality for configuring order component durations, see "About Fulfillment Pattern Component Duration XQuery Expressions" and "About Component Specification Duration XQuery Expressions".

About Fulfillment Pattern Component Duration XQuery Expressions

This topic applies to the Fulfillment Pattern editor, Orchestration Plan tab, Order Components subtab, Duration subtab, Duration Expression area, XQuery subtab.

  • Context: There is no input document for this expression.

  • Prolog: There is no prolog required for this expression.

  • Body: The XQuery body returns a duration value based on the XQuery you enter:

    PyYmMdDThHmMsS
    

    where

    • P begins the expression.

    • yY specifies the year.

    • mM specifies the month.

    • dD specifies the day.

    • T separates the parts of the expression indicating the date from the parts of the expression indicating the time.

    • hH specifies the hour.

    • mM specifies the minutes.

    • sS specifies the seconds.

The following example is a hard-coded duration expression for three hours:

PT3H0M0S

For more information about how OSM uses these fields to calculate order component durations, see OSM Concepts.

Dependency XQuery Expressions

This topic includes information about Orchestration XQuery expressions related to orchestration dependencies:

About Order Item Dependency Property Correlation XQuery Expressions

This topic describes how to use one of the following fields:

  • Fulfillment Pattern editor, Orchestration Plan tab, Dependencies tab, Order Item Dependency subtab, XQuery subtab for the Property Correlation selection

  • Orchestration Dependency editor, Order Item Dependencies tab, XQuery subtab for the Property Correlation selection

to write an expression that specifies dependencies between different order items using order item properties. The Property Correlation XQuery has the same context, prolog, and body structure as the Fulfillment Pattern editor, Order Components tab, Order Item Association subtab, XQuery subtab. See "About Associating Order Items Using Property Correlations XQuery Expressions" for more information.

The following example 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.

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 topic describes how to use one of the following fields:

  • Fulfillment Pattern editor, Orchestration Plan tab, Dependencies subtab, Wait Condition subtab, Wait Delay area, Duration Expression area XQuery subtab for the Duration selection

  • Orchestration Dependency editor, Wait for Condition tab, Wait Delay area, Duration Expression area XQuery subtab for the Duration selection

to write an expression that 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.

The following example shows the sample XQuery to return a duration value.

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 topic describes how to use one of the following fields:

  • Fulfillment Pattern editor, Orchestration Plan tab, Dependencies subtab, Wait Condition subtab, Wait Delay area, Duration Expression area XQuery subtab for the Date Time Expression selection

  • Orchestration Dependency editor, Wait for Condition tab, Wait Delay area, Duration Expression area XQuery subtab for the Date Time Expression selection

to write an expression that 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.

The following example shows the sample XQuery to return a date time value.

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

This topic describes how to use the Fulfillment Pattern editor, Orchestration Plan tab, Dependencies subtab, Wait Condition subtab, Wait for Condition area, XQuery subtab for the Data Change Notification selection,

This topic describes how to use one of the following fields:

  • Fulfillment Pattern editor, Orchestration Plan tab, Dependencies subtab, Wait Condition subtab, Wait for Condition area, XQuery subtab for the Data Change Notification selection

  • Orchestration Dependency editor, Wait for Condition tab, Wait for Condition area, XQuery subtab for the Data Change Notification selection

to write an expression that specifies a value that must exist in order item property (typically a blocking order item property) before a waiting order item starts.

  • 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 returns a specific value and will wait until all blocking order items have the corresponding value and the XQuery returns true.

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

(:   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)

The following example returns true when at least one blocking item is completed.

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 topic describes how to use the Order Item Specification editor, Order Item Dependency tab, Order Item Selector area, XQuery tab to write an expression that creates dependencies between the order items on the follow-on order and the order items on the base order. It is the follow-on order that generates this dependency on the base order.

  • 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 (the base order), and the namespace of the query task that contains the order data you want to view. For example:

    declare namespace osm="http://xmlns.oracle.com/communications/ordermanagement/model";
    declare namespace im="CommunicationsSalesOrderFulfillmentPIP";
    declare namespace osmc="urn:oracle:names:ordermanagement:cartridge: CommunicationsSalesOrderFulfillmentPIP:1.0.0:view:CommunicationsSalesOrderQueryTask";
    
  • Body: The CRM that sends the follow-on order must specify the reference number that uniquely identifies the base order and also the order item line ID of the blocking order item. You can define a variable (such as $dependingLineId) that extracts the dependent line ID from the order item context. For example:

    let $dependingLineId := fn:normalize-space(osm:properties/im:DependingSalesOrderBaseLineId)
    

    You can configure a web service data instance provider that runs a FindOrder Web Service that searches for orders based on the reference value (osm:properties/prop:Ref/text())) in the follow-on order that generates a FindOrder response that includes the order ID of the base order. See OSM Developer's Guide for more information about configuring web service data instance providers. For example:

    <ord:FindOrder xmlns:ord="http://xmlns.oracle.com/communications/ordermanagement"
       xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model"
       xmlns:prop="http://oracle.communications.ordermanagement.unsup.centralom">
       <ord:ViewBy>
          <ord:AmendmentFilter>
             <ord:LevelOfDetail>AmendmentsSummary</ord:LevelOfDetail>
          </ord:AmendmentFilter>
          <ord:LifecycleEventFilter>
             <ord:RetrieveLifecycleEvents>false</ord:RetrieveLifecycleEvents>
          </ord:LifecycleEventFilter>
       </ord:ViewBy>
       <ord:SelectBy>
          <ord:Reference>{fn:normalize-space(osm:properties/prop:Ref/text())} </ord:Reference>
       </ord:SelectBy>
    </ord:FindOrder>
    

    This data instance provider returns the order ID of the base order which you can capture in an XQuery variable (such as $parentOrderID). You can use this variable in a data instance provider that runs a GetOrder Web Service to obtain the order item details from the base order. For example, the following XQuery populates the GetOrder request message using the results from the "findOrder" data instance provider to provide the value for the order ID of the base order in the Order ID field:

    <ord:GetOrder xmlns:ord="http://xmlns.oracle.com/communications/ordermanagement"
        xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model">
            <ord:OrderId>{vf:instance("findOrder")/ord:Order[last()]/ord:Amendments/ord:AmendedOrderSummary/ord:Id/text()}</ord:OrderId> <ord:View>CommunicationsSalesOrderQueryTask</ord:View>
    </ord:GetOrder>
    

    This data instance provider returns all order item instances in the base order that you can then search through to find the blocking order item using the $dependingLineId variable. You can capture the results in an XQuery variable (such as $parentOrderItemId). For example:

    let $parentOrderItemId :=fn:normalize-space(vf:instance("getOrder") /ord:Data/osmc:_root/osmc:ControlData/osmc:OrderItem [osmc:BaseLineId=$dependingLineId]/@index)
    

    The XQuery body returns the order ID of the base order and the order item property that specifies the blocking order item on the base order:

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

    where

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

    • fromOrderItemId: Returns the blocking order item property value that controls the dependency. OSM internally monitors the blocking order item until it is no longer being processed by any order component on the base order.

The following example shows an XQuery for an inter-order dependency.

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()

Order Transformation Manager XQuery Expressions

The following topics provide reference information about order transformation manager XQuery expressions.

About Transformation Sequence XQuery Expressions

When working with Transformation Sequence editor, see the following topics for information about defining XQuery expressions related to transformation sequences:

About Order Item Context XQuery Expressions

This topic describes how to use the Transformation Sequence editor, Dependencies tab, Order Item Context subtab, Expression area, XQuery subtab to write an expression that defines the context order items for the order transformation. To see the Order Item Context subtab, you must select a transformation stage in the tree on the Dependencies tab.

  • Context: The input document is the complete set of source order items.

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

            declare namespace prop='http://oracle.communications.centralom';
    
  • Body: The XQuery body returns the source order items that should be considered the context for the transformation stage.

The following example shows an XQuery expression for selecting an order item context.

        declare namespace prop='http://oracle.communications.centralom';
        osm:orderItem[osm:properties/prop:serviceIntance = 'Y']

About Related Order Item Selector XQuery Expressions

This topic describes how to use the Transformation Sequence editor, Dependencies tab, Related Order Item Selector subtab, Expression area, XQuery subtab to write an expression that defines the related order items for a particular context order item. To see the Related Order Item Selector subtab, you must select a transformation stage in the tree on the Dependencies tab.

  • Context: The input document is a context order item.

  • Prolog: You can declare the order item namespace and the namespace for the order transformation manager functions in the XQuery prolog. For example:

            declare namespace prop='http://oracle.communications.broadband;
    declare namespace otmfn=”java:oracle.communications.ordermanagement.orchestration.transformation.XQueryFunctions.”;
    
  • Body: The XQuery body returns the source order items related to the context order items.

The following example shows an XQuery expression that returns sibling order items as related order items to the order transformation.

        declare namespace prop='http://oracle.communications.broadband;
declare namespace otmfn=”java:oracle.communications.ordermanagement.orchestration.transformation.XQueryFunctions.”;
        let $siblings := otmfn:siblings (., &rsquor;{http://oracle.communications.broadband}default')
        return $siblings[! fn:exists(osm:properties[prop:serviceInstance = 'Y'])]

For more information about the transformation.XQueryFunctions class, install the OSM SDK and extract the OSM Javadocs from the OSM_home/SDK/osm7.w.x.y.z-javadocs.zip file (where OSM_home is the directory in which the OSM software is installed and w.x.y.z represents the specific version numbers for OSM). See OSM Installation Guide for more information about installing the OSM SDK.

About Stage Condition XQuery Expressions

This topic describes how to use the Transformation Sequence editor, Dependencies tab, Stage Condition subtab, Expression area, XQuery subtab to write an expression that determines whether a particular transformation stage should be run. To see the Stage Condition subtab, you must select a transformation stage in the tree on the Dependencies tab.

  • Context: The input document is the complete set of target order items.

  • Prolog: You can declare the order item property and parameter namespaces in the XQuery prolog. For example:

            declare namespace prop='http://oracle.communications.broadband';
    
    declare namespace parm='http://oracle.communications.broadband';
    
  • Body: The XQuery body returns a Boolean, with true meaning that the transformation stage should be run and false meaning that the transformation stage should not be run.

The following example shows an XQuery expression that returns true if certain parameters have not been defined, and false if the parameters are already defined.

declare namespace prop='http://oracle.communications.cso';
declare namespace parm='http://oracle.communications.broadband';
not(fn:exists(osm:properties/prop:Parameters[fn:exists(parm:uploadSpeed) and fn:exists (parm:downloadSpeed)]))

About Mapping Rule XQuery Expressions

When working with Mapping Rule editor, see the following topics for information about defining XQuery expressions related to order decomposition:

About Mapping Condition XQuery Expressions

This topic describes how to use the Mapping Rule editor, Mapping tab, Condition subtab, Expressions area, XQuery subtab to write an expression that defines a condition that must be satisfied to apply this mapping.

  • Context: The input document is a target order item.

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

            declare namespace prop='http://oracle.communications.broadband';
    
  • Body: The XQuery body returns a Boolean, with true meaning that the mapping rule should be run and false meaning that the mapping rule should not be run.

The following example shows an XQuery expression that will execute the rule only if the target action is None.

declare namespace prop='http://oracle.communications.cso';
osm:properties/prop:Action/text() = 'None'

About Action Mapping XQuery Expressions

This topic describes how to use the Mapping Rule editor, Mapping tab, Actions subtab Action Mappings area, XQuery subtab to write an expression that defines the mapping for an action code for a particular mapping rule. To access this field, you must deselect Use Relationship Action Map and select the Advanced option.

  • Context: The input document is a source order item.

  • Prolog: You can declare the following variables within the prolog to determine the action code.

    • You can declare $sourceValue to access the action code of the source order item. This is the Order Item Action property value for the source order item.

    • You can declare $currentTargetValue to access the action code of the target order item. This is the Order Item Action property value for the target order item.

  • Body: The XQuery body returns an action code, or returns () to leave the current value unchanged.

The following example shows an XQuery expression that returns the source action code if the target action code is not already set and otherwise leaves the target action code unchanged.

                declare $sourceValue external;
        declare $currentTargetValue external;
        if (! fn:empty($currentTargetValue)) 
            $sourceValue
        else 
           ()

About Entity-to-Entity Advanced Mapping XQuery Expressions

This topic describes how to use the Mapping Rule editor, Mapping tab, Mapping subtab, Mapping Rule Item area, XQuery subtab to write an expression that defines an advanced mapping between two entities. This field is displayed when you select the target of an entity-to-entity mapping. This is the only type of mapping available for entity-to-entity mapping.

  • Context: The input document is a source order item.

  • Prolog: You can declare any namespaces needed to construct the target property (or properties) in the XQuery prolog. For example:

    declare namespace prop='http://oracle.communications.cso;
    
  • Body: The XQuery body returns a list of order item properties to be set on the target order item. If the property already exists on the target order item, it will be overwritten by the value returned from this XQuery expression.

The following example shows an XQuery expression that returns the structured Parameters property for the target order item.

declare namespace prop='http://oracle.communications.cso;
<prop:Parameters xmlns:param="http://oracle.communications.broadband">
   <parm:AAAAccount>Account1</parm:AAAAccount>
   <parm:DownloadSpeed>6</parm:DownloadSpeed>
   <parm:UploadSpeed>0.6</parm:UploadSpeed>
   <parm:MAC/>
   <parm:Brand>Siemens</param:Brand>
   <parm:Model>4200</parm:Model>
   <parm:Firewall>Y</parm:Firewall>
</prop:Parameters>

About Entity-to-Data-Element Advanced Mapping XQuery Expressions

This topic describes how to use the Mapping Rule editor, Mapping tab, Mapping subtab Mapping Rule Item area, XQuery subtab to write an expression that defines an advanced mapping between an entity and a data element. This field is displayed when you select the target of an entity-to-data-element mapping and select the Advanced option in the Mapping Rule Item topic.

  • Context: The input document is a source order item.

  • Prolog: There is no prolog for this XQuery.

  • Body: The XQuery body returns a data element value or returns () to leave the current value unchanged.

The following example shows an XQuery expression that returns "Y" if a particular parameter exists, and () if it does not exist.

if fn:exists(vf:instance("checkMe")/somevalue) 
   "Y"
else 
   ()

About Data-Element-to-Data-Element Advanced Mapping XQuery Expressions

This topic describes how to use the Mapping Rule editor, Mapping tab, Mapping subtab Configuration subtab, XQuery subtab to write an expression that defines an advanced mapping between two data elements. This field is displayed when you select the target of a data-element-to-data-element mapping and select the Advanced option in the Mapping Rule Item topic.

  • Context: The input document is a source order item during normal transformation. If invoked during forward data propagation, the input document is empty.

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

    declare namespace prop='http://oracle.communications.centralom';
    

    You can also declare the following variable within the prolog to determine the action code.

    • You can declare $value to contain the values of the target data elements.

  • Body: The XQuery body returns one or more data element values or returns () to leave the current value unchanged.

The following example shows an XQuery expression that returns the target value of a data element based on the value of the source data element.

declare variable $value external;
if (fn:empty($value)) then ('unknown') else (fn:concat('Loc: ', $value))

The following example shows an XQuery expression that returns the target value of a data element based on characteristics of the source order item.

declare namespace prop='http://oracle.communications.centralom';
if (fn:exists(osm:properties/prop:ServicePoint/text())) 
then (fn:concat('Loc: ', fn:normalize-space(osm:properties/prop:ServicePoint/string()))) 
else ('unknown')

About Reverse Mapping XQuery Expressions

This topic describes how to use the Mapping Rule editor, Mapping tab, Mapping subtab, Bi-Directional Mapping subtab, XQuery subtab to write an expression that defines an advanced mapping between two data elements. This field is displayed when you select the target of a data element-to-data element mapping and select the Advanced option in the Mapping Rule Item topic, if
Supports Bi-Directional Mapping is selected in the Details subtab of the Mapping tab for the selected mapping.

  • Context: The input document is empty.

  • Prolog: You can declare the following variables within the prolog to determine the action code.

    • You can declare $value to access the updated target value.

  • Body: The XQuery body returns the updated source value.

The following example shows an XQuery expression that returns () if the return value is unknown and otherwise returns the updated value.

declare variable $value external;
if ('unknown' = $value) then() else (fn:substring($value, 5))

About Multi-Instance XQuery Expressions

This topic describes how to use the Mapping Rule editor, Mapping tab, Mapping subtab, Multi-Instance Expression subtab, XQuery subtab to write an expression that defines key mapping for a multi-instance structure. This field is displayed when you select the target of a data element-to-data element mapping and select the Advanced option in the Mapping Rule Item topic, if the target data element is a member of a multi-instance structure.

  • Context: The input document is a source order item.

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

            declare namespace prop='http://oracle.communications.broadband';
    
  • Body: The XQuery body returns a key value that identifies a source order item instance.

The following example shows an XQuery expression that returns the concatenation of two source order item properties for the key value.

fn:concat(prop:areaCode, '-', prop:localNumber)

About Order Item Parameter Binding XQuery Expressions

This topic describes how to use the Order Item Parameter Binding editor, Parameter Bindings tab, Binding Expression area, XQuery subtab to write an expression that defines the bindings for one or more parameters on a conceptual model entity from an order item.

  • Context: The input document is an input order item. Each order item element in this node set is passed into the XQuery as the context.

  • Prolog: You can declare the namespace for the incoming order and the namespace for the conceptual model entity in the XQuery prolog. For example:

    declare namespace im="http://xmlns.oracle.com/InputMessage";
    declare namespace otm="CommonModelBroadbandCart/1.0.0.0.0";
    
  • Body: The body of the XQuery will return a node set of elements that correspond to the conceptual model entity data elements. Since you can have as many separate bindings between the entities as you like, this can return anything from one data element to all of them.

The following example shows an XQuery expression that returns an UploadSpeed and a DownloadSpeed parameter from two name-value pairs where the names are Upload Speed and Download Speed.

declare namespace fulfillord="http://xmlns.oracle.com/InputMessage";
declare namespace otm="OSMCom_3Play/1.0.0.0.0";

<otm:UploadSpeed>{fn:normalize-space(fulfillord:itemReference/fulfillord:specificationGroup/fulfillord:specification[fulfillord:name='Upload Speed']/fulfillord:value)}</otm:UploadSpeed>

<otm:DownloadSpeed>{fn:normalize-space(fulfillord:itemReference/fulfillord:specificationGroup/fulfillord:specification[fulfillord:name='DownloadSpeed']/fulfillord:value)}</otm:DownloadSpeed>

About Transformed Order Item Fulfillment State XQuery Expressions

This topic describes how to use the Transformed Order Item Fulfillment State Composition Rule Set editor, Composition Rules tab, Source Order Item subtab, XQuery field to write an expression that defines the conceptual model entities that should be present if the condition is to be evaluated. This field is only available when you have a condition selected in the tree in the tab, and you have selected the Advanced option on the subtab.

  • Context: The input document is the order.

  • Prolog: You can declare $orderItemIndex to access the index of the order item being considered.

  • Body: The body of the XQuery will return a Boolean value indicating whether the current rule should be used to calculate the fulfillment state.

The following example shows an XQuery expression that returns true if a particular order item property has a specific value.

declare variable $orderItemIndex external;
 
let $orderData := fn:root(.)/GetOrder.Response
let $orderItem := $orderData/_root/ControlData/OrderItem[@index=$orderItemIndex]
return 
    if (fn:exists($orderItem) and fn:data($orderItem/AnyProperties) = 'ABC')
    then fn:true()
    else fn:false()