Manipulate the Akeneo PIM data
#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 can be manually applied from the User Interface or run using a cronjob.
#File Structure
Enrichment rules are defined in YAML format, so 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
operator: IN
value:
- camcorders
- field: name
operator: CONTAINS
value: Canon
- field: camera_brand
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
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’s code (dynamic)*
- priority
- conditions*
- actions*
- Structure’s elements which define a condition are:
- field*
- locale
- scope
- operator*
- value*
An enrichment rule is structured as follow:
[free rule code]:
priority*:
conditions:
- field*:
locale:
scope:
operator*:
value*:
actions:
- type:*
[Diverse elements according to the action]
Elements with * are mandatory. Fill in the locale and scope elements only if your condition applies on localizable and/or scopable attributes.
Dashes (-) must be placed before an element field and after each element contained in value part.
Colon (:) mandatory after each structure element.
For more details you can see the YAML specifications.
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 and scope elements.
The definition of conditions is very important, make sure you select only products concerned by the rule. Add conditions so the rule(s) will not be executed if needed.
- 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
operator: IN
value:
- camcorders
- field: name
operator: CONTAINS
value: Canon
- field: camera_brand
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
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 locale and ecommerce channel will be updated only if its value is EMPTY and if the source field “description” for en_US locale and print channel is NOT EMPTY.
rules:
copy_description_us_to_ecommerce_us:
priority: 0
conditions:
- field: family
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
Akeneo rules engine proposes 4 kinds of actions:
#Copy
This action copies an attribute value into another.
Source and target attributes should share the same type. If the source attribute is empty, the value “empty” will also be copied.
- Two parameters are required while the four others 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).
For instance, you have a scopable and localizable attribute called “description”, you can copy its content from en_US locale and print channel to the en_US locale and ecommerce 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 value(s) to an attribute having the type text, textArea, simple select…
- Two parameters are required while the two others are optional.
- field: attribute code.
- locale: locale code for which value is assigned (optional).
- scope: channel code for which value is assigned (optional).
- value: attribute value.
For instance, to set the value “My very new description for purple tshirt” to your 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, a reference entity multiple links attribute or a product to categories.
- Two parameters are required while the two others are optional.
- field: attribute code.
- locale: locale code for which value is assigned (optional).
- scope: channel code for which value is assigned (optional).
- items: attribute values to add.
For instance, to add the category “t-shirts”, action will be as follows:
actions:
- type: add
field: categories
items:
- t-shirts
#Remove
This action removes values from a multi-select attribute, a reference entity multiple links attribute or a product category.
- Two parameters are required while the three others are optional.
- field: attribute code or “categories”.
- locale: locale code for which value is assigned (optional).
- scope: channel code for which value is assigned (optional).
- items: values to remove.
- include_children: if
true
, then also apply the removal of the children to the given categories. Only applicable iffield
is set to “categories” (optional, defaults tofalse
).
For instance, to remove the category “t-shirts”, action will be as follows:
actions:
- type: remove
field: categories
items:
- t-shirts
To remove the category “clothing” and its children, action will be as follows:
actions:
- type: remove
field: categories
items:
- clothing
include_children: true
To unclassify products from the whole “Master catalog” tree, action will be as follows:
actions:
- type: remove
field: categories
items:
- master
include_children: true
In order to fully unclassify a product (i.e. remove all its categories, from every category tree), it is far more efficient to use a set action:
actions:
- type: set
field: categories
value: []
#Fields
#Created
Operator |
|
Value | date format: yyyy-mm-dd. If operator is EMPTY or NOT EMPTY, value element will be ignored. |
Example | field: created
operator: =
value: "2015-01-23"
|
#Updated
Operator |
|
Value | date format: yyyy-mm-dd. If operator is EMPTY or NOT EMPTY, value element will be 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 elements are mandatory. |
Example | field: completeness
locale: fr_FR
scope: print
operator: =
value: "100"
|
#Family
Operator |
|
Value | Family code. If operator is EMPTY or NOT EMPTY, value element will be ignored. |
Example | field: family
operator: IN
value:
- camcorders
- digital_cameras
|
#Groups
Operator |
|
Value | Group code. If operator is EMPTY or NOT EMPTY, value element will be ignored. |
Example | field: groups
operator: IN
value:
- oro_tshirts
- akeneo_tshirts
|
#Categories
Operator |
|
Value | Category code |
Example | field: categories
operator: IN
value:
- C0056
- F677
|
#Attribute Types
#Text / Textarea
Operator |
|
Value | Text, with or without quotation marks. If operator is EMPTY or NOT EMPTY, value element will be ignored. |
Example | field: description
operator: CONTAINS
value: "Awesome product"
|
#Metric
Operator |
|
Value | Numeric value and measure unit code. Dot “.” is the decimal separator. No space between thousands. If operator is EMPTY or NOT EMPTY, value element will be 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
|
#Simple select list / Reference entity single link
Operator |
|
Value | Option code. If operator is EMPTY or NOT EMPTY, value element will be ignored. NOT IN (red, blue) means != red and != blue. |
Example | field: size
operator: IN
value:
- xxl
|
#Multiselect List / Reference entity multiple links
Operator |
|
Value | Option code. If operator is EMPTY or NOT EMPTY, value element will be ignored. NOT IN (red, blue) means != red and != blue. |
Example | field: material
operator: IN
value:
- GOLD
- LEATHER
|
#Number
Operator |
|
Value | Number. If operator is EMPTY or NOT EMPTY, value element will be ignored. |
Example | field: min_age
operator: =
value: 12
|
#Date
Operator |
|
Value | Format date: yyyy-mm-dd. If operator is EMPTY or NOT EMPTY, values information is ignored. |
Example | field: created_date
operator: ">"
value: "2016-05-12"
|
#Price
Operator |
|
Value | Numeric value and currency code. Dot “.” is the decimal separator. No space between thousands. If operator is EMPTY or NOT EMPTY, value element will be 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 |
|
Value | Text. If operator is EMPTY or NOT EMPTY, value element will be ignored. |
Example | field: small_image
operator: CONTAINS
value: ../../../
src/PimEnterprise/Bundle/
InstallerBundle/Resources/
fixtures/icecat_demo/images/
AKNTS_PB.jpg
|
Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!