When a user requests an asynchronous operation from an extension service, the service can create a task object and add it to an organization's tasks list.

Every VMware Cloud Director organization has a tasks list and accepts requests to add a task to the list. When a client requests an asynchronous operation from a service, the service starts to process the request and also POSTs a Task element to the organization's tasksList URL. VMware Cloud Director adds information such as an id and startTime to the Task, places it on the organization's TasksList, creates an event in the organization's event stream, and returns the Task to the service. The service can then send the Task, as an AMQP message, to VMware Cloud Director, which sends it as a response to the client that made the original request.

Note: Because of the diversity of sources from which an extension service can draw references to the User, Owner, and Organization elements of a Task, it may not always be possible for every client to resolve such references. For example, if a service creates an object in an organization of which you are not a member, you will not be able to resolve the reference to the object in the Owner element of the Task.

Prerequisites

This operation is restricted to system administrators.

Procedure

  1. Retrieve the XML representation of the organization in which you want to create the Task.
    Use a request like this one: 
    GET https://vcloud.example.com/api/admin/org/26
  2. Examine the response to locate the Link element that contains the URL for adding tasks to the organization's tasks list.
    This element has a rel attribute value of task:create and a type attribute value of application/vnd.vmware.vcloud.task+xml, as shown here: 
    <Link
   rel="task:create"
   type="application/vnd.vmware.vcloud.task+xml"
   href="https://vcloud.example.com/api/tasksList/26" />
  3. Create a Task element that specifies the details of the task.
  4. POST the Task element to the organization's tasksList URL.

Results

The server creates a task object and adds it to the organization's tasks list, and returns the representation of the object to the service. To return the XML representation of the task object to the client that made the original request, the service must create a JSON representation of the Task and return it to VMware Cloud Director AMQP service.

Example: Add a Task to an Organization's Tasks List

Request: 
POST https://vcloud.example.com/api/tasksList/26
Content-Type: application/vnd.vmware.vcloud.task+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Task
   xmlns="http://www.vmware.com/vcloud/v1.5"
   status="running"
   serviceNamespace="org.example.vcd.backup"
   type="application/vnd.vmware.vcloud.task+xml"
   operation="Backup in progress for virtual machine with id 7b91b053-2b..."
   operationName="backupInProgress"
   name="task">
 <Owner
      type="application/vnd.vmware.vcloud.org+xml"
      name="Finance"
      href="https://vcloud.example.com/api/org/26"
      id="26" />
   <User
      type="application/vnd.vmware.admin.user+xml"
      name="bob"
      href="https://vcloud.example.com/api/admin/user/39" />
   <Progress>10</Progress>
</Task>
Response: 
200 OK
Content-Type: application/vnd.vmware.vcloud.task+xml
...
<Task
   href="https://vcloud.example.com/api/task/604"
   ...
   operationName="backupInProgress"
   ... >
   ...   
</Task>