Get started with the rules engine

Summary

The rules engine can radically boost your productivity in the PIM by automating actions. As explained in this article, a rule enables you to automatically apply one or several actions to a specific list of products and product models. To set the targeted products, you have to define conditions (that are composed of fields and operators).

The rules are defined in a YML file that you can import in the PIM using a dedicated job profile or via the interface.

To guide you in the rules engine usage, read below and find out what you can use it for and how it works.

Name your rules

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:

camera_copy_name_to_model:
    priority: 0
    conditions:
        -   operator: AND
            value:
                -   field: family
                    operator: IN
                    value:
                        - camcorders
                -   field: camera_model_name
                    operator: EMPTY
    actions:
        -   type: copy
            from_field: name
            to_field: camera_model_name
    labels:
        en_US: 'Copy name to model'
        fr_FR: 'Copie nom vers modèle'

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

labels: {}

The rule code will appear between brackets [ ] in the interface if no label is set.

 

You can also search on your rule labels under Settings/Rules.

Define a status for your rules

Thanks to the status, you can define whether or not the rule must be automatically executed.   
A status can be defined with the enabled key. The rule cannot be executed from cronjob or manually when the value is false.   
In the rule import, this key is not mandatory. If it's not specified, the rule is enabled and set to true, by default.   
To define the rule status, please follow this format:

camera_copy_name_to_model:
    priority: 0
    enabled: true
    conditions:
        -   operator: AND
            value:
                -   field: family
                    operator: IN
                    value:
                        - camcorders
                -   field: camera_model_name
                    operator: EMPTY
    actions:
        -   type: copy
            from_field: name
            to_field: camera_model_name
    labels:
        en_US: 'Copy name to model'
        fr_FR: 'Copie nom vers modèle'
        

Available actions

As of today, eight actions are available in the rules engine:

  1. Copy
  2. Add
  3. Set
  4. Remove
  5. Concatenate
  6. Clear
  7. Calculate
  8. Generate

What are these actions for? Let's discover it 😉

Copy

The Copy action enables you to copy an attribute value in another one.

The expected values are:

  • from_field: the code of the attribute to be copied
  • to_field: the attribute code where the value will be copied
  • from_locale: the locale code of the value to be copied (optional)
  • from_scope: the channel code of the value to be copied (optional)
  • to_localethe locale code where the value will be copied (optional)
  • to_scope: the channel code where the value will be copied (optional)

It is possible to copy values from an attribute type to another attribute of the same type (for example: from a text attribute type to another text attribute type). There are some exceptions, mind you!

You can copy the values of a table attribute to the same table attribute only, when you need to copy values from one locale/channel to another. 

 

You can go even further. It is possible to copy attribute values in another attribute value field even if they are two different types of values. There are some exceptions, mind you! Take a look at the list below.

You can copy the given attribute to a selection of attribute types that we defined based on logical criteria:

You can copy the option code of a simple select attribute to:

  • a reference entity single link attribute (the record must already exist)
  • a text attribute
  • a text area attribute

You can copy the option codes of a multi-select attribute to:

  • a reference entity multiple links attribute (the records must already exist)
  • a text attribute (a comma separates the codes)
  • a text area attribute (a comma separates the codes)

You can copy the value of a text attribute to:

  • a text area attribute
  • a simple select attribute (the option code must already exist)
  • a reference entity single link attribute (the record must already exist)

You can copy the value of an identifier attribute to:

  • a text attribute
  • a text area attribute

You can copy the value of a date attribute to:

  • a text attribute
  • a text area attribute

The date will be copied into the ISO 8601 format (ex: 2019-01-25T12:00:00+01:00).

 

You can copy the value of a measurement attribute to:

  • a text attribute
  • a text area attribute
  • a number attribute

You can copy the value of a number attribute to:

  • a text attribute
  • a text area attribute
  • a measurement attribute

You can copy the value of a price attribute to:

  • a text attribute
  • a text area attribute

You can copy the record code of a reference entity single link attribute to

  • a text attribute
  • a text area attribute
  • a simple select attribute (the option code of the simple select attribute must already exist)

You can copy the record label of a reference entity single link attribute to

  • a text attribute
  • a text area attribute

You can copy the value of a text attribute in a reference entity to:

  • a text attribute
  • a text area attribute
  • a simple select attribute (the option code of the simple select attribute must already exist)
  • a reference entity single link attribute (the record must already exist)

You can copy the value of a number attribute in a reference entity to:

  • a text attribute
  • a text area attribute
  • a measurement attribute

You can copy the value of a reference entity multiple links attribute to:

  • a text attribute
  • a textarea attribute
  • a multi-select attribute (the option codes of the multi-select attribute must already exist)

You can copy the value of an asset collection to:

  • another asset collection attribute

Specificity regarding simple select/multi-select attributes

In a list, an option is defined by a code and a label (the label is not mandatory). When the rule engine performs a copy action, it uses the option codes.

To copy values from a simple select attribute to another or from a multi-select attribute to another, every option you want to copy must already exist in the target attribute.

For instance, if you have two attributes: Attribute 1 and Attribute 2, both containing sizes.  
You want to copy the size filled in Attribute 1 to Attribute 2. Both have an option with code "S", but this option doesn't have the same label: in Attribute 1, the label is Small, whereas, in Attribute 2, it is S.  
When you perform a copy action on one or several products to copy this size, the option with code S will be copied from attribute 1 to attribute 2 in your product page, and the result will be:

  • Attribute 1: Small
  • Attribute 2: S

EXAMPLE

You have a value per channel and value per locale attribute called description. You can copy its content from the en_US locale and the print channel to the en_US locale and the e-commerce channel. The action will be defined as follows:

actions:
              - type: copy
                  from_field: description
                  from_locale: en_US
                  from_scope: print
                  to_field: description
                  to_locale: en_US
                  to_scope: ecommerce

Add

The Add action allows you to add values to a multi-select attribute or a reference entity multiple-link attribute. Also, it makes it possible to add a product to categories and groups.

The expected values are:

  • field: the attribute code or property
  • items: the value codes. It has to be an array of the items you need to add.
  • locale: the locale code for which the value is assigned (optional)
  • scope: the channel code for which the value is assigned (optional)

EXAMPLE

To add the “t-shirts” category to a set of products, the action will be as follows:

actions:
              - type: add
                  field: categories
                  items:
                    - t-shirts

Add associations

The add action can also associate products/product models/groups without removing previously associated ones. You can choose only to associate products or product models or groups, or any combination you like.

For instance, the following action will associate the product_42 product and the tshirt group to your product (while keeping previously associated products and groups), and won't update the associated product models.

actions:
              - type: add
                field: associations
                items:
                    X_SELL:
                        products:
                          - product_42
                        groups:
                          - tshirts

Set

The Set action assigns values to attributes and system properties: categories, status (enabled/disabled), groups, family, and associations. Beware, the new ones will replace the previous values.

The expected values are:

  • field: the attribute code or property
  • value: the attribute value or property value
  • locale: the locale code for which the value is assigned (optional)
  • scope: the channel code for which the value is assigned (optional)

EXAMPLE

To set the “My very new description for purple T-shirt” value to your description attribute in the en_US locale and for the e-commerce channel, the action will be as follows:

For instance, the following actions will disable the product and set its family to shoes. It will also categorize it in casual and women (while uncategorizing it from its previous categories), and add it to the summer group (while removing it from its previous groups).

actions:
              - type: set
                field: enabled
                value: false
              - type: set
                field: family
                value: shoes
              - type: set
                field: categories
                value:
                   - casual
                   - women
              - type: set
                field: groups
                value:
                  - summer

Set associations

As for the add action, you can associate any combination of products, product_models, or groups for each association type. You can decide which associated products, product_models, or groups you want to update. The other ones will not be updated.

In the example below, you can see that the following action will replace the associated products for the X_SELL association, but won't replace associated product models or groups.   
And for the UPSELL association, it will replace the associated product models and groups but not the associated products.

actions:
              - type: set
                field: associations
                value:
                    X_SELL:
                        products:
                          - product_42
                          - another_product
                    UPSELL:
                        product_models:
                          - amor
                        groups:
                          - tshirts

Remove

The Remove action enables you to remove values from a multi-select attribute, a reference entity multiple link attribute, an asset collection attribute, a price collection attribute, a product category or a group.

The expected values are:

  • field: the attribute code or “categories”
  • items: the value codes to remove
  • locale: the locale code for which the value is assigned (optional)
  • scope: the channel code for which the value is assigned (optional)
  • include_children: if true, then it also applies the removal of the children to the given categories. It is only applicable if the field is set to “categories” (It's optional. By default, it is set to false)

EXAMPLE

To remove the “t-shirts” category, the action will be as follows:

actions:
              - type: remove
                  field: categories
                  items:
                    - t-shirts

To remove the “clothing” category and its children, the action will be as follows:

actions:
              - type: remove
                  field: categories
                  items:
                    - clothing
                  include_children: true

To declassify products from the whole “Master catalog” tree, the action will be as follows:

actions:
              - type: remove
                  field: categories
                  items:
                    - master
                  include_children: true
        

Concatenate

The Concatenate action concatenates at least two values into a single value. A space separates each source value.

The action is only for attribute values 😉.

 

Concatenation only works if both of the fields are not empty, so we recommend using NOT EMPTY in the construction of your conditions to prevent warnings.

 

The possible source attribute types are:

  • Text
  • Text area
  • Date
  • Identifier
  • Measurement
  • Number
  • Price
  • Simple select
  • Multi-select (a comma separates values)
  • Code from reference entity
  • Label from reference entity
  • Text attribute from reference entity
  • Number attribute from reference entity
  • Reference entity multiple links

The possible target attribute types are:

  • Text
  • Text area

The parameters from and to are required in this format. Depending on the source attribute type, some optional keys can be added.The expected values are:

from

  • field: the attribute code.
  • locale: the locale code for which the value is assigned (optional)
  • scope: the channel code for which the value is assigned (optional)
  • format: format of the date following the PHP format specification (optional, only relevant for date attributes). By default, it is Y-m-d (e.g.,i.e. 2020-01-31)
  • currency: the currency code for which the price is assigned (optional, only relevant for price_collection attributes). By default, all the prices in the collection are displayed, separated by a comma.
  • label_locale: the locale code for the label of the option or record (optional, only relevant for simple select, multi-select, reference entity single link, and reference entity multiple link attributes). By default, the code of the option is used.
  • unit_label_locale: the locale code for the unit of the measurement (optional, only relevant for measurement attributes). By default, the code of the unit is used.

 

We don't manage grammar corrections when using a measurement attribute type in a concatenation (i.e., no plural management).

 

Here is an example:

actions:
            - type: concatenate
              from:
                  - field: brand
                  - field: color
                    label_locale: en_US
                  - field: name
                    scope: ecommerce
                    locale: en_US

to

  • fieldthe attribute code.
  • locale: the locale code for which the value is assigned (optional)
  • scope: the channel code for which the value is assigned (optional)

EXAMPLE

To concatenate the brand (without a value per locale and without a value per channel) and the model in the en_US locale into the product title value in the en_US locale, the action will be as follows:

actions:
            - type: concatenate
              from:
                  - field: brand
                  - field: model
                    locale: en_US
              to:
                  field: product_title
                  locale: en_US

Clear

This action clears the value(s) assigned to an attribute, product category, product group, or product association.

The expected values are:

  • field: the attribute code, "categories", "groups" or "associations".
  • locale: the locale code for which the value is assigned (optional).
  • scope: the channel code for which the value is assigned (optional).

EXAMPLES

To clear the brand in en_US locale, the action will be as follows:

actions:
            - type: clear
              field: brand
              locale: en_US

To clear all the categories that are linked to products, the action will be as follows:

actions:
            - type: clear
              field: categories
        

To clear all the product associations, the action will be as follows:

actions:
            - type: clear
              field: associations

Calculate

This action allows calculating numeric attribute values, with simple mathematical operations (addition, subtraction, multiplication, and division).

This action only accepts number, measurement or price collection attributes for both the source and the destination. Additionally, a number attribute from a Reference Entity can be used as the source only.

The action is split into 3 required steps, and 1 optional:

destination: the value you want to update. It is composed of:

  • field: the attribute code (required)
  • locale: locale code if the attribute is localizable (optional)
  • scope: channel code if the attribute is scopable (optional)
  • currency: currency code if the attribute is a price collection (required if the destination attribute type is a price collection)
  • unit: unit code if the attribute is a measurement (optional, the default measurement unit of the attribute will be used if not set)

source: the first operand of the operation. It requires at least either a value or a field and additional items. For instance, you can have:

  • value: a constant numeric value - decimal separator: dot, no thousands separator, e.g: 1515.14 (required)

OR:

  • field: attribute code of the source value (required)
  • locale: locale code if the attribute is localizable (optional)
  • scope: channel code if the attribute is scopable (optional)
  • currency: currency code if the attribute is a price collection (required if the source attribute type is a price collection)

operation_list: the list of operations to execute (at least one operation is required)

It is exactly the same format as the source property, with an additional required field:

  • operatorcan be either add, subtract, multiply, or divide (required)

The operations are applied in the order they are provided, regardless of any mathematical priority. For instance, 5 - 3 + 2 x 5 will result in ((5 - 3) + 2) x 5) = 20

 

If a product value required in an operation is empty or if a division by zero occurs, the product won't be updated.

round_precision (optional): rounds the final result of the operation(s)

If this parameter is not specified or if the value is null, the final result will not be rounded. The round precision can be:

  • a positive number: it represents the number of decimals to keep
  • 0: rounded with no decimal
  • a negative number: the rounding will occur before the decimal point (for example, with a precision of -1: 81 becomes 80, with a precision of -2: 81 becomes 100)

If the destination attribute does not allow decimals, the action can be applied only when the result is an integer. This behavior can be changed by setting up the round_precision to 0: the result will be rounded, and the action will be applied.

EXAMPLES

For instance, to calculate the volume of a cone (volume = (π x R² x h) / 3), given a radius and a height, you can use the following action:

actions:
              - type: calculate
                destination:
                  field: volume
                  unit: CUBE_CENTIMETER
                source:
                  value: 3.14
                operation_list:
                  - operator: multiply
                    field: radius
                  - operator: multiply
                    field: radius
                  - operator: multiply
                    field: height
                  - operator: divide
                    value: 3

The following action will calculate a price in euros, based on the price in dollars and a ratio, and round the result to the nearest integer value:

actions:
              - type: calculate
                round_precision: 0
                destination:
                  field: price
                  scope: ecommerce
                  currency: EUR
                source:
                  field: price
                  scope: ecommerce
                  currency: USD
                operation_list:
                  - operator: multiply
                    field: ratio

When using measurement attributes, their value will be converted to the default measurement unit defined for the attribute. For instance, a Length attribute can have a 'CENTIMETER' default unit and yet its value for the product is 1 INCH. In that case, the value will be converted to 2.54 (1 inch = 2.54 cm).

 

Also, no consistency check is performed regarding the units. You can perfectly multiply a frequency by a length and put the result in a price attribute, even if it makes no sense 😃

 

 

Generate

Generate with AI

You can now automate content generation for a range of products using AI-Enhanced Enrichment, thanks to two new actions available in the Rule Engine: 

  • 'Generate attribute value with AI’ 
  • 'Generate translation with AI'

To use the two new rules, you will need first to enable AI for content generation and/or translation at the attribute level. 

On the tab ‘Generative AI’ of your attribute in Settings/Attributes, select ‘Yes’ if you want to enrich this attribute through AI. Then, select the attributes (text or text area attributes) that you would like to consider when generating product content within the attribute you enable with Generative AI.

Then, select a pre-defined template of instructions (’System prompt’) that will be used to prompt OpenAI’s ChatGPT and allow it to be as precise as possible in the content that will be created. You also have the option to generate a custom template of instructions (’System prompt’) if you choose ‘Custom’ in the drop-down list.

Prompt Guidelines

If you would like to build your customizable prompt, we can recommend checking out our ‘Prompt Guidelines’ section in our article dedicated to 'AI-Enhanced Enrichment' for advice on how to create an accurate system prompt for your business. You can then test the accuracy of your prompt by generating descriptions for several products in the Product Edit Form before automating this action with the Rule Engine.

 

 

  • How to set up these new rules?

You can define the ‘Conditions’ for your Product Selection in the first part. The attributes or system fields will select and filter your products/product models. Altogether, your Conditions will create your 'Product selection'.

 

Your whole product catalog will be selected by default if you do not add any condition in the product selection of your rule. With these two new rules, existing content on your attributes might be erased and replaced by AI-generated content. We strongly recommend to fine-tune your selection with the relevant conditions for your products.

 

 

To generate AI-Enhanced product content in the Rules Engine, select the action ‘Generate attribute value with AI’: you must select the target attribute where product content will be generated, and the channel and locale of your choice.

To generate AI-Enhanced product translation in the Rules Engine, select the action ‘Generate translation with AI’: you must select your source attribute with channel and locale and then your target locale(s). You can select one or several locales as your target.

 

When creating a rule, if you notice that some fields are locked when selecting an action, it could be that your attribute is not enabled with AI. To do so, navigate through Settings/ Attributes and then select the Attribute (text or text area) that needs to benefit from ‘AI-Enhanced enrichment’, then select ‘This attribute can be enriched through AI’ for Generation and/or translation.

 

 

New permissions 

If you do not see these two new rules available in the Rules Engine, we can recommend to check the ‘Permissions’ area of your PIM: System / Roles / Permissions / AI. You will have three ACL groups to choose from:

  • Enable AI on attributes: this will allow users to set up any text or text area attributes to be enabled with AI, allowing for future AI-Enhanced content to be generated.
  • Authorize AI usage on Product Edit Form: this will allow users to benefit from our new ‘Ask AI’ button on every text and text area attribute.
  • Authorize Rules Configuration with AI: this will allow users to benefit from our two new rules to automate the generation of AI directly in the Rules Engine.

By default, these three permissions will be disabled.

 

 

To learn more about our AI-Enhanced enrichment feature and additional capabilities in the PIM, check out our dedicated article.

 

Generate Dynamic Content

This feature lets you dynamically insert product information into your dynamic templates, using the “Generate Dynamic Content” rule in the PIM. Imagine you want to create a product description that includes the product's name and color. To do this, you'll use the attribute codes assigned to these properties in your PIM.

Here's a basic example:

Let's say you have a product and want to include its name, stored in an attribute called product_name, and its color, stored in an attribute called product_color, in your description. You would write the following template:

This product is called {{ product.product_name }} and its color is {{ product.product_color }}.

When this template is processed, it will be replaced with the actual values from the product. For instance, if the product's name is "Elegant Lamp" and its color is "Golden", the output would be:

This product is called Elegant Lamp and its color is Golden.

 

Key Takeaway:

  • Replace product_name and product_color in the example with the actual attribute codes from your PIM.
  • The general format is {{ product.attributecode }} where attributecode is the code of the attribute you want to retrieve.
  • The table below provides more detailed examples for various attribute types and advanced options.

Remember that the feature uses Twig, a powerful templating language. While basic usage is straightforward, you can refer to the provided Twig documentation for more complex operations.

 

Integrate product values in your dynamic content

Here is a table with most common ways to retrieve values from a product.

If you need more advanced information go the next section of this page. Keep in mind this a just a sum of common expressions but you may need to use most advanced Twig configurations depending on your needs.

Here is a list of attributes types & properties available : Text, Number, Measurement, Price, Simple Select, Reference entity single link, Family, Category

Attribute type Capabilities (not exhaustive) Expression to use in your dynamic template Example of output
Text Attribute Display the full text {{ product.Attributecode }} My text
  Display the text of a specific locale (localizable attribute) {{ product.Attributecode(null, 'fr_FR') }} Mon Texte
  Display the text of a specific channel and locale (localizable & scopable attribute) {{ product.Attributecode('ecommerce', 'fr_FR') }} Mon autre texte
Number Attribute Display the number {{ product.Attributecode }} 1
  Display the rounded number using round filter {{ product.AttributeCode | round }} 1234.1400
  Display the rounded number with 2 decimals using round filter {{ product.AttributeCode | round(2) }} 1234.14
  Display the number with 2 decimals, a space for thousands and a dot for decimals using number_format filter {{ product.Attributecode | number_format(2, '.', ' ') }} 1 234.14
Measurement Attribute Display the number & the unit {{ product.Attributecode }} 6000.0000 CENTIMETER
  Display the number only {{ product.AttributeCode | amount }} 6000.0000
  Display the unit only {{ product.AttributeCode | unit }} CENTIMETER
  Display the rounded number only using round filter {{ product.AttributeCode | amount | round }} 6000
  Display the number only with 2 decimals, a space for thousands and a dot for decimals using number_format filter {{ product.Attributecode | amount | number_format(2, '.', ' ') }} 6 000.00
Price Attribute Display the number & the currency {{ product.Attributecode }} 2500.12 EUR, 2400.00 USD
  Display the number only of a specific currency {{ product.Attributecode | price('EUR') }} 2500.12
  Display the number only of a specific currency using round filter {{ product.Attributecode | price('EUR') | round }} 2500
  Display the number only with 2 decimals, a space for thousands and a dot for decimals using number_format filter {{ product.Attributecode | price('EUR') | number_format(2, '.', ' ') }} 2 500.12
  Apply a country specific currency format using format_currency filter {{ product.Attributecode | price('EUR') | format_currency('EUR', {}, 'fr') }} 2 500,12 €
Simple Select Attribute Display the code of the attribute option {{ product.Attributecode | optionCode }} optioncode
  Display the label of the option in the locale of destination {{ product.Attributecode | optionLabel(target.locale) }} Option Label
  Display the label of the option in a specific locale {{ product.Attributecode | optionLabel('fr_FR') }} Label de l’option
  Apply a default value when the label is empty using the default filter {{ product.Attributecode | optionLabel('en_US') | default('default label') }} default label
Multi Select Attribute List all option codes, separated by a comma {{ product.Attributecode | optionCode }} optioncode1,optioncode2
  List all option codes, separated by a comma {{ product.Attributecode | optionCode }} optioncode1,optioncode2
  List all option labels in a specific locale, separated by a comma {{ product.Attributecode(null, 'en_US') | optionLabel('en_US') }} option label 1,option label 2
Reference entity single link Attribute Display the code of the reference entity record {{ product.Attributecode }} record_code
  Display the label of the reference entity record in the locale of destination {{ product.Attributecode | recordLabel(target.locale) }} Record Label
  Display the label of the reference entity record in a specific locale {{ product.Attributecode | recordLabel('en_US') }} Record Label
  Apply a default value when the label is empty using the default filter {{ product.Attributecode | recordLabel('en_US') | default('default label') }} default label
Reference entity multiple link Attribute Display the codes of the reference entity records, separated by a comma {{ product.Attributecode }} record_code1, record_code2, record_code3
  Display the labels of the reference entity records in the locale of destination, separated by a comma {{ product.Attributecode | recordLabel(target.locale) }} Record Label 1, Record Label 2, Record Label 3
  Display the labels of the reference entity records in a specific locale, separated by a comma {{ product.Attributecode | recordLabel('en_US') }} Record Label 1, Record Label 2, Record Label 3
Categories List all categories of a product with their codes, separated by a comma {{ product.categories | join(', ') }} camcorders, cameras_sales
  List all categories of a product with their label of a specific locale, separated by a comma {{ product.categories | categoryLabel('en_US') | join(', ') }} Camcorders, Cameras
  List all categories of a product with their label of the locale of destination, separated by a comma {{ product.categories | categoryLabel(target.locale) | join(', ') }} Caméscopes numériques, Caméras
Family Display the family code {{ product.family }} camcorders
  Display the family label in the locale of destination {{ product.family | familyLabel(target.locale) }} Caméscopes numériques
  Display the family label in a specific locale {{ product.family | familyLabel('en_US') }} Camcorders
UUID Display the product UUID  {{ product.UUID }} 2a443ff2-f9f6-4cfc-bba8-eb15b10ef8cc
  Generate a UUID in a specific attribute {{ uuid() }} 1a6aad95-7f69-46f8-a7a7-68fe6f7013b7

 

Preview your dynamic content

Before applying your rule to all target products, use the preview feature to verify that your content generates as expected.

Steps:

  1. Enter your template: In the designated area, type or paste your dynamic content template.
  2. Select a preview product: Click the "Preview Product" button and choose a specific product or product model from the list.
  3. Review the results: The preview will display the generated content for up to 3 matching products and/or product models. For accurate results, especially with complex templates, it's recommended to initially shorten your product selection with a single, representative product.
  4. Refresh the preview: After making changes to your template, click the refresh icon (arrows) in the top right corner to update the preview.

Note: Some dynamic content might be generated (and previewed) as empty in the following contexts:

  • The attribute is empty for the product.
  • There is a syntax error in the dynamic value (incorrect attribute code, invalid characters, etc.).

Available fields

Now that you have discovered all the available actions, you can easily see which can be useful in your daily work 😉. But, to write a rule, you must define your product selection. You need to know the available fields and their operators to do so.

Remember that the filters (or "fields") used in the rules are the same as in the product grid.

 

As of today, the following fields are supported in the rules engine, and each of them has its own business rules. Here we go!

Created

The possible operators for the created field are:

  • =
  • ‘>’
  • <
  • BETWEEN
  • NOT BETWEEN
  • EMPTY
  • NOT EMPTY

The format of the date is:

  • "yyyy-mm-dd HH:MM:SS" (UTC time)
  • “now”
  • "<relative date format>" (see below)

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

The "relative date format" only works with the <, >, = and != operators.

 

EXAMPLE

- field: created
          operator: =
          value: "2015-01-23 00:00:00"
        - field: created
          operator: <
          value: "-10 days"

Updated

The possible operators for the updated field are:

  • =
  • ‘>’
  • <
  • BETWEEN
  • NOT BETWEEN
  • EMPTY
  • NOT EMPTY

The format of the date is:

  • "yyyy-mm-dd HH:MM:SS" (UTC time)
  • “now”
  • "<relative date format>" (see below)

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

The "relative date format" only works with the <, >, = and != operators.

Please note that the hour format is in the UTC timezone.

 
-
          field: updated
          operator: =
          value: "2015-01-23 00:00:00"
        -
          field: updated
          operator: '>'
          value: "-1 year"

Focus on the “relative date format”

The relative date format allows to specify dates that are relative to the rule execution date. It, the only relevant relative date format for the created and updated properties  is formatted as follows:

<+/-><count> <unit>, with:

  • "+" means a date in the future, "-" a date in the past
  • the count is an integer
  • unit is one of the following values: minute, hour, day, week, month, or year with an optional final s

For instance, +1 month means in one month, and -2 days means two days ago

Obviously, the only relevant relative date format for the created and updated properties is the "past" relative date.

 

Enabled (status)

The possible operators for the enabled field are:
  • =
field: enabled
        operator: =
        value: false

If you want to select the activated products, set the value to "true". If you want to select the deactivated ones, set it to "false".

 

Completeness

The possible operators for the completeness field are:

  • =
  • ‘>’
  • <

EXAMPLE

field: completeness
        locale: fr_FR
        scope: print
        operator: =
        value: "100"

The locale and scope elements are mandatory.

 

The value field requires a percentage.

 

Family

The possible operators for the family field are:

  • IN
  • NOT IN
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: family
        operator: IN
        value:
         - camcorders
         - digital_cameras

The value expects family codes.

 

Family variant

The possible operators for the family_variant field are:

  • IN
  • NOT IN
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: family_variant
        operator: IN
        value:
         - shoes_by_size
         - clothing_by_color
        

The value expects family variant codes.

 

Parent

The possible operators for the parent field are:

  • IN
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: parent
        operator: IN
        value:
         - model_tshirt_red
         - model_pants_blue

The value expects product model codes.

 

Identifier

The possible operators for the identifier field are:

  • STARTS WITH
  • CONTAINS
  • DOES NOT CONTAIN
  • =
  • “!=”
  • IN
  • NOT IN

EXAMPLE

field: identifier
        operator: IN
        value:
         - model_tshirt_red
         - tshirt_red_xxl

The value expects product identifiers or product model codes.

 

Entity type

The only accepted operator for the entity_type field is:

  • =

EXAMPLE

field: entity_type
        operator: =
        value: Akeneo\Pim\Enrichment\Component\Product\Model\ProductModelInterface
        

The value field expects either Akeneo\Pim\Enrichment\Component\Product\Model\ProductInterface for products or Akeneo\Pim\Enrichment\Component\Product\Model\ProductInterface for product models.

 

Groups

The possible operators for the groups' field are:

  • IN
  • NOT IN
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: groups
        operator: IN
        value:
         - oro_tshirts
         - akeneo_tshirts

The value field expects the group codes.

 

Categories

The possible operators for the categories field are:

  • IN
  • NOT IN
  • UNCLASSIFIED
  • IN OR UNCLASSIFIED
  • IN CHILDREN
  • NOT IN CHILDREN

EXAMPLE

field: categories
        operator: IN
        value:
         - C0056
         - F677

The field expects the category code.

 

Attribute types

Now that the actions and the fields don't have any secret for you anymore, you can discover which attribute types you can use as targets for your rules. It means these attributes can receive the values you defined in your rules.

Text / Text area

The possible operators for the text/textarea attribute types are:

  • STARTS WITH
  • CONTAINS
  • DOES NOT CONTAIN
  • =
  • EMPTY
  • NOT EMPTY

If the operator is EMPTY or NOT EMPTY, the value element will be ignored

 

EXAMPLE

field: description
        operator: CONTAINS
        value: "Awesome product"
        

text can be written with or without quotation marks.

Identifier

The possible operators for the identifier attribute type are:

  • STARTS WITH
  • CONTAINS
  • DOES NOT CONTAIN
  • =
  • “!=”
  • IN
  • NOT IN

EXAMPLE

field: sku
        operator: CONTAINS
        value: "AKNTS_PB"
        

Measurement

The possible operators for the measurement attribute type are:

  • <
  • =
  • ‘>’
  • ‘>=’
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: weight
        operator: =
        value:
         amount: 0.5
         unit: KILOGRAM

We expect numeric value and measurement unit code in the following format:

  • dot “.” is the decimal separator,
  • there is no space between thousands.

Boolean

The possible operators for the boolean attribute type are:

  • =

EXAMPLE

field: shippable_us
        operator: =
        value: false

If you want your rule to be applied to a boolean attribute type set to "Yes", you should set "true" as a value. If you want your rule to be applied to a boolean attribute type set to "No", you should set "false" as a value.

 

The possible operators for the Simple select list / Reference entity single link attribute types are:

  • IN
  • NOT IN
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: size
        operator: IN
        value:
         - xxl

We expect the option code as a value.

The possible operators for the Multiselect list / Reference entity multiple link attribute types are:

  • IN
  • NOT IN
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: material
        operator: IN
        value:
         - GOLD
         - LEATHER

We expect the option code as a value.

Number

The possible operators for the Number attribute type are:

  • <
  • =
  • ‘>’
  • ‘>=’
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: min_age
        operator: =
        value: 12

We expect a number as a value.

Date

The possible operators for the Date attribute type are:

  • <
  • ‘>’
  • =
  • BETWEEN
  • NOT BETWEEN
  • EMPTY
  • NOT EMPTY

The format of the date is:

  • “yyyy-mm-dd”
  • “now”
  • "<relative date format>" (see below)

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

The "relative date format" only works with the <, >, = and != operators.

 

EXAMPLE

-
          field: release_date
          operator: =
          value: "2015-01-23"
        -
          field: creation_date
          operator: '>'
          value: "-1 year"

Focus on the “relative date format”

The relative date format allows to specify dates that are relative to the rule execution date, it is formatted as follows:

<+/-><count> <unit>, with:

  • "+" means a date in the future, "-" a date in the past
  • count is an integer
  • unit is one of the following values: day, week, month or year with an optional final s

For instance, +1 month means in one month, and -2 days means 2 days ago

EXAMPLE

field: created_date
        operator: '>'
        value: "2016-05-12"

The "relative date format" is based on the UTC timezone. It means that if you are located in Eastern Australia (UTC +10) and the rules are executed on the 06/22/20 at 8:00am, the "relative date" will be based on the 06/21/20

 

Price

The possible operators for the Price collection attribute type are:

  • <
  • =
  • ‘>’
  • ‘>=’
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: basic_price
        operator: <=
        value:
          amount: 12
          currency: EUR
        
        field: null_price
        operator: NOT EMPTY
        value:
          amount: null
          currency: EUR

We expect numeric value and currency code in the following format:

  • dot “.” is the decimal separator,
  • there is no space between thousands.

Picture or file

The possible operators for the Picture or File attribute types are:

  • STARTS WITH
  • CONTAINS
  • DOES NOT CONTAIN
  • =
  • EMPTY
  • NOT EMPTY

EXAMPLE

field: small_image
        operator: CONTAINS
        value: ../../../
         src/PimEnterprise/Bundle/InstallerBundle/Resources/fixtures/icecat_demo/images/AKNTS_PB.jpg

We expect a text as a value (it should match the filename).

Asset collection

The possible operators for the Asset Collection attribute type are:

  • IN
  • NOT IN
  • EMPTY
  • NOT EMPTY

The value element will be ignored if the operator is EMPTY or NOT EMPTY.

 

EXAMPLE

field: packshot
        operator: IN
        value: [my_product_packshot]

In this example, we select all the products with the "my_product_packshot" asset in their "packshot" asset collection.

We expect an array of asset codes as value.

A real example

You're done with all these specifications!

We hope that you perfectly understand the rules engine operation now. But to clarify it, we thought it would be better to take a real example of a rule 😉.

Let's say that, among all the attributes of your product form, you have one price collection attribute type and a boolean attribute type. In the price collection, you define the price of your product in USD. The boolean attribute defines if your product is ready to be sent to your ecommerce platform (if it is set to "yes", it means that the product is ready).

Manually changing the status of the boolean attribute is time-consuming and a very repetitive task... But for the rules engine, it's a perfect match! The mission of the rules engine here is to automate the status change of the boolean once the price attribute has a value.

To do so, follow these steps:

  1. Open a text editor to write the YML code of the rule.
  2. Write this:
my_rule:
    priority: 90
    enabled: true
    conditions:
        -   operator: AND
            value:
                -   field: basic_price
                    operator: NOT EMPTY
                    value:
                        amount: null
                        currency: EUR
    actions:
        -   field: ecommerce_ready
            value: true
            type: set
    labels:
        en_US: 'Set ecommerce_ready'
        fr_FR: 'Définir ecommerce_ready'

And finally, import your YML file using the Akeneo rules import job.

If you want to execute the rule directly:

  1. Go to SettingsRules
  2. Click on the "play" button on your rule line and confirm.

The rule is executed 😉