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