APIScript

APIScript is an XML-based language included with CData Sync that can be used to write custom processing logic. APIScript makes it easy to call extrenal processes allowing you to integrate Sync with other business processes. Sync includes complete Snippets for sending emails, executing batch files, working with databases, and much more. You can insert these examples into your events from the admin console.

However, APIScript 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”.
• Item: A related group of attribute-value pairs that describe an input or output. For example:

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

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

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

• Describe event 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.

Items in APIScript

In APIScript, items are used to represent inputs to operations. Items are created, named, and given attribute values through the api:set keyword:

<api: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 APIScript.

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.

Select 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:

<api:set item="item1" attr="attr1" value="value1"/>
<api:set item="item1" attr="attr2" value="item1.attr1"/>
<api: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 APIScript 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 event if no other item is specified. This means that you can use api:set to write attributes to the default unnamed item and those attributes will be passed as input to the next operation called in the event. This is one way to provide an operation’s required parameters.
• Processing the current item in the output of an operation or event: If you do not specify a variable name for the result of an operation, then inside the api: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 APIScript keyword:

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

Event Inputs (_input)

The input for a event can be read from the _input item. The _input item contains variables defined in the info block in the Event. When you read values from the default item in an event, 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 of the event.

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

Operation Outputs (_out[n])

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