More Macro Functions
AddJsonProperty()
This function inserts a new property into a string that represents a valid JSON document and returns the extended JSON string.
If the input string is empty, a new JSON document is created. By calling this macro function multiple times, a full JSON document can be created successively within a field.
Return type: text
Parameter | Data Type | Description |
|---|---|---|
1 | Text | JSON string or empty string for the creation of a new JSON document |
2* | Text | JSONPath expression that describes the path of the new JSON property to be created Specify the absolute path here in full, using the same syntax as in the |
3 | (variable) | Value assigned to the JSON property Default setting: |
Examples
AddJsonProperty("", "Name", "Value") returns a string with a new JSON object "{""Name"": ""Value""}".
AddXmlNode()
This function inserts a new element into a string that represents a valid XML document and returns the extended XML string.
If the input string is empty, a new XML document including the declaration element will be created. You can call this macro function multiple times to create a full XML document successively within a field.
Return type: text
Parameter | Data Type | Description |
|---|---|---|
1 | Text | XML string or empty string for the creation of a new XML document |
2* | Text | XML expression that describes the path of the new XML element (node or attribute) to be created Specify the absolute path here in full, using the same syntax as in the |
3 | (variable) | Value assigned to the XML element (optional) If this value is empty, an empty node or an attribute with an empty value will be created in the XML document. If the value is not of the "Text" type, the value will be converted to the program's internal string notation. |
4 | Text | Specification of a namespace URI that is added to the element (optional) Specify the associated prefix in the XPath expression. You can include multiple elements in the expression, but only one URI, which will always only refer to the last element in the path. If the higher-level elements are also to be assigned to a namespace, build up the path step by step in multiple macro calls. |
5 | Number | Number of the node level in the XPath expression A new XML node is created at this level. If a node with the same name already exists, the new node will be created parallel to it. Counting starts at 1. Default value: If, for example, the If a node that already exists multiple times in an XPath expression is addressed and is not to be recreated, the last existing node will always be selected. When structuring an XML document step-by-step, additional data will typically be appended at the end. |
Examples
AddXmlNode("", "/Root/Name", "Value") returns a string with a new XML document ?xml version=""1.0"" encoding=""UTF-8""?><Root><Name>Value</Name></Root>".
CallWebService()
This function executes a query against an external web service and returns the HTTP body content from its response.
Return type: text
Parameter | Data Type | Description |
|---|---|---|
1* | Text | Name of the |
2 | Text | Value that is transferred to the web service as HTTP body content |
3 | Text | Alternative to first parameter: name filter for a file attachment Only the first attachment found is taken into account. Data from the second parameter and from a file of text, JSON, or XML type is always transferred in text form. Other file types are transferred as binary data. |
4 | Text | Value of the associated "Content-Type" header for the data transmitted in the HTTP body in accordance with parameter 2 or parameter 3 For data in JSON format, this might be |
Examples
CallWebService("WebService1", "{}", , "application/json") sends the data of the (in the example empty) JSON object to a web service whose connection parameters are defined under the name WebService1 in the configuration, and receives its response as a return value.
CallWebService("Google") loads the HTML data "<!doctype html><html..." from the Google start page if a web service connection named Google is configured with the URL https://www.google.com and the GET method.
CheckMandatory()
This function performs a mandatory value check for a field, i.e., the function will throw an error if the relevant field value is empty.
Depending on the data type, values will be taken as empty if they are not entered in the field macro IsEmpty() field macro. In contrast to the standard behavior, no return value will be generated. The existing field value will be retained.
Parameter | Data Type | Description |
|---|---|---|
1 | (variable) | Field value to be checked When used as a field initialization macro according to |
Examples
CheckMandatory("ABC") does not throw an error.
CheckMandatory(0) throws an error (zero is considered an "empty" numerical value).
DecodeBase64()
This function returns the decoded value of a Base64-encoded string.
Return type: text
Parameter | Data Type | Description |
|---|---|---|
1 | Text | Base64-encoded string to be decoded |
Examples
DecodeBase64("SGVsbG8=") returns "Hello".
EncodeBase64()
This function returns the Base64-encoded value of a string, the content of a file attachment or the content of an external file.
Return type: text
Parameter | Data Type | Description |
|---|---|---|
1 | Text | String to be decoded |
2 | Text | Alternative to the first parameter: name filter for a file attachment, whereby only the first attachment found is taken into account |
3 | Text | Alternative to the first and second parameter: full path of an external file in the file system |
Examples
EncodeBase64("Hello") returns "SGVsbG8=".
EncodeBase64( , "*.txt") returns the encoded content of a text file attachment or "", if not found.
EncodeBase64( , , "c:/test.txt") ergibt den kodierten Inhalt einer externen Datei.
ExecDbCommand()
This function executes a database command that is not a SELECT query (see QueryDbField()).
Such a database command might be an INSERT or UPDATE command, for example. The return value is the number of affected data records (e.g., 1 for a successful INSERT command).
Return type: number
Parameter | Data Type | Description |
|---|---|---|
1* | Text | Name of the property Non-SELECT commands are only supported for the data sources "OLEDB," "Microsoft SQL Server," and "MongoDB." In the case of "OLEDB" and "Microsoft SQL Server," we recommend including typed field variables in the form |
Examples
ExecDbCommand("DBCommand1") executes a database command that is configured under the name DBCommand1. The command can, for example, use the INSERT INTO [Table1]([Column1]) VALUES (@Field1) command to insert the value of the Field1 field into a table and return a 1 as the result of the execution.
ExternalFileExists()
This function checks whether an external file exists in the file system.
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1* | Text | Full path of the file in the file system |
Examples
ExternalFileExists("c:/test.txt") returns TRUE if the file exists.
GetDbCounter()
This function returns an integer automatically incremented with each call.
The same internal database table is used to store the current counter values as for the document macro functions or field macro functions WriteToCustomStore() and ReadFromCustomStore().
Return type: number
Parameter | Data Type | Description |
|---|---|---|
1 | Text | Context information about the following key, if this alone is not clear enough or unique (optional) |
2* | Text | Key under which the current counter value is stored |
3 | Number | Start value for creation of a new counter Default value: |
Examples
GetDbCounter( , "Counter1", 1000) returns 1000 if the counting key was newly created.
GetExternalFiles()
This function reads the names of external files in the file system that correspond to a given name pattern.
Return type: array of text values
Parameter | Data Type | Description |
|---|---|---|
1* | Text | Path of the root directory from which the files are searched for |
2 | Text | Name filter for the files to be searched for Default value: |
3 | Number | Maximum depth up to which subfolders are searched If the files are located in subfolders, the file names read will be preceded by the relative path in relation to the root directory. Default value: |
Examples
GetExternalFiles("c:/test", "*.txt") returns the names of all text files that are located directly in the folder (not in subfolders) (e.g., ["1.txt", "2.txt"] or [] if there is no match).
GetMd5Hash()
This function returns the MD5 hash value of a string, the content of a file attachment, or the content of an external file.
Return type: text
Parameter | Data Type | Description |
|---|---|---|
1 | Text | String used to calculate the hash value |
2 | Text | Alternative to the first parameter: name filter for a file attachment, whereby only the first attachment found is taken into account |
3 | Text | Alternative to the first and second parameter: full path of an external file in the file system |
Examples
GetMd5Hash("Hello") ergibt "8B1A9953C4611296A827ABF8C47804D7".
GetMd5Hash( , "*.txt") returns the hash value of a text file attachment or "" if not found.
GetMd5Hash( , , "c:/test.txt") returns the hash value of an external file.
GetNull()
This function returns the value NULL.
By default, the macro interpreter does not directly support the value NULL. Instead, empty values are used depending on the data type (e.g., an empty string "" for an empty text value). However, NULL values can occur in exceptional cases (e.g., as the result of an external database query).
The GetNull() function is used to generate NULL values for testing purposes and is not intended for use in productive configuration. The test generation of NULL values can be used to check the behavior of macro functions when such values are sent.
Examples
GetNull() returns NULL.
GetUuid()
This function returns a newly created UUID (Universally Unique Identifier) with a length of 36 characters (32 digits plus delimiters).
Return type: text
Examples
GetUuid() returns a UUID as a string (e.g., "0bdebfe9-077a-4bd4-ae02-6eb1a2815440").
IsEmpty()
This function checks if a value is "blank."
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1 | (variable) | Value to be checked |
Examples
IsEmpty("") and IsEmpty(NULL) returns TRUE.
IsEmpty(0) returns TRUE.
IsEmpty(0001-01-01) returns TRUE.
IsEmpty([]) returns TRUE.
IsEmpty(FALSE) returns FALSE (Boolean values are not considered empty).
IsNull()
This function checks if a value is NULL.
By default, the internal macro interpreter is not designed to handle NULL values. Instead, the macro interpreter uses empty values depending on the data type (see IsEmpty()). A corresponding check function is available for the special case where values are read from an external database and NULL values are not converted to the type-appropriate empty values, but are to be retained as NULL values. The IsEmpty() function also recognizes NULL values, but does not differentiate between these values and the regular empty values.
An explicit check for NULL values is useful if these values can occur as the result of a database query. During further processing, it may be necessary to differentiate between cases, as the macro functions are not designed to process NULL values, depending on their specific implementation.
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1 | (variable) | Value to be checked |
Examples
IsNull("") returns FALSE.
IsNull(NULL) returns TRUE.
Lookup()
This function reads from a lookup list the value associated with a defined key, or an empty text value if the key is not found.
The contents of such a list are defined in the Lookup[] property of the scenario configuration (see General Properties).
Return type: text
Parameter | Data Type | Description |
|---|---|---|
1 | Text | Name of the lookup list to use according to its property |
2 | Text | Key to be read from the list |
Examples
Lookup("Lookup1", "KeyA") returns the value of the key KeyA in the lookup list Lookup1, e.g. "ValueA" or "", if not found.
LookupLike()
This function reads from a lookup list one or all values whose keys match a defined pattern. The return value type is text or array, depending on whether one or more values are read. If no value is found, the return value will contain an empty string or array.
Parameter | Data Type | Description |
|---|---|---|
1 | Text | Name of the lookup list to use according to its property |
2 | Text | Wildcard expression of the search pattern, analogous to operator |
3 | Text | Definition of which values of which entries are read from the list in the case that the search pattern is ambiguous:
|
Examples
Examples of a lookup list Lookup1 with the key/value pairs KeyA=ValueA, KeyB=ValueB and KeyC=ValueC:
LookupLike("Lookup1", "key*", "Last")returns"ValueC".LookupLike("Lookup1", "key*", "All")returns["ValueA", "ValueB", "ValueC"].LookupLike("Lookup1", "wrongKey", "All")returns[].
QueryDbField()
This function performs a SELECT query to an external data source and returns the first field of the first record found.
The return type varies.
Parameter | Data Type | Description |
|---|---|---|
1* | Text | Name of the property The command must be a SELECT query. When using an OLEDB or native SQL server connection, typed field variables in the form |
2 | Bool | Boolean value determining whether a By default, the macro interpreter does not directly support the value NULL. Instead, empty values are used depending on the data type (e.g., an empty string By default, NULL values from the database are converted to an empty value that matches the source data type. If the NULL value is to be retained instead, the This parameter also defines the return value if a data set is not found (i.e., defining whether an empty value appropriate to the type or wether a |
Examples
QueryDbField('DBSelect1') executes a database query that is configured under the name DBSelect1. The query can, for example, use the command SELECT [Column1] FROM [Table1] WHERE [Column2] = @Field2 to filter for data records with the value of Field2. The result is the value of the Column1 column of the first data record found (e.g., "Value1" for a text value, "" or NULL depending on the second parameter if there is no match).
ReadFromCustomStore()
This function reads a value previously persisted by the document macro function WriteToCustomStore() again.
The return type varies.
Parameter | Data Type | Description |
|---|---|---|
1 | Text | Context information about the following key, if this alone is not clear enough or unique (optional) |
2* | Text | Key under which the value to be read is stored If no key is found, an error is thrown. |
Examples
ReadFromCustomStore( , "CustomKey1") returns the value of the CustomKey1 key (e.g., "Value1" for a text value).