Order Item Parameter Binding XQuery Expressions
This topic discusses best practices for writing an order item parameter binding XQuery. It also provides sample XQuery code that can be used in your cartridges.
Note:
Order Item Parameter Binding applies to product, service, and resource specifications equally.-
XQuery Context:
The order item is passed into the XQuery as the context. As an example from the XQuery below:
let $lineItem := . -
Body:
The body of the XQuery should return a node set of elements that correspond to the conceptual model entity data elements.
OSM best practice suggests the use of two XQuery files to do the order item parameter binding.
A main XQuery file which is specified in the binding expression on the Order Item Parameter Binding Editor (ParameterBindings Tab). This XQuery is generic in nature and can be used across many solutions.
The second is an XQuery library module that is tied to the incoming order type. This library module is imported by the main XQuery and handles order specific processing.
The main XQuery uses an OSM model variable to know what module file to use. You will need to define an OSM model variable BINDING_MODULE to point to the location of the module that understands the input order. You can see an example of the main XQuery below:
(: This binding module is aware of the incoming order structure so that it can parse the incoming payload as needed :)
import module namespace bindingModule = "http://oracle.communications.orchestration.com/parameterBindingModule" at "%{BINDING_MODULE}";
(: This variable defines the input document of the incoming request. To maintain backward compatibility :)
declare variable $inputDoc as document-node() external;
(:Product Type will be populated by server runtime with setting from parameter binding entity. To maintain backward compatibility :)
declare variable $parameterKeyName as xs:string external;
(: bindingMap will be populated by server runtime with the correct mapping content for the product specification :)
declare variable $bindingMap as document-node() external;
declare function local:mapParameter(
$parameterMap as node(),
$incomingName as xs:string,
$incomingValue as xs:string) as element()*
{
(: Find the conceptual model entry in the map that has a key matching the incoming name :)
let $matchedAttribute := $parameterMap/attributes/attribute[key = $incomingName]
let $conceptualModelUri := $parameterMap/conceptualModelURI
let $conceptualModelName := $matchedAttribute/value/text()
let $result :=
if (fn:exists($conceptualModelName))
then
(
element {QName($conceptualModelUri, $conceptualModelName)}{
$incomingValue
}
)
else ()
return
(
$result
)
};
let $lineItem := .
let $parameterList := bindingModule:getIncomingParameters($lineItem)
return
(
for $parameter in $parameterList
return
(
let $incomingName := bindingModule:getIncomingName($parameter)
let $incomingValue := bindingModule:getIncomingValue($parameter)
return
local:mapParameter($bindingMap, $incomingName, $incomingValue)
)
)
In the main XQuery, when the OSM target server version is 7.5.0, then the OSM server will populate the variable $bindingMap with the content of the correct XML binding file that is generated by Design Studio.
The following example is a TMF622 BindingModule XQuery. It provides functions to retrieve the parameters and parameter values from a TMF 622 order item. Both the namespace and the location of the parameters are specific to a TMF 622 order:
(: OSM namespaces :)
declare namespace oms="urn:com:metasolv:oms:xmlapi:1";
(: Incoming order namespace as supplied by OSM Gateway :)
declare namespace tmf="http://oracle.communications.orchestration.com/tmf-api/productOrderingManagement/%{TMF622_VERSION}/productOrder/inputMessage";
(:~
: Get the product characteristics for a line item in the 622 product order structure
:
: @param $orderItem order line item context.
: @return XML elements of the product characteristics for the given product order line item.
:)
declare function bindingModule:getIncomingParameters(
$orderItem as element()) as element()*
{
let $product := $orderItem/tmf:product
return (
$product/tmf:productCharacteristic
)
};
(: Namespace specific method to retrieve the parameter(attribute) name from the payload :)
declare function bindingModule:getIncomingName(
$incomingAttribute as element()) as xs:string
{
$incomingAttribute/tmf:name/text()
};
(: Namespace specific method to retrieve the parameter(attribute) value from the payload :)
declare function bindingModule:getIncomingValue(
$incomingAttribute as element()) as xs:string
{
let $value := $incomingAttribute/tmf:value/text()
return(
if(fn:exists($value))
then
(
$value
)
else ""
)
};
(: OSM namespaces :)
declare namespace oms="urn:com:metasolv:oms:xmlapi:1";
(: Incoming order namespace as supplied by OSM Gateway :)
declare namespace tmf="http://oracle.communications.orchestration.com/tmf-api/serviceOrdering/%{TMF641_VERSION}/serviceOrder/inputMessage";
(:~
: Get the service characteristics for a line item in the 641 service order structure
:
: @param $orderItem order line item context.
: @return XML elements of the service characteristics for the given service order line item.
:)
declare function bindingModule:getIncomingParameters(
$orderItem as element()) as element()*
{
let $service := $orderItem/tmf:service
return (
$service/tmf:serviceCharacteristic
)
};
(: Namespace specific method to retrieve the serviceCharacteristic name from the payload :)
declare function bindingModule:getIncomingName(
$incomingAttribute as element()) as xs:string
{
$incomingAttribute/tmf:name/text()
};
(: Namespace specific method to retrieve the serviceCharacteristic value from the payload :)
declare function bindingModule:getIncomingValue(
$incomingAttribute as element()) as xs:string
{
let $value := $incomingAttribute/tmf:value/text()
return(
if(fn:exists($value))
then
(
$value
)
else ""
)
};
See the "How to Access to the Parameter Binding Document Using the new XQuery Context (Doc ID 3001948.1)" KM article on My Oracle Support for more information about accessing the parameter binding document using the new XQuery context.