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}
}