Version 22.0.8473

• ArcScript
• Example Scripts
  • Using Event Inputs
  • Using Operations
  • Extending the Example Scripts
• Items in ArcScript
  • Declaring Items
  • Passing Items as Query String Parameters
  • Selecting Attribute Values
  • Default Item
• Named Items
  • Script Inputs (_input)
  • Script Outputs (_out[n])
  • HTTP Request (_request)
  • HTTP Response (_response)
  • HTTP Headers (_httpheaders)
  • HTTP Cookies (_cookies)
  • ASP.NET Session (_session)
  • CData Arc Message (_message)
    • Metadata
    • Body
  • Mapping Context (_map)
  • Application Log (_log)
  • CData Arc Connector (_connector)

ArcScript

ArcScript is an XML-based language included with CData Arc that can be used to write custom processing logic. ArcScript makes it easy to transform files or messages and integrate with other business processes. Arc 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, ArcScript is also a high-level programming language that enables you to control almost every aspect of data access and processing. You use keywords, attributes, items, operations, and feeds to write scripts:

• Attribute: The name part of a name-value pair, as in attribute=”address”, value=”123 Pleasant Lane”.
  • Attributes in ArcScript can also be denoted as an array by using the # character. This means that the array can contain more than one value, where each value may be referred to using 1-based indexing.
  • For example, [myitem.myattribute#2] would refer 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: for example, 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 ArcScript statement, like arc:set.

ArcScript 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, the inputs to an operation, and feeds, the operation’s result.
• Process the feed resulting from an operation call by iterating through its items.

Example Scripts

ArcScript is a simple, XML-based language that can be used in events to enable powerful automation capabilities. Arc includes complete code snippets for automating common actions, such as sending an email. On the Settings tab for a Script connector or on the Events tab for your connector, click Insert Snippet and select the action you want to perform. The necessary code is inserted at the cursor.

This section shows how to use and extend the included 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 available, as well. Below are the available inputs for the After Receive event:

<arc:info title="After Receive"  desc="This event is fired after receiving a file.">
  <input name="Filename"         desc="The name of the file that was sent." />
  <input name="FilePath"         desc="The path of the file that was received." />
  <input name="MessageId"        desc="The Id of the transmission." />
  <input name="ErrorMessage"     desc="If an error occurred, this will contain the error message." />
</arc:info>

Using Operations

Use the included code examples to invoke some of the built-in operations. The following example sends an email after a file is received. To send an email, simply replace the placeholder values:

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

Extending the Example Scripts

Use the included code examples to pass in predefined inputs to an operation. You can also pass in additional inputs that are specific to the operation. For example, the appSendEmail operation accepts several additional inputs, such as the body text, attachments, and SSL/TLS properties. You can provide these values with the arc:set keyword.

With the arc:call keyword, you can call any of the built-in operations in an event and also make calls to the API.

Use other ArcScript keywords to control execution flow and more. ArcScript is computationally complete. It also has many enhancements designed to make processing and automation easy. See Scripting for more information on the syntax of ArcScript and its capabilities.

Items in ArcScript

Feeds are composed of items, but in ArcScript, 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 ArcScript and passing these items 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 line above sets the mask attribute to the value *.txt on the item named input. In this case, the input item is like a variable in ArcScript.

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 the example above, if the input item did not already exist, it would be created and the mask attribute would be set on it.

Passing Items as Query String Parameters

As an alternative to creating explicit input items, you can pass input parameters to operations in the form of query string parameters. As an example of the difference between explicitly declaring items and passing them as parameters, consider the following lines that declare an item, 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 instead use this syntax:

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

Note that using this format requires you to 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 (e.g., “input.mask”). To query an attribute value, surround the attribute name in square brackets ([]). This instructs 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.

Note that you can use a backslash to escape square brackets in string literals.

Default Item

In ArcScript there is always an implicit, unnamed item on an internal stack of items, the default item. In the following two cases, the default item is commonly used to make scripts shorter and easier to write:

• Calling operations: The default item is the item passed by default to the operation called by your script if no other item is specified. This means that you can use arc:set to write attributes to the default unnamed item and those attributes will be 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 the result of an operation, then inside the arc:call block that invokes the operation, the default item will refer to the current item produced by the operation.

Manipulate the default item by simply omitting the item attribute of an ArcScript keyword:

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

Named Items

In addition to items declared within the script, several built-in items are available in the scope of a script. Built-in, or special, items are available in ArcScript that provide an interface for accessing parts of HTTP requests, responses, and more. These special items are useful for mapping inputs in HTTP requests to operation inputs.

The following sections detail the special 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 the variables defined in the info block or in the script will be available in the _input item.

Note that inside an arc:call block _input is no longer the default item and you must reference it by name if you need access to it.

Script Outputs (_out[n])

The current item in the feed produced by the arc:call keyword can be accessed through the default item or a named special item, “_outX”, where X is the level of nesting of arc:call keywords. For example, if you are inside a single arc:call keyword, the item’s name will be “_out1”. If you are inside three levels of nested arc:call keywords, then it will be “_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.

HTTP Response (_response)

The response item allows the script writer to write directly to the HTTP response. You can set the attributes listed below in the response item.

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)

You can 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 ArcScript 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.

CData Arc Message (_message)

When a file passes through an Arc workflow, 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).

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 Arc, 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.

Mapping Context (_map)

The _map item is a special item available in the XML Map Connector. Attributes set in the _map item are always available later in the mapping (i.e. 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 may need to count the number of Line Items in the document, and 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 within the CTT segment mapping.

Application Log (_log)

The _log item is a hook into the Arc 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 will appear in the Application Log when the script executes" />

This attribute can be set multiple times within the same script to log multiple messages to the Application Log. The attribute value does not need to be cleared or appended, simply setting the attribute value like the above example will cause the specified value to be logged.

CData Arc Connector (_connector)

The _connector item provides access to the fields/properties of the current connector. Note that using this item requires a scripting context within the connector; this is always available via the events of any connector, and some connectors can also evaluate ArcScript within special configurable fields.

The available properties are the same as the values stored in the port.cfg file within the connector’s folder, and should be accessed using the following syntax:

[_connector.propertyName]