Data Factory > rules-engine-import-rules

TL;DR;

This task allows to update the mapping rules linked to a table.

Name:

TIP

The full documentation of the behavior of this task is detailed in the Learning Center.

Import process details

mermaid

flowchart TD
    start_process(start)
    for_each_element("For each set of rules on an identifier / classification / Field")
    for_each_rule("For each rule")
    is_rule_valid("Is the rule valid? (see [1])")
    add_log_to_execution_report("Add log to the execution report")
    end_for_each_rule("End of treatment for the current rule")
    import_rule("Import rule")
    end_for_each_element("End of treatment for the current set of rules")
    start_process --> for_each_element
    for_each_element --> for_each_rule
    for_each_rule --> is_rule_valid
    is_rule_valid -- "Rule is valid" --> import_rule
    is_rule_valid -- "Rule is not valid [2]" --> add_log_to_execution_report
    import_rule --> end_for_each_rule
    add_log_to_execution_report --> end_for_each_rule
    end_for_each_rule -- "There are still rules to import" --> for_each_rule
    end_for_each_rule -- "There are no more rules to import" --> end_for_each_element
    end_for_each_element -- "There are still set of rules to import" --> for_each_element
    end_for_each_element -- "There are no more set of rules to import" --> end_process

[1] A rule is considered valid if it follows below constraints [2] Execution report logs are defined below

Key points

The rules-engine-import-rules import every rule that can be importde. An error on a rule import is not preventing the import of the other rules. Mapping rules import is exhaustive

If a rule exists in the import file, it is imported
If a rule does not exist in the import file, it is deleted

Terminology

We call table target, the table on which we create links with other tables
We call tables sources, the tables linked to the target table via the identifier target (target-identifier) and source (source-identifier)
We call target-identifier or identifier target the identifier within the table target serving as a link with the table source
We call source-identifier or identifier source the identifier belonging to the source table allowing to make the link with the target identifier of the current table

Key elements

The link between two tables (Source-Table) is created on the target table, i.e. on the table on which we are trying to import mapping rules

Source table \ Target table	Owned table	Shared table
Owned table	Yes	Yes
Shared table	Yes	Yes

DANGER

You cannot link a table to itselft (see an example below). In this case we add a log in the import execution report (INVALID_SOURCE_TABLE):

xml

<Rules-Engine table="products-retailer-A" account="f4784206-9584-42a8-b36b-7f263d9af96a">
    <Source-Tables>
        <Table key="products-retailer-A" source-identifier="reference" target-identifier="ean" />
    </Source-Tables>
    <Rules />
</Rules-Engine>

DANGER

You cannot create several links (Source-Table) on identifiers of the same level of the target table and the same source table. In this case we add a log in the import execution report (MULTIPLE_SOURCES_ON_TARGET_IDENTIFIER):

xml

<Rules-Engine table="retailer-A-products" account="f4784206-9584-42a8-b36b-7f263d9af96a">
    <Source-Tables>
        <Table key="products" source-identifier="reference" target-identifier="ean" />
        <Table key="products" source-identifier="product-code" target-identifier="ref" />
    </Source-Tables>
    <Rules />
</Rules-Engine>

In other words, a target identifier of a level can only be linked once to the same source table.

DANGER

xml

<Rules-Engine table="products-retailer-A" account="f4784206-9584-42a8-b36b-7f263d9af96a">
    <Source-Tables>
        <Table key="productsA" source-identifier="ean13" target-identifier="ean13" />
        <Table key="productsA" source-identifier="model" target-identifier="product-code" />
    </Source-Tables>
    <Rules />
</Rules-Engine>

In other words, on a given level of a target table, there can only be a single link to a source table.

Valid example

xml

<Rules-Engine table="productsFnac" account="f4784206-9584-42a8-b36b-7f263d9af96a">
    <Source-Tables>
        <Table key="productsA" source-identifier="gencod" target-identifier="ean13" />
        <Table key="productsB" source-identifier="sku" target-identifier="ean13" />
    </Source-Tables>
    <Rules />
</Rules-Engine>

In the case of a multilevel table, it is possible to create any type of link as long as they respect the rules previously stated

Valid example

Incoherent example

The setting below is technically sound, although it will produce inconsistent matches between items.

Conditions

Actions

See the page dedicated to the actions

Complete example

voir

Mapping Rules Lifecycle

The file is exhaustive for a given target table. If a rule does not appear in the file, it is deleted.

Additional notes

Mapping rules on elements that are already the target of a formula are not imported.
Existing rules will not be executed (more detail here)

Impact on the life cycle of fields

Key elements :

xml

<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>

source and destination must be surrounded by {{ and }} to be interpreted.
On utilisera obligatoirement un CDATA
La notation source permet de sélectionner un attribut source
- Le premier paramètre est la clé de l’attribut, exemple source("composition")
  - Si la clé de l’attribut contient une quote " , elle devra être doublée, exemple : source("la""composition""")
- Le deuxième paramètre est à utiliser si l’attribut source est une liste d’options ou une classification. Exemple : source("color", "key")
  - Les valeurs possibles sont les mêmes que pour l’attribut use
- Le troisième paramètre est à utiliser si l’attribut source est une liste d’options ou une classification et que le second attribut est title-local
  - Les valeurs possibles correspondent à la liste des langues standard dans l’application
La notation destination permet de sélectionner un attribut dans la table de destination

Exemple complet

voir

Mapping rules life cycle

The file is exhaustive for a given target table. If a rule does not appear in the file, it is deleted.

Details on importing mapping rules on a table with multiple levels

DANGER

The creation of mapping rules between tables with more than one level is not permitted at present.

Additional notes

Mapping rules on elements already targeted by a formula are still imported. Although these will not be executed (more details here)

Life cycle impact of fields

Key points:

Ignore archived target or source attributes, and raise a warning in the log file
A rule can only be created if it mentions an existing field/classification/identifier (archived or not)
Within a condition, an archived element (option, category, etc.) is considered as “empty” (the EMPTY rule is assumed to always return true).

xml

<Condition source="erp" operator="EQUALS">
    <Value>frigo</Value>
</Condition>

If the fridge category is archived, the condition necessarily returns false

The import execution report

Structure of the `report.xml` file

xml

<Report task="rules-engine-import-rules" date="2013-04-01T17:13:41.000Z" action-id="6011339103483173319a1614"> 
    <Input key="request">https://app.product-live.com/file/request.xml</Input> 
    <Log type="error"> 
        <Metadata name="xpath"></Metadata>
        <Metadata name="code">RE_RULES_CAN_NOT_BE_APPLY_TO_INTERNAL_TABLE</Metadata>
        <Message> 
            Le message d'erreur 
        </Message> 
    </Log> 
</Report>

XPath	Description	Occurrence
`/Report@task`	The task key, here `rules-engine-import-rules`	1
`/Report/Input`	Allows to mention the inputs of the task	1..*
`/Report/Log`	A line of the report	0..*
`/Report/ Log @type`	Can be `error`, `warning` or `info`	1
`/Report/Log/Metadata-Collection`	Allows to group a set of `Metadata`	0..*
`/Report/ Log / Metadata-Collection@name`	The name of the metadata group	1
`/Report/Log/Metadata`	Represents metadata, itself defined by a name and a value	0..*
`/Report/ Log / Metadata@name`	The metadata name	1
`/Report/ Log /Message`	The message associated with this line in the report	1

Technical logs

Code	Case	Message	Kind	Comment
`DEACTIVATED`	Feature toggle on feature is disabled on this account	Task rules-engine-import-rules is not activated to create or update mapping rules on your account. Please contact Product-Live team at contact@product-live.com to enable it	error	early break mapping import before parsing the xml

Logs related to `/Rules-Engine/Source-Tables`

Code	Cas	Message	Type	Commentaire
`SOURCE_TABLE_DOES_NOT_EXIST`	For the `Rules-Engine/Sources-Tables/Table` element, the `key` attribute references a table that does not exist or is not accessible	Table with key `key` does not exist on your account - In the table key attribute, you must refer to a valid table key on your account, or if you want to create rules on a table shared by one of your partners, you must use the attribute key and the attribute account. See the documentation for more information.	error	In this case the "source" is not saved
`SOURCE_IDENTIFIER_DOES_NOT_EXIST`	For the `Rules-Engine/Sources-Tables/Table` element, the `source-identifier` attribute does not reference a source table identifier	The key `source-identifier` is not a valid identifier key from table `key`	error	In this case the "source" is not saved
`TARGET_IDENTIFIER_DOES_NOT_EXIST`	For the `Rules-Engine/Sources-Tables/Table` element, the `identifier-target` attribute does not reference an identifier of the target table	The key `identifier-target` is not a valid identifier key from table `Rules-Engine@table`	error	In this case the "source" is not saved
`MULTIPLE_SOURCES_ON_TARGET_IDENTIFIER`	Several pairs (`key`, `account`, `identifier-target`) exist	The identifier-target `identifier-target` cannot refer to multiple source-identifier on the same source table	error	In this case none of the sources are imported
`DUPLICATE_SOURCE_ON_TARGET_TABLE`	The same source table is linked several times to the same target table while multi-level mapping is not activated	`targetTableKey` cannot be linked multiple times to `sourceTableKey`.	error	In this case no source is imported
`DUPLICATE_LINK_ON_SOURCE_IDENTIFIER`	The same level of a source table is linked several times to the same target table	The level of `source-identifier` cannot be linked multiple times to `sourceTableKey`.	error	In this case no source is imported
`INVALID_SOURCE_TABLE`	The suggested table source is invalid	The source table must be an owned table	error	In this case the source is not imported
`DUPLICATE_LINK_ON_TARGET_LEVEL`	The same level of a target table is linked several times to the same level of a source table	The level of `target-identifier` cannot be linked multiple times to the same level of `sourceTableKey`.	error	In this case the source is not imported

Logs related to `/Rules-Engine/Rules/*`

Code	Case	Message	Kind	Comment
`RULES_CAN_NOT_BE_APPLIED_ON_INTERNAL_TABLE`	An internal table cannot be the target of mapping rules	Rule cannot be applied on an internal table	error
`RULE_TITLE_IS_MISSING`	`Rule` does not have a “title” attribute	Rule on `{Identifier \| Classification \| Field}` `{key}` is missing a title	caution
`RULE_PRIORITY_IS_UNVALID`	The priority on the rules is not consistent (example 1, 2, 4, 9 or 1, 1, 2, 2)	Rule priority on `{Identifier \| Classification \| Field}` `{key}` is invalid	error	We do not import the rules on this element
`RULE_TARGET_KEY_DOES_NOT_EXIST`	The `key` for the element does not exist	The `{Identifier \| Classification \| Field}` `{key}` on table `{rule-engine@table}` does not exist	error	We do not import the rules on this element
`RULE_SOURCE_TABLE_DOES_NOT_EXIST`	The table source mentioned is not referenced (or was referenced but invalid, see above)	The source table for the `{Identifier \| Classification \| Field}` `{key}` on table `{rule-engine@table}` does not exist	error	We do not import the rules on this element
`RULE_INADEQUATE_SOURCE`	The source table mentioned does exist, however, the mapping on the identifiers (source->target) does not allow the creation of rules on the identifier “key”	The source table `{rule-engine@table}` link does not allow to create rules for `{Identifier \| Classification \| Field}` `{key}`	error	We do not import the rules on this element
`RULE_IS_MISSING_A_TITLE`	`Rule` does not have a “title” attribute	Rule on `{Identify	Classification	Field}` is missing a title
`INCONSISTENT_PRIORITY`	The priority on the rules is not consistent (example 1, 2, 4, 9 or 1, 1, 2, 2)	Rule priority on `{Identifier	Classification	Field}` is invalid
`RULE_KEY_DOES_NOT_EXIST`	The `key` for the element does not exist	The {Identifier	Classification	Field} `{key}` on table `{rule-engine@table}` does not exist
`RULES_CAN_NOT_USE_MULTI_LEVEL_TABLE`	A multi-level table cannot be the source of mapping rules	Rule cannot use multi-level table	error
`RULES_CAN_NOT_BE_APPLIED_ON_MULTI_LEVEL_TABLE`	A multi-level table cannot be the target of mapping rules	Rule cannot be applied to multi-level table	error
`RULE_INADEQUATE_SOURCE_FIELD_TYPE`	A non `DATE` or `DATE-TIME` type field is used to automate a `DATE` type field	The source field `{Field}{key}` type is not compatible with the Rule Action	error	We do not import the Rules on this element
`RULES_CANNOT_BE_APPLIED_ON_MULTI_LEVELS_FIELD`	A mapping rule is defined on an attribute of a target multi-level table while the "multi-level mapping" feature flag is disabled	`targetFieldKey` cannot be automated. Fields from multi-level tables cannot be automated	error	We do not import the rules on this element
`RULES_CANNOT_USE_MULTI_LEVELS_TABLE`	A mapping rule is defined on an attribute that uses an attribute of a multi-level source table as a condition or action while the "multi-level mapping" feature flag is disabled	`targetFieldKey` cannot be automated using `source-table`. Fields from multi-levels table cannot be used in automation	error	We do not import the rules on this element

Logs related to `/Rules-Engine/Rules/Classification`

Code	Case	Message	Kind	Comment
`RULE_SOURCE_SOURCE_CATEGORY_DOES_NOT_EXIST`	In the `Map`, a source element does not exist	Rule on classification `{key}` - The key {source} from source `{Map@source}` does not exist	error	We do not import the entry in question
`RULE_CATEGORY_MENTIONED_MULTIPLE_TIME`	In the `Map`, an element is mentioned several times	Rule on classification `{key}` - The key {source} from source `{Map@source}` cannot be referenced more than once	error	We do not import the "entries" in question
`RULE_SOURCE_TARGET_CATEGORY_DOES_NOT_EXIST`	In the `Map`, a target element does not exist	Rule on classification `{key}` - The target key {target} does not exist	error	We do not import the entry in question
`RULE_ON_CLASSIFICATION_SOURCE_CATEGORY_DOES_NOT_EXIST`	In the `Map`, a source element does not exist	Rule on classification `{key}` - The key {source} from source `{Map@source}` does not exist	error	We do not import the entry in question
`RULE_ON_CLASSIFICATION_SOURCE_CATEGORY_IS_MENTIONED_SEVERAL_TIMES`	In the `Map`, an element is mentioned several times	Rule on classification `{key}` - The key {source} from source `{Map@source}` cannot be referenced more than once	error	We do not import the "entries" in question
`RULE_ON_CLASSIFICATION_TARGET_CATEGORY_DOES_NOT_EXIST`	In the `Map`, a target element does not exist	Rule on classification `{key}` - The target key {target} does not exist	error	We do not import the entry in question
`FIELD_SOURCE_INACCESSIBLE`	The link with the source table is established at a level below the level of the Field	`Rules`.`Field`.`key` cannot be automated. `source-table` level is below `Rules`.`Field`.`key` level	error	We do not import the "entries" in question
`RULE_SOURCE_FIELD_INACCESSIBLE`	{Action}\|{Condition} `source`.`key` level is below `Rules`.`Field`.`source-table` level	Rule `Rules`.`Field`.Rule``@name cannot be imported.	error	We do not import the “entries” in question
`RULE_TARGET_FIELD_INACCESSIBLE`	{Action}\|{Condition} `target`.`key` level is below target field level	Rule `Rules`.`Field`.Rule``@name cannot be imported.	error	We do not import the "entries" in question

Annexes

QA jobs concerning the application of mapping rules: link
XSD of document file: request.xsd
Batch 1 - Data Factory tasks: link
Batch 2 - The user interface: link

Data Factory > rules-engine-import-rules ​

Import process details ​

Terminology ​

Key elements ​

Conditions ​

Actions ​

Complete example ​

Mapping Rules Lifecycle ​

Additional notes ​

Impact on the life cycle of fields ​

Exemple complet ​

Mapping rules life cycle ​

Details on importing mapping rules on a table with multiple levels ​

Additional notes ​

Life cycle impact of fields ​

The import execution report ​

Structure of the report.xml file ​

Technical logs ​

Logs related to /Rules-Engine/Source-Tables ​

Logs related to /Rules-Engine/Rules/* ​

Logs related to /Rules-Engine/Rules/Classification ​

Annexes ​

Data Factory > rules-engine-import-rules

Import process details

Terminology

Key elements

Conditions

Actions

Complete example

Mapping Rules Lifecycle

Additional notes

Impact on the life cycle of fields

Exemple complet

Mapping rules life cycle

Details on importing mapping rules on a table with multiple levels

Additional notes

Life cycle impact of fields

The import execution report

Structure of the `report.xml` file

Technical logs

Logs related to `/Rules-Engine/Source-Tables`

Logs related to `/Rules-Engine/Rules/*`

Logs related to `/Rules-Engine/Rules/Classification`

Annexes