Mapper (Feed Import)

The mapper is the module used to import catalog data into laets PIM. This tool allows to import products, offers, variations. The data can be uploaded by file or can be downloaded over http(s). Feeds must be either a CSV file or a Google Spreadsheet.


Prequisites

Knowledge about the marketplace application configuration:

Note :

All those API requests must be done sequentially (waiting for the request result before sending the next one).

Note :

The structure of the catalog source file must be fixed. If there is one change or more (one new column for example), all the following requests must be done again.


Mapper creation

  
  POST {{api_url}}/v1/mapper_configuration/

with the body:

  
  {
  "name": "Feed Products Test Collection Seller Integration",
  "application": "/v1/application/{{APPLICATION_ID}}/",
  "izberg_entity": "product_and_offer",
  "language": "de",
  "method": "http",
  "options": {
      "url": "http://feedsourceurl.com"
  },
  "merchant": "/v1/merchant/{{MERCHANT_ID}}/"
  }

where

  • name: the name of the mapper configuration object.
  • {{APPLICATION_ID}}: the application identifier.
  • izberg_entity: the type of import (can be product, offer, product_and_offer).
  • method: protocol to fetch the source feed (http, ftp).
  • options->url: the url address of the feed source.
  • {{MERCHANT_ID}}: the merchant identifier.

Note :

Be sure that your feed source is well structured since the beginning of the operation because the mapper will use it to initialize the configuration.

The following examples are available in the postman collection:

  • Mapper creation and update (“01. Mapper” -> “Sample Workflow Creation & Update”)
  • Mapper update only (“01. Mapper” -> “Sample Workflow Update Only”)


Mapper initialization and configuration

The 3 following steps (and associated requests) describe how to initialize and configure the mapper:


Step 1: Mapper initialization
  
  POST {{api_url}}/v1/mapper_configuration/{{MAPPER_CONFIGURATION_ID}}/initialize/

with the body:

  
  {
  "parser_method":"csv"
  }

where:

  • parser_method: protocol used to fetch the source feed (csv, xml, json, googlesheet)

Sample Response:

  
  {
  "abortion_threshold_override": null,
  "application": {
      "id": 658,
      "pk": 658,
      "resource_uri": "https://api.sandbox.iceberg.technology/v1/application/658/"
  },
  "cache_version": 0,
  "can_create": true,
  "can_update": true,
  "create_parsing_report": true,
  "created_on": "2018-01-03T15:20:51+01:00",
  "encoding": null,
  "every": 0,
  "fields": [],
  "id": 4989,
  "is_processing": false,
  "izberg_entity": "product_and_offer",
  "language": "fr",
  "last_automatic_run_date": null,
  "last_modified": "2018-01-03T15:22:43+01:00",
  "last_transformation_log": null,
  "mapper": {
      "id": 4987,
      "pk": 4987,
      "resource_uri": "https://api.sandbox.iceberg.technology/v1/mapper_mapper/4987/"
  },
  "matcher": {
      "id": 4969,
      "pk": 4969,
      "resource_uri": "https://api.sandbox.iceberg.technology/v1/mapper_matcher/4969/"
  },
  "merchant": {
      "id": 12719,
      "pk": 12719,
      "resource_uri": "https://api.sandbox.iceberg.technology/v1/merchant/12719/"
  },
  "meta": {},
  "method": "http",
  "name": "Feed Products Test Collection Seller Integration",
  "next_automatic_run_date": null,
  "options": {
      "url": "http://feedsourceurl.com"
  },
  "parser": {
      "application": {
          "id": 658,
          "pk": 658,
          "resource_uri": "https://api.sandbox.iceberg.technology/v1/application/658/"
      },
      "created_on": "2018-01-03T15:22:43+01:00",
      "id": 4804,
      "merchant": {
          "id": 12719,
          "pk": 12719,
          "resource_uri": "https://api.sandbox.iceberg.technology/v1/merchant/03034/"
      },
      "method": "csv",
      "options": {},
      "resource_uri": "https://api.sandbox.iceberg.technology/v1/mapper_parser/4804/"
  },
  "parsing_report_format": "yaml",
  "period": "days",
  "report_email_addresses": null,
  "resource_uri": "https://api.sandbox.iceberg.technology/v1/mapper_configuration/4989/",
  "save_content": true,
  "status": "active",
  "user": "test_user"
  }

Note :

The {{MATCHER_ID}} will be useful for the matching configuration.


Step 2: Mapper mapping configuration

This step will auto-map all the fields from your feed if they have the exact same syntax as the fields in the laets API/Flat-File.

  
  POST {{api_url}}/v1/mapper_configuration/{{MAPPER_CONFIGURATION_ID}}/auto_mapping/

with an empty body.


Step 3: Mapper matching configuration

This step allows you to add some configuration on the matcher object. The matcher is an object from the mapper configuration that drives the matching of the different attribute values. For example you can disable the matching for the application_categories, as you already pulled the categories ids in section 2 PIM Categories and Attributes:

  
  POST {{api_url}}/v1/mapper_matcher/{{MAPPER_MATCHER_ID}}/

with the body:

  
  {
    "disable_matching":["application_categories", "language", "condition"]
  }

where:

  • {{MAPPER_MATCHER_ID}}: the identifier of the matcher (returned in the initialize POST call, or simply by making a GET call on the mapper configuration object).
  • disable_matching: the list of attributes needing a specific value for which you wish do disable the matching, as you probably already pulled the correct values.

Note :

If an attribute is specified in the disable_matching list, the mapper will wait for the exact value in the source feed. The recommendation is to list all the attributes needing specific value in the disable_matching list.


Launch the Mapper

  
  POST {{api_url}}/v1/mapper_configuration/{{MAPPER_CONFIGURATION_ID}}/run/

with an empty body.

Note :

The launch of the mapper is asynchronous. The mapper monitoring section will be used to check the status of the launch.


Mapper monitoring

Each time the mapper is launched, an import history is created. The corresponding API ressource is called a /v1/mapper_transformation_log/. The resource imports mapper_transformation_log can be fetched to verify:

  • The status of the mapper (parsing, importing, running).
  • The number of imported items, warnings and error.

The following request allows to list the different mapper_transformation_log:

  
  GET {{api_url}}/v1/mapper_transformation_log/?configuration={{MAPPER_CONFIGURATION_ID}}&limit=10&offset=0

To obtain the details of a given mapper_transformation_log (especially if error or warning happened):

  
  GET {{api_url}}/v1/mapper_transformation_log_detail/?transformation_log ={{MAPPER_TRANSFORMATION_LOG_ID}}&limit=10&offset=0


Mapper Samples

The Postman collection contains 2 samples to describe how to implement mapper integration with the:

  • Standard mode 
  • Update only mode