General information about rule format¶

Quick Overview¶

This cookbook is about a feature only provided in the Enterprise Edition.

Enrichment rules allow to set values for products given specific conditions. These rules are regularly applied, as a user who would regularly edit a product.

File Structure¶

Enrichment rules are defined in YAML. The file extension has to be ”.yml”. Indentation is mandatory within the file and has to follow the YAML format strictly. You have to import a rule so that it can be used in the PIM.

This file starts with “rules” root element, which contains the list of enrichment rules. This document is about this list. Each rule is referred to by a code and can contain a list of conditions and actions.

# Example of a file with 2 rules
rules:
    camera_set_canon_brand:
        priority: 0
        conditions:
            - field: family.code
              operator: IN
              value:
                - camcorders
            - field: name
              operator: CONTAINS
              value: Canon
            - field: camera_brand.code
              operator: NOT IN
              value:
                - canon_brand
        actions:
            - type: set
              field: camera_brand
              value: canon_brand
    camera_copy_name_to_model:
        priority: 0
        conditions:
            - field: family.code
              operator: IN
              value:
                - camcorders
            - field: camera_model_name
              operator: EMPTY
        actions:
            - type: copy
              from_field: name
              to_field: camera_model_name

Indentation is mandatory within the file and must be strictly identical to the one shown in the example.

Enrichment Rule Structure¶

Structure’s elements which define a rule are:

rule code (dynamic)
priority*
conditions
actions

Structure’s elements which define a condition are:

field
locale*
scope*
operator
value

An enrichment rule is structured as follows:

[free rule code]:
    priority​*:
    conditions:
        - field:
          locale​*:
          scope​*:
          operator:
          value:
    actions:
        - type:
          [Diverse elements according to the action]

Elements with * are optional.

Dashes - before element field and after each element contained in value part are mandatory.

Colon : mandatory after each structure element.

Tip

For more details you can see the YAML specifications.

Warning

Rules code choice is up to you, however it has to contain only alphanumeric characters, underscores, dashes and be less than 255 characters.

A priority can be given to a rule. Priority will be considered for rules execution order. Without any given priority, rule has a zero-priority. The higher the priority, the sooner the rule will be executed. Therefore, a rule with 90-priority will be executed before rules with a 0-priority. If no rule has defined priority, they will be executed in a “technical” order. (database reading order)

Action’s conditions can be applied on localizable and scopable values. In this case, it has to be specified using locale and scope elements.

The definition of conditions is very important to select only the products concerned by the rules. Don’t forget to add conditions to not execute the rules at each execution.

The field “camera_brand” will be updated only if its value is not already equal to “canon_brand”.

rules:
    camera_set_canon_brand:
        priority: 0
        conditions:
            - field: family.code
              operator: IN
              value:
                - camcorders
            - field: name
              operator: CONTAINS
              value: Canon
            - field: camera_brand.code
              operator: NOT IN
              value:
                - canon_brand
        actions:
            - type: set
              field: camera_brand
              value: canon_brand

The field “auto_focus_points” will be updated only if its value is not already equal to “4”.

rules:
    camera_set_autofocus_point:
        priority: 0
        conditions:
            - field: family.code
              operator: IN
              value:
                - camcorders
            - field: name
              operator: CONTAINS
              value: Canon
            - field: auto_focus_points
              operator: !=
              value: 4
        actions:
            - type: set
              field: auto_focus_points
              value: 4

The field “description” for en_US ecommerce will be updated only if its value is EMPTY and if the source field “description” for en_US print is NOT EMPTY.

rules:
    copy_description_us_to_ecommerce_us:
        priority: 0
        conditions:
            - field: family.code
              operator: IN
              value:
                - camcorders
            - field: description
              locale: en_US
              scope: ecommerce
              operator: EMPTY
            - field: description
              locale: en_US
              scope: print
              operator: NOT EMPTY
        actions:
            - type: copy
              from_field: description
              to_field: description
              from_locale: en_US
              from_scope: print
              to_locale: en_US
              to_scope: ecommerce

Enrichment Rule Definition¶

Available Actions List¶

Copy¶

This action copies an attribute value into another.

Warning

Source and target should share the same type. If source attribute is empty, the value “empty” will also be copied.

Two parameters are required and four other are optional:

from_field: code of the attribute to be copied.
from_locale: locale code of the value to be copied (optional).
from_scope: channel code of the value to be copied (optional).
to_field: attribute code the value will be copied into.
to_locale: locale code the value will be copied into (optional).
to_scope: channel code the value will be copied into (optional).

Tip

For instance, to copy description from en_US print channel to the en_US description e-commerce channel, 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

Set¶

This action assigns values to an attribute.

Two parameters are required, two other are optional.

field: attribute code.
locale: local code for which value is assigned (optional).
scope: channel code for which value is assigned (optional).
value: attribute value.

Tip

For instance, to set the value “My very new description for purple tshirt” to description attribute in en_US locale, for ecommerce channel, the action will be as follows:

actions:
    ­ type:   set
      field:  description
      locale: en_US
      scope:  ecommerce
      value:  "My very new description for purple tshirt"

Add¶

This action allows to add values to a multi-select attribute or a product to categories.

Two parameters are required, two other are optional.

field: attribute code.
locale: local code for which value is assigned (optional).
scope: channel code for which value is assigned (optional).
items: attribute values to add.

Tip

For instance, adding category “t-shirts” action will be as follows:

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

Remove¶

This action removes values to a multiselect, a category or a collection.

Two parameters are required, two other are optional.

field: attribute code.
locale: local code for which value is assigned (optional).
scope: channel code for which value is assigned (optional).
items: attribute values to remove.

Tip

For instance, removing category “t-shirts” action will be as follows:

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

Fields¶

Created¶

Operator	= != “>” < BETWEEN NOT BETWEEN EMPTY NOT EMPTY
Value	dates format: yyyy-mm-dd. If operator is EMPTY or NOT EMPTY values information is ignored.
Example	field: created operator: = value: "2015-01-23"

Updated¶

Operator	= != “>” < BETWEEN NOT BETWEEN EMPTY NOT EMPTY
Value	dates format: yyyy-mm-dd. If operator is EMPTY or NOT EMPTY values information is ignored.
Example	field: updated operator: = value: "2015-01-23"

Enabled¶

Operator	= !=
Value	activated => true, deactived => false.
Example	field: enabled operator: = value: false

Completeness¶

Operator	= != “>” <
Value	Percentage. /!locale and scope are mandatory
Example	field: completeness locale: fr_FR scope: print operator: = value: "100"

Family¶

Operator	IN NOT IN EMPTY NOT EMPTY
Value	Family codes or ids. If operator is EMPTY or NOT EMPTY, value information is ignored.
Example	field: family.code operator: IN value: - camcorders - digital_cameras

Groups¶

Operator	IN NOT IN EMPTY NOT EMPTY
Value	Groups codes or Ids. If operator is EMPTY or NOT EMPTY values information is ignored.
Example	field: groups.code operator: IN value: - oro_tshirts - akeneo_tshirts

Categories¶

Operator	IN NOT IN UNCLASSIFIED IN OR UNCLASSIFIED IN CHILDREN NOT IN CHILDREN
Value	Categories codes or ids.
Example	field: categories.code operator: IN value: - C0056 - F677

Attribute Types¶

Text / Textarea¶

Operator	STARTS WITH ENDS WITH CONTAINS DOES NOT CONTAIN = != EMPTY NOT EMPTY
Value	Text, with or without quotation marks. if operator is EMPTY or NOT EMPTY values information is ignored.
Example	field: description operator: CONTAIN value: "Awesome product"

Metric¶

Operator	< <= = != “>” >= EMPTY NOT EMPTY
Value	Numeric value and measure unity code. Dot ”.” is the decimal separator. No space between thousands. If operators is EMPTY or NOT EMPTY values information is ignored.
Example	field: weight operator: = value: amount: 0.5 unit: KILOGRAM

Boolean¶

Operator	= !=
Value	Yes => true, No => false
Example	field: shippable_us operator: = value: false

Multiselect List¶

Operator	IN NOT IN EMPTY NOT EMPTY
Value	Option code. If operator is EMPTY or NOT EMPTY, value information is ignored. NOT IN (red, blue) means != red and != blue.
Example	field: material.code operator: IN value: - GOLD - LEATHER

Number¶

Operator	< <= = != “>” >= EMPTY NOT EMPTY
Value	Number. If operator is EMPTY or NOT EMPTY, values information is ignored.
Example	field: min_age operator: = value: 12

Date¶

Operator	< “>” = != BETWEEN NOT BETWEEN EMPTY NOT EMPTY
Value	Format date: yyyy-mm-dd. If operator is EMPTY or NOT EMPTY, values information is ignored.
Example	field: fix_date operator: ">" value: "2016-05-12"

Price¶

Operator	< <= = != “>” >= EMPTY NOT EMPTY
Value	Numeric value and currency code. Dot ”.” is the decimal separator. No space between thousands. If operator is EMPTY or NOT EMPTY, values information is ignored.
Example	field: basic_price operator: <= value: amount: 12 currency: EUR field: null_price operator: NOT EMPTY value: amount: null currency: EUR

Picture or file¶

Operator	STARTS WITH ENDS WITH CONTAINS DOES NOT CONTAIN = != EMPTY NOT EMPTY
Value	Text. If operator is EMPTY or NOT EMPTY, values information is ignored.
Example	field: small_image operator: CONTAIN value: ../../../ src/PimEnterprise/Bundle/ InstallerBundle/Resources/ fixtures/icecat_demo/images/ AKNTS_PB.jpg

General information about rule format¶

Quick Overview¶

File Structure¶

Enrichment Rule Structure¶

Enrichment Rule Definition¶

Available Actions List¶

Copy¶

Set¶

Add¶

Remove¶

Fields¶

Created¶

Updated¶

Enabled¶

Completeness¶

Family¶

Groups¶

Categories¶

Attribute Types¶

Text / Textarea¶

Metric¶

Boolean¶

Dropdown List¶

Multiselect List¶

Number¶

Date¶

Price¶

Picture or file¶