Skip to main content

Special SCM Fields

Overview​

This document covers the usage of special SCM fields in the SCM API.

Special SCM fields are used during data uploads and have pre-defined system functionalities such as:

  • Assign Codes to Products
  • Assign Logistic Units to codes
  • Assigning data to logistical units (LU's) which are themselves Scantrust codes
  • Activate Codes

Assign Products​

Products can also be assigned and changed through the upload API. The dedicated field for this is ‘product’.

The assigned value should be an existing product for the current company. The value can either be the product ID or the product SKU which both are unique within a company.

The assignment of products is often used when a work order has been made for a generic, fictive product and assigned to the real product when produced.

Example: A work order with code (extended_id= ‘0A705681370410MRP0410DAF47A8A7C’) has been created for my generic product (SKU=gen_1). I have now decided to assign this code to my real product that has just been produced (SKU=prod_1) I would also like this code to contain the production date and production line it was produced on.

SYNC POST Request body

{
	"data_key": "extended_id",
"items": [
{ "extended_id": "0A705681370410MRP0410DAF47A8A7C", "product": "prod_1", "production_date": "01/12/2016", "production_line": "13A"}, ….
	]
}

ASYNC POST Request body

{
  "constraints": {
    "extended_id": ["0A705681370410MRP0410DAF47A8A7C"]
  },
  "scm_data": {
    "product": "prod_1",
    "production_date": "01/12/2016",
    "production_line": "13A"
  }
}

WARNING: products usually belong to a campaign, for which the SCM fields are defined. So be careful that when changing a code to a product outside the current campaign, the campaign for that product (and code!) will change and so the rules for that other campaign are applied.

Assign Logistic Units​

A logistic unit (LU) is used to group codes onto certain units used for logistics. This offers a nesting mechanism where a child item (product) can belong to a parent (case, box, pallet etc.), for example: Product → Case → Pallet

Each Logistic Unit (LU) is defined as a normal SCM data-field in the system. This means a code will have the value for a LU set for an SCM field.

When assigning an LU, other SCM fields can also be set using this logistic unit as the key to upload. This greatly simplifies uploading data for cases and pallets of products.

Example:

A product with a code is part of a case which also has a scantrust label. The case code can then on turn be part of a pallet code. In this example ‘case’ and ‘pallet’ would be logistic units.

Pallets: (LU=pallet_code, production_date=2021-04-01)

  • p001

Cases: (LU=case_code, ship_date =2021-04-22)

  • Case: 123
  • Case: 456
  • Case: 789

Items:

  • Item: serial number=1a
  • Item: serial number=2a
  • Item: serial number=3a

SYNC POST Request body

{
  "data_key": "pallet_code",
  "items": [{ "pallet_code": "p001", "production_date": "2021-04-01" }]
}

The following example could be used to upload JUST the shipment date for one case (456):

{
  "data_key": "case_code",
  "items": [
    { "case_code": "123", "ship_date": "2021-04-22" },
    { "case_code": "456", "ship_date": "2021-04-22" },
    { "case_code": "789", "ship_date": "2021-04-22" }
  ]
}

ASYNC POST Request body

{
  "constraints": {
    "pallet_code": ["p001"]
  },
  "scm_data": {
    "production_date": "2021-04-01"
  }
}

The following example could be used to upload JUST the shipment date for 2 cases (123 & 456):

{
  "constraints": {
    "case_code": ["123", "456"]
  },
  "scm_data": {
    "ship_date": "2021-04-22"
  }
}

When this upload is done, Item 1a will have the following fields set:

  • Serial_number = 1a
  • Pallet_code = p001
  • Case_code = 789
  • Production_date = 2021-04-01
  • Ship_date = 2021-04-22

Assigning data to LU’s which are Scantrust codes​

In some cases, the LU’s to which codes have been linked, are themselves scantrust codes. This can happen for example when both the cases AND the items IN the case each have a Scantrust Code.

In this case, the programmer will have to make a decision if the parent-item should also be updated or not, and 2 calls should be made to the API to update the information, once for the parent-item to update its children, and once for the parent item itself.

Example:

Case: serial_number = 12345678:

  • Item 1: extended_id = HGDTQD54D5SD86EEDF1
  • Item 2: extended_id = HGDTQD54D5SD86EEDF2
  • Item 3: extended_id = HGDTQD54D5SD86EEDF3

SYNC POST Request body

// CALL 1:  update the CHILDREN of case_code:
{
 "data_key": "case_code",
 "items": [
 { "case_code": "12345678", "ship_date": "2021-04-22"} //set ship date on ALL codes in case
]
}

// CALL 2: now update the case
{
 "data_key": "serial_number",
 "items": [
 { "serial_number": "12345678", "ship_date": "2021-04-22"} //set ship date on the case
]
}

ASYNC POST Request body

// CALL 1:  update the CHILDREN of case_code:
{
    "constraints": {
        "case_code": ["12345678"]
    },
    "scm_data": {
		 "ship_date": "2021-04-22"
    }
}
// CALL 2: now update the case
{
    "constraints": {
        "serial_number": ["12345678"]
    },
    "scm_data": {
		 "ship_date": "2021-04-22"
    }
}

Activate Codes​

By default, codes are inactive on creation of the work order. The only exception is when the brand specifies the codes to be active upon completion of the work order. This happens on the work order create page in the Scantrust portal.

In most cases, codes will be activated when the scm production data is set.

  • The special key activation_status or status (legacy, will be overridden by the former if both provided) can be used for this purpose. (SYNC)
  • The special key activation_status is used for this purpose. (ASYNC)

activation_status can have 3 different values:

  • activation_status = 0 (marks the code inactive)
  • activation_status = 1 (marks the code active)
  • activation_status = 2 (marks the code blacklisted)

The status of codes can be updated through the SCM upload endpoint the same way as normal SCM data.

Example:

Items: (activation_status=1, product=P1)

  • Item 1: extended_id=HGDTQD54D5SD86EEDFS
  • Item 2: extended_id=AGDTQD54D5SD86EEDFX

SYNC POST Request body

{
  "data_key": "extended_id",
  "items": [
    { "extended_id": "HGDTQD54D5SD86EEDFS", "activation_status": "1", "product": "P1" },
    {
      "extended_id": "AGDTQD54D5SD86EEDFX",
      "activation_status": "1",
      "status": "0",
      "product": "P1"
    } // 1 will be assigned to the activation_status of this code, since the value of status will be overridden by the value of activation_status.
  ]
}

ASYNC POST Request body

{
  "constraints": {
    "extended_id": ["HGDTQD54D5SD86EEDFS", "AGDTQD54D5SD86EEDFX"]
  },
  "scm_data": {
    "activation_status": 1, // Activate this code
    "product": "P1"
  }
}

System Alerts​

Some SCM fields are used by the system to trigger alerts. Special rules apply to these fields in order for them to interact with the system.

keydescription
intended_marketThis field is used to trigger out_of_market alerts. The value must contain a ISO-2 country code (see here for the list of officially assigned codes) or a region key. Regions can be defined in the Scantrust Portal under “Regions” and contain a list of countries or custom region.
after_sell_byField used to trigger after_sell_by alerts. The value is a date defined by this specific format YYYY-MM-DD. Codes scanned after this date, will trigger the alert.
date_consumedDO NOT SET: This field should not be uploaded by any handler. When the field has been made available in the campaign settings, it will be set by the system automatically when a user marks a product code to be consumed, given that this Scantrust consumer setting has been enabled by the brand.