Version 22.0.8473

• Custom Scripts
• ArcScript Operations
• Conditional Logic
• Foreach Loop Index
• Map Item

The XML Map connector is designed to perform as much of the mapping as possible through the designer, however there may be situations where scripting is required to handle custom use cases.

Custom Scripts

To access additional operations beyond the formatters provided in the Expression Editor, click on the angle brackets adjacent to a destination element (</>) to open a Custom Script for that element.

The custom script editor, supports all of the features of ArcScript found in the Scripting section. As with other sections of ArcScript in Arc, the code block contains an arc:info section where the input parameters available to the script are defined. Additionally, there is an output element result.text that can be set to return the results of the custom script. The value that is returned in result.text is the value used to populate the destination element.

As an example, a script can be used to determine the SKU for an item based on the item’s name. A simple way of accomplishing this is to use a select/case statement in combination with the xpath formatter to check the ItemName element of the input XML:

ArcScript Operations

ArcScript is fully available within code view, including powerful ArcScript Operations. For example, the source XML may contain an ID of an item, and the SKU for that item must be retrieved from a database; in this case the dbQuery operation can look up the SKU for the corresponding ID.

Conditional Logic

ArcScript also supports performing conditional logic within a mapping template. The arc:if keyword is one of many keywords available to assist in performing conditional logic within templates. For example, if the source file contained information about customers within QuickBooks, it may be desirable to perform different business logic for customers with an outstanding balance as opposed to customers that have paid in full. A simple example of this use case might look like the following:

<arc:set attr="paidInFull" val="true" />
<arc:if exp="[xpath('balance')] > 0">
  <arc:set attr="paidInFull" val="false" />
</arc:if>
<arc:set attr='result.text'>[paidInFull]</arc:set>

Foreach Loop Index

When an element mapping is within a Foreach loop, the index of the current loop is always available within a custom script. The \_index attribute is reserved for the current index of the inner-most Foreach loop that contains the current element.

As an example, imagine mapping a LineItem element that exists within two Foreach loops: one loop for each order in the document, and another loop (within the first loop) for each item in an order. Referencing ‘[_index]’ within the LineItem element mapping will return the number of times the inner loop (the ‘item’ loop) has looped so far. This value is 1-indexed.

Map Item

It may be useful to set scripting variables at one point in the mapping and then reference those variables later in the mapping. This is supported via the _map item.

The _map item is just like any other ArcScript item, except that its scope encompasses an entire document processed by the XML Map Connector. In other words, any attributes of the _map item will persist throughout the mapping and are only cleared when the XML Map Connector finishes processing a file.

For example, a mapping project may require tallying up the total cost of multiple line items in a purchase order (i.e. the mapping includes some number of LineItemCost elements and also a TotalCost element). ArcScript could be used to keep track of the running total by setting an attribute of the _map item like the following:

<arc:set attr="_map.sum_cost" value="[_map.sum_cost | def(0) | add([xpath(LineItemCost)])]" />

The above line adds the value of the LineItemCost element to the current value of _map.sum_cost (with a default value of 0 if _map.sum_cost does not yet exist). If this code is included in an element within the Foreach loop that loops over all of the line items, the value of _map.sum_cost will be the TotalCost when the Foreach loop exits.

Since the attributes of _map are preserved, this same _map.sum_cost value can be referenced later in the TotalCost element mapping, e.g.:

<arc:set attr="result.text">[_map.sum_cost]</arc:set>