Version 23.4.8839

• 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 on the Flows pages. However, some edge cases might require extending the Arc feature set with ArcScript, an XML-based scripting language included with the application.

Use scripting to modify files (content, headers, filenames, an so on), 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, and describes the supported value formatters, keywords, and operations in detail, with examples.

Scripting Hooks

Arc exposes three primary hooks into the scripting language: the Events on all connectors, the dedicated Script connector, and the custom script option in the XML Map connector.

Event Scripting

Each connector exposes opportunities to execute a custom script at specific moments during the processing of a file. These are called events.

• 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. This event only applies to connectors that send files outside of the application (such as uploading a file to a remote server).

• The After Receive event fires after the connector creates a new file. This newly created file might be the result of receiving a file from an outside source (such as receiving a message over AS2) or from modifying or transforming a file already in the Arc flow (for example, converting an EDI file into XML causes a new XML file to be created).
  
  For example, you might need to add a custom header to a file just received over AS2. You can write the logic for determining the header value and adding the header to the file in ArcScript, then set this script in the After Receive event of the AS2 connector responsible for receiving the file.

Note: You cannot use event scripts to create files directly into a flow, or to modify the contents of the files through a flow.

Error Handling in Events

Event script execution is triggered by the successful sending or receiving of a file, so errors thrown in the script do not affect the status of the send/receive operation. For this reason, you should limit scripting in events to scripts that are guaranteed to succeed, or that can fail without impacting the overall flow.

To ensure that an exception in a script causes a file to stop processing, move the script into a dedicated Script connector, which is described in the next section. Using a Script connector also allows for errors to be logged to the Transaction Log, and for using the Arc retry functionality for operations that fail.

Script Connector

Arc includes a dedicated connector for executing custom scripts. You can trigger a Script connector in a flow by passing a file to the connector (in the same way as any other connector), or you can use the Receive Automation setting to have it automatically execute according to an specified interval.

Script connectors are the most flexible way in which to execute custom logic in ArcScript. In addition, the Arc flow can be easier to understand and maintain if script execution is represented visually with a dedicated connector, instead of being configured in an Event of another connector.

Script connectors can generate output files using 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 way to use the XML Map designer is by 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 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, such as setting variables and calling operations.

The XML Map connector also has a custom script editor for specific element mappings. All ArcScript features are available in custom scripts to support arbitrary business logic during a mapping. These scripts have a unique requirement where 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 links to the topics that describe ArcScript’s features in detail.

Introduction

The Introduction covers the core concepts of the ArcScript language and includes several example scripts for reference. CData strongly recommends that you start with this section if you are new to ArcScript.

Keywords

Each line of ArcScript begins with a keyword. For example, arc:set is the keyword to set an attribute (variable), arc:if introduces conditional logic, and arc:call invokes an ArcScript operation.

Keywords describes all of the available keywords.

Operations

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

Operations lists all available operations, describes the input and output parameters, and provides examples of them in use.

Note: Some operations are specific to a certain connector. They are described in the documentation for that connector; for example, the Notify connector documentation includes the notifySendEmail operation.

Formatters

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

Formatters lists each available formatter and its parameters.