Rules engine – Templates (advanced formulas)

What is a template?

A template is an advanced formula used in some rules engine actions (for example on Text or Number columns) to compute the final value of a target cell.

Instead of simply copying a value from another field or setting a static default value, a template lets you:

Combine several fields together
Clean or normalize text (uppercase, lowercase, trim, replace, etc.)
Perform mathematical operations
Work with children items (variants, levels, etc.)

Templates are based on the Twig template engine.

When should I use a template?

Typical use cases:

Concatenate fields
Example: build a product label from brand + model + color.
Normalize text
Example: ensure a title is always uppercase or trimmed.
Compute a number
Example: convert mm to cm, compute a discount, add two measures.
Aggregate information from children
Example: list all colors available for a product from its variants.

If a simple “Use value from another field” or “Use a default value” is enough, prefer these actions. Use templates when you need logic or transformation.

Template configuration

When you configure a template via Data Factory (XML), the Twig expression is wrapped in a <Template> node inside a SET_TEXT or SET_NUMBER action.
This <Template> node accepts a few optional attributes specific to the Template action.

Common attributes (all target types)

trim-spaces (optional, true / false, default: false)
If true, leading and trailing spaces are removed from the final result before it is written into the target cell.
This is recommended for identifiers and single‑line text fields to avoid accidental spaces.
engine (optional, twig.1 / twig.2, default: twig.1)
Selects which template engine is used to execute the expression. This attribute is specific to the Template action and is ignored by other actions (such as Copy).
See Template engines for details on the differences and performance impact.

Additional attributes for Number targets

When the template is used on a Number target column (SET_NUMBER action), the <Template> node also accepts:

precision (required): number of decimal places to keep in the final result.
round (required): rounding mode to apply. Possible values are:
- UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN.

These attributes behave the same way as on the Copy node of SET_NUMBER actions, but are applied to the result of the template expression.

For a quick overview of the rounding outputs, see: Rounding methods.

Example:

xml

<Action type="SET_TEXT">
  <Template trim-spaces="true" engine="twig.1">
    <![CDATA[{{ source("TITLE") | default('') | upper }}]]>
  </Template>
</Action>

xml

<Action type="SET_NUMBER">
  <Template precision="0" round="CEILING" engine="twig.1">
    <![CDATA[{{ source("WIDTH_MM") }} / 10]]>
  </Template>
</Action>

Template syntax (Twig basics)

Twig uses two kinds of delimiters:

{{ ... }}: output the result of an expression (what will be written into the target cell)
{% ... %}: control logic (loops, conditions, variables, etc.)

Examples:

Display a value:

twig

{{ target('TITLE') }}

Simple condition:

twig

{% if source('BRAND') == 'ACME' %}
  {{ 'ACME PRODUCT' }}
{% else %}
  {{ source('BRAND') ~ ' ' ~ source('MODEL') }}
{% endif %}

For more details about the Twig syntax, see the Twig documentation.

Useful Twig functions and filters

Twig provides many built‑in filters. Some of the most useful in the rules engine context are:

Function	Description
`lower`	Converts a string to lowercase
`upper`	Converts a string to uppercase
`trim`	Trims whitespace from the beginning and end of a string
`replace`	Replaces substrings inside a string
`date`	Formats a date to a given format
`merge`	Merges two arrays
`filter`	Filters an array using a condition

Example – uppercase a title and trim it:

twig

{{ target('TITLE') | default('') | trim | upper }}

The default('') part ensures the value is never null before applying upper, which would otherwise cause an error.

Product‑Live specific functions

In addition to Twig’s native filters, several custom functions are available in the rules engine templates:

Function	Description
`source`	Access the value of a property on a source item
`target`	Access the value of a property on the current (target) item
`loadChildren`	Load children of an item so you can iterate on them
`base64_encode`	Encode a string into a Base64 value (useful for URLs, filters, etc.)
`base64_decode`	Decode a Base64 string into a readable string

`source` function

The source function reads a property from a source item.

Signature:

source(fieldKey)
source(fieldKey, mode)
source(fieldKey, mode, locale)

Where:

fieldKey: key of the field to read (e.g. TITLE, COLOR)
mode (for classifications and option lists): title, title-local, or key
locale: locale to use when mode is title-local (e.g. fr, en)

Examples:

twig

{{ source('TITLE') }}
{{ source('COLOR', 'key') }}
{{ source('COLOR', 'title-local', 'fr') }}

In contexts where there are multiple source items, source returns the value from the most recently updated source item.

`target` function

The target function reads a property from the current target item (the one the rule is updating). It has exactly the same signature and behavior as source, but on the target side.

Examples:

twig

{{ target('TITLE') }}
{{ target('COLOR', 'title') }}
{{ target('COLOR', 'title-local', 'en') }}

In the pure Formula context (outside of a mapping between two tables), source and target behave the same way and both read from the current item.

`base64_encode` / `base64_decode`

These functions are useful when you need to build URLs or encoded filters.

Encode a JSON filter to Base64:

twig

{{ base64_encode("[{\"fieldKey\":\"EAN\",\"operator\":\"contains\",\"criteria\":{\"string\":\"2000099919335\"}}]") }}

Decode a Base64 string:

twig

{{ base64_decode("e1wiZmllbGRLZXlcIjpcIkVBTlwiLFwib3BlcmF0b3JcIjpcImNvbnRhaW5zXCIsXCJjcml0ZXJpYVwiOntcInN0cmluZ1wiOlwiMjAwMDA5OTkxOTMzNVwifX0=") }}

`loadChildren` function

The loadChildren function dynamically loads the children of an item and replaces IDs by full child items.

Signature: loadChildren(item)
Input: usually sourceItem (parent) or the current targetItem
Output: list (array) of items

Example – list all children having color = RED and display their ident:

twig

{% for item in loadChildren(sourceItem) %}
  {% if item.fields.color.value.data == 'RED' %}
    {{ item.fields.ident.value.data }}
  {% endif %}
{% endfor %}

This function can significantly increase task execution time. Use it only when necessary.

Template engines

When configuring a template in a rule action (for example SET_TEXT or SET_NUMBER), you can choose a template engine.
In XML (Data Factory / Table Import – Schema), this is done via the optional engine attribute on the <Template> tag:

xml

<Template engine="twig.2">
  <![CDATA[{{ source("TITLE") | upper }}]]>
</Template>

If the engine attribute is omitted, the default engine twig.1 is used.

`twig.1` engine (default)

The twig.1 engine:

Supports the basic Twig features (syntax, standard filters, etc.).
Adds the Product‑Live specific functions described above:
- source
- target
- base64_encode
- base64_decode
- loadChildren

All the examples on this page use the twig.1 engine.

`twig.2` engine

The twig.2 engine:

Supports only the basic Twig features (no source, target, loadChildren, base64_*, etc.).
Is lighter and faster to execute.
Is recommended for tables containing a large number of template rules where performance is critical.

Because the engine is configured per rule (<Template engine="...">), it is possible to mix twig.1 and twig.2 on the same table, depending on the needs of each rule.

Accessing the whole item (`targetItem`)

In some advanced cases, you may need to access the raw JSON structure of the item.

Example – display the whole targetItem as JSON:

twig

{{ targetItem | json_encode | raw }}

Example – access a simple text field value:

twig

{{ targetItem.fields.TITLE.value.data.data }}

Examples

Uppercase a title

Goal: write the title of the source item into the target, in uppercase.

twig

{{ source('TITLE') | default('') | upper }}

Result: Air Jordan → AIR JORDAN.

Concatenate title and child colors

Goal: for each child having a defined color, display Title Color on a new line.

twig

{% for item in loadChildren(sourceItem) %}
  {% if item.fields.color.value.data != null and item.fields.color.value.data is not empty %}
    {{ sourceItem.fields.title.value.data }} {{ item.fields.color.value.data }}
  {% endif %}
{% endfor %}

Example output:

txt

Air Jordan RED
Air Jordan BLUE

This can be used in a LONG-TEXT or HTML-TEXT field to store multi‑line content.

Find the most expensive variant and return its ident

Goal: among all children, find the one with the highest price and return its ident.

twig

{% set maxPrice = 0 %}
{% set maxPriceIdent = null %}
{% for child in loadChildren(sourceItem) %}
  {% set priceField = child.fields.price %}
  {% if priceField is defined and priceField.value.data > maxPrice %}
    {% set maxPrice = priceField.value.data %}
    {% set maxPriceIdent = child.fields.ident.value.data %}
  {% endif %}
{% endfor %}
{{ maxPriceIdent }}

XML examples (Data Factory – Table Import Schema)

Templates can also be configured via XML imports, using Data Factory tasks such as Table Import – Schema (see the dedicated documentation).

Below are a few examples of rules using the Template parameter.

Example – Build a description from two source fields

In this example, the rule fills the description field on the target table by combining the composition and matière fields from the source table, using HTML tags and a Twig template:

xml

<Rules-Engine table="TARGET_TABLE_KEY" account="ACCOUNT_ID">
  <Source-Tables>
    <Table key="source_table_1" source-identifier="gencod" target-identifier="ean13" />
  </Source-Tables>
  <Rules>
    <Field key="description" source-table="source_table_1">
      <Rule priority="1">
        <Conditions>
          <Condition-Group>
            <Condition target="description" operator="EMPTY" />
            <Condition source="composition" operator="NOT_EMPTY" />
            <Condition source="matière" operator="NOT_EMPTY" />
          </Condition-Group>
        </Conditions>
        <Action type="SET_TEXT">
          <Template trim-spaces="true">
            <![CDATA[
              <b>Composition</b>
              <br></br>
              {{ source("composition") }}
              <br></br>
              <br></br>
              <b>Matières</b>
              <br></br>
              {{ source("matière") }}
            ]]>
          </Template>
        </Action>
      </Rule>
    </Field>
  </Rules>
</Rules-Engine>

Example – Simple template on a field

This example shows a simpler rule that builds the English title titleEn from brand and model:

xml

<Rules-Engine table="TARGET_TABLE_KEY" account="ACCOUNT_ID">
  <Source-Tables>
    <Table key="source_table_1" source-identifier="gencod" target-identifier="ean13" />
  </Source-Tables>
  <Rules>
    <Field key="titleEn" source-table="source_table_1">
      <Rule priority="1">
        <Conditions>
          <Condition-Group>
            <Condition target="titleEn" operator="EMPTY" />
            <Condition source="brand" operator="NOT_EMPTY" />
            <Condition source="model" operator="NOT_EMPTY" />
          </Condition-Group>
        </Conditions>
        <Action type="SET_TEXT">
          <Template trim-spaces="true">
            <![CDATA[{{ source("brand") }} {{ source("model") }}]]>
          </Template>
        </Action>
      </Rule>
    </Field>
  </Rules>
</Rules-Engine>

In both cases, the <Template> node wraps a Twig expression (inside <![CDATA[ ... ]]>). The execution behavior and limitations are the same as for templates created directly in the Rules Engine UI.

Testing your templates

You can test templates outside Product‑Live using the web app twig.stapps.io:

Paste the JSON input you want to use (for example a simplified sourceItem + targetItem)
Paste your Twig template
Click Render to see the result

Error handling and limitations

If a template is invalid or produces an error, the value is not updated (the task continues for other items).
Execution time is limited: if a template takes too long to run, it is considered as an error and the value is not updated.
The maximum output size of a template is 1000 characters. If the result is larger, the template is considered in error and the value is not updated.

For best performance and reliability:

Keep templates as simple as possible.
Avoid heavy loops on large sets of children when you can express the same logic with several simpler rules.

Rules engine – Templates (advanced formulas) ​

What is a template? ​

When should I use a template? ​

Template configuration ​

Common attributes (all target types) ​

Additional attributes for Number targets ​

Template syntax (Twig basics) ​

Useful Twig functions and filters ​

Product‑Live specific functions ​

source function ​

target function ​

base64_encode / base64_decode ​

loadChildren function ​

Template engines ​

twig.1 engine (default) ​

twig.2 engine ​

Accessing the whole item (targetItem) ​

Examples ​

Uppercase a title ​

Concatenate title and child colors ​

Find the most expensive variant and return its ident ​

XML examples (Data Factory – Table Import Schema) ​

Example – Build a description from two source fields ​

Example – Simple template on a field ​

Testing your templates ​

Error handling and limitations ​

Rules engine – Templates (advanced formulas)

What is a template?

When should I use a template?

Template configuration

Common attributes (all target types)

Additional attributes for Number targets

Template syntax (Twig basics)

Useful Twig functions and filters

Product‑Live specific functions

`source` function

`target` function

`base64_encode` / `base64_decode`

`loadChildren` function

Template engines

`twig.1` engine (default)

`twig.2` engine

Accessing the whole item (`targetItem`)

Examples

Uppercase a title

Concatenate title and child colors

Find the most expensive variant and return its ident

XML examples (Data Factory – Table Import Schema)

Example – Build a description from two source fields

Example – Simple template on a field

Testing your templates

Error handling and limitations