Tasks

Introduction

Many administrative actions take noticeable time to complete: they are not instantaneous. For example, the action of updating the firmware on the HSM can take a couple minutes to complete. Rather than block and wait for the action to complete, the REST API creates tasks for time-consuming resources and returns a response immediately for the action. An application can monitor an associated task for state and perform different actions depending upon the state. Returning to firmware update, for example, an application might display: an hour glass to signify that the operation is still in progress; a check mark for a successful completion; or an X for a failed operation. The state obtained for a GET operation on the applicable task identifier provides the information needed to decide what follow on action to take.

How to Use Tasks

An application can use a task and the state returned on query in different ways. The description that follows outlines one way. For the purpose of an example, assume that you want to login to the HSM.

Post the login resource on the HSM:

POST /api/lunasa/hsms/151256/login

{"ped": "1", "password": "", "role": "so"}

You get back:

{
    "finishTime": "",
    "instance": "/tasks/3",
    "responseUrl": "/tasks/3/response",
    "sourceUrl": "/api/lunasa/hsms/151256/login",
    "startTime": "",
    "state": "Waiting",
    "details": ""
}

To obtain a list of tasks from the appliance, get the tasks:

GET /tasks

The server response for our example might include:

{
    "tasks": [
        {
            "finishTime": "",
            "instance": "/tasks/6",
            "responseUrl": "/tasks/6/response",
            "sourceUrl": "",
            "startTime": "2015-07-05T06:53:36Z",
            "state": "Running",
            "details":""
        }
    ]
}

"Running" means that the HSM login action is still in progress. After sufficient time to allow the login to complete, a query of tasks shows:

{
    "tasks": [
        {
            "finishTime": "2015-07-05T06:53:49Z",
            "instance": "/tasks/6",
            "responseUrl": "/tasks/6/response",
            "sourceUrl": "/api/lunasa/hsms/151256/login",
            "startTime": "2015-07-05T06:53:36Z",
            "state": "Finished",
            "details":""
        }
    ]
}

Starting a login again and using the task instance returned in the server response to do a GET operation shows:

GET /tasks/7
...
{
    "finishTime": "",
    "instance": "/tasks/7",
    "responseUrl": "/tasks/7/response",
    "sourceUrl": "/api/lunasa/hsms/151256/login",
    "startTime": "2015-07-05T09:10:30Z",
    "state": "Running",
    "details":""
}

Periodically polling with a GET on this resource continues to show a "Running" state. If the action fails (e.g., no PED response), the server response is:

GET /tasks/7
...
    "finishTime": "2015-07-05T09:15:30Z",
    "instance": "/tasks/7",
    "responseUrl": "/tasks/7/response",
    "sourceUrl": "/api/lunasa/hsms/151256/login",
    "startTime": "2015-07-05T09:10:30Z",
    "state": "Error",
    "details":""
}

Other states that you might encounter are:

"Waiting" - This state means that the REST API is blocked from handing off a request to a plugin to complete. For example, with multi-party authentication, login to the REST API reports this state until authentication is established.
"Cancelled" - This state is reserved for future use and is TBD until then.
"Timed Out" - This state is reserved for future use and is TBD until then.
"Skipped" - This state is reserved for future use and is TBD until then.

NOTE: Applications may choose to cleanup the tasks, this is done with the delete task resources (DELETE /tasks/{taskid} and DELETE /tasks), however this is not required as the maxiumum amount of stale tasks is 20. Stale tasks refer to tasks that either need to be started or queried for results in order to be removed (Waiting, Finished, Error).

Tasked Resources

Any resource action can result in a task. The return code for a tasked action on a resource is 202. Some resource actions are more likely to always use tasks to track progress, specifically:

POST /api/lunasa/hsms/{hsmid}/... (see Note 1)
POST /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/actions/backup
POST /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/actions/restore
DELETE /api/lunasa/hsms/{hsmid}/partitions/{partitionid}
POST /api/lunasa/hsms/{hsmid}/partitions
POST /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/actions/initialize
PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid}/password
PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid}
PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid}
PATCH/api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid}
POST /api/lunasa/hsms/{hsmid}/peds/{pedid}/actions/connect
POST /api/lunasa/hsms/{hsmid}/peds/{pedid}/actions/disconnect
POST /api/lunasa/hsms/{hsmid}/firmware/actions/rollback
POST /api/lunasa/hsms/{hsmid}/firmware/actions/upgrade
PUT /api/lunasa/hsms/{hsmid}/policies/{policyid}
PATCH /api/lunasa/hsms/{hsmid}/policies/{policyid}

Note 1: Any resource that uses the PIN entry device is tasked. For example, /api/lunasa/hsms/{hsmid}/login.

Some reference pages show examples of how tasks might result for certain operations.