XML Functions¶
XML functions are typically used in transformation mapping scripts that require the manipulation and access of XML data.
Attribute
¶
Declaration¶
type Attribute(string attributeName, string attributeValue)
Syntax¶
Attribute(<attributeName>, <attributeValue>)
Required Parameters¶
attributeName:
Attribute nameattributeValue:
Attribute value
Description¶
Creates an attribute for an XML node. See also the CreateNode
function.
Examples¶
// Adds an attribute "name" with a value of "value"
Attribute("name","value");
CreateNode
¶
Declaration¶
string CreateNode(string namespace, string nodeName, type attributeSubelement[,...])
Syntax¶
CreateNode(<namespace>, <nodeName>, <attributeSubelement>[,...])
Required Parameters¶
namespace:
The namespace of the nodenodeName:
Name of the nodeattributeSubelement:
A subelement: a value, attribute, or sub-node
Optional Parameters¶
attributeSubelement:
Additional subelements (a value, attribute, or sub-node), as required
Description¶
Creates a string representing an XML node. If the target node is the value node of an XML Any node, an XML element corresponding to the nodeName
and nodeValue
will be created.
Starting from the third argument, a series of values, attributes, and sub-nodes can be specified. Values are specified directly. Attributes and sub-nodes can be created with the Attribute
and CreateNode
functions respectively.
Examples¶
// Creates a node with a sub-node
CreateNode("http://example.com/xml",
"Contact", "Bill G.", Attribute("Type", "VIP"),
CreateNode("http://example.com/xml",
"Title", "Manager")
);
GetNodeName
¶
Declaration¶
string GetNodeName(type path)
Syntax¶
GetNodeName(<path>)
Required Parameters¶
path:
A string reference path expression that selects a single node in the current transformation, or raw XML
Description¶
Retrieves the name of a node. This method is typically used to retrieve the name of a node returned by either of the SelectNodeFromXMLAny
orSelectSingleNode
functions.
To enter a path to a node into the function for the path
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
Examples¶
// Retrieves the name of a node
GetNodeName(SelectNodeFromXMLAny("Account", Root$Any.));
GetNodeValue
¶
Declaration¶
string GetNodeValue(type path)
Syntax¶
GetNodeValue(<path>)
Required Parameters¶
path:
A string reference path expression that selects a single node in the current transformation, or raw XML
Description¶
Retrieves the value of a node. This method is typically used to retrieve the value of a node returned by either of the SelectNodeFromXMLAny
orSelectSingleNode
functions.
To enter a path to a node into the function for the path
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
Examples¶
// Retrieves the value of a node
GetNodeValue(SelectNodeFromXMLAny("Account", Root$Any.));
GetXMLString
¶
Declaration¶
string GetXMLString(type path[, bool qualified])
Syntax¶
GetXMLString(<path>[, <qualified>])
Required Parameters¶
path:
A string reference path expression that selects a single node in the current transformation
Optional Parameters¶
qualified:
A boolean value (defaultfalse
); when qualified (true
), the XML string returned is easier to read but may not by itself be valid XML
Description¶
Returns (when used in a Formula Builder mapping) the corresponding XML string found in the source XML document at the specified path.
To enter a path to a node into the function for the path
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
Examples¶
// Retrieves the corresponding XML string at the specified path
GetXMLString([Header$DETAIL.]);
// Retrieves the corresponding XML string at the specified path
GetXMLString([root$transaction.response$body$queryResponse$result$records.Case$Account$]);
IsNil
¶
Declaration¶
bool IsNil(string path)
Syntax¶
IsNil(<path>)
Required Parameters¶
path:
A string reference path expression that selects a single node in the current transformation
Description¶
Returns (when used in a Formula Builder mapping) if the corresponding XML node has the attribute "xsi:nil
" with the value of true
(or 1).
To enter a path to a node into the function for the path
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
As described in XML Schema, an element may be valid without content if it has the attribute xsi:nil
with the value true
.
Examples¶
// Returns if the node is nil
IsNil("Header$DETAIL.");
RunXSLT
¶
Declaration¶
array RunXSLT(string xslt, string xml1[, string xml2,... string xmlN)
Syntax¶
RunXSLT(<xslt>, <xml1>[, <xml2>,... <xmlN>])
Required Parameters¶
xslt:
An XSLT stylesheetxml1...xmlN:
One or more XML documents
Description¶
Supports running XSLT (v1-3) on a number of input XML documents. Takes as input an XSLT stylesheet and one or more XML documents and returns an array of XML documents.
Examples¶
// Running XSLT on XML Files
// Read in a stylesheet
xslt = ReadFile("<TAG>Sources/XSLT</TAG>");
// Read in two XML files for processing
xml1 = ReadFile("<TAG>Sources/XML1</TAG>");
xml2 = ReadFile("<TAG>Sources/XML2</TAG>");
// RunXSLT on the stylesheet and the two XML files
output = RunXSLT(xslt, xml1, xml2);
// As RunXSLT() returns an array,
// retrieve the output from each element
i = 0;
While(i < Length(output),
// Write output to a file
WriteFile("<TAG>Targets/XML Output FTP</TAG>",
output[i], "output" + (i+1) + ".xml");
i++;
);
Jitterbit-specific Concepts¶
Using an existing XSLT Transform¶
It is also possible to use an existing XLST Transform as the first argument to RunXSLT()
. An XLST Transform is defined as a separate entity from the script and can be reused in multiple scripts and XLST Transform operations. This must be an XLST Transform defined in the current project. See the instructions on inserting project items.
// Runs an existing XSLT Transform, passing values
// using variables customers, salesPeople, salesOrders
mergedOut = RunXSLT("<TAG>XSLT Transforms/Merge Transform</TAG>",
customers, salesPeople, salesOrders);
Referring to Files from within an XSLT Stylesheet¶
While Jitterbit has broad support for XSLT, projects that use XSLT must follow rules to pass the security standards. These rules mean that access to files or URIs must always be through the use of sources and targets defined in the same project.
To reference these files or URIs in a stylesheet, use the XLST fn:doc
function and specify 'param1'
for the first XML input, 'param2'
for the second XML input, and so on for each additional XML file.
For this example, given the previous example of processing three XML files (customers, salesPeople, salesOrders
), you could refer to them in an XSLT stylesheet using:
<xsl:for-each select="doc('param1')/*:Customers/*:SalesOrder[customer_external_id!=''][sales_person_external_id!='']">
...
<xsl:for-each select="doc('param2')/*:SalesPeople/*:Account[*:customer_id/string(number(text()))=$CustomerExtId][1]">
...
<xsl:for-each select="doc('param3')/*:SalesOrders/*:SalesOrder[customer_external_id!=''][sales_person_external_id!='']">
If you have a single input XML file, it is not required to use the doc('param1')
syntax as Jitterbit will set the initial context to that single file.
Specifying a Starting Template in the Stylesheet¶
In some situations, Jitterbit needs to know where in a stylesheet to begin processing. This is achieved by including in the stylesheet a template with the specific name of start_here
:
<xsl:template name="start_here" match="/">
SelectNodeFromXMLAny
¶
Declaration¶
type SelectNodeFromXMLAny(string nodeName, type anyNodes)
Syntax¶
SelectNodeFromXMLAny(<nodeName>, <anyNodes>)
Required Parameters¶
nodeName:
The desired node nameanyNodes:
The data element path of a value node of an XML Any element, a string reference path expression to an array of XML nodes in the current transformation, or raw XML
Description¶
Returns the first XML node from a list of XML Any nodes that match the node name.
To enter a path to an array of XML nodes into the function for the anyNodes
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
Examples¶
// Looks for the first node that matches "Account"
SelectNodeFromXMLAny("Account", Root$Any#.);
SelectNodes
¶
Declaration¶
array SelectNodes(type node, string xPathQuery[, string xPathArg1,... string xPathArgN])
Syntax¶
SelectNodes(<node>, <xPathQuery>[, <xPathArg1>,... <xPathArgN>])
Required Parameters¶
node:
A string reference path expression to the desired node in the current transformation, an XML fragment to run the query on, or raw XMLxPathQuery:
The data element path of a value node of an XML Any element
Optional Parameters¶
xPathArg1...xPathArgN:
Prefixes specifying the namespaces of nodes in the XPath query
Description¶
Runs an XPath query (see the XPath standard, v1-v3) on either an XML fragment or an XML node returned from another function, and returns the results of the query.
If the optional prefixes are used to specify the namespaces of the node in the XPath query, the prefixes must be specified as one or more string arguments after the XPath (see the second example).
To enter a path to a node into the function for the node
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
To support HTML characters, set jitterbit.decode.html.chars
to true
upstream of a script using this function. This variable is supported with string data when using 10.49 agents and later.
Examples¶
// Connects to an LDAP server, runs a search,
// and then runs an XPath Query on the results
LDAPConnect("directory.company.example.com","ghvwright","1LikesPe@ches",0);
searchResults = LDAPSearch("CN=Users,DC=company,DC=example,DC=com",
"(&(objectCategory=person)(objectClass=user))", 1,
"name", "whenCreated", "description", "telephoneNumber");
resultNodes = SelectNodes(searchResults,
"/DirectoryResults/Entry[name='Administrator']/whenCreated" );
SelectNodes(Root$Any$,
"ns1:E2/ns2:E3",
"ns1=http://xyz1.example.com/",
"ns2=http://xyz2.example.com/");
Note
In this second example, the reference node is an XML node for an XML Any node. In the XPath query, ns1:E2
is not the reference node itself.
Since the prefixes ns1
and ns2
are used in the XPath query, they are defined as additional arguments after the XPath.
SelectNodesFromXMLAny
¶
Declaration¶
array SelectNodesFromXMLAny(string xPathQuery, type anyNodes[, string xPathArg1,... string xPathArgN])
Syntax¶
SelectNodesFromXMLAny(<xPathQuery>, <anyNodes>[, <xPathArg1>,... <xPathArgN>])
Required Parameters¶
xPathQuery:
An XPath queryanyNodes:
The data element path of a value node of an XML Any element, a string reference path expression to an array of XML nodes in the current transformation, or raw XML
Optional Parameters¶
xPathArg1...xPathArgN:
Prefixes specifying the namespaces of nodes in the XPath query
Description¶
Returns an array of all the XML nodes that are matched by an XPath query (see the XPath standard, v1-v3) run against either a path of a value node of an XML Any element or an array of XML nodes.
If the optional prefixes are used to specify the namespaces of the node in the XPath query, the prefixes must be specified as one or more string arguments after the XPath (see the second example).
To enter a path to an array of XML nodes into the function for the anyNodes
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
Examples¶
// Select all the nodes with the given names
SelectNodesFromXMLAny("Account|Customer|Name", Root$Any#.);
// Select email addresses and phone numbers only
$nodes = SelectNodesFromXMLAny("cust:EmailAddress|cust:PhoneNumber",
Customer$Any#., "cust=urn:xmlns:25hoursaday-com:customer");
SelectSingleNode
¶
Declaration¶
type SelectSingleNode(type node, string xPath,...)
Syntax¶
SelectSingleNode(<node>, <xPath>,...)
Required Parameters¶
node:
A string reference path expression to the desired node in the current transformation, an XML fragment to run the query on, or raw XMLxPathQuery:
The data element path of a value node of an XML Any element
Optional Parameters¶
xPathArg1...xPathArgN:
Prefixes specifying the namespaces of nodes in the XPath query
Description¶
Runs an XPath query (see the XPath standard, v1-v3) on either an XML fragment or an XML node returned from another function, and returns the first node in the results of the query.
If the optional prefixes are used to specify the namespaces of the node in the XPath query, the prefixes must be specified as one or more string arguments after the XPath (see the second example).
To enter a path to a node into the function for the node
parameter, double-click the desired XML node folder to insert its qualified path at the location of your cursor. For more information, see the instructions on inserting XML node paths.
To support HTML characters, set jitterbit.decode.html.chars
to true
upstream of a script using this function. This variable is supported with string data when using 10.49 agents and later.
Examples¶
// Connects to an LDAP server, runs a search,
// runs an XPath Query on the results, and
// selects the first node in the query results
LDAPConnect("directory.company.example.com", "ghvwright", "1LikesPe@ches", 0);
searchResults = LDAPSearch("CN=Users,DC=company,DC=example,DC=com",
"(&(objectCategory=person)(objectClass=user))", 1, "name",
"whenCreated", "description", "telephoneNumber");
resultNode = SelectSingleNode(searchResults,
"/DirectoryResults/Entry[name='Administrator']/whenCreated");
// Selects the first node in an XPath query result.
// The reference node is an XML node for an XML Any node.
// In the XPath query, "ns1:E2" is not the reference node itself.
// Since the prefixes ns1 and ns2 are used in the XPath query,
// they are defined as additional arguments after the XPath.
SelectSingleNode(Root$Any$,
"ns1:E2/ns2:E3",
"ns1=http://xyz1.example.com",
"ns2=http://xyz2.example.com/");