Upload SCM Data (SYNC)

Overview

This document covers the process of uploading SCM data to the Scantrust API synchronously.

WARNING: updating large volumes of codes synchronously can lead to timeouts. This can be prevented by uploading data asynchronously, see section Upload SCM Data (ASYNC)

To upload SCM data from your server, the belwo components need to be configured:

• Upload handler: This handler formats the data, pre-validates and uploads the data
• API Endpoint: the Scantrust API will accepts a batch of records and process the changes

UAT token permissions

The UAT token needs to have access to the following permissions:

• codes_view
• scm_bulk_edit
• scm_code_edit
• product_view

The UAT token must be set in the header fields of all requests as described in Authentication & Tokens.

Prerequisites

There are 3 main prerequisites to fulfill:

1. Brand owner/SCM User account on the Scantrust portal:

   • Scantrust will provide a developer test-account as well as a production account.

2. A campaign that is setup to include the desired SCM fields:

   • Example: production_date, intended_market, rfid,..
   • Note: SCM fields not included in the campaign will be discarded by the system.

3. A work order for a product that is included in the campaign, and which has valid codes to be updated.

Data key

In order to upload information for a code, a data key must be chosen to select the desired codes to upload data for.

There are 3 ways to determine a key:

1. By default this key will be extended_id (the unique message each code holds).

2. The key can also be set to serial_number if they are set on the codes.

3. SCM data can also be used as a key:

   • Codes with RFID tags can be uploaded by key ‘rfid’ and value of each tag.
   • Codes with a Logistic Unit can be updated based on the unit.

Date Format

• The Scantrust API uses ISO-formatted dates. The format for SCM fields of type “Date” should be be YYYY-MM-DD.
• If you wish to store date data in other formats, please use the text type.
• All data is accepted and saved as provided by the uploader. In the case of fields of type "date" this can result in display & editing issues in the portal.

Upload Handler

The upload handler will communicate with the API endpoint, handle the data to be uploaded, and processes the response from the server.

Workflow:

1. Pre-validate data to be uploaded
2. Format data to be uploaded to the specified JSON structure
3. Upload JSON data to the API
4. Process the response

Pre-Validation of uploaded file

It is recommended to pre-validate the data to be uploaded. This prevents unnecessary calls to the API.

Following pre-validation should be done:

1. Format Checking:

   • Verify the data contains either 'extended_id' or the desired for 'data_key'.
   • Verify that all items have the same # of fields.

2. Preliminary Error Checking:

   • Verify that no key value is duplicated.
   • Verify that no key value is blank.

Format data to be uploaded

Data must be uploaded using JSON as the format. The API will accept batches of items not larger than 100 per call. Therefore the data must be split into batches of max 100 items per POST. It is recommended to keep a log file containing the keys/batch # of previously uploaded items so they can be skipped when uploading. This prevents items from getting uploaded twice if the API intercepts a defective item in a specific batch.

General flow

1. Process the data and create an array of JSON objects
2. Create batches of 100 rows
3. Ignore previously uploaded rows
4. Convert all values to strings
5. Send request
6. Send a request and save the key value as 'uploaded' in a logfile:
   • Subsequent runs should ignore all keys that are in the 'uploaded' file

Upload the data

A POST request containing the formatted data of max 100 items is made to the /api/v2/scm/upload/ endpoint. This POST request should contain the UAT obtained from the API.

The UAT is sent in the request header as follows:

(headers = { "Authorization": "UAT " + token })

API Design

POST: /api/v2/scm/upload/

Uploads SCM data regarding any code owned by the company, in a batch of up to 100 records per request. Multiple requests can be made to update more items.

Attribute	Required?	Description
data_key	Optional	Select which SCM data field to use as the KEY field when updating a record. Key must be present in the code. Match will be CASE SENSITIVE and EXACT. Example uses: - Use the rfid SCM field as the key - Use the case_number SCM field as the key Default: "extended_id"
items	required	List of scm data in key/value pairs, to upload to individual codes. Each key needs to reference the key of the SCM field as defined the campaign. The names of the keys can be confirmed by downloading the template.csv file from the SCM T&T tab for the campaign.

Body Parameters POST (application/json):

{
	"data_key": "extended_id",
"items": [
{ "extended_id": "HGDTQD54D5SD86EEDFS", "intended_market": "cn", ...},
	{ "extended_id": "JF5FPO58DFITE4EDXD2", "intended_market": "de", ... },
	...
	]
}

Response (200): Status OK

When a batch of max 100 codes is successfully posted, a response with affected and posted codes will be given.

{
  "total_updates": 0,
  "changes": [
    {
      "test_text": "hhh",
      "test_case": "5412166701007",
      "test_boolean": "true"
    }
  ],
  "items": {
    "HGDTQD54D5SD86EEDFS": ["scm_data", "more_data", "data3"],
    "JF5FPO58DFITE4EDXD2": ["scm_data"],
    "JF5FPO58DFITE4EDXD2": ["scm_data"]
  },
  "codes_affected": 1
}

Note: in "items", "scm_data" will only list the affected field key names, not the values.

Response (400) : Invalid Data Format

An exception will be raised (with an appropriate error message) when any of the following is detected in a row:

• No key field is found, or a key is empty
• Key field not found (e.g. extended_id was wrong)
• Data format of the "items" dictionary was incorrect
• Batch was too large: items exceeded the maximum of 100 records in one request
• SCM field length <=50 characters

Example:

Invalid extended_id

{
  "errors": [
    {
      "message": "Invalid value passed for extended_id: '2AFEDB9A420410MRP041044F47CE86E'",
      "line": "1",
      "field": "extended_id",
      "key_value": "2AFEDB9A420410MRP041044F47CE86E"
    }
  ]
}

Invalid product

{
  "errors": [
    {
      "message": "Invalid Product",
      "line": "1",
      "field": "product",
      "key_value": "2AFEDB9A420410MRP041044F47CE86E"
    }
  ]
}

Special Cases

Special SCM fields can be used to alter the code and internal functions (assign a product, activation status, LU assignment, ...)

See docs: Special SCM Fields