Script syntax for exports

Relatics offers a powerful syntax to precisely define the information you want to extract from a Relatics workspace. This article describes the building blocks needed to build a script for exports.

Iterator

[Action]
    {@Id}
    {Name}
[.Action]

In the example above, [Action] is an iterator. By using an iterator in a script, Relatics is instructed to ‘iterate’ through all elements of the specified type element (e.g. Action). In other words, Relatics will go through every element in the type element Action. Between the iterator tags, Relatics is instructed to parse syntax for every iteration of the specified type (e.g. Action). In the example, this means that for every Action, the ID and Name are exported.

Notes:

• An iterator can be recognized by brackets and the name of a type within the brackets. For example, [Action].
• An iterator is closed by brackets with a dot and the type element name. A notation variant is brackets with a dot. For example, [.].

Inserter

[Action]
    {@Id}
    {Name}
[.Action]

In the script examples given earlier, you may have noticed model references between curly braces (e.g. {Name}). These so-called inserters are used to define which Relatics properties will be included in the export output.

Notes:

• What is between curly braces must equate to one value per iteration.
• A single iterator can have multiple inserters.

Next to properties, system attributes can be used for inserters. System attributes are not defined by a power user but, instead, are predefined by Relatics. Inserters with system attributes can be recognized by the @ symbol. Notice how, in the example given earlier, the inserter {@Id} was responsible for printing the IDs of the Iterator Action.

Nesting

[Person]
    {@Id}
    {Name}
    [is responsible for: Action]
        {@Id}
        {Name}
    [.is responsible for: Action]
[.Person]

An iterator is an instruction for Relatics to reach specific type elements. It gives navigational instructions to the script, similar to how you click on an element Relatics table to navigate its relations and properties. It is possible to include the Actions by a responsible Person in the script output. We can achieve this by nesting our iterators like in the example above. With the iterator [Person], an iteration is started through all elements of the Person type element. Nested in is another iterator [is responsible for: Action], which for each person, iterates across all their actions. The Actions are included because of the {Name} inserter.

Notes:

• Within the inserter braces, multiple paths can be used, but they must lead to a single value per iteration.
• Contrary to report syntax, a nested path within a single inserter is not allowed to include type property values. However, type properties can be used in filters.

Filter

It is possible to apply filters to the iterators in the script. Filters are specified within iterator brackets, and it is possible to apply multiple filters on a single iterator. The following example will elaborate on the syntax used to apply a filter in a script:

[Action | FILTER({Status} = "New")] 
    {@ID}
    {Name}
    {Status}
[.]

To apply a filter to an iterator, start by putting a pipe symbol after the type element name. Then type FILTER and write your filter operation between parentheses. In this case, Status is a list property of the Action type element, and we used it to filter for Relatics elements with a Status property of ‘New’.

It is only possible to filter by certain property types:

[Action | FILTER({Status} IN ("New", "Busy"))]
    {@ID}
    {Name}
    {Status}
[.]

[Action | FILTER({Deadline} > "1950-01-01") FILTER({Deadline} < "2050-01-01")]
    {@ID}
    {Name}
    {Deadline}
[.]

[Action | FILTER({has responsible: Person/Age} NOTEMPTY) FILTER({has responsible: Person/Age} >= 18)]
    {@ID}
    {Name}
[.]

Filters can also be applied to iterators containing Relations without specified properties. However, you are only able to filter whether a relation ‘exists’ or does ‘not exist’. The script syntax that enforces the existence of a relation is EXIST, and for ‘not exist’ is NOTEXISTS:

[Action | FILTER([has responsible: Person] EXISTS)]
    {@ID}
    {Name}
[.Action]

To instruct Relatics to filter on a nested level, a path within a single inserter can be used. Similarly to a URL, you separate the model references within the inserter with a forward slash, e.g. FILTER({has responsible: Person/Age} >= 18).

Notes:

• It is not possible to filter by specific instances.
• It is possible to apply multiple filters within a single iterator, e.g. [Action | FILTER({has responsible: Person/Age} NOTEMPTY) FILTER({has responsible: Person/Age} >= 18)]
• When a filter on a nested iterator should also affect the parent iterator, the filter needs to be repeated on its parent.
• A filter of date and list properties will need the value between quotes, but a filter of a number property will not need the value between quotes.
• The script can only parse dates in the format yyyy-mm-dd; dates in other formats may lead to syntax errors.
• You are able to filter by collection relations. To illustrate, take our example above and imagine an Action can have a Person or an Organization responsible for it. You can choose whether to filter:
  1. By Person exclusively. E.g. [Action | FILTER([has responsible: Person] EXISTS)]
  2. By Organization exclusively. E.g. [Action | FILTER([has responsible: Organization] EXISTS)]
  3. By Person or Organization. E.g. [Action | FILTER([has responsible: *] EXISTS)]

Hierarchy

Archived elements

By default, iterators loop through all the elements of a type element. This is also true for type elements where archiving is configured. In case you only want to iterate through a specific archiving state, some extra syntax has to be added to the iterator:

[Action | ARCHIVEEXCLUDED)]
    {@ID}
    {Name}
    {Status}
[.Action]

[Action | ARCHIVEONLY]
    {@ID}
    {Name}
    {Status}
[.Action]

Foreign relations (Libraries)

This syntax is exclusive to library definitions.