ViPR 2.2 - Track Status of Asynchronous Operations with Tasks Using the REST API

Table of Contents

Overview

A number of ViPR operations and services are processed asynchronously. Asynchronous operations return a task or list of tasks.

Each task represents a block of work performed by the controller engine. These tasks can be followed to determine if the operation has succeeded, failed or is in progress, and can be followed using both the UI and the REST API.

There are two types of tasks:
  • Tenant tasks, such as adding a host.
    • Any user that is a member of the tenant can view the tasks that are related to that tenant.
    • Any user that is a member of the tenant can view the details of the tasks related to that tenant.
  • System tasks that are not associated with any tenant, such as adding a storage array.
    • Only a system administrator can view system tasks.
    • Only system administrators and security administrators can view the details of a system task.

By default, tasks last for seven days from the date of completion. In addition, the time interval between task cleaning operations is 60 minutes. But these values can be changed, as described in Change task-related configuration settings.

In addition, when you delete a resource the tasks that are associated with the resource are still available for viewing.

The EMC ViPR REST API Reference provides additional information concerning the methods in the Task API.

Back to Top

Track status of asynchronous operations using task details

Asynchronous operations return a task. You can periodically check the details of the task, using GET /vdc/tasks/{id}, to determine if the operation has succeeded, failed, or is in progress.

When a task is first created, it is in the pending state which indicates that the operation is in progress. In this example, a EMC ScaleIO storage provider is added to ViPR and a task in the pending state is returned.

Request
POST https://<ViPR_VIP>:4443/vdc/storage-providers
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>

<storage_provider_create>
  <name>scaleio_block_1</name>
  <interface_type>scaleio</interface_type>
  <ip_address>lglbg045.lss.emc.com</ip_address>
  <port_number>22</port_number>
  <user_name>root</user_name>
  <password>admin</password>
  <secondary_username>admin</secondary_username>
  <secondary_password>Danger0us1</secondary_password>
  <element_manager_url>https://lglbg045.lss.emc.com/resources/dashboard.jnlp?host=10.247.78.45&username=admin</element_manager_url>
</storage_provider_create>
Response
HTTP 202 Accepted
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task>
    <creation_time>1415211256218</creation_time>
    <global>false</global>
    <id>urn:storageos:Task:9d520090-6518-49a2-8b7b-af2c7066416d:vdc1</id>
    <inactive>false</inactive>
    <internal>false</internal>
    <link rel="self" href="/vdc/tasks/urn:storageos:Task:9d520090-6518-49a2-8b7b-af2c7066416d:vdc1"/>
    <name>SCAN STORAGE PROVIDER</name>
    <remote>false</remote>
    <tags/>
    <vdc>
        <id>urn:storageos:VirtualDataCenter:d649923c-3d28-4195-bd6e-d7139c0df033:vdc1</id>
        <link rel="self" href="/vdc/urn:storageos:VirtualDataCenter:d649923c-3d28-4195-bd6e-d7139c0df033:vdc1"/>
    </vdc>
    <associated_resources/>
    <op_id>18315650-b792-4ec9-86e9-5198dd28588b</op_id>
    <progress>0</progress>
    <resource>
        <id>urn:storageos:StorageProvider:7c347281-416f-453d-ade1-31ab03ddf1b9:vdc1</id>
        <link rel="self" href="/vdc/storage-providers/urn:storageos:StorageProvider:7c347281-416f-453d-ade1-31ab03ddf1b9:vdc1"/>
        <name>scaleio_block_1</name>
    </resource>
    <start_time>1415211256216</start_time>
    <state>pending</state>
</task>
The task that is returned from an asynchronous operation includes:
  • A description of the operation, which in this example is scanning a storage provider.
  • The ID of the task.
  • The ID, name, and a link to the resource associated with the operation. In this example, it is the storage provider that has been created in ViPR and is being discovered.
  • The state of the task, which is pending.

You can use the ID of the task returned from the operation to check the details of the task to determine when it has completed. A task can complete successfully or with an error. To check the details of a task, you use GET /vdc/tasks/{id}.

Request
GET https://{Conref}<ViPR_VIP>:4443/vdc/tasks/urn:storageos:Task:9d520090-6518-49a2-8b7b-af2c7066416d:vdc1
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
Response
HTTP 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task>
    <creation_time>1415211256218</creation_time>
    <global>false</global>
    <id>urn:storageos:Task:9d520090-6518-49a2-8b7b-af2c7066416d:vdc1</id>
    <inactive>false</inactive>
    <internal>false</internal>
    <link rel="self" href="/vdc/tasks/urn:storageos:Task:9d520090-6518-49a2-8b7b-af2c7066416d:vdc1"/>
    <name>SCAN STORAGE PROVIDER</name>
    <remote>false</remote>
    <tags/>
    <vdc>
        <id>urn:storageos:VirtualDataCenter:d649923c-3d28-4195-bd6e-d7139c0df033:vdc1</id>
        <link rel="self" href="/vdc/urn:storageos:VirtualDataCenter:d649923c-3d28-4195-bd6e-d7139c0df033:vdc1"/>
    </vdc>
    <associated_resources/>
    <end_time>1415211260337</end_time>
    <message>Operation completed successfully</message>
    <op_id>18315650-b792-4ec9-86e9-5198dd28588b</op_id>
    <progress>100</progress>
    <resource>
        <id>urn:storageos:StorageProvider:7c347281-416f-453d-ade1-31ab03ddf1b9:vdc1</id>
        <link rel="self" href="/vdc/storage-providers/urn:storageos:StorageProvider:7c347281-416f-453d-ade1-31ab03ddf1b9:vdc1"/>
        <name>scaleio_block_1</name>
    </resource>
    <start_time>1415211256216</start_time>
    <state>ready</state>
</task>
The status of the task is determined as follows:
  • In progress: state is pending and progress indicates the percentage complete
  • Completed successfully: message is Operation completed successfully and state is ready.
  • Completed with an error: state is error and there is an error message and error code included in the task details.
Back to Top

Search for tasks by resource ID or state

GET /vdc/tasks/search is used to search for tasks.

The search returns a list of task IDs that match the specified resource ID or state. You can refine the search by specifying a tenant ID. You can also set the tenant ID to system to only retrieve system tasks.

The tasks that are returned are not in the order in which they were created.

Search by resource ID

Searching by resource ID returns a list of the tasks that were created for operations involving the specified resource.
GET https://10.247.100.247:4443/vdc/tasks/search?resource=urn:storageos:StorageProvider:870df5c8-5cae-4d87-9d53-e080e477edf4:vdc1
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>


HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
    <resource>
        <id>urn:storageos:Task:001b3608-5e50-4dd4-a62a-3e66b5e76656:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:001b3608-5e50-4dd4-a62a-3e66b5e76656:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:001daa35-567d-4db2-8fd1-91baf87c36b4:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:001daa35-567d-4db2-8fd1-91baf87c36b4:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:00213867-7c6f-40e3-ac20-096d2f26a36b:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:00213867-7c6f-40e3-ac20-096d2f26a36b:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:00244adb-4da1-4e8c-8dd0-dbaff16248fb:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:00244adb-4da1-4e8c-8dd0-dbaff16248fb:vdc1"/>
    </resource>
</results>

Search by state

Searching by state returns a list of IDs for all tasks that are in the state that you specify. The state can be:
  • pending
  • ready
  • error

You can also include a tenant ID to specify from which tenant the tasks should be returned. Setting the tenant ID equal to system returns the system tasks that match the requested state. If you do not include a tenant ID, then tasks will be returned from all tenants to which you have access.

Once you have the task IDs, you can view the details of a single task or multiple tasks.

In this example, all system tasks that have completed successfully and are in the ready state are returned.
GET https://<ViPR_VIP>:4443/vdc/tasks/search?state=ready&tenant=system
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>


HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
    <resource>
        <id>urn:storageos:Task:001b3608-5e50-4dd4-a62a-3e66b5e76656:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:001b3608-5e50-4dd4-a62a-3e66b5e76656:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:001daa35-567d-4db2-8fd1-91baf87c36b4:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:001daa35-567d-4db2-8fd1-91baf87c36b4:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:00213867-7c6f-40e3-ac20-096d2f26a36b:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:00213867-7c6f-40e3-ac20-096d2f26a36b:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:00244adb-4da1-4e8c-8dd0-dbaff16248fb:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:00244adb-4da1-4e8c-8dd0-dbaff16248fb:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:0031bcaa-9cea-4954-8b57-99062058a700:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:0031bcaa-9cea-4954-8b57-99062058a700:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:00a3dded-c348-474b-a806-239519c5c4e1:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:00a3dded-c348-474b-a806-239519c5c4e1:vdc1"/>
    </resource>
    <resource>
        <id>urn:storageos:Task:00daeba5-3574-4cfd-bd51-b8d828b8c6f6:vdc1</id>
        <link rel="self" href="/vdc/tasks/urn:storageos:Task:00daeba5-3574-4cfd-bd51-b8d828b8c6f6:vdc1"/>
    </resource>
</results>

Back to Top

Get statistics for tenant and system tasks

GET vdc/tasks/stats?tenant=<tenant_URI> is used to get a count of the number of tenant and system tasks in the error, pending, and ready (completed) state.

When you send a GET /vdc/tasks/stats request without any tenant specified, then a task status count is returned for your tenant. In this example, there are no tasks for the tenant of the logged in user.
GET https://<ViPR_VIP>:4443/vdc/tasks/stats
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>

HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task_stats>
     <error>0</error>
     <pending>0</pending>
     <ready>0</ready>
</task_stats>
You can also get the task status count for system tasks, by specifying system as the tenant. In this example, there are no system tasks in the error or pending state, but there are 1686 tasks that have successfully completed.
GET https://<ViPR_VIP>:4443/vdc/tasks/stats?tenant=system
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>

HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task_stats>
     <error>0</error>
     <pending>0</pending>
     <ready>1686</ready>
</task_stats>
Back to Top

Change task-related configuration settings

There are two task configuration settings that can be changed using PUT /config/properties.

Before you begin

task_ttl Number of minutes to keep tasks once they have completed. The default is 10080 (7 days).
task_task_clean_interval Time interval in minutes between task cleaning operations. The default is 60 minutes.
Note Image
After you change this property, you must initiate a reboot of the ViPR nodes. Rebooting ViPR nodes may disrupt ViPR processes that are currently running.

In this example, task_ttl is changed to 8 days (11520 minutes). Since only the task_ttl is being updated, you do not need to reboot the ViPR nodes.

Procedure

  1. Change a task configuration property by sending a PUT /config/properties request. The request returns
    Request
    PUT https://<ViPR_VIP>:4443/config/properties
    Content-Type: application/xml
    X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    
    <property_update>
      <properties>
        <entry>
             <key>task_ttl</key>
             <value>11520</value>
        </entry>
      </properties>
    </property_update>
    Response
    HTTP 200 OK
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <cluster_info>
         <cluster_state>UPDATING</cluster_state>
         <link rel="self" href="/upgrade/cluster-state"/>
    </cluster_info>
Back to Top

Important REST API calls to manage tasks

The table shows some important APIs that are used to manage tasks.

Back to Top