Expression Designer Functions

Docentric uses XPath expressions in both the Docentric Designer and the Formula Designer for User-defined placeholders. These XPath expressions are based on standard XPath functions described here. On top of standard ones, we added additional Docentric-specific functions to improve your experience for data extraction and manipulation.

Below are images of XPath expression designer in the Docentric Designer (image on the left) and in the User-defined placeholders Formula designer (image on the right)

 

Basic Syntax

Let's begin with basic XPath usage for data selection from the Docentric Data Source Packages (DDSP) file.

Selecting Nodes

Path expression	Description
.	Selects the current node.
..	Selects the parent of the current node.
@	Selects attributes.

Predicates

Predicates, boolean expressions enclosed in square brackets, are used to filter nodes based on specific criteria or values. They are evaluated for each node in a path expression's result set.

The following XML structure will be used to demonstrate predicate examples:

Path expression	Result
SalesInvoiceLines[1]/@LineAmount	returns 700.
SalesInvoiceLines[last()]/@LineAmount	returns 900.
SalesInvoiceLines[@LineAmount > 1000]	returns <SalesInvoiceLines LineAmount="2000.0000000000"></SalesInvoiceLines> node.

Wildcards

Wildcards can be used to select unknown XML elements.

The following XML structure will be used to demonstrate wildcard examples:

Wildcard	Description	Example
*	Matches any element node	count(*) will match any node in the current context without its children and return the number of <SalesInvoiceLines> nodes so it returns 3.
@*	Matches any attribute node	count(SalesInvoiceLines/PackingSlip/@*) will match all attributes from all <PackingSlip> nodes so it returns 6.
node()	Matches any child node of any type	count(node()) will select all child nodes of any type without descendants in the current context and return 3 which is a number of <SalesInvoiceLines> nodes.

Functions and Variables

Functions and Variables are categorized by argument type (e.g., string, number, date-time) or primary operation (e.g., conditional, context, node-set). Optional parameters are denoted with a question mark suffix.

Boolean

Syntax	Return Type	Description	Example
boolean(object)	boolean	Converts the argument to a Boolean.	boolean(1) returns True. boolean("false") returns False.
false()	boolean	Returns True.	false() returns False.
lang(string)	boolean	Returns true if the xml:lang attribute of the context node is the same as the argument string.	lang("en-US") returns True if the context node has an xml:lang attribute of "en-US".
not(boolean)	boolean	Returns True if the argument is false, otherwise, False.	not(true) returns False.
to-boolean(object)	boolean	Converts the argument to a Boolean. If the argument is a node-set, then it takes the text of the first node and converts it to a Boolean value. It returns True if the text is ‘true’ or ‘1’; Otherwise, it returns False.	to-boolean("true") returns True.
true()	boolean	Returns True.	true() returns True.

Conditional

Syntax	Return Type	Description	Example
iif(object, object, object)	object	Returns one of two values (the second and the third parameter), depending on whether the Boolean expression (the first parameter) evaluates to true or false.	iif(1 > 0, "red", "blue") returns the string "red".
coalesce(object*)	object	Accepts a list of parameters and returns the first value from the list that is not an empty string nor empty node set.	coalesce("", 1, "bar") returns the string "1".

Context

Context functions require a Current Data Context. In Docentric Designer, reference it using List and Group tags.

For context function examples, we'll use an XML structure with a List tag bound to SalesInvoiceLines.

Syntax	Return Type	Description	Example
current()	node-set	Returns the current XML node that is the current data context item.	current() returns the current <SalesInvoiceLines> node.
current-collection()	node-set	Returns the node-set which is the resulting item collection of the current directly or indirectly wrapping List or Group tagging element.	current-collection() returns the current <SalesInvoiceLines> node.
current-index()	node-set	Returns the 1-based index of the current data context item in the resulting item collection. The resulting item collection is the product of a List or Group tagging element.	current-index() returns 1 or 2.
data-source(string?)	node-set	Returns the root XML element of the specified data source.	data-source('GeneralData') returns <GeneralData> root element.
last-processed-group-element-result()	node-set	Returns all groups created by the last processed Group tagging element.	last-processed-group-element-result(SalesInvoiceLines)[1]/@Name returns "Low-Range Speaker".
var-element-value()	-	Returns the value of the specified Var tagging element. The argument must be the name of an existing Var tagging element.	We create Var-Tagging element with name Counter and value 0. Then, when we use var-element-value("Counter"), it returns 0.

Date-Time

Syntax	Return Type	Description	Example
date-time-add-days(object, object)	date-time	Returns a date-time value that adds the specified number of days (second parameter) to the given date-time value (first parameter).	date-time-add-days("2023-08-20T15:20:00", 3) returns the date-time value "2023-08-23T15:20:00".
date-time-add-months(object, object)	date-time	Returns a date-time value that adds the specified number of months (second parameter) to the given date-time value (first parameter).	date-time-add-months("2023-08-20T15:20:00", 1) returns the date-time value "2023-09-20T15:20:00".
date-time-add-years(object, object)	date-time	Returns a date-time value that adds the specified number of years (second parameter) to the given date-time value (first parameter).	date-time-add-years("2023-08-20T15:20:00", 1) returns the date-time value "2024-08-20T15:20:00".
day(date-time)	number	Returns the day component of the given date-time.	day("2023-08-20T15:20:00") returns the number 20.
hour(date-time)	number	Returns the hour component of the given date-time.	hour("2023-08-20T15:20:00") returns the number 15.
millisecond(date-time)	number	Returns the millisecond component of the given date-time.	millisecond("2023-08-20T15:20:00.123") returns the number 123.
minute(date-time)	number	Returns the minute component of the given date-time.	minute("2023-08-20T15:20:00") returns the number 20.
month(date-time)	number	Returns the month component of the given date-time.	month("2023-08-20T15:20:00") returns the number 8.
now()	date-time	Returns a date-time that is the current date and time on this computer, expressed as the local time.	now() returns the current date and time in the local time zone.
second(date-time)	number	Returns the second component of the given date-time.	second("2023-08-20T15:20:00") returns the number 0.
to-date-time(date-time)	date-time	Converts the given date-time formatted string to a date-time value.	to-date-time("2023-08-20T15:20:00") returns the date-time value "2023-08-20T15:20:00".
year(date-time)	number	Returns the year component of the given date-time.	year("2023-08-20T15:20:00") returns the number 2023.

Misc

Syntax	Return Type	Description	Example
label(object)	string	Returns a label translation for the provided label code.	label("@SYS80991") returns Name.
load-binary(string, string?)	string	Loads the resource from the specified URL and returns the binary data encoded as Base 64 string. The first parameter accepts the resource URL. The second (optional) parameter accepts a boolean value indicating whether an error due to a failed operation should be suppressed ('false' by default).	load-binary("https://ax.docentric.com/image.jpg") returns Base 64 string of the image.jpg.
load-text(string, string?)	string	Loads the text file/resource from the specified URL and returns the data as string. The first parameter accepts the resource URL. The second (optional) parameter accepts a boolean value indicating whether an error due to a failed operation should be suppressed ('false' by default).	load-text("https://ax.docentric.com/text.txt") returns text data from text.txt as a string.

Node-Set

The following XML structure will be used to demonstrate Node-Set functions examples:

Syntax	Return Type	Description	Example
count(node-set)	number	Returns the number of nodes in the node-set argument.	count(SalesInvoiceLines) returns 2.
id(object)	node-set	Selects elements by their unique ID.	id(SalesInvoiceLines/@Name = "Mid-Range Speaker") returns None.
index-of(node-set, node-set)	number	Reports the one-based index of the first occurrence of the specified reference node (second parameter) in the source node set (first parameter).	index-of(SalesInvoiceLines, PackingSlip) returns -1.
last()	number	Returns a number equal to context size of the expression evaluation context.	last() returns 2.
local-name(node-set?)	string	Returns the local part of the expanded name of the node in the node-set argument that is first in document order.	local-name(SalesInvoiceLines) returns SalesInvoiceLines.
name(node-set?)	string	Returns a string containing a QName representing the expanded name of the node in the node-set argument that is first in document order.	name(SalesInvoiceLines) returns SalesInvoiceLines.
names(node-set)	node-set	Returns a string collection containing a QName representing the expanded name of all the nodes in the given node-set argument.	names(SalesInvoiceLines) returns SalesInvoiceLinesSalesInvoiceLines.
namespace-uri(node-set?)	string	Returns the namespace Uniform Resource Identifier (URI) of the expanded name of the node in the node-set argument that is first in document order.	namespace-uri(SalesInvoiceLines) returns https://ax.docentric.com
position()	number	Returns the index number of the node within the parent.	position() returns 1.
skip(node-set, number)	node-set	Skips the specified number (second parameter) of XML nodes in the given node set (first parameter) and then returns the remaining nodes.	skip(SalesInvoiceLines, 1) returns <SalesInvoiceLines LineAmount="80.0000000000" Name="Low-Range Speaker"></SalesInvoiceLines>.
take(node-set, number)	node-set	Returns only the first specified number (second parameter) of XML nodes in the given node set (first parameter).	take(SalesInvoiceLines, 1) returns <SalesInvoiceLines LineAmount="1920.0000000000" Name="Mid-Range Speaker"></SalesInvoiceLines>.

Number

The following XML structure will be used to demonstrate Number functions examples:

Syntax	Return Type	Description	Example
abs(number)	number	Returns the absolute value of a specified number.	abs(-10) returns 10.
ceiling(number)	number	Returns the smallest integer that is not less than the argument.	ceiling(3.14) returns 4.
floor(number)	number	Returns the largest integer that is not greater than the argument.	floor(3.14) returns 3.
number (Object?)	number	Converts the argument to a number.	number("123") returns the number 123.
round(number)	number	Returns an integer closest in value to the argument.	round(3.14) returns 3.
round-number(number, number)	number	Rounds the given decimal value to the specified number of fractional digits.	round-number(3.14159, 2) returns 3.14.
sum(node-set)	number	Returns the sum of all nodes in the node-set. Each node is first converted to a number value before summing.	sum(SalesInvoiceLines/@LineAmount) returns 600.

String

Syntax	Return Type	Description	Example
$cr	string	Returns a carriage return character.	$cr.
$lf	string	Returns a new line feed.	$lf.
$new-line	string	Returns a new line string.	$new-line.
$tab	string	Returns a tab character.	$tab.
char(number)	string	Returns the character from the provided ASCII number.	char(65) returns the character A.
concat(string, string, string*)	string	Returns the concatenation of the arguments.	concat("Hello", " ", "World") returns the string Hello World.
contains(str1, str2)	boolean	Returns true if the first argument string contains the second argument string; otherwise returns false.	contains("Hello World". "World") returns true.
format(node-set, node-set, node-set?)	string	Converts the numeric or date-time value to its equivalent string representation, using the specified format. This function accepts 3 parameters. The first one is a number or date-time value to format. The second parameter is a format string. The third parameter is optional and accepts a value representing a culture name (e.g., 'en-US') to be used for the format operation instead of the currently set culture.	format (1234567890, "###,###,###,###") returns the string "1,234,567,890".
get-string-binary(node-set)	string	Encodes the given string by using the UTF-8 encoding and returns the binary result in the form of a Base 64 string.	get-string-binary("Hello World") returns the Base 64 string SGVsbG8gV29ybGQ=.
lower-case(string)	string	Returns the given string converted to lowercase.	lower-case("Hello World") returns the string "hello world".
normalize-space(string)	string	Returns the argument string with the white space stripped.	normalize-space(" Hello World ") returns the string "Hello World".
replace(string, string, string)	string	Replaces parts of the input string (the first parameter) with the replacement string (the third parameter) that match regular expression pattern.	replace("Hello World", "World", "Universe") returns the string "Hello Universe".
starts-with(string, string)	boolean	Returns true if the first argument string starts with the second argument string; otherwise returns false.	starts-with("Hello", "He") returns True.
string(object?)	string	Converts an object to a string.	string(123) returns "123".
string-find(node-set, node-set)	number	Searches the input string (first parameter) for an occurrence of the search string (second parameter). It returns the character index of the first occurrence of the search string.	string-find("Hello World", "e") returns 2.
string-join(node-set, string, string?)	string	Returns the string containing the concatenated strings of the given nodes delimited by the string specified by the second parameter. The third parameter is optional and specifies the string which acts as the last delimiter.	string-join("Hello", "World", "-") returns "Hello-World".
string-length(string)	number	Returns the number of characters in the string.	string-length("Hello World") returns 11.
string-split(string, boolean, string)	node-set	Returns a node set of strings that contains the substrings of the input string (first parameter) delimited by the specified string (third parameter). If the Remove Empty Entries flag (second parameter) is set to True, then all empty strings will be removed from the result.	string-split("Contoso Entertainment System USA", true(), " ") returns "ContosoEntertainmentSystemUSA".
substring(string, number, number?)	string	Returns the substring of the first argument starting at the position specified in the second argument and the length specified in the third argument.	substring("Hello World", 1, 5) returns "Hello".
substring-after(string, string)	string	Returns the substring of the first argument string that follows the first occurrence of the second argument string in the first argument string.	substring-after("Hello World", " ") returns "World".
substring-before(string, string)	string	Returns the substring of the first argument string that precedes the first occurrence of the second argument string in the first argument string.	substring-before("Hello World", " ") returns "Hello".
translate(string, string, string)	string	Returns the first argument string with occurrences of characters in the second argument string replaced by the character at the corresponding position in the third argument string.	translate("Hello World","o","M") returns "HellM WMrld".
trim(node-set)	string	Removes whitespaces on the left and the right side of the input string and returns the remaining string. If the input string is not provided, the current XML node is used as the input.	trim(" Hello World ") returns "Hello World".
upper-case(string)	string	Returns the given string converted to uppercase.	upper-case("Hello World") returns "HELLO WORLD".

Operators

XPath operators are categorized into subgroups. The following XML structure will be used to demonstrate operator examples:

Axes

The purpose of axes is to find nodes in DDSP data sections based on their relationships, such as parent-child or sibling relationships. XPath includes several axes that we can use to traverse through these relationships:

Syntax	Description	Example
ancestor::	The ancestor of the context node. The ancestors of the context node consist of the parent of the context node and the parent's parent and so on; thus, the ancestor:: axis always includes the root node unless the context node is the root node.	ancestor::ReportData selects the ancestor nodes of the current node, up to the root node. In this case, the expression will select the <ReportData> node.
ancestor-or-self::	The context node and its ancestors. The ancestor-or-self:: axis always includes the root node.	ancestor-or-self::SalesInvoiceLines selects the ancestor nodes of the current node, including the current node itself. In this case, the expression will also select the current node, which is the <SalesInvoiceLines> node.
attribute::	The attributes of the context node. This axis will be empty unless the context node is an element.	attribute::Name selects the attributes of the current node. In this case, the expression will select the Name attribute of the <SalesInvoiceLines> node.
child::	The children of the context node. A child is any node immediately below the context node in the tree. However, neither attribute nor namespace nodes are considered children of the context node.	child::PackingSlip selects the child nodes of the current node. In this case, the expression will select the <PackingSlip> node.
descendant::	The descendants of the context node. A descendant is a child or a child of a child and so on; thus, the descendant:: axis never contains attribute or namespace nodes.	descendant::SalesInvoiceLines selects the descendant nodes of the current node. In this case, the expression will select the <SalesInvoiceLines> node and all of its child nodes, including the <PackingSlip> node.
descendant-or-self::	The context node and its descendants.	descendant-or-self::SalesInvoiceLines selects the descendant nodes of the current node, including the current node itself. In this case, the expression will also select the current node, which is the <SalesInvoiceLines> node.
following::	All nodes that are after the context node in the tree, excluding any descendants, attribute nodes, and namespace nodes.	following::PackingSlip selects all nodes that are after the current node in the tree, excluding any descendants, attribute nodes, and namespace nodes. In this case, the expression will select the <PackingSlip> node.
following-sibling::	All the following siblings of the context node. The following-sibling:: axis identifies just those children of a parent node who appear in the tree after the context node. This axis excludes all other children that appear before the context node. If the context node is an attribute node or namespace node, the following-sibling:: axis is empty.	following-sibling::PackingSlip selects all the following siblings of the current node. In this case, the expression will be empty because the <SalesInvoiceLines> node does not have any following siblings.
namespace::	The namespace nodes of the context node. There is a namespace node for every namespace which is in scope for the context node. This axis will be empty unless the context node is an element.	namespace::xmlns selects the namespace nodes of the current node. In this case, the expression will select the namespace node with the prefix xmlns.
parent::	The parent of the context node if there is one. The parent is the node immediately above the context node in the tree.	parent::SalesInvoiceLines selects the parent of the current node. In this case, the expression will select the <ReportData> node.
preceding::	All nodes that are before the context node in the tree, excluding any ancestors, attribute nodes, and namespace nodes. One way to think of the preceding axis is all nodes whose content occurs in their entirety before the start of the context node.	preceding::SalesInvoiceLines selects all nodes that are before the current node in the tree, excluding any ancestors, attribute nodes, and namespace nodes. In this case, the expression will be empty because the <PackingSlip> node is the first child of the <SalesInvoiceLines> node.
preceding-sibling::	All the preceding siblings of the context node. The preceding-sibling:: axis identifies just those children of a parent node who appear in the tree before the context node. This axis excludes all other children that appear after the context node. If the context node is an attribute node or namespace node, the preceding-sibling:: axis is empty.	preceding-sibling::PackingSlip selects all the preceding siblings of the current node. In this case, the expression will be empty because the <PackingSlip> node does not have any preceding siblings.
self::	Just the context node itself.	self::PackingSlip selects just the context node itself. In this case, the expression will select the <PackingSlip> node.

Comparison

Syntax	Description	Example
=	Equal to.	SalesInvoiceLines/@Name = "Mid-Range Speaker" returns True.
!=	Not equal to.	SalesInvoiceLines/@Name != "Mid-Range Speaker" returns True.
<	Less than.	SalesInvoiceLines/@LineAmount < 2000 returns True.
>	Greater than.	SalesInvoiceLines/@LineAmount > 1000 returns True.
<=	Less than or equal.	SalesInvoiceLines/@LineAmount <= 1920 returns True.
>=	Greater than or equal.	SalesInvoiceLines/@LineAmount >= 1920 returns True.

Logical

Syntax	Description	Example
and	Logical AND.	child::PackingSlip and SalesInvoiceLines/PackingSlip/@ShowCustPackingSlipTrans = "false" returns true.
or	Logical OR.	child::PackingSlip or SalesInvoiceLines/PackingSlip/@ShowCustPackingSlipTrans = "true" returns true.
|	Set operation; returns the union of two sets of nodes.	(child::PackingSlip) | (child::SalesInvoiceLines) will return all nodes that are either children of the PackingSlip element or children of the SalesInvoiceLines element.

Numeric

Syntax	Description	Example
+	Add.	SalesInvoiceLines/@LineAmount + 80 returns 2000.
-	Subtract.	SalesInvoiceLines/@LineAmount - 20 returns 1900.
*	Multiply.	SalesInvoiceLines/@LineAmount * 2 returns 3840.
div	Divide.	SalesInvoiceLines/@LineAmount div 2 returns 960.
mod	Modulo. Returns the remainder from a truncating division.	SalesInvoiceLines/@LineAmount mod 100 returns 20.

See Also:

Configurable Business Documents >>
Template Design >>