Import Items

Import items into a Product-Live table.

Json

Example

json

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

Definition

Property	Type	Required	Description
			The name (or type) of the task
			The unique name of the task in your job. It is used to reference this task in the workflow.
			The functional description of this task in your job.
			The type of the task. It must be `SUB_WORKFLOW`.
			`true`: the job continues if there is an error on this task. `false`: the job fails.
			Input parameters of the task. See below

Inputs

Property	Description
request	A valid input. See the complete definition below.
accountKey	Optional The account key of the partner required when importing items on a shared table. The account key can be found in Settings > Network > Partners.
mode	Optional Enum: `CREATE_OR_UPDATE` \| `UPDATE_ONLY` \| `CREATE_ONLY`. Default: `CREATE_OR_UPDATE`. `CREATE_OR_UPDATE` = if the item exist, it is updated, if not the item is created. `UPDATE_ONLY` if the item exist, it is updated, if not the item is not created. `CREATE_ONLY` if the item exist, it is not updated, if not the item is created.

Input request

Examples

Single levelMultiple levels

xml

<Table key="PRODUCTS">
  <Items>
      <Item partition="ACTIVES">
          <Identifier key="EAN_13">1234567890123</Identifier>
          <Classification key="TYPOLOGY">LAPTOPS</Classification>
          <Field key="TITLE_EN">Laptop 1</Field>
          <Field key="DESCRIPTION_EN">The new laptop</Field>
          <Field key="PRICE" suffix="EURO">1899.99</Field>
      </Item>
      <Item partition="ACTIVES">
          <Identifier key="EAN_13">1234567890124</Identifier>
          <Classification key="TYPOLOGY">LAPTOPS</Classification>
          <Field key="TITLE_EN">Laptop 2</Field>
          <Field key="DESCRIPTION_EN" delete="true"/>
      </Item>
  </Items>
</Table>

xml

<Table key="PRODUCTS">
  <Items>
      <Item partition="ACTIVES">
          <Identifier key="REFERENCE">00034</Identifier>
          <Classification key="TYPOLOGY">DRESS</Classification>
          <Field key="TITLE_EN">Black women's lapel collar button down dress</Field>
          <Item>
              <Identifier key="REFERENCE_COLOR">00034-RED</Identifier>
              <Field key="COLOR">RED</Field>
              <Field key="FRONT_IMAGE">https://your-domain.com/images/00034-red_front.jpg</Field>
              <Item>
                  <Identifier key="SKU">00034-RED-34</Identifier>
                  <Identifier key="EAN_13">1234567890123</Identifier>
                  <Field key="SIZE">34</Field>
                  <Field key="PRICE" suffix="EURO">19.9</Field>
                  <Field key="STOCK">320</Field>
              </Item>
              <Item>
                  <Identifier key="SKU">00034-RED-36</Identifier>
                  <Identifier key="EAN_13">1234567890124</Identifier>
                  <Field key="SIZE">36</Field>
                  <Field key="PRICE" suffix="EURO">19.9</Field>
                  <Field key="STOCK">218</Field>
              </Item>
          </Item>
          <Item>
              <Identifier key="REFERENCE_COLOR">00034-GREEN</Identifier>
              <Field key="COLOR">GREEN</Field>
              <Field key="FRONT_IMAGE">https://your-domain.com/images/00034-green_front.jpg</Field>
              <Item>
                  <Identifier key="SKU">00034-GREEN-34</Identifier>
                  <Identifier key="EAN_13">1234567890125</Identifier>
                  <Field key="SIZE">34</Field>
                  <Field key="PRICE" suffix="EURO">80.9</Field>
                  <Field key="STOCK">114</Field>
              </Item>
              <Item>
                  <Identifier key="SKU">00034-GREEN-36</Identifier>
                  <Identifier key="EAN_13">1234567890126</Identifier>
                  <Field key="SIZE">36</Field>
                  <Field key="PRICE" suffix="EURO">80.9</Field>
                  <Field key="STOCK">136</Field>
              </Item>
          </Item>        
      </Item>
  </Items>
</Table>

Definition

XPath	Description	Occurs
Table	Root of the document	1
Table/@key	The key of the table	1
./Items	The items element	0..1
./Items/Item	For each item	0..*
../Item/@partition	The partition key	1
../Item/Identifier	The Identifier value. At least one.	1..5
../Item/Identifier/@key	The Identifier key.	1
../Item/Classification	The category key.	0..5
../Item/Classification/@key	The Classification key.	1
../Item/Field	The Field value. Depending on the data type. See in examples	0..*
../Item/Field/@key	The Classification key.	1
../Item/Field/@delete	To delete a value.	1
../Item/Field/@quantity	For Field with type MULTIPLE-SELECT-QUANTIFIED \| MULTIPLE-SELECT-QUANTIFIED-WITH-COMMENTS the quantity.	0..1
../Item/Field/@comment	For Field with type MULTIPLE-SELECT-QUANTIFIED-WITH-COMMENTS the comments.	0..1
../Item/Field/@suffix	For Field with type NUMBER, the unit.	0..1
../Item/Field/@file-key	For Field with type IMAGE \| ATTACHMENT. Use this attribute to store the MD5 or the ETag of the file. Therefore if you import the same file twice, then it will be downloaded once. This does a huge difference for imports with a lot of files.	0..1
../Item/Field/@file-hash	For Field with type IMAGE \| ATTACHMENT. This is the file id in Product-Live, this field is used when items are exported from Product-Live and then imported again. If both file-key and file-hash are filled, then file-key is ignored. If none of these values are filled, the file will be downloaded. Always try to use one of these values.	0..1
../Item/Item	If you have combined items with multiple-levels. See examples for other elements.	0..*

Classifications or Fields with type `SINGLE-SELECT`

xml

<Table key="PRODUCTS">
    <Items>
        <Item partition="ACTIVES">
            <Identifier key="ean">1234567890123</Identifier>
            <Classification key="TYPOLOGY">PHONES</Classification>
            <Field key="COLOR">RED</Field>
        </Item>
    </Items>
</Table>

For Classification the value is the key of the Category.
For Fields with type SINGLE-SELECT, the value is the key of Option.
Remember that only one category is allowed by Classification, but you can create up to 5 Classifications.

Fields with type `MULTIPLE-SELECT`

xml

<Table key="PRODUCTS">
    <Items>
        <Item partition="ACTIVES">
            <Identifier key="ean">1234567890123</Identifier>
            <!--
              Duplicates the lines for each options.
              The value is the key of the option.
            -->
            <Field key="CONNECTORS">USB</Field>
            <Field key="CONNECTORS">HDMI</Field>
            <!--
                For MULTIPLE-SELECT-QUANTIFIED
            -->
            <Field key="CONNECTORS_QUANTIFIED" quantity="2">USB</Field>
            <Field key="CONNECTORS_QUANTIFIED" quantity="3">HDMI</Field>
            <!--
                For MULTIPLE-SELECT-QUANTIFIED-WITH-COMMENTS
            -->
            <Field key="CONNECTORS_QUANTIFIED_WITH_COMMENTS" quantity="2" comment="1 USB-C and 1 USB 2.0">USB</Field>
            <Field key="CONNECTORS_QUANTIFIED_WITH_COMMENTS" quantity="3" comment="3 HDMI 3.1">HDMI</Field>
        </Item>
    </Items>
</Table>

Fields with type `NUMBER`

xml

<Table key="PRODUCTS">
    <Items>
        <Item partition="ACTIVES">
            <Identifier key="ean">1234567890123</Identifier>
            <!-- The separator is . -->
            <Field key="PRICE" suffix="EURO">12.9</Field>
        </Item>
    </Items>
</Table>

To import a number with a unit on a field, the value must be a valid number, and the suffix key must exist on the field. Otherwise neither the value nor the unit are imported.

If no unit is provided and a default unit is set on the field, that default unit is applied on the item's field.

Fields with type `DATE` | `DATE-TIME`

Format used is ISO8601.

xml

<Table key="PRODUCTS">
    <Items>
        <Item partition="ACTIVES">
            <Identifier key="ean">1234567890123</Identifier>
            <!-- Field with type DATE-TIME : Z means UTC-->
            <Field key="publication">2020-04-10T13:40:23.830Z</Field>
            <!-- Field with type DATE -->
            <Field key="publication">2020-04-10</Field>
        </Item>
    </Items>
</Table>

Fields with type `IMAGE` | `ATTACHMENT`

xml

<Table key="PRODUCTS">
    <Items>
        <Item partition="ACTIVES">
            <Identifier key="ean">1234567890123</Identifier>
            <!--
                The value must be a valid url
                accessible without authentication.
                In this case example, the file will be downloaded
                for each import, this is not the best practice.
            -->
            <Field key="image1">https://your-domain.com/valid-url-0.jpg</Field>
            <!--
                In this example the file-key is the ETag
                of the file on your server. Therefore if this file is imported
                several times, it will be downloaded once.
                This this is the best pratice when importing files
                from your servers.
            -->
            <Field key="image2" file-key="33a64df551425fcc55e4d42a148795d9f25f89d4">https://your-domain.com/valid-url-1.jpg</Field>
            <!--
                In this example the file-hash property
                reference the id of the file in Product-Live.
                Therefore if you export this file, and then import
                it again, it will not be downloaded twice.
                This is the best practice when exporting and then
                importing items in Product-Live.
            -->
            <Field key="image3" file-hash="a1d0c6e83f027327d8461063f4ac58a6">https://pl.com/valid-url-2.jpg</Field>
        </Item>
    </Items>
</Table>

Scope	`IMAGE`	`ATTACHMENT`
url	The url must be public e.g. without authentication	The url must be public e.g. without authentication
Maximum file size	20 Mb	2 Gb
Maximum resolution	36 Mp	Not applicable
Valid file formats	`JPEG`, `PNG`, `GIF`, `WebP`	All

(Note: the maximum upload time is set to 1 minute, so depending on the connection speed, the maximum size may vary)

Outputs

Property	Type	Description
report		Report on the integration. View below for more details.
createdItemsCount		Count items created .
updatedItemsCount		Count items updated.

Output report

Example

xml

<Report task="table-import-items" date="2013-04-01T17:13:41.000Z" action-id="6011339103483173319a1614"> 
    <Input name="request"></Input>
    <Input name="accountKey"></Input>
    <Input name="mode"></Input>
    <Log type="info">
        <Metadata name="xpath"></Metadata>
        <Metadata name="code"></Metadata>
        <Metadata name="table-key"></Metadata>
        <Metadata name="partition-key"></Metadata>
        <Metadata-Collection name="identifier">
            <Metadata name="EAN"></Metadata>
            <Metadata name="SKU"></Metadata>
        </Metadata-Collection>
        <Message>
            The following item was not imported. It was already existing in the table "products":
            SKU: 00034-red-34
            EAN: 1234567890123
        </Message>
    </Log>
</Report>

XPath	Description	Occurrence
/Report@task	Task name	1
/Report/Input	Inputs used in the task	1..*
/Report/Log	For each log	0..*
/Report/ Log @type	Enum: error, warning or info	1
/Report/ Log / Metadata-Collection	Metadata collection	0..*
/Report/ Log / Metadata-Collection@name	Metadata collection name	1
/Report/ Log / Metadata	Metadata	0..*
/Report/ Log / Metadata@name	Metadata name	1
/Report/ Log /Message	Message	1

Limits and additional notes

The limitation of the input file size is 2 Gb

Even if there is a limite you can encounter errors on your files. This is because your generated file can be very different that the ones we used for our tests.

Best practice: never send empty data and use differential import to only import data that have been modified.

FAQ

Does an empty value delete the value?

No, empty values are ignored.

What happen if there is more elements or more attributes?

They are ignored without warnings. If you export items there will be more attributes in the export files than in input expected. These attributes will be ignored.

Import Items ​

Json ​

Example ​

Definition ​

Inputs ​

Input request ​

Examples ​

Definition ​

Classifications or Fields with type SINGLE-SELECT ​

Fields with type MULTIPLE-SELECT ​

Fields with type NUMBER ​

Fields with type DATE | DATE-TIME ​

Fields with type IMAGE | ATTACHMENT ​

Outputs ​

Output report ​

Example ​

Limits and additional notes ​

FAQ ​

Does an empty value delete the value? ​

What happen if there is more elements or more attributes? ​

Import Items

Json

Example

Definition

Inputs

Input request

Examples

Definition

Classifications or Fields with type `SINGLE-SELECT`

Fields with type `MULTIPLE-SELECT`

Fields with type `NUMBER`

Fields with type `DATE` | `DATE-TIME`

Fields with type `IMAGE` | `ATTACHMENT`

Outputs

Output report

Example

Limits and additional notes

FAQ

Does an empty value delete the value?

What happen if there is more elements or more attributes?