Download Code Data
UAT token permissions
The UAT token needs to have access to the following permissions:
codes_view
The UAT token must be set in the header fields of all requests as described in Authentication & Tokens.
Code Data Search Filters
To download your Code Data, you need to:
- Find the campaign ID of the products on which your codes are applied.
- Optional: if you want to filter on products or SCM fields, you meed to find the scm field keys and product id's
- Filter the codes: use the campaign ID, time-range, product or SCM fields as filters to find your codes
- Generate a search task
- Check the status of this search task until the status is complete
- Generate a download link
- Download the codes in CSV format
1. Find your campaign ID
- Log on to the portal and click on CAMPAIGNS in the left hamburger menu
- On the campaign for which you want to download the data, click the DASHBOARD icon
- When the dashboard opens, the URL in the browser will show
https://portal.scantrust.com/#/dashboard?tabIndex=0&campaignId=126&page=1 - The campaign-id needed is in the value of the parameter
campaignId=
2. Find your campaign SCM Field Keys (optional)
- Log on to the portal and click on CAMPAIGNS in the left hamburger menu
- On the campaign for which you want to download the data, click the OPTIONS icon
- Click the SCM T&T tab
- From the right pabel, copy the keys of each of the active fields (in brackets behind the label).
- Use these keys to filter the code-search if required
3. Filter the codes
All of the filters used in the portal in the codes created screen can also be user to filter the code downloadsd. Some of the options are:
- time-range (timeframe or date_from / date_to)
- flags (counterfeit / genuine etc.)
- code activation status (inactive / active / blacklisted)
- SCM fields (as defined for the campaign, for example intended_market, case_no etc.)
4. Create a search task
GET: /api/v2/codes/download/?campaign=2084
| Parameter | Required? | Description |
|---|---|---|
| campaign_id | required | ID of the campaign |
| timeframe | optional | -1y (year), -1m (month), -1w (week) |
| or | ||
| date_from | optional | ISO date (ie. 2018-12-21T23:59:59.549Z) |
| date_to | optional | ISO date (ie. 2018-12-21T23:59:59.549Z) |
| activation_status | optional | inactive=0, active=1, blacklisted=2 |
| {scm field} | optional | Any SCM field key/value as a filter. |
| product | optional | product ID (not SKU) |
Examples
Show all scans for campaign 195 which are blacklisted and which have intended_market set to "China" (Zh):
/api/v2/dashboard/scans/?campaign=195&flags=out-of-market&limit=2000&offset=0&scm_intended_market=zh&timeframe=-1m
Show all scans for campaign 195 made between 2021-01-31 and 2021-05-18 for product 332:
/api/v2/dashboard/summary/?campaign=195&date_from=2021-01-31T16:00:00.000Z&date_to=2021-05-18T15:59:59.000Z&flags=&product=332
Show all scans for campaign 195 made in the past year which were for codes which are inactive (activation_status=0):
/v2/dashboard/summary/?activation_status=0&campaign=543&timeframe=-1y
Response (200): Status OK
Because the data generated by this search can range in the millions, this endpoint first generates a task which will run in the background. It will then generate a document_key
{
"document": {
"key": "mfoi66hz93c9"
},
"task": "rq:job:e6f16079-f368-4d8f-940a-7c0266e03d02"
}
The client needs to extract the document_key from the response and use it in the next request to check the generation-status:
5. Check the status of your search task
GET: /api/v2/documents/{document_key}
parameter: document_key as retrieved from the previous request
Response (200): Status OK
{
"key": "mfoi66hz93c9",
"description": "",
"status": "complete",
"category": "code",
"doctype": "search-result",
"related_id": null,
"parameters": {
"campaign": "2084",
"activated_at": "2019-09-30T16:00:00.000Z,2021-01-31T16:00:00.000Z"
},
"file_size": 253,
"row_count": 0,
"expires_at": "2021-04-17T02:31:59.467855Z",
"is_expired": false,
"created_at": "2021-04-15T02:31:58.385106Z",
"company": 446,
"owner": 391,
"created_by": 391
}
The response will contain the key, status as well as the parameters used to do the search.
Once the status has reached complete, another request can be made to create a download link.
The field row_count will indicate how many codes were found.
6. Generate a download link
GET: /api/v2/documents/{{document_key}}/get-download-link/
parameter: document_key as retrieved from the previous request
Response (200): Status OK
The response will contain a secured download link to the search result CSV file:
{
"link": "https://api.staging.scantrust.io/api/v2/documents/download/yNKtdRwgAdLYUTKMLSOYkJHDGgSBLxUS/"
}
7. Download the CSV file
When that link is downloaded, the server will send a response as a 302 - redirect
The response sends the client to the CSV file in the Scantrust Amazon S3 bucket
Note: After following the link, the download link becomes invalid. Please ensure the download happens as soon as possible after generating the link
Note:
- the CSV file is compressed in zip-format and needs to be unpacked
- the CSV file is formatted as comma-separated double-quoted with header.
Response (200): Status OK
Example CSV:
"extended_id","serial_number","brand","product","sku","status","blacklist_reason","scm_updated_by","scm_updated_at","activated_by","activated_at","workorder_id","farm_name","organic","harvest_date","sent_to_plant","plant","sell_by_date","temp_humid_in_ph","shipped_from_plant","arrived_in_dc","dc_name","temp_humid_in_dc","shipped_from_dc","case_number"
"D7BDCA03B80610826432DAD3","","American Pork","Pork","259052703982","active","none","","","","","3413","","","","","","","","","","","","",""
"DE8429F00C043SMPHGG3SCE54D3DBE2","","American Pork","Pork","259052703982","active","none","","2019-06-14T09:35:08.207234+00:00","jelle@test.com","2020-02-13T08:43:54.256017+00:00","3414","","","","","","","","","","","","",""
"F628FC48BC043SMPHGG3S4E54681B26","","Queen Victoria","Lettuce","060556200408","active","none","j@test.com","2018-06-14T20:03:33.627564+00:00","","","3414","Aliso Farms","No","2018-06-14","2018-06-14","Packaging Plant 1","2018-06-14","36°F 95%","2018-06-15","2018-06-15","UST","36° 95%","2018-06-16","52C3F83EAA043SMPHGG3S9E4483193F"
"70E19832F1043SMPHGG3S64644B7B66","","American Pork","Pork","259052703982","active","none","j@test.com","2018-06-13T23:21:40.214562+00:00","","","3414","Aliso Ranch","No","2018-06-14","2018-06-14","Processing Plant 1","2018-06-21","36°F 85%","2018-06-15","2018-06-15","UST","36°F 85%","2018-06-15","FD27177428043SMPHGG3S2824AA697A"
"4324CAC06E043SMPHGG3SF124F8BADE","","Queen Victoria","Lettuce","060556200408","active","none","scmuser@test.com","2018-05-26T17:14:12.055232+00:00","","","3414","ST Test","","","","","","","","","","","",""
For a glossary of all the code fields see Code Data Glossary