Functions
Version 24.1.8906
Version 24.1.8906
Functions
Think of functions as a special type of formatter that produces an output value, but does not require an input like the standard formatters do. Functions can be used by themselves or as the start of a more complex expression, where other formatters are piped in after it. For example [vault(foo)] can be resolved by itself, but you can also use it as the start of an expression (for example, [vault(foo) | equals(bar)] to check if the foo vault value is equal to bar).
CSV Functions
csv(value)
Used after loading data from a CSV file. The csvListRecords operation parses a CSV file, and the CSV formatter functions like other formatters by generating the values from a CSV document.
- value: The string of CSV column headers to find the values from. If the CSV file does not have headers, columns can be accessed by a generic index (c1, c2, c3, …) instead, if you set the requireheader attribute to false.
Example
In the following snippet, a CSV document is defined in memory in ArcScript.
<arc:set attr="data" value=
"column1,column2,column3
entry1,entry2,entry3
entry4,entry5,entry6"
/>
Next, the csvListRecords operation is called and CSV formatters are displayed from the sample CSV document.
<arc:call op="csvListRecords">
Row [_index] values: [csv('column1')], [csv('column2')], [csv('column3')]
</arc:call>
Running this code displays the following output:
Row 1 values: entry1, entry2, entry3
Row 2 values: entry4, entry5, entry6
JSON Functions
hasjsonpath(jsonpath)
Checks if the input jsonpath exists in the JSON document and returns a boolean (true/false).
- jsonpath: The relative jsonpath to check.
Example
<arc:set attr="json.text">
{
"key1": null,
"key2": "this is a string",
"key3": "hello world",
"key4": 123,
"key5": {},
"key6": \[],
"key7": true
}
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
<!-- This checks to see if the desired jsonpath exists and throws an error if it does not. -->
<arc:if exp="[hasjsonpath(key10) | equals(false)]">
<arc:throw code="noJSONPath" desc="The jsonpath you were looking for does not exist!" />
</arc:if>
</arc:call>
isjsonpathnull(jsonpath, [ifTrue], [ifFalse])
Checks the input jsonpath and returns a boolean (true/false) if the jsonpath is null or does not exist.
- jsonpath: The optional relative json to check.
- ifTrue: The optional value to be returned if the formatter resolves to true.
- ifFalse: The optional value to be returned if the formatter resolves to false.
Example
<arc:set attr="json.text">
{
"key1": null,
"key2": "this is a string",
"key3": "hello world",
"key4": 123,
"key5": {},
"key6": \[],
"key7": true
}
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
<arc:if exp="[IsJSONPathNull(key1) | equals(true)]" >
<!-- This executes because key1 has a value of null -->
<arc:set attr="_log.info" value="The jsonpath for key1 either has a value of null or does not exist." />
<!-- Overriding the default true/false output of the formatter to 1/0 -->
<arc:if exp="[IsJSONPathNull(key10, 1, 0) | equals(1)]" >
<!-- This executes because key10 does not exist within the input json text -->
<arc:set attr="_log.info" value="The jsonpath for key10 either has a value of null or does not exist." />
</arc:if>
</arc:if>
</arc:call>
jsonpath(jsonpath)
You can use this formatter inside calls to JSON operations that have the JSON DOM available. You can use the jsonDOMSearch and jsonDOMGet operations to parse a JSON document. The jsonpath formatter is a formatter of the DOM object that functions like other formatters by generating the values from an JSON document. The jsonpath formatter returns the current jsonpath location of an JSON document. Optionally, you can supply a string of a relative jsonpath to find the associated JSON value.
- jsonpath: The optional relative jsonpath to find the associated JSON value from.
Example
<arc:set attr="json.text">
{
"key1": null,
"key2": "this is a string",
"key3": "hello world",
"key4": 123,
"key5": {},
"key6": \[],
"key7": true
}
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
<!-- This prints 'I just want to say, hello world!' to the application log -->
<arc:set attr="_log.info" value="I just want to say, [jsonpath(key3)]!"/>
</arc:call>
jsontype(jsonpath)
Returns the data type (string, number, object, array or boolean) of the current JSON name/value pair.
- jsonpath: The optional relative jsonpath to find the associated JSON value from.
Example
<arc:set attr="json.text">
{
"key1": null,
"key2": "this is a string",
"key3": "hello world",
"key4": 123,
"key5": {},
"key6": \[],
"key7": true
}
</arc:set>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
<!-- Creating some output data that describes various elements of the input json -->
<arc:set attr="output.data">The jsontype of key4 is [jsontype(key4)]
The jsontype of key5 is [jsontype(key5)]
The jsontype of key6 is [jsontype(key6)]
The jsontype of key7 is [jsontype(key7)]
</arc:set>
</arc:call>
<arc:set attr="output.filename" value="output.txt" />
<arc:push item="output" />
<!-- contents of output.txt -->
The jsontype of key4 is NUMBER
The jsontype of key5 is OBJECT
The jsontype of key6 is ARRAY
The jsontype of key7 is BOOL
XML Functions
hasxpath(xpath)
Checks to see if the input xpath exists in the XML document and returns a boolean (true/false).
- xpath: The relative xpath to check.
Example
<arc:set attr="xml.text">
<Items>
<Foo>Bar</Foo>
<Bar>Foo</Bar>
</Items>
</arc:set>
<arc:set attr="xml.xpath" value="/Items"/>
<arc:call op="xmlDOMSearch" in="xml" out="result">
<!-- This checks to see if the desired xpath exists and throws an error if it does not -->
<arc:if exp="[hasxpath(helloworld) | equals(false)]">
<arc:throw code="noXPath" desc="The xpath you were looking for does not exist!" />
</arc:if>
</arc:call>
isxpathnull(xpath, [ifTrue], [ifFalse])
Checks the input xpath and returns a boolean in the form of the xsi:nil XML attribute (xsi:nil="true/false") if the xpath is null or does not exist. Use the ifTrue and ifFalse parameters to specify alternate values when the condition is and is not met.
- xpath: The optional relative xpath to check.
- ifTrue: The optional value to be returned if the formatter resolves to true.
- ifFalse: The optional value to be returned if the formatter resolves to false.
Example
<arc:set attr="xml.text">
<Items>
<Foo>Bar</Foo>
<Bar>Foo</Bar>
<helloworld xsi:nil="true" />
</Items>
</arc:set>
<arc:set attr="xml.xpath" value="/Items"/>
<arc:call op="xmlDOMSearch" in="xml" out="result">
<arc:if exp="[IsXPathNull(helloworld) | contains(true)]" >
<!-- This executes because the 'helloworld' has the xsi:nil attribute set to true -->
<arc:set attr="_log.info" value="The xpath for 'helloworld' either has a value of null or does not exist." />
<!-- Overriding the default output of the formatter to use true/false. If the exp is true, the script inside will run. -->
<arc:if exp="[IsXPathNull(waldo, true, false)]" >
<!-- This executes because the 'waldo' element does not exist within the input xml text -->
<arc:set attr="_log.info" value="The xpath for 'waldo' either has a value of null or does not exist." />
</arc:if>
</arc:if>
</arc:call>
xpath(xpath)
Used inside calls to XML operations that have the XML DOM available. You can use the xmlDOMSearch and xmlDOMGet operations to parse an XML document. The XPath formatter is a formatter of the DOM object that functions like other formatters by generating values from an XML document. The XPath formatter returns the current XPath location of an XML document.
- xpath: The optional string of a relative XPath to find the associated XML value from.
Example
In the following snippet, an XML document is defined in memory in ArcScript.
<arc:set attr="text">
<root>
<A>Value_One</A>
<A>
<B>
<C>Value_Two</C>
</B>
</A>
<A>
<B>Value_Three</B>
</A>
</root>
</arc:set>
In this snippet, the xmlDOMSearch operation is called and XPath formatters are displayed from the sample XML document.
<arc:call op="xmlDOMSearch?xpath=/root/A">
Current XPath is [xpath] and the 'B' element value is [xpath(B) | empty("not present")]
</arc:call>
When run against the preceding XML document, this code displays the following output.
Current XPath is /root/A[1] and the 'B' element value is not present
Current XPath is /root/A[2] and the 'B' element value is not present
Current XPath is /root/A[3] and the 'B' element value is Value_Three
The XPath formatter displays the three A elements that are iterated over, but only Value_Three from the final B element is displayed because [xpath(B)] ignores the values in other elements.
xpathcount(xpath)
Similar to the XPath formatter, except that it returns the count of the elements that match the provided XPath. Used inside calls to XML operations that have the XML DOM available. You can use the xmlDOMSearch and xmlDOMGet operations to parse an XML document. The XPathCount formatter is a formatter of the DOM object that functions like other formatters by generating counts from an XML document.
- xpath: The optional string of a relative XPath from which to calculate the count.
Example
<arc:set attr="xml.xpath" value="/Items/Cars/Subaru" />
<arc:set attr="xml.text">
<Items>
<Cars>
<Subaru>
<Color>Blue</Color>
<Year>2017</Year>
</Subaru>
<Honda>
<Color>Red</Color>
</Honda>
</Cars>
</Items>
</arc:set>
<arc:call op="xmlDOMSearch" in="xml" out="result">
<!-- xpathcount is a context-senstive function in arcscript. If an xml document is loaded in a
search, xpathcount returns the count of the number of elements that match the provided xpath. -->
<arc:set attr="output.Data" value="[xpathcount('/Items/Cars/*/Color')]" />
</arc:call>
<arc:set attr="output.filename" value="test.txt" />
<arc:push item="output" />
When this code is run, it returns 2 as output.
xsubtree(xpath)
Parse XML trees from nested XML structures.
Example
In the example XML document below, there are three entries under /Event/Attendees.
<arc:set attr="xml.text">
<Event>
<Subject>Meeting</Subject>
<Attendees>
<User>
<Code>1</Code>
<Name>TEST1</Name>
</User>
<User>
<Code>2</Code>
<Name>TEST2</Name>
</User>
<User>
<Code>3</Code>
<Name>TEST3</Name>
</User>
</Attendees>
</Event>
</arc:set>
<arc:set attr="xml.xpath" value="/Event/Attendees" />
<arc:call op="xmlDOMSearch" in="xml">
[xsubtree(.)] <!-- Insert desired xpath in parentheses -->
</arc:call>
The . character in the xsubtree command instructs the script to use the current xpath. In this example, that path is /Event/Attendees, which returns all three entries:
<User>
<Code>1</Code>
<Name>TEST1</Name>
</User>
<User>
<Code>2</Code>
<Name>TEST2</Name>
</User>
<User>
<Code>3</Code>
<Name>TEST3</Name>
</User>
To show only the subtree for the second occurrence of the User xpath in /Event/Attendees, replace the command with xsubtree(User\[2\]). The result of that is:
<User>
<Code>2</Code>
<Name>TEST2</Name>
</User>
Other Functions
guid(includehyphens)
Generates a globally-unique identifier (GUID) value. By default, the formatter returns all of the characters in a single, unformatted string. To include hyphens that conform to the standard 8-4-4-4-12 GUID format, use the includehyphens parameter, and set it to true.
This formatter does not modify the input attribute (variable), so no such input attribute is required.
Example
<arc:set attr="myGUID" value="[guid(true)]" />
vault(ItemName)
Returns the value of an item in the Global Settings Vault that matches the provided value for ItemName.
Note: Use caution when referring to encrypted vault items in scripting contexts to ensure that sensitive information is not included in the logs.
Example
<arc:set attr="URLtoResource" value="[Vault(commonURL)]" />