Many administrative actions on the appliance take time to complete. Updating the HSM firmware, for example, can take several minutes. Instead of simply blocking further actions during this time, the REST API creates tasks for time-consuming resources and returns an immediate response for the action. An application can monitor the state of an associated task and perform different actions accordingly. While the firmware is updating, for example, an application might display one of the following:

An hourglass, signifying that the operation is still in progress
A checkmark for a successful update
An X for a failed update

The state obtained for a GET operation on the applicable task identifier provides the information to decide what follow-on action to take.

How to Use Tasks

This example describes one way that an application can use a task (logging in to the HSM) and the state returned by the server on query.

Post the login resource on the HSM:

POST
https://LUNAIPADDRESS:PORT/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
https://LUNAIPADDRESS:PORT/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 login is completed, a query of tasks returns:

{
    "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 new login operation and using the task instance returned in the server response for a GET operation shows:

GET
https://LUNAIPADDRESS:PORT/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 returns a "Running" state. If the action fails (due to no PED response, for example), the server response is:

GET
https://LUNAIPADDRESS:PORT/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":""
}

You might encounter the following other states:

"Waiting" - 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 clean up stale tasks (tasks in "Waiting, "Finished", "Error" states that must be started or queried in order to be removed) using the delete task resources (DELETE /tasks/{taskid} and DELETE /tasks). Cleanup is not required, however; a maximum of 20 stale tasks is allowed.

Commonly 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.