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.

transaction-GUI

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