Bulk Load API¶
Two API calls are required.
Task |
Call |
URL |
Parameters |
Response |
|---|---|---|---|---|
Submit file |
POST |
/api/
uploadfiles/
This URL will be moved to tool/UploadFile in future. |
hierarchy=[hierarchy]
Content-Type:
multipart/form-data
name='uploadedfile'
filename=<filename>
the file to upload
|
{"uploadedfiles":
[{"id": "<file_id>",
"name": "<filename>"}]}
|
The response is HTTP 202
Task |
Call |
URL |
Parameters |
Payload |
|---|---|---|---|---|
Bulk Load |
POST |
/api/tool/
BulkLoad/
|
method=
bulkload_spreadsheet
hierarchy=[hierarchy]
|
Examples: {'bulkload_file':
'<filename>',
'execute_immediately':
true}
or: {'bulkload_file':
'<filename>',
'execute_immediately':
false
'execute_date':
'2013-06-20',
'execute_time':
'12:00:00',
'execute_timezone':
'0'}
|
The following curl commands illustrate the two steps:
Step 1
curl -H 'Authorization: Basic <auth_key>'
-F uploadedfile="@<file>.xlsx"
'http://<hostname>/api/uploadfiles/'
Step 2
curl -H 'Authorization: Basic <auth_key>'
-H 'Content-Type: application/json'
-H 'accept: application/json'
--data-binary '{"bulkload_file":"DEMO.xlsx","execute_immediately":true}'
'http://<host>/api/tool/BulkLoad/?hierarchy=[hierarchy]&
method=bulkload_spreadsheet&
nowait=true&
format=json'
The response to this call is for example as in the following table.
Response |
|---|
{"href": "/api/tool/Transaction/0b340a6f-b658-48bb-ac8c-7562adc5572d",
"success": true,
"transaction_id": "0b340a6f-b658-48bb-ac8c-7562adc5572d"}
|
If the Bulk Load is to be scheduled, the payload of the second task includes schedule details:
execute_immediately is set to false
execute_date is added in the format YYYY-MM-DD
execute_time is added in the format HH:MM:SS
execute_timezone is added in the format of a numeric value in minutes relative to UTC. For example, UTC is 0, UTC+2:00 is 120, UTC-1:00 is -60, and so on.
An entry is also generated in the schedule; that is, an instance is added to the data/Schedule module.
If the second task payload has ‘execute_immediately’:true, a POST is generated to /api/data/Bulkload/. The payload includes the uploaded filename and a generated name and time stamp as well as a description, for example:
{'filename': '<file>.xlsx', 'description': 'Generated by Bulk Loader
Administration Tools', 'name': 'AnyUser.xlsx -- 2013-05-21
16:47:11.801664 (UTC)'}
To inspect the detailed progress and status of the transaction, use the API call from the response above:
GET /api/tool/Transaction/[pkid]
with parameters:
hierarchy=[hierarchy]format=json
The response to this GET call is a JSON object that provides details of the transaction, as for example in the truncated snippet:
...
"href": "/api/tool/Transaction/[pkid]
"log_id": "53a8053ea616540708141f44",
"message": "data_Countries_bulkloadsheet.xlsx is a valid
"severity": "info",
"time": "2014-06-23T10:45:18.029000",
"transaction_id": "[pkid]"
}
],
"pkid": "[pkid]",
"resource": {},
"rolled_back": "No",
"started_time": "2014-06-23T10:45:17.813000",
"status": "Success",
"sub_transactions": [
{
"action": "Execute Resource",
"detail": "Execute : data_Countries_bulkloadsheet.xlsx -- ...
"status": "Success",
"submitted_time": "2014-06-23T10:45:19.567000",
"transaction": "/api/tool/Transaction/[pkid1] ...
},
{
"action": "Create Schedule",
"detail": "Name:data_Countries_bulkloadsheet.xlsx -- 2014- ...
"status": "Success",
"submitted_time": "2014-06-23T10:45:18.912000",
"transaction": "/api/tool/Transaction/[pkid2] ...
},
{
"action": "Create Bulk Load",
"detail": "Name:data_Countries_bulkloadsheet.xlsx -- 2014-06 ...
"status": "Success",
"submitted_time": "2014-06-23T10:45:18.419000",
"transaction": "/api/tool/Transaction/[pkid3] ...
}
],
"submitted_time": "2014-06-23T10:45:17.794000",
On the GUI, the same transaction displays as in the Transaction log image.
For long transactions, to retrieve a summary of the status of the transaction,
the transaction can be polled, using poll in the URL, using the same parameters:
GET /api/tool/Transaction/poll/?transactions=[pkid]
In this case, there is a shortened response, for example:
{"[pkid]":
{"status": "Processing",
"href": "/api/tool/Transaction/0b340a6f-b658-48bb-ac8c-7562adc5572d",
"description": null}
}