Function Formatters

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, …), if you set the requireheader attribute to false.

Example

In the following snippet, a CSV document is defined in memory in Script.

<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 return if the formatter resolves to true.
ifFalse: The optional value to return 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 a JSON document. It returns the current jsonpath location of a 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>

jsonsubtree(jsonpath)

You can use jsonsubtree to parse JSON subtrees from nested JSON structures.

jsonpath: The optional string of a relative jsonpath indicating which level of the structure to begin from.

Example

Three User entries under the /json/Event/Attendees object in the JSON data are included in the following script. The Attendees object is a subtree of the root object.

<arc:setc attr="json.text">
{
  "Event": {
    "Subject": "Meeting",
    "Attendees": {
      "User": [
        {
          "Code": "1",
          "Name": "Jane Doe"
        },
        {
          "Code": "2",
          "Name": "John Smith"
        },
        {
          "Code": "3",
          "Name": "Alex Johnson"
        }
      ]
    }
  }
}
</arc:setc>
<arc:set attr="json.jsonpath" value="/json/Event/Attendees" />
<arc:call op="jsonDOMSearch" in="json">
<arc:set attr="_log.info">  <!-- Logging the results to the application log -->
[jsonsubtree(.)]  <!-- Insert your desired jsonpath inside the parentheses -->
</arc:set>
</arc:call>

In this example, the jsonpath is the . character which instructs the script to use the current jsonpath based on where it is in the root object. Here, that path is /json/Event/Attendees, which returns all three entries. The following image shows how it appears in the Application log of the Logs page:

Here is the raw JSON subtree result:

"Attendees": {
      "User": [
        {
          "Code": "1",
          "Name": "Jane Doe"
        },
        {
          "Code": "2",
          "Name": "John Smith"
        },
        {
          "Code": "3",
          "Name": "Alex Johnson"
        }
      ]
    }

To show only the subtree for the second occurrence of the User jsonpath in /json/Event/Attendees, replace the path inside the jsonsubtree formatter call with jsonsubtree(User/\[2\]). This results in the following output:

{
  "Code": "2",
  "Name": "John Smith"
}

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 runs. -->
    <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. It 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 Script.

<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-sensitive 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.

xpath: The optional string of a relative XPath indicating which level of the structure to begin from.

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.

includehyphens: Set to true to include hyphens in the GUID being returned.

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, [ifnotexists])

Returns the value of a vault item in the Global Settings Vault that matches the provided value for ItemName. By default, if the vault item does not exist, an error is thrown.

ItemName: The name of the vault item to retrieve.
ifnotexists: To prevent an error being thrown if a vault item does not exist, supply this optional parameter and a default value such as value does not exist. That value is returned when no vault item with the specified ItemName exists.

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)]" />

Getting Started

Flows

EDI Trading Partner Management Console

Connectors

Mapping

Admin API

How-To Guides

Scripting

Software License and Third-Party Copyrights

CSV Functions

csv(value)

Example

JSON Functions

hasjsonpath(jsonpath)

Example

isjsonpathnull(jsonpath, [ifTrue], [ifFalse])

Example

jsonpath(jsonpath)

Example

jsonsubtree(jsonpath)

Example

jsontype(jsonpath)

Example

XML Functions

hasxpath(xpath)

Example

isxpathnull(xpath, [ifTrue], [ifFalse])

Example

xpath(xpath)

Example

xpathcount(xpath)

Example

xsubtree(xpath)

Example

Other Functions

guid(includehyphens)

Example

vault(ItemName, [ifnotexists])

Example

​CSV Functions

​csv(value)

​Example

​JSON Functions

​hasjsonpath(jsonpath)

​Example

​isjsonpathnull(jsonpath, [ifTrue], [ifFalse])

​Example

​jsonpath(jsonpath)

​Example

​jsonsubtree(jsonpath)

​Example

​jsontype(jsonpath)

​Example

​XML Functions

​hasxpath(xpath)

​Example

​isxpathnull(xpath, [ifTrue], [ifFalse])

​Example

​xpath(xpath)

​Example

​xpathcount(xpath)

​Example

​xsubtree(xpath)

​Example

​Other Functions

​guid(includehyphens)

​Example

​vault(ItemName, [ifnotexists])

​Example

CSV Functions

csv(value)

Example

JSON Functions

hasjsonpath(jsonpath)

Example

isjsonpathnull(jsonpath, [ifTrue], [ifFalse])

Example

jsonpath(jsonpath)

Example

jsonsubtree(jsonpath)

Example

jsontype(jsonpath)

Example

XML Functions

hasxpath(xpath)

Example

isxpathnull(xpath, [ifTrue], [ifFalse])

Example

xpath(xpath)

Example

xpathcount(xpath)

Example

xsubtree(xpath)

Example

Other Functions

guid(includehyphens)

Example

vault(ItemName, [ifnotexists])

Example