Automation iterators

An automation iterator (later refereed as "iterator") specifies under what conditions an automation script iterator should execute and part of the execution context.

The main difference between triggers and iterators is, that an iterator is executed for multiple resources defined by the constraints, one after another.

A trigger is executed for a single resource defined by the constraints.

Iterators are defined by the iterator (i) {…} method defined by the automation script.

Iterators are evaluated in an isolated context, outside of the actual automation script. This prevents use of any constants or other symbols defiled outside of the iterator.

For example, the following iterator will not work:

// @todo provide an example, similar to how triggers have it.

Trigger and iterator are not compatible; you can only use one or the other within the same automation script.

Iterator interface

i: Defines the resource, action and the filter used for resource fetching. Passed object must conform to the interface:

interface {
  resourceType: string; (1)
  eventType: 'onManual' | 'onInterval' | 'onTimestamp' = 'onManual'; (2)
  action: 'update' | 'delete' | 'clone' | '' = ''; (3)
  filter: IteratorFilter; (4)
}

1	define the resource type; see resources and events for details.
2	define the event type; see resources and events for details.
3	define what action the script performs; see Iterator actions for details,
4	define the filter to use.

interface IteratorFilter {
  query: string; (1)
  sort: string; (2)
  limit: number | string; (3)
  offset: number | string; (4)
  [_: string]: number | string; (5)
}

1	SQL like query filter to use (`WHERE <query>`).
2	SQL like sort to use (`ORDER BY <sort>`).
3	Maximum number of resource.
4	Offset from first record.
5	additional non-standard resource specific parameters. `i.at` Defines that the automation script is executed at a specific time, defined as a ISO 8601 timestamp. `i.every` Defines the interval in which the automation script is executed, defined as a cron expression.

Iterator actions

Iterator script doesn’t perform any operation on the resource except if explicitly specified by the action property.

update: The result of the automation script will be used to update the original resource.
delete: The result of the automation script will be used to delete the original resource.
clone: The result of the automation script will be used to create a new resource with updated values; original resource is left unchanged.