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

Verify that you are logged in to the vCloud API as a system administrator.

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

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 vCloud Director AMQP service.

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"
   name="task">
   <User
      type="application/vnd.vmware.admin.user+xml"
      name="administrator"
      href="https://vcloud.example.com/api/admin/user/85" />
</Task>

Response:

200 OK
Content-Type: application/vnd.vmware.vcloud.task+xml
...
<Task
   ...
   operationName="jobCustom"
   operation="External processing" >
   ...   
</Task>