You are here: Using BML > Functions & Scripts > XML

XML

OVERVIEW

This group of functions streamlines XML manipulations.

ADMINISTRATION

Closedapplytemplate()

Syntax: applytemplate(String templateFileLocation [, Dictionary payload [, String defaultErrorMessage]])

While the most common use case of this function is to create an XML string, you can also use applytemplate to build strings in other formats, such as JSON.

Parameters:

# Parameter Data Type Description
1 templateFileLocation String

Location of the template file.

The template file can contain attribute variable names or local BML variable names for replacement.

2 Dictionary payload Integer Applied to the template file.
3 default ErrorMessage String Optional: What is returned if an error occurs.

Return Type: String that represents the result of applying a set of token key/value pairs to the template file. This set of token key/value pairs can come from either an explicitly user defined map, or implicitly imported rule input variables from System, Main Document or Sub Document.

ClosedOverwriting an imported rule input variable

ClosedOverwrite Globally

To overwrite an imported rule input variable, use the imported rule input variable name as the key in the user map. This value from the user map will be applied globally to either the main document or sub document within the template.

ClosedOverwrite Locally

To overwrite an imported rule input variable within a specific document, use a prefix of "[documentNumber]~" (such as 1~) on the imported rule input variable name as the key in the user map.

ClosedValid Formats for Template Files

The tokens in the template file should start with "{{" and end with "}}" signs. This is the list of valid formats and features.

ClosedExample of {{#each <SubDocumentVariableName>}} {{/each}}

Imagine that the SubDocumentVariableName is "lineItem" and the attributes "_price_subtotal" and "_price_net_price" of the lineItem have been manually imported as rule inputs in BML scripts. To reference those attributes within the template, use the following code:

{{#each lineItem}}

<Line>

<PriceSubTotal>{{_price_subtotal}}</PriceSubTotal>

<PriceNetPrice>{{_price_net_price}}</PriceNetPrice>

</Line>

{{/each}}

ClosedExample of {{#if YOUR_NOT_NULL_STRING_VALUE_HERE}} {{/if}}

Imagine this template:

{{#if _type}}<Line><PriceSubTotal>{{_price_subtotal}}</PriceSubTotal></Line>{{/if}}

If the variable "_type" contains the value "RECURRING", then the template will be rendered.

If the variable "_type" contains the value "" or null, then nothing will be rendered for the template.

ClosedExample of {{formatDateString context originalFormat newFormat}}

ClosedExample of {{#equal context compareTo}}{{else}}{{/equal}}

{{#equal price_type "RECURRING"}}<recurringprice>{{_recurringprice}}</recurringprice>{{else}}Price type is not recurring.{{/equal}}

If variable "price_type" is "RECURRING", then above template will be rendered as <recurringprice>34</recurringprice>.

If variable "price_type" is not "RECURRING", then "Price type is not recurring." will be rendered.

The {{else}} is optional.

ClosedProcessing Rules for Template Files

ClosedExample of Processing Rules for Template Files


Closedreadxmlsingle() and readxmlmultiple()

Syntax for readxmlsingle(): readxmlsingle(String xmlPayload, String[] xpaths [, String defaultErrorMessage])

This function reads a set of single XML node content based on a set of XPath expressions.

Syntax for readxmlmultiple(): readxmlmultiple(String xmlPayload, String[] xpaths [, String defaultErrorMessage])

Reads a set of multiple XML node contents based on a set of XPath expressions.

Parameters:

# Parameter Data Type Description
1 xmlPayload String

 

2 xpaths String  
3 default ErrorMessage String Optional: What is returned if an error occurs.

Return Type: String

This function will return a BMLDictionary, where the String keys are the input xpaths and String values are the XPath evaluation results for the input xpaths.

If an error occurs, the function will return a BMLDictionary that contains the error message. The key for the error message in the BMLDictionary is "BM_READXMLSINGLE_ERROR" for readxmlsingle and "BM_READXMLMULTIPLE_ERROR" for readxmlmultiple.

ClosedProcessing Rules

If a given XPath is evaluated as a single node in result, the returned String content is based on the node type and content.

Node Type and Content Returned String Content
ATTRIBUTE_NODE ATTRIBUTE_NODE value
Node that contains text content in its child nodes The concatenated node values from TEXT nodes and CDATA nodes, if they contain not-empty text, are returned as the content of the node
Node that does not contain text content in its child nodes A String representation of the node (XML fragment)
Multiple ATTRIBUTE_NODE or ELEMENT_NODEs Only the content of the first node string will be returned, based on String content retrieving rules

ClosedDefining Namespaces

To avoid abuse in the usage of the namespace prefix, the input argument xmlPayload should not contain namespace prefixes for more than 1,000 namespaces. Otherwise, the error message "IllegalArgumentException" will be returned.

There are three ways to define namespaces in a document:

Namespaces are used differently, depending on their context.

Namespace Context Namespace Use
The input XML document contains default namespaces, but the default namespace is not on the root The element(s) in such a default namespace will be ignored.
The input XML document contains default namespaces on the root. The input XPath for these default namespace elements should contain a namespace prefix "BM_NS". If the return is an XML fragment, the returned evaluated result will contain the namespace attribute information.
The input XML document contains no namespaces No namespace prefix is needed in the input XPath.
The input XML document contains namespaces with prefixes. A namespace prefix is needed in the input XPath. If the return is an XML fragment, the returned evaluated result will contain the namespace attribute information.

ClosedExample of readxmlsingle():

ClosedExample of readxmlmultiple():


Closedtransformxml()

Syntax: transformxml(String xml, String xslFileLocation [, String defaultErrorMessage])

This function transforms an XML string with an XSLT file stored in the File Manager.

It returns the transformed xml message, or the error message if it failed to transform. The error message will be either the default error message (if it is defined) or the system-generated error message, which starts with "ERROR: ".

Parameters: 

Return Type: String

Example of transformxml():

xmlcontent = "<?xml version="1.0" encoding="UTF-8"?><book><id>123456</id></book>";

xslt = "xsl/test.xsl";

output = transformxml(xmlcontent, xslt); output has the generated result.


NOTES

RELATED TOPICS

Related Topics Link IconSee Also