Version 22.0.8473

• Scripting Hooks
  • Event Scripting
    • Error Handling in Events
  • Script Connector
  • XML Map Connector
• Using ArcScript
  • Introduction
  • Keywords
  • Operations
  • Formatters

CData Arc is designed to handle complex data integration use cases through configured Connectors in the Flows page. However, some edge cases may require extending the Arc feature set with ArcScript, an XML-based scripting language included with the application.

Scripting can be used to modify files (content, headers, filename, etc), trigger external message flows, model custom data that doesn’t easily fit into a standardized format, execute external scripts and processes, and more. This section contains an overview of ArcScript as a language, as well as the supported value formatters, keywords, and operations.

Scripting Hooks

Arc exposes three primary hooks into the scripting language: the Events of any Connector, the dedicated Script Connector, and the Custom Script option within the XML Map Connector.

Event Scripting

Each Connector exposes opportunities to execute a custom script at specific moments during the processing of a file. The Before Send event fires after a connector has fully prepared a file to send/process a file, but before the sending/processing actually occurs.

The After Send event fires after the connector has sent the file (note that this event only applies to connectors that send the file outside of the application, e.g. uploading the file to a remote server).

The After Receive event fires after the connector creates a new file; this newly created file may be the result of receiving a file from an outside source (e.g. receiving a message over AS2) or from modifying/transforming a file already within the Arc flow (e.g. converting an EDI file into XML causes a new XML file to be created).

As an example, it might be necessary to add a custom header to a file just received over AS2. The logic for determining the header value and adding the header to the file can be written in ArcScript, then this script could be set in the After Receive event of the AS2 connector responsible for receiving the file.

Error Handling in Events

Event script execution is triggered by the successful sending or receiving of a file, and errors thrown in the script will not affect the status of the send/receive operation. For this reason, scripting in events should be limited to scripts that are guaranteed to succeed or can fail without impacting the broader Flow.

In order to ensure that an exception in a script causes the file to stop processing, the script should be moved into a dedicated Script Connector as described in the next section. This also allows for logging errors to the Transaction Log and utilizing the Arc retry functionality for operations that might fail.

Script Connector

Arc includes a dedicated Connector for executing custom scripts. A Script Connector can be triggered in a Flow by passing a file to the connector (like any other connector), or it can execute according to an automated interval via Receive Automation.

Script Connectors are the most flexible context in which to execute custom logic via ArcScript. Additionally, the Arc flow may be easier to understand and maintain if the script execution is represented visually with a dedicated connector, rather than being configured in an Event of another connector.

Script Connectors can generate output files via the push keyword, or simply execute some logic without generating any output.

XML Map Connector

The XML Map Connector provides a visual designer to transform XML from one structure to another. The primary method of using the XML Map designer is dragging and dropping elements from the source tree to the destination tree. This simple approach is augmented with scripting concepts to support extensible custom processing during a mapping.

The XML Map Connector’s Expression Editor uses ArcScript’s Formatters to dynamically modify and format data during the mapping. These expressions do not require other aspects of scripting, like setting variables and calling operations.

In addition, the XML Map Connector has a Custom Script option for any specific element mapping. The full feature set of ArcScript is available in these custom scripts to support arbitrary business logic during a mapping. These scripts have a unique requirement that the result.text attribute is set to the output value (the value that should be set in the mapped XML element) by the end of script execution.

Using ArcScript

This section contains reference materials for ArcScript’s feature set.

Introduction

The Introduction page covers the core concepts of the ArcScript language and includes various example scripts to reference. It is strongly recommended to start with this section if you are new to the ArcScript language.

Keywords

Each line of ArcScript begins with a keyword: arc:set to set an attribute (variable), arc:if to introduce conditional logic, arc:call to invoke an ArcScript operation, etc.

The Keywords section describes each keyword available in ArcScript.

Operations

Advanced processing in ArcScript is performed via operations. Each operation executes a specific task like a database query, an HTTP request, or a file read.

The Operations section lists each available operation and describes the input and output parameters.

Note that some operations are specific to a certain Connector and are documented in the Connector documentation; for example, the Notify Connector documentation includes the notifySendEmail operation.

Formatters

ArcScript uses formatters to modify values within a script. These formatters can perform mathematical operations, string manipulation, date formatting, and more.

The Formatters section lists each available formatter and its applicable parameters.