Compensation XQuery Expressions

The following topics provide information about automation and manual task compensation XQuery expressions.

For general OSM XQuery information, see "General XQuery Information."

Task Re-Evaluation and Rollback XQuery Expressions

You can dynamically assign compensation strategies to tasks by creating XQuery expressions in the Design Studio Task Editor Compensation tab for re-evaluation compensation strategies or compensation strategies for when a task is no longer required.

Note:

If the XQuery expression is invalid OSM logs the error but does not rollback the transaction. Instead, OSM uses the static compensation strategy as the default.

This section refers to the Design Studio OSM Automated Task or Manual Task editor, Compensation tab Compensation Expression XQuery field for re-evaluation compensation strategies:

  • Context: The context for this XQuery is the current order data. You can get the current order data using the XML API GetOrder.Response function.

  • Prolog: You can declare the XML API namespace to use the GetOrder.Response function in the XQuery body to extract the order information. You must declare the java:oracle:communications.ordermanagement.compensation. ReevaluationContext OSM Java package that provides methods that access the contemporary and historical order perspectives and compares the two. You can use the results of this comparison to determine what compensation strategy is required for a task based on revision order data.

    For example:

    declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace context = "java:oracle.communications.ordermanagement.compensation.ReevaluationContext";
declare namespace log =  "java:org.apache.commons.logging.Log";

declare variable $log external; 
declare variable $context external;

    For more information about the classes in the OSM packages, 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.

  • Body: The body must return a valid compensation option.

    For example, the following XQuery expression creates variables for the ReevaluationContext methods. The expression then checks that a specific value exists in the $value variable and that the value in the $significantValue variable both exists and is significant. If the value exists and is significant, then the expression sets the compensation strategy for the task to Undo then Do (undoThenDo in the ReevaluationContext Java class). If not, then the expression sets the compensation strategy to Redo (redo in the ReevaluationContext Java class).

    let $inputDoc := self::node()
let $hopDoc := context:getHistoricalOrderDataAsDOM($context)
let $ropDoc := context:getCurrentOrderDataAsDOM($context) 
let $diffDoc := context:getDataChangesAsDOM($context)
let $value := $inputDoc/GetOrder.Response/_root/service[name='BB']//orderItemRef/specificationGroup//specification[value='100']
let $significantValue := $diffDoc/Changes/Add[@significant='true']/specification[value='100']
let $currentValue := $ropDoc/ GetOrder.Response/_root/service[name='BB']//orderItemRef/specificationGroup//specification[value='100']
 
return if (fn:exists($value) and fn:exists($significantValue))
then
    context:undoThenDo($context)
else
    context:redo($context)

This section refers to the Design Studio OSM Automated Task or Manual Task editor, Compensation tab Compensation Expression XQuery field for when a task is no longer required. The context, prolog, and body are similar to the XQuery expression for the re-evaluation strategy, except that the XQuery expression implements the java:oracle:communications.ordermanagement.compensation.RollbackContext package.

For example:

declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace context = "java:oracle.communications.ordermanagement.compensation.RollbackContext";
declare namespace log =  "java:org.apache.commons.logging.Log";
 
declare variable $log external; 
declare variable $context external;
 
let $inputDoc := self::node()
let $hopDoc := context:getHistoricalOrderDataAsDOM($context)
let $ropDoc := context:getCurrentOrderDataAsDOM($context) 
let $diffDoc := context:getDataChangesAsDOM($context)
 
let $value := $inputDoc/GetOrder.Response/_root/service[name='BB']//orderItemRef/specificationGroup//specification[value='100']
return if (fn:exists($value))
then
    context:undo($context)
else
    context:doNothing($context)

In Progress Compensation Include XQuery Expressions

You can determine if an in progress task should be compensated by writing an XQuery expression in the Design Studio Task Editor Compensation tab.

Note:

If the XQuery expression is invalid OSM logs the error and includes the in progress task in the compensation plan as it defaults the expression to true.

This section refers to the Design Studio OSM Automated Task or Manual Task editor, Compensation tab, In Progress Compensation Include Expression XQuery field for dynamically defining when in progress tasks should be included in compensation. This XQuery expression runs when OSM first analyzes the task for compensation:

  • Context: The context for this XQuery is the current task order data. You can get the current task order data using the XML API GetOrder.Response function.

  • Prolog: You can declare the XML API namespace to use the GetOrder.Response function in the XQuery body to extract the order information.

    For example:

    declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace log =  "java:org.apache.commons.logging.Log";

declare variable $log external; 
declare variable $context external;

  • Body: Based on task context data, the body must return true if the in progress task requires compensation or false if it does not.

For example:

declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace log =  "java:org.apache.commons.logging.Log";
declare variable $log external; 
 
let $inputDoc := self::node()
let $value := $inputDoc/GetOrder.Response/_root/data
 
return (
    if (fn:contains($value, "includeInCompensation")) then
        fn:true()
    else
        fn:false()
)

In Progress Compensation Complete XQuery Expressions

You can determine when the compensation for an in progress task is complete by writing an XQuery expression in the Design Studio Task Editor Compensation tab.

Note:

If the XQuery expression is invalid OSM logs the error and includes the in progress task in the compensation plan as it defaults the expression to true.

This section refers to the Design Studio OSM Automated Task or Manual Task editor, Compensation tab, In Progress Compensation Complete Expression XQuery field for dynamically defining when in progress tasks completes compensation activities. This XQuery expression runs whenever data changes on the compensating task:

  • Context: The context for this XQuery is the current task order data. You can get the current task order data using the XML API GetOrder.Response function.

  • Prolog: You can declare the XML API namespace to use the GetOrder.Response function in the XQuery body to extract the order information.

    For example:

    declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace log =  "java:org.apache.commons.logging.Log";

declare variable $log external; 
declare variable $context external;

  • Body: Based on task context data, the body must return true if the in progress task has completed all compensation activities or false if it has not.

For example:

declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace log =  "java:org.apache.commons.logging.Log";
declare variable $log external; 
let $inputDoc := self::node()
let $value := $inputDoc/GetOrder.Response/_root/data
return (
    if (fn:contains($value, "compensationDone")) then
                fn:true()
    else
                fn:false()

In Progress Compensation Grace Period XQuery Expressions

You can determine whether a grace period should be observed before starting compensation for an in progress task by writing an XQuery expression in the Design Studio Task Editor Compensation tab.

Note:

If the XQuery expression is invalid OSM logs the error and includes the in progress task in the compensation plan as it defaults the expression to true.

This section refers to the Design Studio OSM Automated Task or Manual Task editor, Compensation tab, When an amendment occurs if this task is in progress it will: tab, Dynamic Expression XQuery field for dynamically defining the grace period for an in progress task based on task data. This XQuery expression runs after OSM has determined whether the in progress task needs to be compensated:

  • Context: The context for this XQuery is the current task order data. You can get the current task order data using the XML API GetOrder.Response function.

  • Prolog: You can declare the XML API namespace to use the GetOrder.Response function in the XQuery body to extract the order information. You can also declare the $gracePeriod variable in the XQuery prolog which contains the grace period specified on the order life-cycle policy.

    For example:

    declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace log =  "java:org.apache.commons.logging.Log";

declare variable $gracePeriod external; 
declare variable $log external; 
declare variable $context external;

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

For example, this XQuery uses order data to define the specific grace period duration for the task. The last statement calls the $gracePeriod variable which represents the grace period duration specified on the order life-cycle policy:

declare namespace osm = "urn:com:metasolv:oms:xmlapi:1";
declare namespace log =  "java:org.apache.commons.logging.Log";
declare variable $log external; 
declare variable $gracePeriod external; 
 
let $inputDoc := self::node()
let $value := $inputDoc/GetOrder.Response/_root/data
 
return (
    if (fn:contains($value, '-immediate-')) then
        xs:duration('PT0S')
    else if (fn:contains($value, '-override-')) then
        xs:duration('PT20S')
    else if (fn:contains($value, '-negative-')) then
        xs:duration('-PT10S')
    else if (fn:contains($value, '-invalidNumber-')) then
        fn:number(0)
    else if (fn:contains($value, '-invalidString-')) then
        xs:string('UNKNOWN')
    else 
        xs:duration(fn:concat('PT', $gracePeriod, 'S'))