Version 23.4.8843

• APIScript
• Items in APIScript
  • Select Attribute Values
  • Default Item
  • Event Inputs (_input)
  • Operation Outputs (_out[n])

APIScript

APIScript is an XML-based language that you can use to write custom processing logic. This script, which is included with CData Sync, makes it easy to call external processes that allow you to integrate Sync with other business processes. Sync includes complete code snippets for sending emails, executing batch files, working with databases, and much more. You can insert these snippets into your events from the Admin console.

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 (for example, attribute="address", value="123 Pleasant Lane").

• Item - A related group of attribute-value pairs that describe an input or output, as shown in this 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 that produce feeds as output.
• Feed - A list of items (for example, a list of customers with their addresses and telephone numbers).
• Keyword - An APIScript statement (for example, api:set).

APIScript includes many keywords that allow you to perform the following tasks:

• 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 operations

• create and modify items, the inputs to an operation, feeds, and the operation’s result

• process the feed that results from an operation call by iterating through its items

Items in APIScript

In APIScript, items are used to represent inputs to operations. You create, name, and give attribute values to items by using the api:set keyword, as shown in the following example:

<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 that is named input is never declared. Instead, the item is created the first time that you try to set an attribute for it. In the example above, if the input item does not exist already, it is created and the mask attribute is set for that item.

Select 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 ([]). The brackets instruct 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 is assigned the literal string value value1.
• item1.attr2 is assigned the literal string value item1.attr1.
• item1.attr3 is assigned the value value1 because the string "[item1.attr1]" is evaluated at run time as the attr1 attribute of item1.

Note: You can use a backslash (\) to escape square brackets in string literals.

Default Item

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

• Calling operations: The default item is the item that is passed, by default, to the operation called by your event when no other item is specified. As a result, you can use api:set to write attributes to the default unnamed item, and those attributes are passed as input to the next operation that is called in the event. This method is one way to provide the required parameters for an operation.

• 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, the default item (inside the api:call block that invokes the operation) refers to the current item that is 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 an event can be read from the _input item. The _input item contains variables that are 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: Inside an api:call block, the _input item is no longer the default item. You must reference it by name if you need access to it.

Operation Outputs (_out[n])

You access the current item in the feed that is produced by the api:call through the default item or a named special item, _outX, where X specifies the level of nesting for the api:call keywords. For example, if you are inside a single api:call keyword, the item’s name is _out1. If you are inside three levels of nested api:call keywords, then the name is _out3.