Overview

Reference Entity Rules let you automate attribute enrichment on Reference Entity Records. Define conditions to target specific records and actions to apply automatically whenever a record is saved, keeping your reference data consistent and up to date without manual intervention.

Access

To access Reference Entity Rules, navigate to Settings > Rules and select the Reference Entity Rules tab.

The rules list displays the following information for each rule:

• Label: the rule's display name. If no label is defined, the rule code appears in brackets.
• Status: Enabled or Disabled. Only enabled rules run automatically.
• Priority: execution order when multiple rules apply to the same record. Higher values run first.
• Reference entity identifier: the Reference Entity the rule targets.
• Execution type: always Triggered for Reference Entity Rules (see Execution).
• Actions: the action types configured on the rule (Copy and/or Template).

Create a rule

In the PIM UI

To create a rule in the UI, navigate to Settings/Rules and click Create. A pop-up will appear.

Each Reference Entity Rule is defined by the following properties, set when the rule is created.

By Import

To create rules using a YML file, first create it, then import it into the PIM using the Rule import in YML import job.

Each rule must have a unique code. It can also have a label per enabled PIM locale. This label will appear under Settings/Rules and be visible in your product form under your smart attributes. You can add the labels' settings anywhere in your rule. In the example below, it is placed at the end of the rule, and it adds labels for your American English and French locales. Here is the expected format:

rule_number_2:
        type: record
        priority: 0
        enabled: true
        conditions:
            -
                operator: AND
                value:
                    -
                        field: color
                        value:
                            value: null
                            reference_entity_attribute: label
                            reference_entity_attribute_scope: null
                            reference_entity_attribute_locale: en_US
                            reference_entity_attribute_operator: 'NOT EMPTY'
                        operator: WHERE
                    -
                        field: code
                        value: '123'
                        operator: CONTAINS
        actions:
            -
                template: "{{record.label(null,'en_US')}} is the {{record.biography}} {{record.country}} \nThe 	    favorite colour of the city is {{ record.color | recordLabel('en_US') }}.\n{{ record.code }}"
                to:
                    field: description
                type: template
        labels:
            en_GB: 'Rule number 2'
            en_US: 'Rule number 2'
            fr_FR: 'Rule number 2'
        triggers: {  }
        execution_type: triggered
        reference_entity_identifier: city

If you do not want to add labels to your rule, leave the labels settings with { }.

labels: {}

Record selection

The Record Selection section defines which records the rule applies to. At least one condition is recommended to avoid targeting all records in the Reference Entity.

When building your rules, you can use condition operators to define how multiple conditions should interact. By default, conditions are combined with AND, meaning all of them must be met. With the OR operator, you can create more flexible rules by allowing records to match if at least one of the conditions is true. This makes it easier to cover broader scenarios without multiplying the number of rules.

Conditions can target the following fields on a record:

Actions

The Then section defines what the rule does when conditions are met. A rule can include multiple actions. Use Add Action to combine Copy and Generate Dynamic Content actions in the same rule.

Two action types are available for Reference Entity Rules.

Copy Attribute Value

The Copy Attribute Value action copies the value of a source attribute into a target attribute on the same record. Source and target must be compatible attribute types.

Configure the following fields for this action:

• Source attribute: the attribute whose value is read.
• Source channel: required if the source attribute is scopable.
• Source locale: required if the source attribute is localizable.
• Target attribute: the attribute where the value is written.
• Target scopable: required if the target attribute is scopable.
• Target locale: required if the target attribute is localizable.

Generate Dynamic Content

The Generate Dynamic Content action generates a text value using a Twig template. The template can reference record attribute values, system properties, and apply formatting functions to produce dynamic output.

Configure the following fields for this action:

• Template: a Twig expression using {{ record.attribute_code }} syntax to reference record data. Maximum 32,000 characters.
• Target attribute: the Text attribute where the rendered result is written. Only Text attributes are supported as targets for record rules.
• Target locale: required if the target attribute is localizable.
• Target channel: required if the target attribute is scopable.

The following record data is accessible in the template:

Execution

Reference Entity Rules use the Triggered execution type exclusively. A rule runs automatically each time a record belonging to the targeted Reference Entity is saved, provided the record matches the rule's conditions. When multiple rules target the same Reference Entity, they are executed in descending Priority order.

Actions are applied asynchronously. The result may appear with a short delay after the record is saved, depending on the processing queue at the time of execution.