Bulk load API ------------- Two API calls are required. .. tabularcolumns:: |p{1.5cm}|p{1cm}|p{3cm}|p{5cm}|p{5cm}| +--------------+--------+----------------------+-------------------------------+----------------------------+ | Task | Call | URL | Parameters | Response | +==============+========+======================+===============================+============================+ | | | :: | :: | :: | | | | | | | | Submit file | POST | /api/ | hierarchy=[hierarchy] | {"uploadedfiles": | | | | uploadfiles/ | Content-Type: | [{"id": "", | | | | | multipart/form-data | "name": ""}]} | | | | This URL will be | | | | | | moved to | name='uploadedfile' | | | | | tool/UploadFile | filename= | | | | | in future. | the file to upload | | +--------------+--------+----------------------+-------------------------------+----------------------------+ The response is HTTP 202 .. tabularcolumns:: |p{1.25cm}|p{1cm}|p{3cm}|p{5.25cm}|p{5cm}| +--------------+--------+---------------------------+-----------------------------------+-----------------------------+ | Task | Call | URL | Parameters | Payload | +==============+========+===========================+===================================+=============================+ | | | | | Examples: | | | | :: | :: | :: | | | | | | | | Bulk Load | POST | /api/tool/ | method= | {'bulkload_file': | | | | BulkLoad/ | bulkload_spreadsheet | '', | | | | | hierarchy=[hierarchy] | 'execute_immediately': | | | | | | true} | | | | | | | | | | | | or: | | | | | | :: | | | | | | | | | | | | {'bulkload_file': | | | | | | '', | | | | | | '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 ' -F uploadedfile="@.xlsx" 'http:///api/uploadfiles/' Step 2 :: curl -H 'Authorization: Basic ' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary '{"bulkload_file":"DEMO.xlsx","execute_immediately":true}' 'http:///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': '.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} } .. |transaction-GUI| image:: /src/images/transaction-GUI.png