Data Factory > table-import-items

TL;DR;

This task provides a way to import items into a table.

Name:

Target

This document deals with importing items through the Data Factory table-import-items task

Inputs and Outputs

{
  "name": "table-import-items",
  "taskReferenceName": "b",
  "description": "The business description of the task",
  "type": "SUB_WORKFLOW",
  "optional": false,
  "inputParameters": {
    "request": "${a.output.resultOfTheTransformation}"
  }
}

Inputs

TIP

If at least one task parameters (whether mandatory or not) is invalid, task execution is stopped and the returned status is FAILED. For example:

• The proposed value for the accountKey property is invalid.

Property	Description
request	Mandatory - File The input file. See below for the different types of input
accountKey	Mandatory if the target is a shared table - String The key of the account in the case of a shared table
mode	Enum - CREATE_OR_UPDATE, UPDATE_ONLY, CREATE_ONLY - Default: CREATE_OR_UPDATE CREATE_ONLY: only items not present in the target table are created (whatever the partition). The other items are simply ignored. UPDATE_ONLY: only the items already present in the target table are updated (whatever the partition). The other items are simply ignored. CREATE_OR_UPDATE: All requested updates are done.

Outputs

WARNING

The createdItemsCount and updatedItemsCount outputs are features in alpha phase. **Do not use in production.

Property	Description
report	File the import report in xml format. See below Non disponible dans l'extension VSCode pour Data Factory
createdItemsCount	Number Number of items created during this import
updatedItemsCount	Number Number of items updated during this import

Example of an input request file

1. Example on a single level

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Classification key="taxonomy">phone</Classification>
            <Field key="titleEn">Phone X</Field>
            <Field key="price">999.9</Field>
            <Field key="frontImage">https://site.com/images/1234567890123_front.jpg</Field>
        </Item>
        <Item partition="active">
            <Identifier key="ean">1234567890124</Identifier>
            <Classification key="taxonomy">phone</Classification>
            <Field key="titleEn">Phone S10</Field>
            <Field key="price">890.9</Field>
            <Field key="frontImage">https://site.com/images/1234567890124_front.jpg</Field>
        </Item>
    </Items>
</Table>

2. 3 levels example

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="reference">00034</Identifier>
            <Classification key="taxonomy">dress</Classification>
            <Field key="titleEn">Black women's lapel collar button down dress</Field>
            <Item>
                <Identifier key="referenceColor">00034-red</Identifier>
                <Field key="color">red</Field>
                <Field key="frontImage">https://site.com/images/00034-red_front.jpg</Field>
                <Item>
                    <Identifier key="sku">00034-red-34</Identifier>
                    <Identifier key="ean">1234567890123</Identifier>
                    <Field key="size">34</Field>
                    <Field key="price">19.9</Field>
                    <Field key="stock">320</Field>
                </Item>
                <Item>
                    <Field key="sku">00034-red-36</Field>
                    <Field key="ean">1234567890124</Field>
                    <Field key="size">36</Field>
                    <Field key="price">19.9</Field>
                    <Field key="stock">218</Field>
                </Item>
            </Item>
            <Item>
                <Identifier key="referenceColor">00034-green</Identifier>
                <Field key="color">green</Field>
                <Field key="frontImage">https://site.com/imagess/00034-green_front.jpg</Field>
                <Item>
                    <Identifier key="sku">00034-green-34</Identifier>
                    <Identifier key="ean">1234567890125</Identifier>
                    <Field key="size">34</Field>
                    <Field key="price">80.9</Field>
                    <Field key="stock">114</Field>
                </Item>
                <Item>
                    <Identifier key="sku">00034-green-36</Identifier>
                    <Identifier key="ean">1234567890126</Identifier>
                    <Field key="size">36</Field>
                    <Field key="price">80.9</Field>
                    <Field key="stock">136</Field>
                </Item>
            </Item>        
        </Item>
    </Items>
</Table>

3. Composite field

Composite field

The Composite field is in phase.

<Table key="PRODUCTS">
  <Items>
      <Item partition="ACTIVES">
            <Identifier key="EAN_13">3210987654321</Identifier>
            <Classification key="TYPOLOGY">CONNECTED_SCALES</Classification>
            <Field key="TITLE_EN">Body Black connected scale</Field>
            <Field key="PRICE" suffix="EURO">99</Field>
            <Field key="BATTERY">
                <Field key="BATTERY_TECHNOLOGY_CODE">ALKALINE</Field>
                <Field key="BATTERY_TYPE_CODE">AAA</Field>
                <Field key"BATTERY_QUANTITY">4</Field>
            </Field>
            <Field key="BLUETOOTH">
                 <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 4.0</Field>
            </Field>
            <Field key="BLUETOOTH">
                 <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 5.0</Field>
            </Field>
            <Field key="BLUETOOTH">
                 <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 6.0</Field>
            </Field>
      </Item>
  </Items>
</Table>

XPath	Description	Occurrence
Table	Root element	1
./@key	The key of the table on which the items should be imported.	1
./Items	Items	0..1
../Item	An item	0..*
../Item/@partition	The key of the partition on which the item must be associated. An item is associated to only one partition. In the case of an update, it is not mandatory to mention the partition key.	0..1
../Item/Identifier	A value for an identifier for the current item	1..5
../Item/Identifier/@key	The key to identify the identifier in question	1
../Item/Identifier/@delete	Allows to express in an explicit way, the deletion order of the value associated to the target identifier on the current item (if true then deletion, otherwise the attribute is ignored)	0..1
../Item/Classification	A classification	0..5
../Item/Classification/@key	The key to identify the classification in question	1
../Item/Classification/@delete	Allows expressing in an explicit way, the deletion order of the value associated to the target classification on the current item (if true then deletion, otherwise the attribute is ignored)	0..1
../Item/Field	A field	0..*
../Item/Field/@key	The key to identify the field in question	1
../Item/Field/@quantity	For the MULTIPLE-SELECT-QUANTIFIED and MULTIPLE-SELECT-QUANTIFIED-WITH-COMMENTS fields, the quantity linked to the selected option(s)	0..1
../Item/Field/@comment	For MULTIPLE-SELECT-QUANTIFIED-WITH-COMMENTS fields, the comment related to the option(s). Limit to 255 characters.	0..1
../Item/Field/@file-hash	The hash of the file present on Product-Live. If this property is indicated, it has priority over the file-key property, if there is no match then look in file-key (see below for more details)	0..1
../Item/Field/@file-key	This property is only present if the target field is of type IMAGE or ATTACHMENT The unique key that identifies the file.	0..1
../Item/Field/@delete	Allows to express in an explicit way, the deletion order of the value associated to the target field on the current item (if true then deletion, otherwise the attribute is ignored)	0..1
../Item/Field/Field	For parent field with type COMPOSITE. Each contained field must be set according to its own type.	0..*
../Item/Item	The child item to the current item	0..*

General behavior of the import

• Empty values are not imported. In the example below, the two items below are equivalent.

<Item partition="active">
    <Identifier key="ident-1"></Identifier>
    <Identifier key="ident-2">A</Identifier>
    <Classification key="taxonomy">TV</Classification>
    <Classification key="taxonomy-bis"></Classification>
    <Field key="title">TV</Field>
    <Field key="description"></Field>
</Item>

... is equivalent to ...

<Item partition="active">
    <Identifier key="ident-2">A</Identifier>
    <Classification key="taxonomy">TV</Classification>
    <Field key="title">TV</Field>
</Item>

• Identifiers, classification and fields that do not exist in the table are simply ignored during import

<Item partition="active">
    <Identifier key="ident-1">A</Identifier>
    <Identifier key="ident-2-x">B</Identifier> <!-- Identifier ident-2-x does not exist in the current table -->
    <Classification key="taxonomy-x">TV</Classification> <!-- Classification taxonomy-x does not exist in the current table -->
    <Field key="description">Hello</Field>
    <Field key="description-x">Hello again</Field> <!-- Field description-x does not exist in the current table -->
</Item>

... is equivalent to ...

<Item partition="active">
    <Identifier key="ident-1">A</Identifier>
    <Field key="description">Hello</Field>
</Item>

• If a value is to be imported, but it does not respect what is defined in matrix, then it is imported anyway.
• If the import of an item cannot be done (for whatever reason), the import of the following items is still attempted.

The logic for creating or updating items

The creation or update of items takes place as shown below. The diagram below describes the process applied for one item, and is repeated for each item communicated in the XML file as input to the task.

flowchart TD
    start_process(Début)
    end_process(Fin)
    execute_formula_on_identifier["Execution of each formula on every item identifiers [1]"]
    exec_formula_in_success{Success?}
    formula_error[The execution of the formulas <br />is in error. <br />The item is not created or updated.]
    does_item_has_at_least_one_identifier{At least one identifier?}
    order_identifier_by_index[The proposed identifiers are ordered according to their index <br /> from 1 - the smallest - to 5]
    select_item_based_on_identifier[For the identifier with the smallest index<br/>If an item exists in the target table, we select it<br/>Otherwise we move to the next identifier]
    does_item_exist{"Does the item exist? [2]"}
    is_max_item_per_partition_reached{"Technical limit reached? [3]"}
    does_account_has_enought_quota{ reached?}
    item_is_not_created_or_update[The item is not created or updated]
    item_is_created["The item is created [4]"]
    is_item_target_the_same_p_item{"Is the parent <br />updated?"}
    item_is_updated["The item is updated [4]"]
    item_parent_cannot_be_update["The parent of an item cannot be updated [5]"]
    start_process --> execute_formula_on_identifier
    execute_formula_on_identifier --> exec_formula_in_success
    exec_formula_in_success -.-> | Success | does_item_has_at_least_one_identifier
    exec_formula_in_success -.-> | In error | formula_error
    formula_error --> end_process
    does_item_has_at_least_one_identifier -.-> |L'item a au moins un identifiant| order_identifier_by_index 
    subgraph "Retrieve the item from the target table"
        order_identifier_by_index --> select_item_based_on_identifier
        select_item_based_on_identifier --> select_item_based_on_identifier
    end
    select_item_based_on_identifier --> does_item_exist
    does_item_exist -.-> |The item exists| is_item_target_the_same_p_item
    is_item_target_the_same_p_item -.-> |Yes| item_parent_cannot_be_update
    item_parent_cannot_be_update --> end_process
    is_item_target_the_same_p_item -.-> |No| item_is_updated
    does_item_exist -.-> |The item does not exist| is_max_item_per_partition_reached
    subgraph "Checking quota and technical limits"
        is_max_item_per_partition_reached -.-> |The number of items in the current partition <br />does not exceed the allowed limit| does_account_has_enought_quota
        does_account_has_enought_quota -.-> |Sufficient quota| item_is_created
        is_max_item_per_partition_reached -.-> |The number of items<br />in the current partition <br />exceeds the allowed limit| item_is_not_created_or_update
        does_account_has_enought_quota -.-> |Insufficient quota| item_is_not_created_or_update
    end
    does_item_has_at_least_one_identifier -.-> |The item has no identifier. It cannot be created or updated| end_process 
    item_is_updated --> end_process
    item_is_created --> end_process
    item_is_not_created_or_update --> end_process

Notes:

• [1] The formulas are executed on the identifiers before determining if the item exists or not in the target table. This preliminary treatment allows authorizing the import of items without identifiers if an identifier appears after the application of the formulas.(see this example for more details). The Pseudo-code is available here.
• [2] The item is considered to exist if the identifier(s) communicated have allowed the selection of an item in the target table (we do not consider the partition communicated for this item)
• [3] The technical limits are described here
• [4] The creation and updating of items are described in detail in the diagram below
• [5] You cannot update the parent to which an item points (see below)

The creation and update of items is done as follows

flowchart TD
    start_process(Start)
    end_process(End)
    get_item_and_merge_it_with_given_item["Retrieve the item from the database if it exists and merge it with the communicated item [1]"]
    execute_formula[Execution of the formulas on the given item]
    exec_formula_in_success{Success?}
    formula_error[The execution of the formulas is in error. The item is not created or updated.]
    create_or_update[Creation or update of the item]
    is_create_or_update_a_success["Success?  [2]"]
    cf[Calculation of conditional formatting]
    item_has_not_been_updated[Creation or update failed. The item is ignored.]
    start_process --> get_item_and_merge_it_with_given_item
    get_item_and_merge_it_with_given_item --> execute_formula
    execute_formula --> exec_formula_in_success
    exec_formula_in_success -.-> |Success| create_or_update
    exec_formula_in_success -.-> |Error| formula_error
    formula_error --> end_process
    create_or_update --> is_create_or_update_a_success
    is_create_or_update_a_success -.-> |Success| cf
    cf --> end_process
    is_create_or_update_a_success -.-> |Error| item_has_not_been_updated
    item_has_not_been_updated --> end_process

Notes:

• [1] The objective here is to update an identifier on which a formula is present, in the case where only part of the sources is communicated.
• [2] It is possible that the creation of the item cannot be done. For example, in the case where a uniqueness constraint on an identifier is not met. In this case, the edition or the creation of the item is not done and no updates ordered on this item will be done. The update date of the item will also remain unchanged.

Examples

If we consider the case below.

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

In this example, we consider that a formula exists on Compound identifier: Compound identifier = Supplier reference + Supplier

Import of an item by proposing a unique identifier

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">1</Identifier>
            <Field key="Supplier reference">REF1 bis</Field>
        </Item>
    </Items>
</Table>

... will update the line number 1.

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1 bis-SAMSUNG    | REF1 bis              | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

Import of an item by proposing several identifiers

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference | Supplier |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">3</Identifier>
            <Identifier key="Unique Code">B</Identifier>
        </Item>
    </Items>
</Table>

... will update the number 2 line

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference | Supplier |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 3         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

To obtain this result, we proceeded as follows:

1. The identifier EAN being the index identifier 1, we search in the target table for an item answering the criteria EAN = 3 -> We get no result
2. The identifier Unique Code being the index identifier 2, we search in the target table for an item answering the criteria Unique Code = B -> We obtain 1 result, the item #2
3. It is the item obtained previously that is updated

Importing an item with multiple identifiers - No match

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference | Supplier |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">3</Identifier>
            <Identifier key="Unique Code">C</Identifier>
            <Identifier key="Compound identifier">REF3-SAMSUNG</Identifier>
        </Item>
    </Items>
</Table>

... will create a third item

we do not update here the identifier "Compound identifier"

A calculated identifier cannot be edited directly.

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 | 3         | C           |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

To obtain this result, we proceeded as follows:

1. The identifier EAN being the index identifier 1, we search in the target table for an item meeting the criteria EAN = 3 -> We get no result
2. The identifier Unique Code being the index identifier 2, we search in the target table for an item answering the criteria Unique Code = C -> No result is obtained
3. No other identifier is communicated, so we create the item in the target table

Import of an item with several identifiers - Uniqueness break on an identifier

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">1</Identifier>
            <Identifier key="Unique Code">B</Identifier>
        </Item>
    </Items>
</Table>

... will not be possible. The value B for the Unique Code identifier is already taken by item number 2.

To obtain this result, we proceeded as follows:

1. The identifier EAN being the index identifier 1, we search in the target table for an item meeting the criteria EAN = 1 -> We get 1 result, the item #1
2. We try to apply the Unique Code = B update on item #1, however the B value for the Unique Code identifier is already assigned to item #2
3. The update of item #1 can therefore not be performed

Important

In the case described above. The item is not imported, and none of the updates ordered on this item will be performed. The update date of the item will also remain unchanged.

INFO

If the case described above is performed from the app.product-live.com application. The item is not updated, and a warning message with the title of the identifier (localized if applicable) is displayed to the user.

Import of an item proposing a "calculated" identifier

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">3</Identifier>
            <Identifier key="Compound identifier">REF1-SAMSUNG</Identifier>
        </Item>
    </Items>
</Table>

... will update the line number 1.

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 3         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

To obtain this result, we proceeded as follows:

1. The identifier EAN being the index identifier 1, we search in the target table for an item answering the criteria EAN = 3 -> We obtain no result
2. There is no criteria on the identifier Unique Code which is the index identifier 2 -> we search on the following index identifier
3. The identifier Compound identifier being the index identifier 3, we search in the target table for an item answering the criterion Compound identifier = REF1-SAMSUNG -> We obtain 1 result, the item #1
4. It is the item obtained previously which is thus updated

Import of an item proposing a "calculated" identifier - And attempt to update this identifier

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">1</Identifier>
            <Identifier key="Compound identifier">REF3-SAMSUNG</Identifier>
        </Item>
    </Items>
</Table>

... targets line number 1, but will not update the Compound identifier

To obtain this result, we proceeded as follows:

1. The identifier EAN being the index identifier 1, we search in the target table for an item meeting the criterion EAN = 1 -> We get 1 result, the item #1
2. It is the item obtained previously which is thus updated, but as the field to be updated is a Compound identifier, this Compound identifier will not be updated.

WARNING

An identifier on which a formula is applied cannot be updated manually.

Import of an item proposing a "calculated" identifier - And attempt to update it via the properties that compose it

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="Compound identifier">REF1-SAMSUNG</Identifier>
            <Field key="Supplier reference">REF1_bis</Field>
            <Field key="Supplier">SAMSUNG</Field>
        </Item>
    </Items>
</Table>

... **will create a third item

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             | REF1_bis-SAMSUNG    | REF1_bis              | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+

To obtain this result, we proceeded as follows:

1. Apply the formulas available on the identifiers of the target table to the item you want to create or update (as mentioned here) -> The proposed value for the Compound identifier is therefore overwritten.
2. The application of these formulas reveals the Compound identifier (or rather a new value for this identifier)
3. The identifier Compound identifier being an index 3 identifier, we search in the target table for an item matching the criterion Compound identifier = REF1_bis-SAMSUNG -> We get no result
4. No other identifier being communicated, we create the item in the target table

WARNING

we cannot update a Compound identifier, if we do not propose another identifier as a complement during the update.

Importing an item without identifying it - special case

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
    <Items>
        <Item partition="active">
            <Field key="Supplier reference">REF3</Field>
            <Field key="Supplier">SAMSUNG</Field>
        </Item>
    </Items>
</Table>

... will create a third item

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference | Supplier |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             | REF3-SAMSUNG        | REF3                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+

To obtain this result, we proceeded as follows:

1. Apply the formulas available on the identifiers of the target table to the item you want to create or update (as mentioned here)
2. Applying these formulas highlights the Compound identifier
3. The Compound identifier being an index 3 identifier, we search in the target table for an item answering the criteria Compound identifier = REF3-SAMSUNG -> We obtain no result
4. No other identifier being communicated, we create the item in the target table

WARNING

This particular case represents the only case where the creation or the update of an item without explicitly communicating is possible.

Special case of fields with the delete attribute

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference    | Supplier    |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           | REF1-SAMSUNG        | REF1                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             |                     |                       |             |
+---+-----------+-------------+---------------------+-----------------------+-------------+

The import of the item below ...

<Table key="products">
  <Items>
    <Item partition="active">
      <Identifier key="EAN">1</Identifier>
      <Field key="Supplier reference" delete="true" />
    </Item>
  </Items>
</Table>

Leads to the recalculation of the formulas and has the effect of deleting the value of the Compound identified for the item with the EAN 1

+---+-----------+-------------+---------------------+-----------------------+-------------+
| # | EAN       | Unique Code | Compound identifier | Supplier reference | Supplier |
|   | index = 1 | index = 2   | index = 3           |                       |             |
|   |           |             |                     |                       |             |
+===+===========+=============+=====================+=======================+=============+
| 1 | 1         | A           |                     |                       | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 2 | 2         | B           | REF2-SAMSUNG        | REF2                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+
| 3 |           |             | REF3-SAMSUNG        | REF3                  | SAMSUNG     |
+---+-----------+-------------+---------------------+-----------------------+-------------+

Multi-levels import

Example:

<Table key="product">
    <Items>
        <Item partition="active">
            <Identifier key="reference">A</Identifier>
            <Classification key="typology">t-shirt</Classification>
            <Field key="title">T-Shirt à col rond</Field>
            <Item>
                <Identifier key="reference_color">A-RED</Identifier>
                <Field key="color">red</Field>
                <Item>
                    <Identifier key="sku">A-RED-S</Identifier>
                    <Identifier key="ean">3253632845670</Identifier>
                    <Field key="size">S</Field>
                </Item>
                <Item>
                    <Identifier key="sku">A-RED-M</Identifier>
                    <Identifier key="ean">3253632845671</Identifier>
                    <Field key="size">M</Field>
                </Item>
                <Item>
                    <Identifier key="sku">A-RED-L</Identifier>
                    <Identifier key="ean">3253632845672</Identifier>
                    <Field key="size">L</Field>
                </Item>
            </Item>
            <Item>
                <Identifier key="reference_color">A-YELLOW</Identifier>
                <Field key="color">yellow</Field>
                <Item>
                    <Identifier key="sku">A-YELLOW-S</Identifier>
                    <Identifier key="ean">3253632845673</Identifier>
                    <Field key="size">S</Field>
                </Item>
                <Item>
                    <Identifier key="sku">A-YELLOW-M</Identifier>
                    <Identifier key="ean">3253632845674</Identifier>
                    <Field key="size">M</Field>
                </Item>
                <Item>
                    <Identifier key="sku">A-YELLOW-L</Identifier>
                    <Identifier key="ean">3253632845675</Identifier>
                    <Field key="size">L</Field>
                </Item>
            </Item>
        </Item>
    </Items>
</Table>

In the example above, we see that 3 levels are present and are designated in a implicit way.

• the level which has the identifier reference is of index 1
• the level which has the identifier reference_color is of index 2
• the level which has the identifiers sku and ean is of index 3
• It is not necessary to specify the target partition for items imported on indexes greater than 1, it is considered that an item and all its children belong to the same partition.
• When an item with index 1 changes partition, all its children change partition at the same time.
• In the example above, we consider that the cluster (represented below) represents 9 items in the target table
  • The import of the above items will therefore decrement by 9 the quota of items available on a given account. The same applies to the technical quota (see).

In the diagram below, the items A-YELLOW-S, A-YELLOW-M and A-YELLOW-L are not shown to facilitate the reading

flowchart TD
    model_A(reference=A)
    model_color_red(reference_color=A-RED)
    model_color_yellow(reference_color=A-YELLOW)
    model_color_red_S(reference_color=A-RED-S)
    model_color_red_M(reference_color=A-RED-M)
    model_color_red_L(reference_color=A-RED-L)
    subgraph "Level 'Model' - index 1"
       model_A
    end
    subgraph "Level 'Model Color' - index 2"
       model_A --> model_color_red
       model_A --> model_color_yellow
    end
    subgraph "Level 'Model Color Size' - index 3"
       model_color_red --> model_color_red_S
       model_color_red --> model_color_red_M
       model_color_red --> model_color_red_L
    end

• As in the example below, the parent items "nest" the child items (of higher level).
• You cannot create or update an item associated with an index level higher than 1 without mentioning all its direct parents.
  • We call direct parents the set of items allowing to link an item of level N to the item of the same "cluster" of level 1. See example below.

In the example below, we indicate in red the direct parents of the item A-RED-M.

flowchart TD
    model_A(reference=A)
    model_color_red(reference_color=A-RED)
    model_color_yellow(reference_color=A-YELLOW)
    model_color_red_S(reference_color=A-RED-S)
    model_color_red_M(reference_color=A-RED-M)
    model_color_red_L(reference_color=A-RED-L)
    subgraph "Level 'Model' - index 1"
       model_A
    end
    subgraph "Level 'Model Color' - index 2"
       model_A --> model_color_red
       model_A --> model_color_yellow
    end
    subgraph "Level 'Model Color Size' - index 3"
       model_color_red --> model_color_red_S
       model_color_red --> model_color_red_M
       model_color_red --> model_color_red_L
    end
    classDef className fill:lightcoral,stroke-width:1px;
    class model_color_red_M,model_color_red,model_A className;

The following import allows to update the item A-RED-M without mentioning the items A-RED-S, A-RED-L, ...

<Table key="product">
    <Items>
        <Item partition="active">
            <Identifier key="reference">A</Identifier>
            <Classification key="typology">t-shirt</Classification>
            <Field key="title">T-Shirt à col rond</Field>
            <Item>
                <Identifier key="reference_color">A-RED</Identifier>
                <Field key="color">red</Field>
                <Item>
                    <Identifier key="sku">A-RED-M</Identifier>
                    <Identifier key="ean">3253632845671</Identifier>
                    <Field key="size">M</Field>
                </Item>
            </Item>
        </Item>
    </Items>
</Table>

• The import of a field, an identifier or a classification on a level that is not its own is ignored. A log will be added to the import execution report.
• An item has a single parent on the lower index.
• You can update the parent of an item.

flowchart TD
    start_process(Start)
    end_process(End)
    order_item_by_index["We consider the list ordered by increasing order of index of the items of the same 'cluster' to import"]
    select_higher_item["Selection of the first item in the list (with the lowest index)"]
    attempt_to_create_or_update["Attempt to create or update the item following the mechanism described above [1]"]
    is_create_or_update_a_success{Success?}
    is_there_any_item_left{Are there any items left to import?}
    child_item_wont_be_imported["The child items of this item will not be imported<br />The child items will be removed from the list of items to import<br />A log will be added to the import execution report"]
    start_process --> order_item_by_index
    order_item_by_index --> select_higher_item
    select_higher_item --> attempt_to_create_or_update
    attempt_to_create_or_update --> is_create_or_update_a_success
    is_create_or_update_a_success -.- yes_success[Yes] -.-> is_there_any_item_left
    is_there_any_item_left -.- yes_item_left[Yes] -.-> select_higher_item
    is_there_any_item_left -.- no_item_left[No] -.-> end_process
    is_create_or_update_a_success -.- no_item_success[No] -.-> child_item_wont_be_imported
    child_item_wont_be_imported --> is_there_any_item_left

• [1] See above the logic of creation and update of items

COMPOSITE field import

Composite field

The Composite field is in phase.

DANGER

Importing a COMPOSITE field is exhaustive:

• Any missing child field will result in its value being deleted.
• Any provided value will overwrite the entire COMPOSITE field, replacing all existing child field values.
• The order in which the values ​​are provided is preserved.

Example:

<Table key="PRODUCTS">
  <Items>
      <Item partition="ACTIVES">
            <Identifier key="EAN_13">3210987654321</Identifier>
            <Classification key="TYPOLOGY">CONNECTED_SCALES</Classification>
            <Field key="TITLE_EN">Body Black connected scale</Field>
            <Field key="PRICE" suffix="EURO">99</Field>
            <Field key="BATTERY">
                <Field key="BATTERY_TECHNOLOGY_CODE">ALKALINE</Field>
                <Field key="BATTERY_TYPE_CODE">AAA</Field>
                <Field key="BATTERY_QUANTITY">4</Field>
            </Field>
            <Field key="BLUETOOTH">
                 <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 4.0</Field>
            </Field>
            <Field key="BLUETOOTH">
                 <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 5.0</Field>
            </Field>
            <Field key="BLUETOOTH">
                 <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 6.0</Field>
            </Field>
      </Item>
  </Items>
</Table>

In the example above, we see that:

• the COMPOSITE field BATTERY is constituted by three field
• the COMPOSITE field BLUETOOTH is repeated three times with a distinct value in the child field ACCEPTED_BLUETOOTH_STANDARD

Partial COMPOSITE field value import

When a COMPOSITE field value is imported on an item, the whole field value is overridden by the new value.

1. First import

<Item partition="ACTIVE" level="PRODUCT">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BATTERY">
        <Field key="BATTERY_TECHNOLOGY_CODE">Li-ion</Field>
        <Field key="BATTERY_TYPE_CODE">AAA</Field>
    </Field>
</Item>

2. Second import

<Item partition="ACTIVE" level="PRODUCT">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BATTERY">
        <Field key="BATTERY_TECHNOLOGY_CODE">ALKALINE</Field>
    </Field>
</Item>

The final item is:

<Item partition="ACTIVE" level="PRODUCT">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BATTERY">
        <Field key="BATTERY_TECHNOLOGY_CODE">ALKALINE</Field>
    </Field>
</Item>

Only the last imported value of the COMPOSITE field remains on the item. The BATTERY_TYPE_CODE field value has been deleted.

Multi-value COMPOSITE field import

When a multi-value COMPOSITE field is imported on an item, all existing values are overridden by the new values. The order in which the values ​​are provided is preserved

<Item partition="ACTIVES">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BLUETOOTH">
        <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 4.0</Field>
    </Field>
    <Field key="BLUETOOTH">
        <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 5.0</Field>
    </Field>
    <Field key="BLUETOOTH">
        <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 6.0</Field>
    </Field>
</Item>

1. Second import

<Item partition="ACTIVES">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BLUETOOTH">
        <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 3.0</Field>
    </Field>
    <Field key="BLUETOOTH">
        <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 4.0</Field>
    </Field>
</Item>

The final item is:

<Item partition="ACTIVES">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BLUETOOTH">
        <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 3.0</Field>
    </Field>
    <Field key="BLUETOOTH">
        <Field key="ACCEPTED_BLUETOOTH_STANDARD">Bluetooth 4.0</Field>
    </Field>
</Item>

Only the last imported value of the COMPOSITE field remains on the item. The previous existing values on the ACCEPTED_BLUETOOTH_STANDARD fields have been deleted. And the new values are imported in the order they are provided.

COMPOSITE child field value deletion

To delete a single field value within a COMPOSITE field, you just have to not import that field. However, you need to reimport all other fields value of the COMPOSITE field otherwise their value will be deleted.

1. First import

<Item partition="ACTIVE" level="PRODUCT">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BATTERY">
        <Field key="BATTERY_TECHNOLOGY_CODE">ALKALINE</Field>
        <Field key="BATTERY_TYPE_CODE">AAA</Field>
    </Field>
</Item>

2. Second import

<Item partition="ACTIVE" level="PRODUCT">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BATTERY">
        <Field key="BATTERY_TECHNOLOGY_CODE">ALKALINE</Field>
    </Field>
</Item>

The final item is:

<Item partition="ACTIVE" level="PRODUCT">
    <Identifier key="EAN_13">3210987654321</Identifier>
    <Field key="BATTERY">
        <Field key="BATTERY_TECHNOLOGY_CODE">ALKALINE</Field>
    </Field>
</Item>

Only the last imported value of the COMPOSITE field remains on the item. The BATTERY_TYPE_CODE field value has been deleted.

More details about the formulas

WARNING

The formulas are calculated after each update of a table on all its items.

The formulas allow to act on:

• The content of a cell - for example via the SET_TEXT or REMOVE_VALUE action
• The behavior of the cell in the interface - for example via the SET_SELECTABLE_OPTIONS action, which limits the options available when editing

For this, the formulas are executed before any import or update of items and after any update of the table structure.

Key points

• Rules are all executed one after the other
  • If a list of options were to be limited more than once, the last proposed limitation would be retained. Two successive uses of the SET_SELECTABLE_OPTIONS action are not cumulative.
• If the execution of a template cannot be performed (in the case of a technical error in particular), the item in question is not imported. A log is added to the execution report. (ITEM_FORMULA_ERROR_ITEM_HAS_BEEN_IGNORED)
• If the execution of a template produces an empty value, we delete the value of the target identifier.
• As for the rules engine tool, the identifiers and fields archived targets of formula are ignored. The fomula is not interpreted on the archived identifiers and fields.
• As for the rules engine tool, in the context of the conditions, if a source field (or classification, identifier) is archived, its value is considered as empty.
• As for the rules engine, within a template, if a source field (or classification, or identifier) is archived, but has a value, we use this value anyway.

Detail regarding the calculation of the formulas

The formulas are recalculated during any edition of the item or any update of the table

WARNING

The formulas are calculated after each update of a table on all its items. This behavior is not active when only the feature flag related to the formula on identifiers is activated.

The formulas on an item are recalculated after any edition of it:

• At the end of an edit request from the grid
• When applying mapping rules
• When importing items
• When applying suggestions
• When importing the table

It is not necessary that all the sources of a formula are communicated for the recalculation to be done

Consider the example below:

The following item is present in the target table:

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">1</Identifier>
            <Field key="Compound identifier">REF1-SAMSUNG</Field>
            <Field key="Supplier reference">REF1</Field>
            <Field key="Supplier">SAMSUNG</Field>
        </Item>
    </Items>
</Table>

We consider that a formula exists on Compound identifier: Compound identifier = Supplier reference + Supplier.

The import of the following item...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">1</Identifier>
            <Field key="Supplier reference">REF2</Field>
        </Item>
    </Items>
</Table>

... results in the recalculation of the Compound identifier although the Supplier field is not communicated.

The result is as shown below:

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="EAN">1</Identifier>
            <Field key="Compound identifier">REF2-SAMSUNG</Field>
            <Field key="Supplier reference">REF2</Field>
            <Field key="Supplier">SAMSUNG</Field>
        </Item>
    </Items>
</Table>

Pseudo code of the algorithm of calculation of the formulas

For each item in items

    var levelIdentifiers = getLevelIdentifiers()
    var itemIdentifiersInXml = getItemIdentifiersFromXml()
    var itemFieldsInXml = getItemFieldsFromXml()
    var existingItem = retrieveItemInDb(itemIdentifiers)

    // Ordonné par identifier.index
    Pour chaque identifier dans levelIdentifiers 

        If identifier n'est pas composé continue

        var formulaApplied = false

        Pour chaque formulaRule dans identifier.formula.rules

            // fields avec l'attribut delete = true sont considérés vide
            If testConditions(formulaRule.conditions, itemFieldsXml) valides 
                formulaApplied = true
                itemIdentifiersXml[identifier] = executeAction(formulaRule.action) 
                break
    
        
        If identifier.formulas.length > 0 ET formulaApplied = false
            If existingItem
                // Concerne l'exemple avec l'attribut delete
                itemIdentifiersXml[identifier] delete attribute = true
            else
                // Voir Import d'un item proposant un identifier "calculé"
                itemIdentifiersXml[identifier] = null

    if existingItem != null 
        for each identifier in levelIdentifiers
            if itemIdentifiersXml[identifier] != null 
            and itemIdentifiersXml[identifier] = existingItem[identifier]
                add existingItem.id attribute to xml
                break

Examples

Example using the SET_SELECTABLE_OPTIONS action

If we consider the following formula on the SIZE field

<Formulas>
    <Field key="SIZE">
        <Rule priority="1" >
            <Conditions>
                <Condition-Group>
                    <Condition source="TYPOLOGY" operator="IN"> 
                        <Value>shoes</Value>
                    </Condition>
                </Condition-Group>
            </Conditions>
            <Action type="SET_SELECTABLE_OPTIONS">
                <Value>38</Value>
                <Value>39</Value>
                <Value>40</Value>
                <Value>41</Value>
                <Value>42</Value>
            </Action>
        </Rule>
        <Rule priority="2" >
            <Conditions>
                <Condition-Group>
                    <Condition source="TYPOLOGY" operator="IN"> 
                        <Value>t-shirt</Value>
                    </Condition>
                </Condition-Group>
            </Conditions>
            <Action type="SET_SELECTABLE_OPTIONS">
                <Value>S</Value>
                <Value>M</Value>
                <Value>L</Value>
                <Value>XL</Value>
            </Action>
        </Rule>
    </Identifier>
</Formulas>

<Item partition="active">
    <Identifier key="ref">A</Identifier>
    <Classification key="TYPOLOGY">dress</Classification> 
    <Field key="SIZE">42</Field>  <!-- Aucune rule n'est déclenchée, l'ensemble des options pour le field SIZE sont disponibles -->
</Item>

In the case below, option M is allowed and is flagged as consistent.

<Item partition="active">
    <Identifier key="ref">A</Identifier>
    <Classification key="TYPOLOGY">t-shirt</Classification> 
    <Field key="SIZE">M</Field>  <!-- Rule 2 is triggered and M corresponds to one of the expected values  -->
</Item>

In the case below, option 42 is not allowed and is "flagged" as inconsistent.

<Item partition="active">
    <Identifier key="ref">A</Identifier>
    <Classification key="TYPOLOGY">t-shirt</Classification>
    <Field key="SIZE">42</Field>  <!-- Rule 2 is triggered and 42 does not correspond to one of the expected values  -->
</Item>

Example using the SET_SELECTABLE_OPTIONS action - Inconsistent rules

If we consider the following formula on the SIZE field

<Formulas>
    <Field key="SIZE">
        <Rule priority="1" >
            <Conditions>
                <Condition-Group>
                    <Condition source="TYPOLOGY" operator="IN"> 
                        <Value>shoes</Value>
                    </Condition>
                </Condition-Group>
            </Conditions>
            <Action type="SET_SELECTABLE_OPTIONS">
                <Value>38</Value>
                <Value>39</Value>
                <Value>40</Value>
                <Value>41</Value>
                <Value>42</Value>
            </Action>
        </Rule>
        <Rule priority="2" >
            <Conditions>
                <Condition-Group>
                    <Condition source="TYPOLOGY" operator="IN"> 
                        <Value>shoes</Value>
                    </Condition>
                </Condition-Group>
            </Conditions>
            <Action type="SET_SELECTABLE_OPTIONS">
                <Value>38</Value>
                <Value>39</Value>  <!-- Ici certaines valeurs mentionnées dans le rule 1 ne sont pas présentes  -->
            </Action>
        </Rule>
    </Identifier>
</Formulas>

As for the previous examples, all the rules are executed, and the result of the last rule interpreted is retained The 42 option is therefore not allowed for the item below.

<Item partition="active">
    <Identifier key="ref">A</Identifier>
    <Classification key="TYPOLOGY">shoes</Classification> 
    <Field key="SIZE">42</Field> <!-- La rule 2 est déclenché et 42 ne correspond pas à l'une des valeurs attendues  -->
</Item>

Behavior for target identifiers of formulas

These fields cannot be edited manually

Identifiers that have a formula (see the table import task for details) cannot be edited manually:

• From the item import task
• Or from the application app.product-live.com

WARNING

If at the time of adding a formula on an identifier, some items already have a value on it, this value can be immediately deleted after importing the table.

Behavior for each "Data Type"

Identifiers

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Identifier key="sku">ASD-123-ZER</Identifier>
        </Item>
    </Items>
</Table>

• As mentioned above, an item must have at least one identifier to be imported.
• "White spaces" and line-terminating characters at the beginning and end of a field are not imported. See more details [below(#treatment-of-invisible-characters-before-importing-at-beginning-and-end-of-character-field)
• If after extracting the characters described above, the string to be imported is empty, it is not imported and any value already present in the item is not replaced or deleted
• If the identifier is archived, the values proposed during the import are still imported.

Classifications

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Classification key="taxonomy">apparel</Classification>
        </Item>
    </Items>
</Table>

• The "white spaces" as well as the line termination characters at the beginning and end of the field are not taken into account when evaluating the proposed option. The two examples below are equivalent. See more details below

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Classification key="taxonomy">
            
            apparel
            
               </Classification>
        </Item>
    </Items>
</Table>

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Classification key="taxonomy">apparel</Classification>
        </Item>
    </Items>
</Table>

• If a key for a proposed category is not valid (i.e. does not exist or is not available in the target table), this category is ignored.
• If there are several categories mentioned for the same field, the last one is imported.
• To delete a value, you just have to put the attribute delete = true (see deleting a value below) on the classification, it then deletes the category, if there was one of this classification.
• If the proposed category is archived, we still import the value proposed during the import.

#	Case	Expected result
1	When importing a new item - with a category on a classification (key=C) - this category does not exist	The category in question is not imported.
2	When updating an existing item I-1 - The "old" item has a value C-1 on the C classification - the "new" item includes the C-2 category for the C classification - the C-2 category exists	We replace the category of the previously saved item, by the category proposed in the imported item. I-1 has the category C-2 on C.
3	When updating an existing item I-1 - The "old" item has a value on the classification C, C-1 - The "new" item includes the category C-3<br/ >this category is archived	We import the proposed category, regardless of its status. I-1 has as category C-3 on C.
4	When updating an existing item I-1 - The "old" item has a value on the C classification, C-1 - the imported item includes the category C-X, C-X category does not exist on the C classification	In this case, we do not delete the option already present on C. I-1 has the category C-1 on V.

Field SINGLE-LINE-TEXT

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="title">Ipod</Field>
        </Item>
    </Items>
</Table>

• "White spaces" as well as line-terminating characters at the beginning and end of a field are not imported. See more details below
• If after extracting the characters described above, the string to be imported is empty, it is not imported and any value already present in the item is not replaced or deleted

Field LONG-TEXT

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="description">It's a revolution</Field>
        </Item>
    </Items>
</Table>

• "White spaces" as well as line-terminating characters at the beginning and end of a field are not imported. See more details below
• If after extracting the characters described above, the string to be imported is empty, it is not imported and any value already present in the item is not replaced or deleted

Field HTML-TEXT

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="descriptionFr">&lt;b&gt;Composition&lt;b&gt;&lt;ul&gt;&lt;li&gt;Cotton&lt;/li&gt;&lt;li&gt;Polyester&lt;/li&gt;&lt;/ul&gt;</Field>
        </Item>
    </Items>
</Table>

• "White spaces" as well as line-terminating characters at the beginning and end of a field are not imported. See more details below
• If after extracting the characters described above, the string to be imported is empty, it is not imported and any value already present in the item is not replaced or deleted
• HTML tags are imported without restriction

Field NUMBER

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="price">10.2</Field>
        </Item>
    </Items>
</Table>

• If the proposed value is not valid (see), this value is not imported and a possible value already present in the item is not replaced or deleted

Regarding NUMBER fields with suffixes

The suffix is mentioned as follows

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="cameraResolution" suffix="unece.unit.E38">100</Field>
        </Item>
    </Items>
</Table>

• If the property delete="true" is set
  • Then delete the value and the Suffix.
• If the number is invalid
  • Then nothing is applied
• If the number is absent
  • Then nothing is applied
• If the suffix is invalid
  • Then no number or suffix should be applied and a log is added to the execution report UNKNOWN_SUFFIX.
• If number is valid.
  • If the suffix is valid.
    • Then the number and the suffix are applied
  • If the suffix is absent.
    • If a default suffix is defined
      • Then the default number and suffix are applied
    • If no default suffix is defined
      • Then the number is applied, no suffix is applied
  • If the suffix is archived.
    • Then number and suffix are applied

Field SINGLE-SELECT

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="color">red</Field>
        </Item>
    </Items>
</Table>

• "White spaces" as well as line-terminating characters at the beginning and end of a field are not imported. See more details below

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="color">
                red     </Field>
        </Item>
    </Items>
</Table>

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="color">red</Field>
        </Item>
    </Items>
</Table>

• If a key for a proposed option is not valid (i.e. does not exist or is not available in the target table), this option is ignored.
• If there are several options mentioned for the same field, the last one is imported.
• To delete a value, just set the attribute delete = true (see deleting a value below) on the field, this will delete the option, if there was one for this field.
• If the proposed option is archived, we still import the value proposed during the import.

#	Case	Expected result
1	When importing a new item - with an option O-X on a SINGLE-SELECT key=F - this option does not exist	The option in question is not imported.
2	When updating an existing item I-1 - The "old" item has a value on the F field, O-1 - The "new" item includes the O-2 option for the F field	We replace the option of the previously saved item, by the option proposed in the "new" item. I-1 has as option O-2 on F.
3	When updating an existing item I-1 - The "old" item has a value on the F field, O-1 - The "new" item includes the O-3 option, this option is archived	We import the proposed option, regardless of its status. I-1 has the option O-3 on F.
4	When updating an existing item I-1 - The "old" item has a value on the F field, O-1 - The "new" item includes the O-X option, this option does not exist on the F field	In this case, we do not delete the option already present on F. I-1 has the option O-1 on F.

Field MULTIPLE-SELECT

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors">USB</Field>
            <Field key="connectors">HDMI</Field>
        </Item>
    </Items>
</Table>

• "White spaces" as well as line-terminating characters at the beginning and end of a field are not imported. See more details below

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connector">
                usb     </Field>
            <Field key="connector">
                hdmi</Field>
        </Item>
    </Items>
</Table>

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connector">usb</Field>
            <Field key="connector">hdmi</Field>
        </Item>
    </Items>
</Table>

• The fields are repeated for each selected option. The value of the element is the key of the option.
• If the same value occurs more than once, the value is imported once.
• If an update is requested on a field, all previously selected options for that item are replaced. The update is exhaustive, not incremental.
• As a reminder, as for the other field types, if a field is not mentioned when an item is updated, it is not modified.
• To delete all the values on a field, you just have to put the attribute delete = true (see deleting a value below) on one of its options, this will delete all the options of this field.
• If one of the proposed options is archived, we still import the value(s) proposed during the import.

Examples:

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" delete="true" />
        </Item>
    </Items>
</Table>

The special case below removes the set of values for the connectors option and then selects the USB option. **This usage is not recommended.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" delete="true" />
            <Field key="connectors">USB</Field>
        </Item>
    </Items>
</Table>

The final result of the above example is as below.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
        </Item>
    </Items>
</Table>

In summary:

#	Case	Expected result
1	When importing a new item - with two options O-1 and O-2 on the same MULTIPLE-SELECT key=F. - The options O-1 and O-2 exist on the field F	The two options O-1 and O-2 are imported. Result: I-1 has as option O-1 and O-2 on F
2	When importing a new item - with two options O-1 and O-2 on the same MULTIPLE-SELECT. - option O-1 is archived, the other is not	Both options are imported. Result: I-1 has option O-1 and O-2 on F.
3	When importing a new item - with two options O-1 and O-X on the same MULTIPLE-SELECT - O-X does not exist	Only the option whose key exists - O-1 - is imported. Result: I-1 has as option O-1 on F
4	When updating an item I-1 - The "old" item has option O-1 and O-2 on field F - The "new" item has only optin O-1 on F	We replace the set of options of the previously saved item with the set of options proposed in the "new"" item. Result: I-1' has option O-1' on F
5	When updating an item I-1 - The "old" item has option O-1 and O-2 on field F - The new item has only option O-3 on F, this option is archived	The set of options of the previously saved item is replaced by the set of options proposed in the imported item, regardless of their status. Result: I-1 has option O-3 on F
6	When updating an item I-1 - The "old" item has option O-1 and O-2 on field F - The new item has only option O-X on F, this option **does not exist on the F field	In this case, the options already present on F are not deleted. Result: I-1 has option O-1 et O-2 on F
7	When updating an item I-1 - The "old" item has option O-1 and O-2 on field F - The "new" item has option O-3 and O-X on F, O-X does not exist on the F field	In this case, the set of options of the previously saved item is replaced by the set of options that are present in the target field proposed in the "new"" item. Result: I-1 has option O-3 on F

Field MULTIPLE-SELECT-QUANTIFIED

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" quantity="3">USB</Field>
            <Field key="connectors" quantity="2">HDMI</Field>
        </Item>
    </Items>
</Table>

Important: The rules proposed above for MULTIPLE-SELECT fields apply to MULTIPLE-SELECT-QUANTIFIED fields

• The fields are repeated for each selected option. The value of the element is the key of the option.
• The quantity attribute is considered a number and follows the same integration rules as NUMBER fields (see above for details)
  • If the data proposed for the quantity attribute is not a valid number, the value is not imported and any value already present in the item is not replaced or deleted. However, the option concerned is imported.
  • In the same way, if the attribute quantity is not filled in, the value for quantity is simply not imported. We still import the option if it is valid. There is simply no quantity set for the connectors/HDMI field.
• If one of the proposed options is archived, we still import the value(s) proposed during the import.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" quantity="3">USB</Field>
            <Field key="connectors">HDMI</Field>
        </Item>
    </Items>
</Table>

Another example, if we consider the following item within a table:

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="title">PC</Field>
            <Field key="connectors" quantity="3">USB</Field>
            <Field key="connectors" quantity="1">HDMI</Field>
        </Item>
    </Items>
</Table>

The import of the item below...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors">HDMI</Field>
        </Item>
    </Items>
</Table>

...produces the item below in the table.

• connectors/USB disappears since it is not mentioned in the update (see above rules for importing multiple option lists)
• connectors/HDMI remains unchanged since the proposed quantity is not a valid number (in this case the quantity is empty)

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="title">PC</Field>
            <Field key="connectors" quantity="1">HDMI</Field>
        </Item>
    </Items>
</Table>

• To delete all the values on a field, set the attribute delete = true.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" delete="true" />
        </Item>
    </Items>
</Table>

Field MULTIPLE-SELECT-QUANTIFIED-WITH-COMMENTS

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" quantity="3" comment="1 USB-C et 2 USB-2">USB</Field>
            <Field key="connectors" quantity="2" comment="1 HDMI4.1 &gt; 1 HDMI2.0">HDMI</Field>
        </Item>
    </Items>
</Table>

Important: The rules proposed above for fields of type MULTIPLE-SELECT and MULTIPLE-SELECT-QUANTIFIED apply to fields of type MULTIPLE-SELECT-QUANTIFIED-WITH-COMMENTS

• as mentioned above for the MULTIPLE-SELECT-QUANTIFIED field, the quantity attribute is considered as a number and follows the same integration rules as NUMBER fields (see above for details)
  • If the data proposed for the quantity attribute is not a valid number, the value is not imported and any value already present in the item is not replaced or deleted. However, the option concerned is imported.
  • In the same way, if the attribute quantity is not filled in, the value for quantity is simply not imported. We still import the option if it is valid. There is simply no quantity filled in for the connectors/HDMI field.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" quantity="3" comment="1 USB-C et 2 USB-2">USB</Field>
            <Field key="connectors" comment="1 HDMI4.1 &gt; 1 HDMI2.0">HDMI</Field>
        </Item>
    </Items>
</Table>

• The comment attribute is considered a text field and follows the same integration rules as SINGLE-LINE-TEXT fields (see above for details)
  • An empty string is considered as valid and is imported as such
• If the data proposed for the comment attribute is not a valid string (or if no value is proposed), the value is not imported and a possible value already present in the item is not replaced or deleted. However, the option concerned is imported.
  • In the same way, if the comment attribute is not filled in, the value for comment is simply not imported. The option is still imported if it is valid. The example below is valid. There is simply no comment filled in for the connectors/HDMI field.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" quantity="3" comment="1 USB-C et 2 USB-2">USB</Field>
            <Field key="connectors" quantity="3">HDMI</Field>
        </Item>
    </Items>
</Table>

Another example, if we consider the following item within a table:

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="title">PC</Field>
            <Field key="connectors" quantity="3" comment="1 USB-C et 2 USB-2">USB</Field>
            <Field key="connectors" quantity="1" comment="1 HDMI4.1 &gt; 1 HDMI2.0">HDMI</Field>
        </Item>
    </Items>
</Table>

The import of the item below...

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" quantity="4">USB</Field>
            <Field key="connectors" comment="">HDMI</Field>
        </Item>
    </Items>
</Table>

...produces the item below in the table:

• the comment associated with connectors/USB remains unchanged since it is not proposed during the import
• the comment associated to connectors/HDMI is updated, the empty value being a valid value for a comment

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="title">PC</Field>
            <Field key="connectors" quantity="4" comment="1 USB-C et 2 USB-2">USB</Field>
            <Field key="connectors" quantity="1" comment="">HDMI</Field>
        </Item>
    </Items>
</Table>

• To delete all the values on a field, set the attribute delete = true.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="connectors" delete="true" />
        </Item>
    </Items>
</Table>

Field DATE

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="publication">2020-04-10</Field>
        </Item>
    </Items>
</Table>

• White spaces" and line-terminating characters at the beginning and end of a field are not interpreted when evaluating the proposed value. See more details below
• If the proposed format is not a valid date format see this document), the date is not imported and a log is added to the execution report.

Field DATE-TIME

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="publication">2020-04-10T13:40:23.83Z</Field>
        </Item>
    </Items>
</Table>

• White spaces" and line-terminating characters at the beginning and end of a field are not interpreted when evaluating the proposed value. See more details below
• If the proposed format is not a valid date format see this document), the date is not imported and a log is added to the execution report.

Field IMAGE

• White spaces" and line-terminating characters at the beginning and end of a field are not interpreted when evaluating the proposed value. See more details below

<Table key="products">
  <Items>
      <Item partition="active">
          <Identifier key="ean">1234567890123</Identifier>
          <Field key="image1" force-update="true">https://your-domain.com/valid-url-0.jpg</Field>
          <Field key="image2" file-key="33a64df551425fcc55e4d42a148795d9f25f89d4">https://your-domain.com/valid-url-1.jpg</Field>
          <Field key="image3" file-hash="a1d0c6e83f027327d8461063f4ac58a6">https://your-domain.com/valid-url-2.jpg</Field>
      </Item>
  </Items>
</Table>

• The expected value for a field of type IMAGE is a valid URL.
• The proposed URL must have the http or https protocol. The ftp protocol for example is not allowed.
• The proposed URL must fall into one of the following two categories:
  • being publicly accessible without an authentication mechanism
  • being an asset produced by the Product-Live platform (e.g. be the URL of an image on another item, or a URL produced by the Data Factory plateform)
• When updating an IMAGE field, several properties can be passed in to define the behavior of the import
  • force-update - This attribute can be set to true or false. If the value passed is true, then the platform will attempt to retrieve the file passed and replace any image already present on the target item
  • file-key - This attribute holds a value that will be attached to the imported image. It allows the user to precisely name an image, and thus avoid an image being re-downloaded if it has not been modified (see more details below)
  • file-hash - If the hash communicated in this attribute is identical to the hash of the image already present on the item, it will not be uploaded by the platform (nor assigned to the target item - see more details below). The hash is always computed by the platform, and cannot be communicated directly by the user. The generated hash is of type sha256
• original-file-name is also an attribute that can be communicated by the user. This value will be returned when the item is exported by the item export task

What is a valid image?

A valid image meets the following criteria:

• The formats supported by the platform are: JPEG, PNG, GIF and WebP
• Its size must be greater than 0
• Its size must be less than 20MB
• Its resolution must be less than the maximum resolution of 50MP (see here for more information)
• The image must be able to be opened, and the following metadata must be extracted:
  • The width of the image in pixels
  • The height of the image in pixels

As indicated below, an invalid image will not be imported.

Import process

The diagram below describes the algorithm for determining whether an image should be imported or not.

 flowchart TD
    start_import(Start)
    end_import(End)
    update_or_creation{Is this an<br /> update?}
    hash_force_update{force-update?}
    has_file_hash{file-hash?}
    hash_file_key{file-key?}
    file_is_ignored[The image is ignored]
    file_import[Attempt to import the image]
    get_etag[Attempt to recover the etag of the target image]
    is_eatag_the_same{Same etag?}
    start_import --> update_or_creation;
    update_or_creation -.-> |The item does <br />not have an image on the target field| file_import;
    update_or_creation -.-> |The item already has an image| hash_force_update
    hash_force_update -.-> |force-update=true| file_import
    hash_force_update -.-> |force-update=false or empty| has_file_hash
    has_file_hash -.-> |The file hash is empty <br />or is present but is different <br />from the one present in the item| hash_file_key
    hash_file_key -.-> |file-key is empty <br />or is present but is different from the one present in the item| get_etag
    get_etag -.-> is_eatag_the_same
    is_eatag_the_same -.-> |The etag is different <br />or could not be recovered| file_import
    is_eatag_the_same -.-> |The eTag information could be recovered <br />and is identical to the one already stored <br />on the item during the previous import| file_is_ignored
    hash_file_key -.-> |file-key is present<br />and is identical to the one <br />present within the item| file_is_ignored
    has_file_hash -.-> |The file hash is present <br />and is identical to the one present in the item| file_is_ignored
    file_is_ignored --> end_import
    file_import --> end_import

The diagram below describes the actual import of an image into an item.

flowchart TD
    start_import(Start)
    end_import(End)
    start_import --> download_image
    download_image[Download the image]
    get_metadata[Metadata retrieval]
    save_item[Saving the image in the item]
    end_image_import_error[End of the import of the image in error]
    end_image_import_success[End of the import of the image in success]
    download_error[The image cannot be imported.<br /> Error Code:<br /> IMAGE_URL_INCORRECT_OR_INACCESSIBLE]
    get_metadata_error[The image cannot be imported.<br /> Error code:<br /> IMAGE_UNABLE_TO_GET_METADATA]
    is_file_an_image_error[The proposed file is not a valid image.<br /> Error Code:<br /> IMAGE_INVALID_FORMAT<br />IMAGE_INVALID_SIZE<br />IMAGE_INVALID_RESOLUTION ]
    is_download_a_success{Success?}
    is_get_metadata_a_success{Success?}
    is_file_an_image{Valid image?}
    download_image --> is_download_a_success;
    is_download_a_success -.->  |The download is a success| get_metadata
    get_metadata --> is_get_metadata_a_success
    is_get_metadata_a_success -.-> |Metadata recovery is a success| is_file_an_image
    is_file_an_image -.-> |The imported file is a valid image| save_item
    save_item --> end_image_import_success
    is_download_a_success -.-> |Download failed| download_error
    is_get_metadata_a_success -.-> |Metadata recovery failed| get_metadata_error
    is_file_an_image -.-> |The imported file is not a valid image| is_file_an_image_error
    download_error --> end_image_import_error
    get_metadata_error --> end_image_import_error
    is_file_an_image_error --> end_image_import_error
    end_image_import_error --> end_import
    end_image_import_success --> end_import

Field ATTACHMENT

• White spaces" and line-terminating characters at the beginning and end of a field are not interpreted when evaluating the proposed value. See more details below

<Table key="products">
  <Items>
      <Item partition="active">
          <Identifier key="ean">1234567890123</Identifier>
          <Field key="file-1" force-update="true">https://your-domain.com/valid-url-0.pdf</Field>
          <Field key="file-2" file-key="33a64df551425fcc55e4d42a148795d9f25f89d4">https://your-domain.com/valid-url-1.pdf</Field>
          <Field key="file-3" file-hash="a1d0c6e83f027327d8461063f4ac58a6">https://your-domain.com/valid-url-2.pdf</Field>
      </Item>
  </Items>
</Table>

• The expected value for a field of type ATTACHMENT is a valid URL.
• The proposed URL must have the http or https protocol. The ftp protocol for example is not allowed.
• The proposed URL must fall into one of the following two categories:
  • being publicly accessible without an authentication mechanism
  • being an asset produced by the Product-Live platform (e.g. be the URL of an image on another item, or a URL produced by the Data Factory plateform)
• When updating an IMAGE field, several properties can be passed in to define the behavior of the import
  • force-update - This attribute can be set to true or false. If the value passed is true, then the platform will attempt to retrieve the file passed and replace any image already present on the target item
  • file-key - This attribute holds a value that will be attached to the imported image. It allows the user to precisely name an image, and thus avoid an image being re-downloaded if it has not been modified (see more details below)
  • file-hash - If the hash communicated in this attribute is identical to the hash of the image already present on the item, it will not be uploaded by the platform (nor assigned to the target item - see more details below). The hash is always computed by the platform, and cannot be communicated directly by the user. The generated hash is of type sha256
• original-file-name is also an attribute that can be communicated by the user. This value will be returned when the item is exported by the item export task

What is a valid file?

A valid file meets the following criteria:

• Its size must be greater than 0
• Its size must be less than the maximum size of 100MB (see here for more information)
• The file must be able to be opened

As shown below, an invalid file will not be imported.

Import process

The diagram below describes the algorithm for determining whether a file should be imported or not.

 flowchart TD
    start_import(Start)
    end_import(End)
    update_or_creation{Is this an<br /> update?}
    hash_force_update{force-update?}
    has_file_hash{file-hash?}
    hash_file_key{file-key?}
    file_is_ignored[The file is ignored]
    file_import[Attempt to import the file]
    get_etag[Attempt to recover the etag of the target file]
    file_metadata_update[The file metadata is updated]
    is_eatag_the_same{Same etag?}
    start_import --> update_or_creation;
    update_or_creation -.-> |The item does not have a file on the target field| file_import;
    update_or_creation -.-> |The item already has a file| hash_force_update
    hash_force_update -.-> |force-update=true| file_import
    hash_force_update -.-> |force-update=false ou vide| has_file_hash
    has_file_hash -.-> |The file hash is empty <br />or is present but is different <br />from the one present in the item| hash_file_key
    hash_file_key -.-> |file-key is empty <br />or is present but is different <br />from the one present in the item| get_etag
    get_etag -.-> is_eatag_the_same
    is_eatag_the_same -.-> |The etag is different <br />or could not be recovered| file_import
    is_eatag_the_same -.-> |The eTag information could be recovered <br />and is identical to the one already stored <br />on the item during the previous import| file_is_ignored
    hash_file_key -.-> |file-key is present <br />and is identical to the one present in the item| file_is_ignored
    has_file_hash -.-> |The file hash is present <br />and is identical to the one present in the item| is_metadata_the_same
    is_metadata_the_same{Same metadata?}
    is_metadata_the_same -.-> |The metadata could be retrieved <br />and are identical to the one already kept <br />on the item during the previous import| file_is_ignored
    is_metadata_the_same -.-> |Metadata is different <br />or could not be retrieved | file_metadata_update
    file_metadata_update --> end_import
    file_is_ignored --> end_import
    file_import --> end_import

The diagram below describes the actual import of an image into an item.

flowchart TD
    start_import(Start)
    end_import(End)
    start_import --> download_image
    download_image[Téléchargement du fichier]
    check_validity[Validation of the conformity of the file]
    save_item[Saving the file in the item]
    end_image_import_error[End of the import of the file in error<br /> The file is not imported]
    end_image_import_success[End of successful file import]
    download_error[The file cannot be imported.<br /> Error code: ATTACHMENT_URL_INCORRECT_OR_INACCESSIBLE]
    get_metadata_error[The file cannot be imported.<br /> Error code: ATTACHMENT_INVALID_SIZE]
    is_download_a_success{Success?}
    is_valid{Success?}
    download_image --> is_download_a_success;
    is_download_a_success -.->  |The download is a success| check_validity
    check_validity --> is_valid
    is_valid -.-> |The attachment is valid| save_item
    save_item --> end_image_import_success
    is_download_a_success -.-> |Download failed| download_error
    is_valid -.-> |The attachment is invalid| get_metadata_error
    download_error --> end_image_import_error
    get_metadata_error --> end_image_import_error
    end_image_import_error --> end_import
    end_image_import_success --> end_import

Processing of invisible characters before import at the beginning and end of a string

White spaces" as well as line termination characters at the beginning and end of a field are not imported. No matter what type of field it is.

"White spaces" are as described below. (Technical note: this is the list of characters described in the ECMA-262 specifications)

Unicode number	Name	Abbreviation
U+0009	CHARACTER TABULATION	<TAB>
U+000B	LINE TABULATION	<VT>
U+000C	FORM FEED (FF)	<FF>
U+0020	SPACE	<SP>
U+00A0	NO-BREAK SPACE	<NBSP>
U+FEFF	ZERO WIDTH NO-BREAK SPACE	<ZWNBSP>

The "line terminators" are as described below. (Technical note: this is the list of characters described in the ECMA-262 specifications)

Unicode number	Name	Abbreviation
U+000A	LINE FEED (LF)	<LF>
U+000D	CARRIAGE RETURN (CR)	<CR>
U+2028	LINE SEPARATOR	<LS>
U+2029	PARAGRAPH SEPARATOR	<PS>

The above characters are removed when they are present at the beginning and end of a string.

Examples:

• Deleting characters at the beginning and end of a string

example 1<SP><SP><SP> becomes example 1

• Retention of line breaks within a string

example 1
example 2<SP><SP><SP>

becomes

example 1
example 2

Deleting a value

It is the delete attribute ( set totrue) that allows to delete the value for the target field on a given item.

In this example we delete the value of the attribute titleEn for the product with the ean 1234567890123.

<Table key="products">
    <Items>
        <Item partition="active">
            <Identifier key="ean">1234567890123</Identifier>
            <Field key="titleEn" delete="true" />
        </Item>
    </Items>
</Table>

WARNING

Deleting the last available identifier on an item is not allowed and will not be taken into account during the import.

Deleting an item

The delete attribute (at true) allows to delete a target item.

In this example we delete the item whose ean identifier is 1234567890123 (if it exists on the active partition).

<Table key="products">
    <Items>
        <Item partition="active" delete="true">
            <Identifier key="ean">1234567890123</Identifier>
        </Item>
    </Items>
</Table>

DANGER

Deleting an item in this way is not recommended. The recommended usage is to use the table-delete-items task which performs an export of the items before attempting any deletions.

Details on the calculation of conditional formatting fields

• Any update on an item implies a complete recalculation of all the conditional formatting fields associated with it.

Details on the execution report

General notes

• The report follows the execution report standard structure.

Example

<Report task="table-import-items" start-at="2023-01-20T13:27:54.810Z" task-cid="..." job-cid="..." end-at="2023-01-20T13:28:51.414Z" duration-ms="56604">
    <Input name="request">https://.../items.xml</Input>
    <Log type="error" code="VALUE_DOES_NOT_EXISTS">
        <Metadata-Collection name="match">
            <Metadata name="identifierKey">sku</Metadata>
            <Metadata name="levelKey">product</Metadata>
        </Metadata-Collection>
        <Metadata name="name">Identifier</Metadata>
        <Metadata name="xpath">/Table/Items/Item[position()=1 and @partition="active"]</Metadata>
        <Message>Identifier does not exist for this combination. identifierKey: sku, levelKey: product</Message>
    </Log>
</Report>

Available logs

code	Message	Metadata	Type	Remarks
WRONG_IDENTIFIER	Identifier with key {key} does not exist on level	partitionKey, identifierKey, levelKey	error	The item is not imported
NO_IDENTIFIER	Identifier is missing. This item has been ignored	partitionKey	error	The item is not imported
IDENTIFIER_TOO_LONG	Identifier {identifiers[idKey].field.keyName} contains more than {Constants.ITEM_IDENTIFIER_MAX_LENGTH} characters	partitionKey	error	The item is not imported
IDENTIFIER_HAS_NO_VALUE	Missing value for identifier found with key {key} on level	partitionKey, key, levelKey	error	The item is not imported
IDENTIFIER_ALREADY_EXISTS	An item with identifier {identifier.keyName}: {item[identifier{identifier.typeIndex}]} already exists	partitionKey	error	The item is not imported
IDENTIFIER_HAS_NO_KEY	Identifier has no key attribute	partitionKey	error	The item is not imported
CATEGORY_UNKNOWN	Category invalid for key {field.keyName} on level	fieldKey, levelKey	warning
FIELD_UNKNOWN	No Field found with key {key} on level	levelKey, key	warning
CLASSIFICATION_HAS_NO_KEY	Classification has no key	partitionKey	warning
FIELD_HAS_NO_KEY	Field has no key	partitionKey	warning
OPTION_UNKNOWN	Value {fieldValueKey} is not a valid option		warning
ATTACHMENT_URL_INCORRECT_OR_INACCESSIBLE	Cannot upload file for {field.keyName}, url	fieldKey, url	warning
ATTACHMENT_INVALID_SIZE	File contains more than {Constants.MAX_ATTACHMENT_BYTES_SIZE} bytes		warning
ATTACHMENT_FILE_WAS_IGNORED_HASH_IS_THE_SAME	File was ignored file hash is the same as old value	fieldKey, levelKey	info
ATTACHMENT_FILE_WAS_IGNORED_FILE_KEY_IS_THE_SAME	File was ignored file key is the same as old value	fieldKey, levelKey	info
ATTACHMENT_FILE_WAS_IGNORED_ETAG_IS_THE_SAME	File was ignored etag is the same as old value	fieldKey, levelKey	info
ATTACHMENT_FILE_WAS_IGNORED_LAST_MODIFIED_DATE_IS_THE_SAME	File was ignored last modified is the same as old value	fieldKey, levelKey	info
IMAGE_URL_INCORRECT_OR_INACCESSIBLE	Cannot upload file for {field.keyName}, url	fieldKey, url	warning
IMAGE_UNABLE_TO_GET_METADATA	Cannot extract metadata for {field.keyName} [{err.message}]	fieldKey, error	warning
IMAGE_INVALID_SIZE	Image contains more than {Constants.MAX_IMAGE_BYTES_SIZE} bytes		warning
IMAGE_INVALID_RESOLUTION	Invalid image resolution. Height: {metadata.imageHeightPixel} x Width: {metadata.imageWidthPixel} greater than		warning
IMAGE_INVALID_FORMAT	Invalid image format. Found {(metadata as unknown as AttachmentMetadata).mimeType}, only {Constants.IMAGE_MIME_TYPE_ALLOWED.join(', ')} are allowed		warning
IMAGE_FILE_WAS_IGNORED_HASH_IS_THE_SAME	File was ignored file hash is the same as old value	fieldKey, levelKey	info
IMAGE_FILE_WAS_IGNORED_FILE_KEY_IS_THE_SAME	File was ignored file key is the same as old value	fieldKey, levelKey	info
IMAGE_FILE_WAS_IGNORED_ETAG_IS_THE_SAME	File was ignored etag is the same as old value	fieldKey, levelKey	info
IMAGE_FILE_WAS_IGNORED_LAST_MODIFIED_DATE_IS_THE_SAME	File was ignored last modified is the same as old value	fieldKey, levelKey	info
ITEM_ALREADY_EXIST_AND_WAS_IGNORED	The current item already exists and cannot be updated in create only mode		warning	mode is CREATE_ONLY and the item already exists
ITEM_DOES_NOT_EXIST_AND_WAS_IGNORED	The current item does not exist and cannot be created in update only mode		warning	mode is UPDATE_ONLY and the item does not exist
ITEM_IS_IDENTICAL_AND_HAS_NOT_BEEN_UPDATED	Item skipped because no change where detected		info
ITEM_MISSING_PARTITION	Partition is mandatory for item creation		error	The item is not imported
ITEM_UNKNOWN_PARTITION	Unknown partition	partitionKey, levelKey	error	The item is not imported
DATE_INVALID_VALUE	Date invalid for key {field.keyName} on level {field.level.keyName} ({datetime.invalidExplanation})	fieldKey, levelKey, reason, explanation	warning
NUMBER_INVALID_VALUE	Number invalid for key {field.keyName} on level	fieldKey, levelKey	warning
NO_LEVEL_AT_INDEX	There is no Level index	partitionKey, depth	error	The item is not imported
FORMULA_ERROR		partitionKey	error	The item is not imported
ITEM_PARENT_UPDATE_IS_NOT_ALLOWED	An item can only have one parent	levelKey, identifiers	error	The item is not imported
REFRESH_ITEM_FAILED	Item refresh encountered an unknown error	identifiers	error
TOO_MANY_ITEMS	The number of items to import is too high	numberOfItems, maxNumberOfItems	error	The items are not imported and the task end in error
UNKNOWN_ENTITY_IGNORED	An unknown entity (Identifier/Classification/Field) on the current item was ignored	key	warning	The item is imported but the unknown entity is ignored

Limitation

• The import of items is limited to 200 000 items per import.
  • This number may be adjusted on demand by creating a dedicated demand here
• At the end of the import, a link allowing to display the imported items is presented in app.product-live.com. For technical reasons, this link only allows you to select the first 500 imported items.