VARIABLES

Provides commands for defining variables and changing their values.

addItem

Adds an item to a Collection. This new item will appear as the last item of the Collection.

Parent commands

• setCollection
  Optional. If placed as a child of setCollection, the collection attribute may be left undefined to have the parent command's new Collection receive the item.

Attributes

value
Required	Value type	EL-evaluated
Yes	Any	Yes
The resolved value of this attribute is the new item for the Collection.

collection
Required	Value type	EL-evaluated
No	Collection	Yes
Defines the Collection into which the new item is added. If this attribute is undefined and this command is a child of setCollection, the item is added into that newly created Collection. Leaving this attribute undefined if this command is not a child of setCollection is considered an error.

Examples

Using addItem as a child of setCollection causes the item to be added into the newly created Collection. Use this way to initialize fresh Collections with content.

<setCollection var="items">
  <addItem value="${item}">

If adding an item to an already existing Collection, the collection attribute needs to be defined.

<setCollection var="items">
...
<addItem value="${item}" collection="${items}">   

addListItem

Adds an item to a Collection. Essentially the same as addItem, but should the item value be a data item, it is placed into a new Collection and this Collection then becomes the added item.

Parent commands

• setCollection
  Required. The Collection created by this parent command receives the item.

The addItem command is the recommended way of adding items to Collections. Unless your logic needs the feature of Data items getting wrapped into Collections, please consider using addItem instead.

Attributes

value
Required	Value type	EL-evaluated
Yes	Any	Yes
The resolved value of this attribute is the new item for the Collection. If the resolved value is a Data item, a new Collection is created and the Data item placed into it, and this Collection then becomes the new item for the parent Collection.

addMapEntry

Adds an entry to a Map. The entry will have the key and value as defined by the values of this command's attributes.

Parent commands

• setMap
  Optional. If placed as a child of setMap, the map attribute may be left undefined to have the parent command's new Map receive the entry.

Attributes

key
Required	Value type	EL-evaluated
Yes	String	Yes
Defines the key for the generated map entry. If the Map already has an entry with this key, that entry will be replaced by this new entry.

value
Required	Value type	EL-evaluated
Yes	Any	Yes
Defines the value for the generated map entry.

map
Required	Value type	EL-evaluated
No	Map	Yes
Defines the Map into which the new entry is added. If this attribute is undefined and this command is a child of setMap, the entry is added into that newly created Map. Leaving this attribute undefined if this command is not a child of setMap is considered an error.

Examples

Any existing Map and Map-like value (such as a Data item) in the variable context can receive new entries through addMapEntry. Note that if the target map already has an entry with the specified key, the value of this new entry overwrites the currently existing value.

<addMapEntry key="testKey" value="${testValue}" map="${testMap}">

The addMapEntry command can also be a child of the setMap command in which case the map attribute may be left undefined, causing the newly created Map to receive the entry.

<setMap var="testMap">
  <addMapEntry key="testKey" value="${testValue}">

addZipItem

Adds a new item into a Zip archive file.

Parent commands

• createZip
  Required. The addZipItem command can only exist as a child of createZip.

Attributes

value
Required	Value type	EL-evaluated
Yes	File	Yes
Defines the File which is to be added as a new item into the archive.

name
Required	Value type	EL-evaluated
No	String	Yes
Defines the name of the new item in the archive. If not defined or if the value is an empty String, the name of the File defined with value is used.

count

Counts the number of items within a Collection and places the result into a new variable. While a Collection's number of items can be easily accessed through the Collection value's size() method, this command offers a safer way of doing this as it doesn't cause errors should the target variable have a null value, or not actually hold a Collection value.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will receive the number of items as a Number value.

value
Required	Value type	EL-evaluated
Yes	Any	Yes
The resolved value of this attribute is expected to be the Collection whose items are counted. However, any kind of value is accepted - even null. The result of the count for any non-Collection, non-null value will always be 1, while null results in 0.

createDocPack

Creates a variable with a new Document package as its value.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the new Document package.

docs
Required	Value type	EL-evaluated
Yes	Collection	Yes
The resolved Collection value of this attribute should contain File items. These items become the contents of the new Document package.

name
Required	Value type	EL-evaluated
Yes	String	Yes
Defines a name for the new Document package.

Examples

Document packages can be used to easily create PDFs that have several documents combined into one. To do this, first create a Collection and add the document files you wish to combine into it.

<setCollection var="documents">
  <addItem value="${doc1}"> 
  <addItem value="${doc2}">

Then make a Document package out of the Collection, and export the package into a PDF file.  

<createDocPack var="package" docs="${documents}" name="combinedDocs">
<exportPDFDocPack var="combinedPDF" docPack="${package}">  

createZip

Creates a variable with a new Zip archive file as its value.

Child commands

• addZipItem
  Required. At least one item has to be added into the new archive. While there is no specific maximum amount of these child commands, the file size of the archive may not exceed 256 megabytes.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the Zip archive file.

fileName
Required	Value type	EL-evaluated
No	String	Yes
Defines the name of the created File. If undefined, the File's name will be the value of var with the ".zip" suffix.

title
Required	Value type	EL-evaluated
No	String	Yes
Defines a title for the created File. If undefined, the File's title will be the value of var.

compression
Required	Value type	EL-evaluated
No	Integer	Yes
Defines the level of the archive's compression. The value can be any number from 0 to 9, 0 being no compression and 9 being the highest level of compression. Providing any other value will produce an error. Note that higher compression levels cause the creation of the archive to take longer, which may or may not be notable as this command is being evaluated. If left undefined, a default compression level intended to be a good compromise between speed and compression is used.

keepContextItems
Required	Value type	EL-evaluated
No	Boolean	Yes
Defines if the Files added to the archive through addZipItem commands are removed from the variable context. A value of true prevents this from happening. Note that this removal only affects Files that have their own variables in the context - Files stored in Collections, for example, will not be affected. If undefined, value of false is used.

filter

Creates a new Collection that contains another Collection's items that pass the specified condition.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the filtered Collection. If all of the source Collection's items fail to pass the filtering condition, the variable's value will be an empty Collection.

value
Required	Value type	EL-evaluated
Yes	Collection	Yes
The resolved Collection value is the source Collection whose contents are filtered. This source Collection will not be modified in any way.

where
Required	Value type	EL-evaluated
Yes	String	No
Specifies the EL-expression that serves as the filtering condition. This expression is evaluated for every item in the source Collection, and all of them for which this expression evaluates into a Boolean true pass the filter and are included in the result. In this expression the currently checked Collection item can be accessed with the variable name defined in itemName (or "x" if that attribute is undefined). The resolved value of this attribute being an empty String or an invalid expression is considered an error.

itemName
Required	Value type	EL-evaluated
No	String	Yes
This attribute can be used to specify the name of the variable representing the source Collection's item in the EL-expression specified in where. If left undefined, the name of the item variable will be "x".

Examples

Filtering a Collection of Salesforce query results:

<query var="lineItems" select="SELECT Id, Name, ListPrice, Quantity FROM OpportunityLineItem WHERE OpportunityId='${mainOppId}'">
<filter var="lowQuantity" value="${lineItems}" itemName="lineItem" where="${lineItem.Quantity < 10}">

You can also continue to filter the result of a previous filtering further:

<filter var="lowerQuantity" value="${lowQuantity}" itemName="lineItem" where="${lineItem.Quantity < 5}">

getContent

Retrieves a File from an Online template archive and stores it into the variable context.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the retrieved File.

dap
Required	Value type	EL-evaluated
Yes	File	Yes
This attribute's resolved value should be the Online template containing the sought resource. The expression ${doc} can be used here to access the Online template currently being evaluated.

resource
Required	Value type	EL-evaluated
Yes	String	Yes
Defines the path to the sought resource within the archive. The path should be relative to the archive's root, eg. "Document/content.html".

parseJSON

Takes JSON content as a File or as a String and parses it into an appropriate structure of variable values. JSON objects become Maps, arrays become Collections and the values within them appear as Strings, Numbers or Booleans.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the parsed result.

value
Required	Value type	EL-evaluated
Yes	String, File	Yes
Defines the JSON content to be parsed.

restoreString

Restores a String previously stored with storeString. The restored String may optionally be parsed into a different type of value.

If you wish to restore several values, instead of a bunch of restoreString commands you may be able to make use of restoreStringSet instead to reduce the command count.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the restored String or the result of it being parsed as defined by parser.

key
Required	Value type	EL-evaluated
Yes	String	Yes
Name of the stored String to restore. Corresponds with the key attribute of the storeString tag.

parser
Required	Value type	EL-evaluated
No	String	No
Defining a value for this attribute causes the restored String to be parsed into a different kind of value. The following values may be used: "json" The restored String is parsed as JSON, resulting in a Map or a Collection containing more values as defined by the JSON content. "file" The restored String is parsed into a File. Name of a Parser The restored String is parsed with the named Parser into a kind of value that the Parser produces. If left undefined, the restored String will appear in the variable context as just a String.

readFrom
Required	Value type	EL-evaluated
No	File	Yes
The resolved File value is where the String to be restored is expected to be stored in. The File may be a Document application, an Office template or a PDF document. If this attribute is not defined, the String is restored from the Document application or Office template in which this command exists in.

restoreStringSet

Restores multiple strings previously stored with storeString or storeStringSet. All stored strings whose names start with the specified prefix, or all of them if no prefix is defined, are restored into variables.  Each created variable's name is the same as its name as a stored string.

Each found string can optionally be parsed into another kind of value with a parser. It's the same parser for all strings, so if there's a need to restore the strings as various kinds of objects, use multiple restoreStringSet (with stricter prefixes) or restoreString commands using different parsers.

At the moment, this command is able to restore values only from PDF documents. For DOCX, PPTX, XLSX and Dynamo Online template files, please use restoreString instead.

Attributes

prefix
Required	Value type	EL-evaluated
No	String	Yes
Stored Strings with names starting with the resolved String are restored. If not defined, all stored Strings found in the file are restored.

parser
Required	Value type	EL-evaluated
No	String	No
Defining a value for this attribute causes the restored Strings to be parsed into values of a different kind. The following values may be used: "json" The restored Strings are parsed as JSON, resulting in a Map or a Collection containing more values as defined by the JSON content. "file" The restored Strings are parsed into Files. Name of a Parser The restored Strings are parsed with the named Parser into value of the kind that the Parser produces. If left undefined, the restored Strings will appear in the variable context as just Strings.

readFrom
Required	Value type	EL-evaluated
Yes	File	Yes
The resolved File value is where the Strings to be restored are expected to be stored in. Unlike with restoreString, with this command the File has to be a PDF document.

set

Sets a variable of the defined name and value into the variable context, overwriting any existing variable with the same name. If placed within a looping command or any other command that creates a local variable context, set can be used to set a new value for a variable in the parent variable context, presuming that the local context does not contain a variable of the same name.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the value.

value
Required	Value type	EL-evaluated
No	Any	Yes
Whatever value this attribute's expression resolves into is set into the variable named with var. If not defined or if the value expression resolves into null, no variable is set. Additionally, if the required attribute resolves into true, an error is produced.

required
Required	Value type	EL-evaluated
No	Boolean	No
If this attribute resolves into true, the value attribute resolving into null produces an error. If not defined, value of false is used.

format
Required	Value type	EL-evaluated
No	String	Yes
If the resolved value of this attribute is the name of a Format, that Format is used format the resolved value of value into a String. If both parser and format are defined, and the parsing process is successful, the value to be formatted is the result of the parsing. If undefined or if the named Format cannot be found, no formatting is done to the value.

parser
Required	Value type	EL-evaluated
No	String	Yes
If the resolved value of this attribute is the name of a Parser, the resolved value of value is first converted into a String (if it isn't one already) and then parsed into another type of value by the Parser. If both parser and format attributes are defined, the parsing process is done before the formatting. If undefined or if the named Parser cannot be found, the value remains retains its original type.

Examples

The set command has a variety of uses despite its simple nature. One common use is to copy parameter values of the Flow into more conveniently named variables. This also makes these values available in contexts where the parameter map is not accessible.

<set var="id" value="${param.id}">

Besides duplicating values of existing variables, set can be used to create entirely new variables. Creating a String only requires the value attribute to not be an EL-expression.

<set var="defaultWeather" value="Somewhat gusty"> 

Boolean values can be set with EL-expressions ${true} and ${false}.

<set var="doesItWork" value="${true}">

The parser attribute can be used to convert existing variables into other types of variables. Converting a String representing a number into an actual Number, for example, allows the value to used in mathematical EL-expressions. Just be sure to use a number parser suited to parsing number strings of the given format.

<set var="numberStr" value="122,25"/>
<set var="actualNumber" value="${numberStr}" parser="numberParser"/> 

The command's unique property to allow overwriting values of variables in parent variable contexts is also essential at times. Any other variable-producing command places its variable into its current context, which, for example, inside a forEach loop is its child context that will terminate when the loop is finished.

In this example, if the set preceding forEach didn't exist, the variable created by the set inside the forEach would just disappear when forEach is done. But with the first set creating the variable in the base variable context, the inner set sets its value there as well, allowing the value to exist past the loop.

<set var="soughtContactId" value="-">
<forEach value="${contacts}" var="${contact}">
  <if test="${contact.Name == soughtContactName}">
    <set var="soughtContactId" value="${contact.Id}">

setCollection

Creates a variable with a new Collection as its value.

Parent commands

• setCollection
  Optional. If setCollection is a child command of another of its kind, the created Collection will be automatically added into the Collection created by the parent command.

Child commands

• addItem
  Optional. Any number of addItem commands may be set as children of setCollection to have the new Collection start out with content instead of being empty.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the new Collection.

setMap

Creates a variable with a new Map as its value.

Child commands

• addMapEntry
  Optional. Any number of addMapEntry commands may be set as children of setMap to have the new Map start out with content instead of being empty.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that will hold the new Map.

data
Required	Value type	EL-evaluated
No	File	Yes
This attribute allows adding of a set of entries defined as a Java properties file. The resolved File value should therefore be such a properties file.

encoding
Required	Value type	EL-evaluated
No	String	Yes
The value of this attribute specifies the encoding of the Java properties file defined with the data attribute. If data is undefined, this attribute has no effect. Valid values for this attribute are the following: US-ASCII (also known as ISO646-US) ISO-8859-1 UTF-8 UTF-16BE UTF-16LE UTF-16 If this attribute is left undefined while data is defined, value of "ISO-8859-1" is used.

ordered
Required	Value type	EL-evaluated
No	Boolean	Yes
Defines whether the Map will be such that its entries will appear in a predictable order when looped through with its keySet() or values() methods. If the resolved value is true, the order is defined for iteration, otherwise the iteration order is more or less random. If not defined, value of false is used as the use cases in which a Map's contents need to be iterated through in some manner, and the order would matter, are not particularly common.

setProperty

Allows a new value to be set for a property of an existing variable.

Attributes

target
Required	Value type	EL-evaluated
Yes	String	No
The resolved String should be an EL-expression specifying the property whose value is to be changed.

value
Required	Value type	EL-evaluated
No	Any	Yes
Defines the new value for the property specified with target.

required
Required	Value type	EL-evaluated
No	Boolean	No
If this attribute resolves into true, the value attribute resolving into null produces an error. If not defined, value of false is used.

setTranslation

Creates a new variable that holds a translation Map found inside the Online template this command is in.

As internal translation resources are a feature available only available in Online templates, this command cannot be used in Office templates.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that holds the translation Map. Depending on the language attribute, the value of this variable can be of two kinds.It can be a single Map holding translations of a single language, or it can be a Map mapping language keys into Maps of corresponding translations.

value
Required	Value type	EL-evaluated
No	String	Yes
This attribute may be used to specify the translation resource to use. The resolved String should be a path within the Online template archive pointing to a translation resource. If not defined, one of the translation resources within the Online template is automatically selected. If there are multiple such resources within the archive, there is no guarantee which one of them is selected.

language
Required	Value type	EL-evaluated
No	String	Yes
If the resolved String is one of the language keys present in the translation resource, only translations of that language are placed into the variable context as a Map. If not defined or the resolved String is blank, all languages present in the translation resource are placed into the variable context as a Map containing Maps.

setText

Creates a new variable holding a String value, or appends new content at the end of an existing variable's value.

Unlike with most commands, the value to set or append is not defined as an attribute value. Instead, the text content within this command becomes the value. Child commands may also be used to alter this text content.

Child commands

Any command can be a child of setText. Logic control commands such as forEach and if can be used to modify the text content.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that holds the String value created out of the text within this command.

append
Required	Value type	EL-evaluated
No	Boolean	No
If this attribute resolves into true and var specifies the name of an already existing variable, this commands's text content is added to the end of the existing variable's value. If the existing variable's value is not a String, it will be converted into one, but do note that the more complex kinds of variables generally turn into descriptor Strings that are not intended to be used as text or presented to users.

sortCollection

Produces a new variable holding a Collection with the contents of the specified Collection sorted.

Collections may contain various kinds of items, such as Maps, and so this command cannot automatically know how the items should be sorted. This needs to be told through the comparableValue  attribute. The attribute's value should be an EL-expression that is evaluated in the context of the Collection; the result of this evaluation for each item should be a value that can be compared with other items' values (eg. Strings can be compared with each other to produce an alphabetical order).

For example, a Collection containing Maps holding data of users could be sorted based on the users' names. A user's name is in its Map behind the key 'Name'. The comparableValue expression to achieve this task would be ${item.Name}. The expression format is much like an expression within a loop iterating through the Collection, with the iterated item's variable name being "item".            

Should the Collection contain values that are directly comparable themselves, such as Numbers, the expression to use is just ${item}.

Not all kinds of values are suitable for sorting. Some value types are not comparable to begin with - such as Collections themselves - and values of different types (eg. Strings and Numbers) cannot be compared with each other. Attempting to do this kind of comparison produces an error.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable that holds the sorted Collection.

value
Required	Value type	EL-evaluated
Yes	Collection	Yes
The resolved value of this attribute is the Collection that is to be sorted. As the sorted Collection becomes a new value, this source Collection remains unmodified.

comparableValue
Required	Value type	EL-evaluated
Yes	String	No
Specifies the expression that is used to find a value from each item in the Collection. The Collection is then sorted based on how these values get sorted. The expression is to be formed as if it was evaluated within a loop iterating through the Collection, with "item" being the variable name for the item itself.

descending
Required	Value type	EL-evaluated
No	Boolean	Yes
If this attribute resolves into true, the order of items in the sorted Collection is reversed.

Examples

Sorting a Collection of Salesforce query results:

<query var="contacts" select="SELECT Id, Name FROM Contact WHERE AccountId='${mainAccId}'">
<sortCollection var="sortedContacts" value="${contacts}" comparableValue="${item.Name}">

storeString

Stores a variable value into a document or another kind of File that can be later restored with restoreString.

Attributes

key
Required	Value type	EL-evaluated
Yes	String	Yes
Defines the name given to the stored String in the File. When this stored String is restored with restoreString, its key value has to match this command's key value.

value
Required	Value type	EL-evaluated
Yes	Any	Yes
The resolved value of this attribute is the value stored. If format is defined, this value is formatted before being stored, otherwise it is stored as is.

format
Required	Value type	EL-evaluated
No	String	No
Defining a value for this attribute causes the stored String to be formatted into a different kind of value before being stored. Matching this format with restoreString's parser allows more complex variable values besides Strings to be stored and restored back into values of their original kinds. The following values may be used: "json" The value is formatted into JSON. This allows various kinds of non-String values, such as Collections and Maps, to stored and restored successfully.   "file" The value is base64-encoded. This allows File values to be stored and restored successfully. Name of a Format The value is formatted with the named Format. If left undefined, the value is converted into a String if it isn't one already and stored.

storeTo
Required	Value type	EL-evaluated
No	File	Yes
The resolved File is where the value is stored. The File may be an Online template, an Office template or a PDF document. If this attribute is not defined, the value is stored into the Online template or Office template in which this command exists in.

storeStringSet

Stores values of multiple variables into a document or another kind of File. They can be then later restored with restoreString or restoreStringSet.            

The values to be stored are defined with the prefix attribute. All variables in the variable context whose names start with that prefix are picked and then stored using their variable names as the storage keys.

Attributes

prefix
Required	Value type	EL-evaluated
Yes	String	Yes
Defines the prefix used to select the variables whose values to store.

format
Required	Value type	EL-evaluated
No	String	No
Defining a value for this attribute causes the stored Strings to be formatted into values of a different kind before being stored. Matching this format with restoreString's or restoreStringSet's parser allows more complex variable values besides Strings to be stored and restored back into values of their original kinds. The following values may be used: "json" The values are formatted into JSON. This allows various kinds of non-String values, such as Collections and Maps, to stored and restored successfully.   "file" The values are base64-encoded. This allows File values to be stored and restored successfully. Name of a Format The values are formatted with the named Format. If left undefined, the values are converted into Strings if they aren't such already and stored.

storeTo
Required	Value type	EL-evaluated
No	File	Yes
The resolved File is where the values are stored. The File may be an Online template, an Office template or a PDF document. If this attribute is not defined, the values are stored into the Online template or Office template in which this command exists in.

toJSON

Creates a JSON representation of the specified value and stores it into the variable context. The JSON conversion works best on Collections, Maps, Numbers, Strings and Booleans - while a File, for example, can be given to this command, the produced JSON will not actually contain the file data and cannot be parsed back into a proper File.  

The JSON produced by this command can be given to the parseJSON command to re-create the original value, unless the JSON was created out of a value of a type that doesn't convert into JSON very well.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable holding the produced JSON String.

value
Required	Value type	EL-evaluated
Yes	Any	Yes
Defines the value of which the JSON representation is created of.

toString

Creates a new variable holding a String that is created out of a specified value. This command has special handling for Collection values, presenting them as comma-separated lists with a specific property representing each of the Collection's items.

Attributes

var
Required	Value type	EL-evaluated
Yes	String	No
Defines the name of the variable holding the produced String.

value
Required	Value type	EL-evaluated
Yes	Any	Yes
Defines the value from which a String is produced out of.

expr
Required	Value type	EL-evaluated
No	String	No
Defines the EL-expression used to produce a String representation out of the value that the value attribute resolves into. If the resolved value is a Collection, then this expression is evaluated for every item in the Collection. The item can appear in the expression represented by the variable name defined in itemName. The results of these evaluations then appear in the Collection's String form separated by commas. If the resolved value is not a Collection, then this expression is evaluated with that value being the variable behind the name defined in itemName. If this attribute is undefined, Collection items and other values are directly converted into Strings. Note that certain kinds of more complex values convert into descriptor Strings that are generally not very suitable for any use - with such values defining a proper expression for this attribute is highly recommended.

itemName
Required	Value type	EL-evaluated
No	String	Yes
This attribute can be used to specify the name of the variable representing the item in the EL-expression specified in expr. If left undefined, the name of the item variable will be "x".

Examples

The toString command can produce a text representation of any value, but its primary feature is its ability to easily create text representations of Collections.

<toString var="contactNames" value="${contacts}" itemName="contact" expr="${contact.Name}">

This would produce a String listing the names of all contacts in the Collection, separated with commas.