top of page

Targets

This section describes the various endpoints to be used for exchanging target variable data between the client’s infrastructure and Trax.

About the target data exchange in general

Trax’ Targets infrastructure can only be used for Trax projects relying on Flex KPIs.

 

KPIs are organised at Trax’ end into Variable Groups.

  1. A Variable Group contains KPIs requiring the same target variable data, eg.
    Variable Group: OSA Main Shelf
    KPIs added to it: OSA Main Shelf, OSA Main Shelf SKU
    Target data: stores, assortment, validity date range .

  2. The available variable groups can vary from project to project and will be provided by Trax.

 

Trax’ Targets API allows a bi-directional exchange of targets variable data between the client’s and Trax’ infrastructure by using Excel or CSV files.

This means in particular the following:

  1. When adding new or updating existing targets data, these need to be added to an Excel or CSV document which has to be sent in the POST requests (see below).

  2. In case an uploaded file fails the validation, the full list of errors is provided by Trax’ response in an Excel file.

  3. The target data already added to our database will also be provided by Trax’ response in an Excel file.

 

The targets data added to the Excel/CSV file should rely on the Trax standard attributes. The basic rules here are:

  1. The header row should contain the attribute names in Trax standard format by default - while the subsequent rows should represent the targets data records by having values for the attributes provided in the header.

  2. Minimal requirement for the file: it needs to contain at least 1 key, 1 data attribute and a start date.

  3. The available attributes/file templates can be provided by Trax.

  4. The target data provided in an excel file are to be associated with a variable group containing the KPIs to be applied to.

  5. Rules for the target CSV file:

    1. Data should be separated by commas.

    2. Date formnat: MM/DD/YYYY

    3. Example:
      store_type,product_ean_code,start_date
      SuperMarket,3574661148458,12/01/2022

  6. Example for an assortment target Excel file:​




     

  7. Important limitations:

    1. The API is able to process files with max. 400K rows.

    2. If contractually agreed on a daily target file update including all targets data, please make sure to send the same date as start and end date.

Upload An Excel File With Target Data To Multiple KPIs (Batch)

Get The Data Of An Uploaded File By ID

Available endpoints

Get Errors Of An Uploaded File In Excel

Update A File Upload (Replace The File or Change the Variable Group)

Get The Data Of All Uploaded Files

Download The Target Data In An Excel

Upload An Excel or CSV File With Targets Data

Finalize Upload (commit data to the database)

GET

  • Aim: To enable Clients to retrieve an uploaded targets data file (source file) with all available data (source file, metadata, status etc.) from Trax

  • Use Case: To check the previously uploaded file status to make sure that the uploaded file was valid and - if requested - successfully added to the database.

Response Example - JSON

{

        "name": "osamain_new_targets.xlsx",

        "variable_group_id": 42,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-11T12:43:48.970000",

        "status": "Failed",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",

        "updated_time": "2022-08-11T12:43:48.970000",

        "id": "62f4f1dd68bcdd097cca1938",

        "updated_by": null,

        "errors": [

            {

                "location": "A42",

                "value": "HyperMarket",

                "error": "Invalid store_type value(s)"

            }

            {

                "location": "B45",

                "value": "394398234234",

                "error": "Invalid product_ean_code value(s)"

            } ],

        "warning": [],

        "variable_group_name": "OSA - Main Shelf"

  }

Upload By ID

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

upload_id string *

Unique identifier of the file upload​

Supported Protocol: HTTPS

GET /targets/api/:version_number/projects/:project_name/uploads/details/:upload_id

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/my-project/uploads/details/62f4f1dd68bcdd097cca1938

Response Details

The response body will contain the following data:

name string 

Name and extension of the uploaded file.

 

variable_group_id string 

Unique identifier of the variable group the file has been associated with.

 

created_by string

Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user​​

 

creation_time date_time 

Timestamp of the file upload​

 

status enum 

Current status of the file upload, options:

Queued - initial status upon upload

Validation in progress - The uploaded file is being validated

Validated - The uploaded file has passed the validation

Failed - The uploaded file failed the validation

Committed - The uploaded file's data have been committed to the targets database.

 

file_url string 

URL to download the uploaded (source) file. NB: Only authenticated users can download the file!

 

id string 

Unique identifier of the file upload.

 

issue_id string 

Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!

 

updated_by string 

Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user

 

updated_time string 

Timestamp of the file upload update.

 

errors object

The 1st 10 erroneous rows of the uploaded file, for data structure see below.

warnings object 

The 1st 10 warnings rows of the uploaded file, for data structure see below.

 

variable_group_name string 

Name of the variable group the file is associated with.

Error data:

error Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the error in the Excel identified with the column-row combination (eg. A2).

value string 

Erroneous value found in the cell.

error string 

Error description​​

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

Invalid upload id 

  • Error Code: 422

  • Error: 1 validation error for Request
    path -> template_id
    invalid ObjectID specified (type=type_error)

 

Missing upload id 

  • Error Code: 404

  • Error: Template not found

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Incalid authentication token

  • Error Code: 401

  • Error: Invalid authentication token

Request Details

Mandatory fields marked indicated by

*

Warning data:

warning Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the warning in the Excel identified with the column-row combination (eg. A2).

value string 

Warning value found in the cell.

warning string 

Warning description​​

POST

Supported Protocol: HTTPS

POST /targets/api/:version_number/projects/:project_name/uploads

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads

upload Object[]

List of uploads, each containing the following fields:

name string 

Name and extension of the uploaded file.

variable_group_id string 

Unique identifier of the variable group the file has been associated with.

issue_id string 

Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!

created_by string 

Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user​​

creation_time date_time 

Timestamp of the file upload​

status enum 

Current status of the file upload, options:

Queued - initial status upon upload
Validation in progress - The uploaded file is being validated

Validated - The uploaded file has passed the validation

Failed - The uploaded file failed the validation

Committed - The uploaded file's data have been committed to the targets database.

file_url string 

URL to download the uploaded (source) file. NB: Only authenticated users can download the file!

id string 

Unique identifier of the file upload.

updated_by string 

Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user

errors object 

The 1st 10 errors rows of the uploaded file, for data structure see below.

warnings object 

The 1st 10 warnings rows of the uploaded file, for data structure see below.

Request Details

Mandatory fields marked indicated by

*

{

    "name": "upload_OSA_MainShelf.csv",

     "variable_group_id": 597,

     "issue_id": null,

     "created_by": "api-user",

     "creation_time": "2022-09-21T11:50:33.593442",

     "status": "Queued",

     "file_url": "https://services-int.traxretail.com/trax-one/integ11/files/download/9957bd30-39a3-11ed-bbbc-87636c21d120",

     "updated_time": "2022-09-21T11:50:33.593446",

     "id": "632afa89e0f7d80e559e0299",

     "updated_by": null,

     "errors": [],

     "warnings": []

}

Response example - JSON

Response Details

The response body will contain the following data:

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

Variable group(s) not added 

  • Error Code: 400

  • Error: "variable_group_id must be an integer number"
    "variable_group_id should not be empty"

Variable group id not an integer

  • Error Code: 400

  • Error: "variable_group_id must be an integer number"

Missing uploaded file

  • Error Code: 400

  • Error: "Missing uploaded file" 
     

Invalid file extension

  • Error Code: 400

  • Error: "Invalid file extension" 

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Invalid authentication token

  • Error Code: 403 - Forbidden

  • Error: "Invalid token!' 

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Upload An Excel/CSV File With Target Data To One Set of KPIs

  • Aim: To enable Clients to upload a file containing new targets data or targets data updates tied to a certain set of KPIs (Variable Group)

  • Use Cases:

    1. To add new targets data/update targets data linked to one Variable Group (certain set of KPIs).

    2. To validate a file before uploading it.

POST Request File Fields

file *

Excel/CSV file with the targets data​

variable_group_id *

Unique identifier of the Variable Group the target data need to be linked to

upload_action enum *

Action to be performed by the API, options:

  • VALIDATE

  • VALIDATE_AND_COMMIT

Mandatory fields marked indicated by

*

  1. Rules and options regarding the upload_action:

    1. The request body needs to contain one of the following possible actions in the upload_action attribute:

      1. VALIDATE_AND_COMMIT

      2. VALIDATE

  2. Providing VALIDATE_AND_COMMIT,

    1. The uploaded file gets validated and if it contains only valid data, these data will be committed to the targets database.

    2. If the file contains (even partially) invalid data, the file’s data (even the valid ones) will not be committed to the database.

  3. Providing VALIDATE,

    1. The uploaded file gets only validated, but not committed to the database. Hence this option can be used for a preliminary file validation. To commit the data to the database, the POST Finalize Upload endpoint needs to be used.

Important notes on how to use the endpoint

Error data:

error Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the error in the Excel identified with the column-row combination (eg. A2).

value string 

Erroneous value found in the cell.

error string 

Error description​​

Warning data:

warning Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the warning in the Excel identified with the column-row combination (eg. A2).

value string 

Warning value found in the cell.

warning string 

Warning description​​

GET

File Errors

  • Aim: To enable Clients to retrieve the errors found in an uploaded targets data file (source file) during validation

  • Use Case: To check the errors if a file upload failed the validation.

Supported Protocol: HTTPS

GET /targets/api/:version_number/projects/:project_name/uploads/:upload_id/download-errors

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/my-project/uploads/62f4f1dd68bcdd097cca1938/download-errors

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

upload_id string *

Unique identifier of the file upload​

Response Details

The response contains the Excel file as a binary string.

Response Example

The file contains all data of the source file, location, error value and error description are added to the rows with errors in an additional column, example:

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

Upload id not found

Error Code: 404

  • Error: Upload not found

Invalid upload id

Error Code: 422

  • Error: Invalid upload id

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Invalid authentication token

  • Error Code: 401

  • Error: Invalid authentication token 

Request Details

Mandatory fields marked indicated by

*

POST

Update File Upload

  • Aim: To enable Clients to replace the uploaded file or change the variable group of a previously uploaded file. NB: updating a file upload is only possible if the file’s data are not yet committed to the database (ie. the file upload status is other than Committed)

  • Use Case: To replace a file having errors with a corrected one.

Supported Protocol: HTTPS

POST /targets/api/:version_number/projects/:project_name/uploads/update/:upload_id

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/update/62f4f1dd68bcdd097cca1938

POST Request File Fields

Mandatory fields marked indicated by

*

file

Excel file with the targets data​ to replace the original file

variable_group_id string *

Unique identifier of the variable group the file upload should be associated with

Response Details

The response body will contain the following data:

name string 

Name and extension of the uploaded file.

 

variable_group_id string 

Unique identifier of the variable group the file has been associated with.

 

created_by string

Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user​​

 

creation_time date_time 

Timestamp of the file upload​

 

status enum 

Current status of the file upload, options:

Queued - initial status upon upload

Validation in progress - The uploaded file is being validated

Validated - The uploaded file has passed the validation

Failed - The uploaded file failed the validation

Committed - The uploaded file's data have been committed to the targets database.

 

file_url string 

URL to download the uploaded (source) file. NB: Only authenticated users can download the file!

 

id string 

Unique identifier of the file upload.

 

issue_id string 

Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!

 

updated_by string 

Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user

 

updated_time string 

Timestamp of the file upload update.

 

errors object

The 1st 10 erroneous rows of the uploaded file, for data structure see below.

warnings object 

The 1st 10 warnings rows of the uploaded file, for data structure see below.

 

variable_group_name string 

Name of the variable group the file is associated with.

Error data:

error Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the error in the Excel identified with the column-row combination (eg. A2).

value string 

Erroneous value found in the cell.

error string 

Error description​​

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

No variable group or file 

  • Error Code: 400 - Bad Request

  • Error: "Missing da​ta for update!"

Variable group does not exist 

  • Error Code: 404 - Not found

  • Error: 'Variable group not found!'

Wrong data format 

  • Error Code: 400 - Bad Request

  • Error: "variable_group_id must be an integer number!"

Wrong upload id 

  • Error Code: 404 - Not found

  • Error: "Template not found!"

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Invalid authentication token

  • Error Code: 403 - Forbidden

  • Error: "Invalid token!' 

Response Example - JSON

{

        "name": "osamain_new_targets.xlsx",

        "variable_group_id": 42,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-11T12:43:48.970000",

        "status": "Queued",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",

        "updated_time": "2022-08-11T12:43:48.970000",

        "id": "62f4f1dd68bcdd097cca1938",

        "updated_by": null,

        "errors": [],

        "warnings": [],

  "variable_group_name": "OSA - Main Shelf

}

Warning data:

warning Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the warning in the Excel identified with the column-row combination (eg. A2).

value string 

Warning value found in the cell.

warning string 

Warning description​​

GET

All File Uploads

  • Aim: To enable Clients to retrieve all uploaded targets data files (source files) with all available data (source file, metadata, status etc.) from Trax

  • Use Case: To get a list of file uploads for reconciliation.

Supported Protocol: HTTPS

GET /targets/api/:version_number/projects/:project_name/uploads?:query_params

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads?limit=100&skip=100

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

limit number

Page size, default: 100

skip number

Offset (starting record), default: 0

Request Details

Mandatory fields marked indicated by

*

Response Details

The response body will contain the following data:

upload Object[]

List of uploads, each containing the following fields:

name string 

Name and extension of the uploaded file.

variable_group_id string 

Unique identifier of the variable group the file has been associated with.

created_by string 

Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user​​

creation_time date_time 

Timestamp of the file upload​

status enum 

Current status of the file upload, options:

Queued - initial status upon upload
Validation in progress - The uploaded file is being validated

Validated - The uploaded file has passed the validation

Failed - The uploaded file failed the validation

Committed - The uploaded file's data have been committed to the targets database.

file_url string 

URL to download the uploaded (source) file. NB: Only authenticated users can download the file!

id string 

Unique identifier of the file upload.

issue_id string 

Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!

updated_by string 

Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user

updated_time string 

Timestamp of the file upload update.

errors object 

The 1st 10 erroneous rows of the uploaded file, for data structure see below.

   

warnings object 

The 1st 10 warnings rows of the uploaded file, for data structure see below.

variable_group_name string 

Name of the variable group the file is associated with.

[

{

        "name": "osamain_new_targets.xlsx",

        "variable_group_id": 42,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-09T14:43:57.063000",

        "status": "Validation in progress",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b2912fd0-17f1-11ed-ad08-590b32c837b3",

        "updated_time": "2022-08-11T13:13:28.756000",

        "id": "62f272adcc01d0694e29a1d2",

        "updated_by": null,

        "errors": [],

        "variable_group_name": "OSA - Main Shelf"

  },

{

        "name": "osamain_new_targets.xlsx",

        "variable_group_id": 42,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-11T12:43:48.970000",

        "status": "Failed",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",

        "updated_time": "2022-08-11T12:43:48.970000",

        "id": "62f4f1dd68bcdd097cca1938",

        "updated_by": null,

        "errors": [

            {

                "location": "A42",

                "value": "HyperMarket",

                "error": "Invalid store_type value(s)"

            }

            {

                "location": "B45",

                "value": "394398234234",

                "error": "Invalid product_ean_code value(s)"

            }

        ],

        "warnings": [

            {

                "location": "A33",

                "value": "394398234444",

                "warning": "This product_ean_code is inactive"

            }

        ],

        "variable_group_name": "OSA - Main Shelf"

  },

{

        "name": "osamain_new_targets.xlsx",

        "variable_group_id": 42,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-09T14:43:57.063000",

        "status": "Committed",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b2912fd0-17f1-11ed-ad08-590b32c837b3",

        "updated_time": "2022-08-09T14:47:45.120000",

        "id": "62f272adcc01d0694e29a1d2",

        "updated_by": null,

        "errors": [],

        "variable_group_name": "OSA - Main Shelf"

  },

]

Response example - JSON

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

Missing/wrong query param 

  • Error Code: 422

  • Error: 1 validation error for Request
    query -> limit
    value is not a valid integer (type=type_error.integer)

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Invalid authenticatrion token

  • Error Code: 401

  • Error: Invalid authentication token

Error data:

error Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the error in the Excel identified with the column-row combination (eg. A2).

value string 

Erroneous value found in the cell.

error string 

Error description​​

Warning data:

warning Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the warning in the Excel identified with the column-row combination (eg. A2).

value string 

Warning value found in the cell.

warning string 

Warning description​​

GET

Download Target Data

  • Aim: To enable Clients to retrieve an excel file with all (active and historical) target data from Trax

  • Use Case: To check the active and historical target data.

Supported Protocol: HTTPS

GET /targets/api/:version_number/projects/:project_name/uploads/download

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/download

Request Details

Mandatory fields marked indicated by

*

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Query Parameters

version_number string *

The current implemented API version. <Major> version (e.g. 'v4')

 

project_name string *

Project name as provided by Trax

 

condensed boolean

Download targets values in condensed (true) or Expended (false or empty, default) mode

on_going_and_future_targets boolean

Download On-going and Future targets (true) or All targets (false or empty, default)

Response Details

The response contains the Excel file as a binary string.

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Invalid authentication token

  • Error Code: 401

  • Error: Invalid authentication token

The file contains all (both active and historical) targets data previously committed to the targets database by default unless you choose otherwise. NB: Targets data tied to the same KPI set (Variable Group) are added to the same sheet.

Response Example

POST

Supported Protocol: HTTPS

POST /targets/api/:version_number/projects/:project_name/uploads/batch

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/batch

Request Details

Mandatory fields marked indicated by

*

{

    "OSA MainShelf": {

        "name": "batch_upload_OSA_MainShelf.xlsx",

        "variable_group_id": 597,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-12T07:02:26.302091",

        "status": "Queued",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b8d2b5e0-1a0c-11ed-a6ad-115f921fe0c4",

        "updated_time": "2022-08-12T07:02:26.302095",

        "id": "62f5fb0268bcdd097cca1950",

        "updated_by": null,

        "errors": []

    },

    "SOS": {

        "name": "batch_upload_SOS.xlsx",

        "variable_group_id": 1722,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-12T07:02:26.565092",

        "status": "Queued",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b8f7ca10-1a0c-11ed-a47b-430fed9059d2",

        "updated_time": "2022-08-12T07:02:26.565098",

        "id": "62f5fb0268bcdd097cca1951",

        "updated_by": null,

        "errors": [],

        "warnings": []

    }

}

Response example - JSON

Response Details

The response body will contain the following data:

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

Variable group(s) not found 

  • Error Code: 200

  • Error: "Variable group not found."

Missing/wrong upload action

  • Error Code: 400

  • Error: "upload action schould be VALIDATE or VALIDATE_AND_COMMIT
    upload action should not be empty

Missing uploaded file

  • Error Code: 400

  • Error: "Missing uploaded file" 
     

Invalid file extension

  • Error Code: 400

  • Error: "Invalid file extension" 

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Invalid authentication token

  • Error Code: 403 - Forbidden

  • Error: "Invalid token!' 

Request Headers

Authorization string

Value: 'Auth-Token {project auth token}'

Authentication token provided by Trax

Upload An Excel File With Target Data To Multiple KPIs (Batch)

  • Aim: To enable Clients to upload an Excel file containing new targets data or targets data updates tied to a certain sets of KPIs

  • Use Cases:

    1. To add new targets data/update targets data linked to one Variable Group (certain set of KPIs).

    2. To add new targets data/update targets data linked to different Variable Groups (certain sets of KPIs).

    3. To validate a file before uploading it.

POST Request File Fields

file *

Excel file with the targets data​

upload_action enum *

Action to be performed by the API, options:

  • VALIDATE

  • VALIDATE_AND_COMMIT

Mandatory fields marked indicated by

*

  1. Rules and options regarding the uploaded file:

    1. This endpoints accepts only Excel files, but no CSVs.

    2. It is possible to upload targets data to different variable groups (sets of KPIs), but each variable group should be added to a separate sheet within the excel file.

    3. Multi-sheet excel files will be by Trax infrastructure split into single-sheet excels hence the response will also contain an array instead of a single object.

  2. To connect the targets data provided in the file to a variable group, the variable group’s name should be added as the sheet’s name.

  3. Rules and options regarding the upload_action:

    1. The request body needs to contain one of the following possible actions in the upload_action attribute:

      1. VALIDATE_AND_COMMIT

      2. VALIDATE

  4. Providing VALIDATE_AND_COMMIT,

    1. The uploaded file gets validated and if it contains only valid data, these data will be committed to the targets database.

    2. If the file contains (partially) invalid data, the file’s data (even the valid ones) will not be committed to the database.

    3. In case of multi-sheet excels, each single-sheet part will undergo the validation and (in the success case) database commit.

  5. Providing VALIDATE,

    1. The uploaded file gets only validated, but not committed to the database. Hence this option can be used for a preliminary file validation. Please note that currently, there is no possibility to commit a valid file’s data into the database via API - this can only be done manually by Trax.

    2. In case of multi-sheet excels, each single-sheet part will undergo validation.

Important notes on how to use the endpoint

error Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the error in the Excel identified with the column-row combination (eg. A2).

value string 

Erroneous value found in the cell.

error string 

Error description​​

Error data:

upload Object[]

List of uploads, each containing the following fields:

name string 

Name and extension of the uploaded file.

variable_group_id string 

Unique identifier of the variable group the file has been associated with.

created_by string 

Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user​​

creation_time date_time 

Timestamp of the file upload​

status enum 

Current status of the file upload, options:

Queued - initial status upon upload
Validation in progress - The uploaded file is being validated

Validated - The uploaded file has passed the validation

Failed - The uploaded file failed the validation

Committed - The uploaded file's data have been committed to the targets database.

file_url string 

URL to download the uploaded (source) file. NB: Only authenticated users can download the file!

id string 

Unique identifier of the file upload.

issue_id string 

Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!

updated_by string 

Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user

updated_time string 

Timestamp of the file upload update.

errors object 

The 1st 10 erroneous rows of the uploaded file, for data structure see below.

warnings object 

The 1st 10 warnings rows of the uploaded file, for data structure see below.

Warning data:

warning Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the warning in the Excel identified with the column-row combination (eg. A2).

value string 

Warning value found in the cell.

warning string 

Warning description​​

POST

Finalize (Commit) File

  • Aim: To enable Clients to commit the data of a valid file to the Trax Targets Database. NB: works only for uploads which haven't been committed yet to the database (the upload status is not committed). 

  • Use Case: To commit the data of a corrected file to the database.

Supported Protocol: HTTPS

POST /targets/api/:version_number/projects/:project_name/uploads/:upload_id/finalize

curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/62f4f1dd68bcdd097cca1938/finalize

POST Request File Fields

Mandatory fields marked indicated by

*

file

Excel file with the targets data​ to replace the original file

upload_id string *

Unique identifier of uploaded file

Response Details

The response body will contain the following data:

name string 

Name and extension of the uploaded file.

 

variable_group_id string 

Unique identifier of the variable group the file has been associated with.

 

created_by string

Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user​​

 

creation_time date_time 

Timestamp of the file upload​

 

status enum 

Current status of the file upload, options:

Queued - initial status upon upload

Validation in progress - The uploaded file is being validated

Validated - The uploaded file has passed the validation

Failed - The uploaded file failed the validation

Committed - The uploaded file's data have been committed to the targets database.

 

file_url string 

URL to download the uploaded (source) file. NB: Only authenticated users can download the file!

 

id string 

Unique identifier of the file upload.

 

issue_id string 

Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!

 

updated_by string 

Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user

 

updated_time string 

Timestamp of the file upload update.

 

errors object

The 1st 10 erroneous rows of the uploaded file, for data structure see below.

warnings object 

The 1st 10 warnings rows of the uploaded file, for data structure see below.

 

variable_group_name string 

Name of the variable group the file is associated with.

Error data:

error Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the error in the Excel identified with the column-row combination (eg. A2).

value string 

Erroneous value found in the cell.

error string 

Error description​​

Validation and Errors

The following are the validations and errors that may appear due to an invalid GET request:

Invalid upload ID 

  • Error Code: 422

  • Error: 1 validation error for Request
    path -> template_id
    invalid ObjectID specified (type=type_error).

Internal Server Error

  • Error Code: 500 - Internal Server Error

  • Error: Trax Internal Error

Invalid authentication token

  • Error Code: 403

  • Error: Invalid token.

Response Example - JSON

{

        "name": "osamain_new_targets.csv",

        "variable_group_id": 42,

        "issue_id": null,

        "created_by": "api-user",

        "creation_time": "2022-08-11T12:43:48.970000",

        "status": "Committed",

        "file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",

        "updated_time": "2022-08-11T12:43:48.970000",

        "id": "62f4f1dd68bcdd097cca1938",

        "updated_by": null,

        "errors": [],

        "warnings": [],

  "variable_group_name": "OSA - Main Shelf

}

Warning data:

warning Object[]

List of the 1st 10 errors found in the uploaded file during validation with the following data:

location string 

Cell of the warning in the Excel identified with the column-row combination (eg. A2).

value string 

Warning value found in the cell.

warning string 

Warning description​​

bottom of page