Introduction to ArcScript - CData Arc Documentation

Script is an XML-based language included with that can be used to write custom processing logic. Script makes it easy to transform files or messages and integrate with other business processes. includes complete Example Scripts for sending emails, executing batch files, working with files, and more. You can insert these examples into your scripts and events from the admin console. However, Script is also a high-level programming language that enables you to control almost every aspect of data access and processing. You can use keywords, attributes, items, operations, and feeds to write scripts and use them in events on all connectors, in the dedicated Script and REST connectors, and in the custom script option in the XML Map connector.

Attribute: The name part of a name-value pair, as in attribute=“address”, value=“123 Pleasant Lane”.
- Use the # character to denote an attribute as an array. This means that the array can contain more than one value, where each value can be referenced using 1-based indexing.
- For example, [myitem.myattribute#2] refers to the second value in the myattribute attribute.

Item: A related group of attribute-value pairs that describe an input or output. For example:

Attribute="name" value="Bob"
Attribute="address" value="123 Pleasant Lane"
Attribute="phone" value="123-4567"

Feed: A list of items, such as a list of customers with their addresses and phone numbers.
Operation: A generic name for methods that accept items as input and produce feeds as output.
Keyword: An Script statement, such as arc:set.

Arrays in Script are limited to 32768 members.

Script includes many keywords that allow you to do the following:

Describe script inputs and outputs
Use high-level programming constructs such as if/else statements and case statements to control execution flow
Call operations and define your own
Create and modify items used as inputs to an operation, as well as feeds (the output of the operation)
Process the feed resulting from an operation call by iterating through its items

Example Scripts

includes complete code snippets for automating common actions, such as sending an email. On the Script connector Settings tab or on the Events tab of any connector, click Insert Snippet and select the action you want to perform. The necessary code is inserted at the cursor. The following sections describe how to use and extend these code snippets to write custom processing logic.

Using Event Inputs

Each event provides relevant inputs that you can use as the input parameters of an operation. Input parameters are defined by the input attributes in the info section. Use the event’s predefined inputs to process the file that was sent or received or send an email containing any error messages. Other inputs are also available. For example, the available inputs for the After Receive event are:

<arc:info title="After Receive" desc="This event is fired after receiving a file.">
  <input name="WorkspaceId"      desc="The id of the workspace that is receiving file." />
  <input name="ConnectorId"      desc="The id of the connector that is receiving file." />
  <input name="Direction"        desc="The direction of transaction." />
  <input name="Filename"         desc="The name of the file that was received." />
  <input name="FilePath"         desc="The path of the file that was received." />
  <input name="Attachment#"      desc="The path of the attachment was received." />
  <input name="MessageId"        desc="The Id of the transaction." />
  <input name="ErrorMessage"     desc="If an error occurred, this will contain the error message." />
</arc:info>

Using Operations

Use the included code samples to invoke some of the built-in operations. The following example uses the appSendEmail operation to send an email after a file is received. To use it, simply replace the placeholder values:

<!-- Send Email -->
<arc:set attr="email.To"         value="Recipient(s)"/>
<arc:set attr="email.Subject"    value="Before Send"/>
<arc:set attr="email.Message"    value="File [Filename] was processed."/>
<arc:call op="appSendEmail"/>

The script shown above only works if you have previously configured a mail server in Settings (accessed by clicking the gear icon). Navigate to the Email Settings section of the Alerts tab. The appSendEmail operation uses the same mail server.

Extending the Example Scripts

Use the included code samples to pass in predefined inputs to an operation. You can also pass in inputs that are specific to the operation. For example, the appSendEmail operation accepts several additional inputs, such as the body text and attachments. Provide these values by using the arc:set keyword. Use the arc:call keyword to call any of the built-in operations in an event, or to make calls to the API. Use other keywords to control execution flow and more. Script is computationally complete. It also includes enhancements designed to make processing and automation easy. See Scripting for more information on the syntax of Script and its capabilities.

Items in Script

Feeds are composed of items, but in Script, items themselves are used for much more than the individual parts of a feed. They are also used to represent inputs to operations.

Declaring Items

For best readability and ease of later script modification, CData recommends creating explicit input items in Script and passing them into operations on separate lines. Items are created, named, and given attribute values through the arc:set keyword:

<arc:set item="input" attr="mask" value="*.txt" />

The previous snippet sets the mask attribute to the value *.txt on the item named input. In this case, the input item is like a variable in Script. However, an item named input is never declared. Instead, the item is created the first time you try to set an attribute on it. In this example, if the input item doesn’t exist, it is created and the mask attribute is set on it.

You can also use a “shorthand” method to declare items and attributes. For example:

<arc:set attr="colors.myfavorite" value="green" />

This snippet creates a colors item with a myfavorite attribute that has a value of green.

Passing Items as Query String Parameters

An alternative to creating explicit input items is to pass input parameters to operations in the form of arc:call query string parameters. For an example of the difference between explicitly declaring items and passing them as parameters, consider the following lines that declare an item called file, and pass this item into an operation to read a line:

<arc:set attr="file.file" value="[filepath]" />

<arc:call op="fileReadLine" in="file">

To accomplish this using query string parameters, you can use this syntax instead:

<arc:call op="fileReadLine?file=[filePath | urlencode]">

Using this format requires that you URL-encode the parameter using the urlencode argument. This ensures that the application correctly parses special or reserved characters in file names without encountering errors.

Selecting Attribute Values

To reference an attribute, use the syntax item.attribute (for example, input.mask). To query an attribute value, surround the attribute name in square brackets ([ ]). This tells the interpreter that you want to evaluate the string instead of interpreting it as a string literal. For example, consider the following code snippet:

<arc:set item="item1" attr="attr1" value="value1"/>
<arc:set item="item1" attr="attr2" value="item1.attr1"/>
<arc:set item="item1" attr="attr3" value="[item1.attr1]"/>

The results are the following:

item1.attr1 gets assigned the literal string value value1.
item1.attr2 gets assigned the literal string value item1.attr1.
item1.attr3 gets assigned the value value1, because the string [item1.attr1] gets evaluated at run time as the attr1 attribute of item1.

You can use a backslash to escape square brackets in string literals.

Default Item

In Script there is always an implicit, unnamed item on an internal stack of items, the default item. While you can use this item to write full scripts, best practice is to define your own explicit input and output items as needed. This makes scripts easier to read and reduces the risk of overwriting an existing attribute. For simple scripting cases, you can use the default item in the following two scenarios to make scripts slightly shorter and easier to write:

Calling operations: The default item is the item passed to the operation called by your script if no other item is specified. This means you can use arc:set to write attributes to the default unnamed item and those attributes are passed as input to the next operation called in the script. This is one way to provide an operation’s required parameters.
Processing the current item in the output of an operation or script: If you do not specify a variable name for an operation result, then inside the arc:call block that invokes the operation, the default item refers to the current item produced by the operation.

Manipulate the default item by omitting the item attribute of an Script keyword, as shown in the following snippet:

<arc:set attr="path" value="." />

Built-in Items

In addition to items declared in a script, several built-in items are available in the scope of a script. Built-in items provide an interface for accessing parts of HTTP requests, responses, and more. These items are useful for mapping inputs in HTTP requests to operation inputs. The following sections describe the built-in items.

Script Inputs (_input)

The input for a script can be read from the _input item. The _input item contains variables found in the URL query string and the POST data when the script is executed. If a variable of the same name exists in the POST data, it overrides the value from the query string. When you read values from the default item in a script, you are reading values from _input; likewise, attributes that you write to the default item are passed as parameters to operations along with the input to the script. Only variables defined in the info block or in the script are available in the _input item.

_input is not the default item inside an arc:call block. If you need access to it, you must reference it by name.

Script Outputs (_out[n])

You can access the current item in the feed produced by the arc:call keyword through the default item or the built-in _outn item, where n is the level of nesting of arc:call keywords. For example, if you are inside a single arc:call keyword, the item’s name is _out1. If you are inside three levels of nested arc:call keywords, then it is _out3.

HTTP Request (_request)

You can access variables passed into the URL query string, POSTed to the script, and other variables as collections of attributes in the _request item. To access a specific collection of attributes, use the name of the collection as the prefix to the attribute you want to read. For example, [_request.qstring:name] reads the value of the variable “name” in the query string and [_request.form:name] reads the value of the variable “name” in the form data.

Attribute	Description
`q[uery]string:*`	Access the values of query string parameters.
`form:*`	Access the values of variables in the form data.
`server:*`	Access the values of server variables.
`body`	Access the raw contents (body) of the request.
`bodybase64`	Access the base64-encoded contents (body) of the request.
`auth:*`	Access authentication information about the user. Determine whether the user is authenticated with `[_request.auth:isauthenticated]`.
`other:*`	Access other information about the request. Retrieve the application path with `[_request.other:applicationpath]`.

HTTP Response (_response)

The _response item allows the script writer to write directly to the HTTP response. You can set the following attributes:

Attribute	Description
`cookie:*`	Set cookies in the response. The name of the attribute is the name of the cookie prefixed by `cookie:` and the value of the attribute is the cookie value.
`writefile`	Write the content of the specified path to the response.
`redirect`	Send the redirect header to the client browser. This can be used to redirect the browser to another URL.
`statuscode`	Set the HTTP status code of the response.
`statusdescription`	Set the HTTP status description of the response.

HTTP Headers (_httpheaders)

The _httpheaders item provides easy access to HTTP headers in scripts and templates. You can read the HTTP request headers by reading from this item. Write to the outgoing response headers by writing to this item. For example, you can set the content type with a line like the following:

<arc:set item="_httpheaders" attr="content-type" value="application/xml"/>

HTTP Cookies (_cookies)

Use the _cookies item to retrieve cookies in the request and set cookies in the response. A cookie with multiple key/value pairs is represented as a collection of attributes that correspond to the key/value pairs of the cookie. The name of the cookie prefixes each attribute of the collection.

ASP.NET Session (_session)

ASP.NET session variables are available in Script through the _session item. Any object stored in the session can be accessed as attributes of this item. The attribute name represents the key used to store the object in the session.

Message (_message)

When a file passes through an flow, the application adds metadata to the file. The resulting combination of the original file and application metadata is called a message. The _message item provides access to the body and metadata of a message in scripting contexts (and in connector fields that can interpret scripting, such as the Subject field in the Email Send Connector).

Arrays in Script are limited to 32768 members. If a message has headers that are repeated more than 32768 times, the oldest headers are dropped off the message.

Metadata

The message metadata includes:

A unique Id (called a MessageId) that identifies the file regardless of any changes to the filename
Information about failures and successes during processing
Any custom metadata promoted programmatically in the flow

To access message metadata, use the header:* attribute of the _message item. For example, when an error occurs while processing a file in , the x-trapped-errordescription header is added to the message that represents that file. This header stores information about the error that occurred, including the ConnectorId where the error occurred and debugging information about the error. The following syntax references this header within a scripting context: [_message.header:x-trapped-errordescription]

Body

To access the body of a message, use the body attribute of the _message item, as shown below: [_message.body] This returns the body of the message as a string.

Adding Tracked Headers

To add a Tracked Header to a message, use the trackedheader attribute of the _message item, as shown below:

<arc:set attr="output.filepath" value="[filepath]" />
<arc:set attr="_message.trackedheader:myHeaderName" value="Myvalue" />
<arc:push item="output" />

Adding Custom Headers

To add custom headers to files, set the Header:header_name attribute of the file item that is pushed out by the connector. For clarity, begin with a script that pushes an unmodified version of the input file as output:

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:push item="outfile" />

The [FilePath] variable resolves to the full path (and filename) of the input file, so this script makes the output file the same as the input file. The following addition to this script adds custom headers to the file before pushing it:

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:set attr="outfile.Header:myHeaderName" value="myValue" />
<arc:push item="outfile" />

You can make custom headers searchable in the logs by navigating to the Tracked Headers field in the Advanced Settings section of the Settings > Advanced page, and adding the header name(s).

Logging Connector Events

To add logging of connector-defined Events to the _message body in Script, add a log attribute prefix, a valid log level entry, and a value to the message. The following example adds an Info row to the log file with the text from the value portion of the attribute:

<arc:set attr="_message.log:info" value="This is an info level log entry" />

Valid log level entries are:

Error
Warning
Info
Debug
Trace

Mapping Context (_map)

The _map item is available in the XML Map connector. Attributes set in the _map item are always available later in the mapping (in other words, these attributes are not cleared and the _map item is never out of scope). The _map item is useful for storing information that is calculated at one point in the mapping and referenced later in the mapping. For example, a mapping involving an EDI document might need to count the number of Line Items in the document, then include this count value in a CTT segment at the end of the document. The Line Item count can be calculated and stored as an attribute of the _map item, then that attribute can be referenced in the CTT segment mapping.

Application Log (_log)

The _log item is a hook into the Application Log. Setting the info attribute of this item to a string causes that string to appear in the Application Log. For example:

<arc:set attr="_log.info" value="this string appears in the Application Log when the script executes" />

You can set this attribute multiple times in the same script to log multiple messages to the Application Log. The attribute value does not need to be cleared or appended; setting the attribute value as shown in the previous example causes the specified value to be logged.

Connector (_connector)

The _connector item provides access to the fields and properties of the current connector. The available properties are the same as the values stored in the port.cfg file in the connector’s folder, and should be accessed using the following syntax: [_connector.propertyName]

Using this item requires a scripting context in the connector. This is always available on the connector Events tab, and some connectors can also evaluate Script in special configurable fields.

​Example Scripts

​Using Event Inputs

​Using Operations

​Extending the Example Scripts

​Items in Script

​Declaring Items

​Passing Items as Query String Parameters

​Selecting Attribute Values

​Default Item

​Built-in Items

​Script Inputs (_input)

​Script Outputs (_out[n])

​HTTP Request (_request)

​HTTP Response (_response)

​HTTP Headers (_httpheaders)

​HTTP Cookies (_cookies)

​ASP.NET Session (_session)

​ Message (_message)

​Metadata

​Body

​Adding Tracked Headers

​Adding Custom Headers

​Logging Connector Events

​Mapping Context (_map)

​Application Log (_log)

​ Connector (_connector)

Example Scripts

Using Event Inputs

Using Operations

Extending the Example Scripts

Items in Script

Declaring Items

Passing Items as Query String Parameters

Selecting Attribute Values

Default Item

Built-in Items

Script Inputs (_input)

Script Outputs (_out[n])

HTTP Request (_request)

HTTP Response (_response)

HTTP Headers (_httpheaders)

HTTP Cookies (_cookies)

ASP.NET Session (_session)

Message (_message)

Metadata

Body

Adding Tracked Headers

Adding Custom Headers

Logging Connector Events

Mapping Context (_map)

Application Log (_log)

Connector (_connector)