Abiquo workflow feature

1 Introduction to workflow
2 Create a workflow integration
3 Workflow integration reference
- 3.1 Sample request
- 3.2 Workflow links
- 3.3 Sample workflow continue request
- 3.4 Sample workflow cancel request
- 3.5 Configure workflow in the platform
- 3.6 Configure workflow per cloud tenant
4 Manual workflow operations
5 URLs of Abiquo API workflow methods

Introduction to workflow

When a user requests a deploy, reconfigure or undeploy, your organization may require an automatic or manual intervention.

The Abiquo workflow feature can suspend user tasks, send details of them to a workflow connector (which will interact with a workflow tool), and wait for a response.

To use the Abiquo workflow feature, create a connector for integration with your workflow system.
The workflow connector should receive HTTP requests, process them and obtain a response from your workflow system, then respond to Abiquo.
Your workflow system can be a sophisticated tool that defines and coordinates different workflows with 3rd-party components or departments, and so on.
Or it could be a simple email notification system that asks for your managers' click of approval.

Workflow notes

Should I use Workflow or Outbound API? If you do not need to suspend tasks in Abiquo until responses are received from the workflow tool, Abiquo recommends that you use the Outbound API
You cannot modify and continue a job that has been paused by the workflow feature, you can only continue or cancel it. In the workflow feature, Abiquo creates the user's job and pauses it before it goes to the virtual factory

The Abiquo workflow feature controls the deploy, reconfigure and undeploy of VMs and virtual appliances (groups of VMs)

This diagram shows a simplified process of how Abiquo deploy will function with workflow.

When the user requests a deploy, undeploy or reconfigure of a VM, Abiquo will check that they are allowed to perform this action and that resources are available.
Abiquo then creates the job and holds it. The VM displays a status of "Waiting for review".
Abiquo sends a message to the workflow endpoint with the information about the user's task(s) and the link(s) to continue or cancel the task(s)
The workflow tool can send an answering request to Abiquo to continue or cancel the task(s)
Abiquo will proceed accordingly

Note that there are also two manual requests in the Abiquo API or UI (Manage workflow tasks)

The user can cancel their own task(s)
The manager user can continue or cancel the task(s)

Create a workflow integration

To create a workflow integration do these steps:

Create a workflow connector to process workflow requests:
1. Receive a POST request by HTTP with details of the requested operation. Abiquo sends the request to continue a task as a webhook (Webhook ). See #Sample Request to Workflow Connector
  1. Check the details and #Links in the request object
  2. If necessary, obtain more information from the Abiquo API or other systems
2. Determine if the user request should be continued or cancelled, using the workflow tool or manually
3. Send a POST request to the continue or cancel link in the original workflow request object
  1. You can add a plain text message body, which will be added to the task
  2. See #Sample workflow continue request and #Sample workflow cancel request
In Abiquo:
1. Create a role for the workflow connector to access Abiquo with the following privileges
  1. Manage workflow - WORKFLOW_OVERRIDE privilege
  2. Sufficient privileges to enable the user to read the data that the workflow connector needs to access
2. Create an Abiquo workflow user with the new role
3. You can register the workflow connector in the Abiquo tenants using OAuth. See Authentication#OAuthv1.0VersionAAuthentication
4. #Configure workflow on the platform
5. #Configure workflow per cloud tenant

Workflow integration reference

This section provides more details about the workflow integration.

Sample request

This is a sample request sent to the workflow connector by Abiquo. It shows the Task DTO of a deploy task with three jobs: schedule, configure and power on.

For testing, you can use a request inspection service, such as http://requestb.in , which will display the POST request from the Abiquo API

Header text:

POST request

FORM/POST PARAMETERS
None


HEADERS
Content-Length: 2626
User-Agent: Java/1.8.0_51
Total-Route-Time: 0
Accept: text/plain
Connection: close
Host: requestb.in
Content-Type: application/vnd.abiquo.tasks+json
Cache-Control: no-cache
Pragma: no-cache
X-Request-Id: 0c069e96-ccc2-4338-8b76-c911314b136c
Connect-Time: 1
Via: 1.1 vegur

Request payload:

{  
   "links":[  

   ],
   "collection":[  
      {  
         "links":[  
            {  
               "diskController":null,
               "diskControllerType":null,
               "diskLabel":null,
               "length":null,
               "title":null,
               "hreflang":null,
               "rel":"self",
               "type":null,
               "href":"cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/4/tasks/d89acdfd-e875-4d45-aacc-3c4b86b98572"
            },
            {  
               "diskController":null,
               "diskControllerType":null,
               "diskLabel":null,
               "length":null,
               "title":null,
               "hreflang":null,
               "rel":"parent",
               "type":null,
               "href":"cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/4/tasks"
            },
            {  
               "diskController":null,
               "diskControllerType":null,
               "diskLabel":null,
               "length":null,
               "title":null,
               "hreflang":null,
               "rel":"target",
               "type":null,
               "href":"cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/4"
            },
            {  
               "diskController":null,
               "diskControllerType":null,
               "diskLabel":null,
               "length":null,
               "title":null,
               "hreflang":null,
               "rel":"user",
               "type":null,
               "href":"admin/enterprises/1/users/1"
            },
            {  
               "diskController":null,
               "diskControllerType":null,
               "diskLabel":null,
               "length":null,
               "title":null,
               "hreflang":null,
               "rel":"cancel",
               "type":null,
               "href":"cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/4/tasks/d89acdfd-e875-4d45-aacc-3c4b86b98572/action/cancel"
            },
            {  
               "diskController":null,
               "diskControllerType":null,
               "diskLabel":null,
               "length":null,
               "title":null,
               "hreflang":null,
               "rel":"continue",
               "type":null,
               "href":"cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/4/tasks/d89acdfd-e875-4d45-aacc-3c4b86b98572/action/continue"
            }
         ],
         "taskId":"d89acdfd-e875-4d45-aacc-3c4b86b98572",
         "userId":"1",
         "type":"DEPLOY",
         "ownerId":"4",
         "state":"QUEUEING",
         "creationTimestamp":1459348714,
         "timestamp":0,
         "jobs":{  
            "links":[  

            ],
            "collection":[  
               {  
                  "links":[  

                  ],
                  "id":"d89acdfd-e875-4d45-aacc-3c4b86b98572.d4759c5f-7661-48aa-a713-9fd324e58873",
                  "parentTaskId":"d89acdfd-e875-4d45-aacc-3c4b86b98572",
                  "type":"SCHEDULE",
                  "description":"Deploy task's schedule on VM with id 4",
                  "state":"PENDING",
                  "rollbackState":"UNKNOWN",
                  "creationTimestamp":1459348714,
                  "timestamp":0
               },
               {  
                  "links":[  

                  ],
                  "id":"d89acdfd-e875-4d45-aacc-3c4b86b98572.2d19f782-8266-480a-a492-cea61dfbd82f",
                  "parentTaskId":"d89acdfd-e875-4d45-aacc-3c4b86b98572",
                  "type":"CONFIGURE",
                  "description":"Deploy task's configure on VM with id 4",
                  "state":"PENDING",
                  "rollbackState":"UNKNOWN",
                  "creationTimestamp":1459348714,
                  "timestamp":0
               },
               {  
                  "links":[  

                  ],
                  "id":"d89acdfd-e875-4d45-aacc-3c4b86b98572.d40ca41d-02cf-49cd-a363-5894fe5e723e",
                  "parentTaskId":"d89acdfd-e875-4d45-aacc-3c4b86b98572",
                  "type":"POWER_ON",
                  "description":"Deploy task's power on on VM with id 4",
                  "state":"PENDING",
                  "rollbackState":"UNKNOWN",
                  "creationTimestamp":1459348714,
                  "timestamp":0
               }
            ],
            "totalSize":null
         }
      }
   ],
   "totalSize":null
}

Workflow links

All links sent to the workflow endpoint will contain only the path segment of the URI because Abiquo might be behind a load balancer, firewall, etc.
So the workflow connector must have the IP address of the Abiquo server.

For example, consider an API on a host with IP 10.0.0.4, but exposed publicly with company.com/abiquo/api.
If Abiquo sent the full URI, the links would be in the form http://10.0.0.4/api/object/task.
However, the API might not be accessible at that IP (due to IPtables, firewalls, etc) but at http://company.com/abiquo/api/object/task.
When it is building the links, Abiquo does not have all the information, e.g. company.com/abiquo/api, so it sends the link with the href object/ task.

Sample workflow continue request

An example request that the workflow tool would send to Abiquo to continue the task. Note the message text is "accepted".

See https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#continue-a-task-on-avirtual-machine

Sample workflow cancel request

An example of a request that the workflow tool would send to Abiquo to cancel a task. Note the message text is "cancelled".

See https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#cancel-a-task-on-avirtual-machine

Configure workflow in the platform

The Workflow endpoint will apply globally for all cloud tenants and users. By default the feature is disabled for the platform and for each tenant.

Privileges: Access Configuration view, Modify configuration data

To configure the workflow in the GUI:

Go to Configuration → General.
Enter the Workflow endpoint. The workflow endpoint is the URL of the web application that connects to the workflow tool
- Abiquo will send tasks for workflow review to this URL
  - The sample endpoint shown in the following screenshot is for testing only
Click the checkbox to Enable workflow for the platform
Save

After you enable workflow for the platform, enable it for each tenant through the UI or the API.

To configure workflow integration using the API do these steps.

Use the SystemPropertiesResource and perform two POST requests in this order to set:

client.main.workflowEndPoint
- URL for communication with the workflow tool
client.main.workflowEnabled
1. 0 = false; disabled (default value)
2. 1 = true; enabled

Configure workflow per cloud tenant

To enable workflow for a tenant in the UI:

Go to Users → edit the enterprise
Go to General and select Enable workflow.

It is also possible to enable workflow for an enterprise using the API.

To configure workflow for an individual enterprise, retrieve the enterprise using the API, then modify the workflow attribute and use a put request to save your modification.

Get an enterprise
You can get an enterprise list and filter by text in the enterprise name.
For example, if the enterprise name is "enterprise_bar_enterprise", it can be found using the "has" parameter with the text "bar".
For details of the GET request to list enterprises, see https://wiki.abiquo.com/api/latest/EnterprisesResource.html#list-enterprises.
By default the workflow attribute is set to false.
Update the enterprise.
From the list, copy the enterprise entity only and set the "workflow" attribute to "true".
Then perform a put request to update the enterprise.
For details of the PUT request, see https://wiki.abiquo.com/api/latest/EnterprisesResource.html#update-an-enterprise

Manual workflow operations

If there is a problem, a user can always cancel their own tasks.

Administrators can manually continue or cancel their users' tasks if they have the following privileges.

Table of privileges for cancelling VM workflow tasks

Privilege	Access Virtual datacenters view	Manage users	Manage users of all enterprises

Privilege	Access Virtual datacenters view	Manage users	Manage users of all enterprises
Cancel own tasks
Cancel your enterprise users' tasks
Cancel tasks for all users

Table of privileges for continuing VM workflow tasks

Privilege	Manage workflow	Manage users	Manage users of all enterprises

Privilege	Manage workflow	Manage users	Manage users of all enterprises
Start your own tasks
Start your enterprise users' tasks
Start tasks for all users

Manage workflow tasks in the UI

Cancel your own queued tasks using the API

To cancel your own tasks in the API:

Use the following request to obtain the pending tasks
GET /api/admin/enterprises/{idEnterprise}/users/{idUsers}/action/pendingtasks
Note that "action" is used in this path because the tasks are not performed on the user entity.
These tasks are ordered by time in descending order, with the capacity to filter tasks. In each task there is a cancel link.
For more details, see https://wiki.abiquo.com/api/latest/UsersResource.html#list-pending-tasks-on-workflow-tool
Send a request to the cancel link to set the task to CANCELLED.
If you send a message body, Abiquo will store the content in the extradata of the task.
For more details, see https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#cancel-a-task-on-a-virtual-machine

Cancel or continue tasks for other users

If a user has the WORKFLOW_OVERRIDE API privilege, they can manage workflow tasks for the users who belong to the enterprises in their scope.
This means they can start (continue, update to PENDING state) or cancel (update to CANCELLED) tasks in the QUEUEING state.

To manage tasks of your users:

Retrieve all pending tasks, with a GET of /api/admin/enterprises/{identerprise}/action/pendingTasks.
For more details, see https://wiki.abiquo.com/api/latest/EnterprisesResource.html#list-tasks-waiting-on-workflow-tool
OR
Filter tasks by user and retrieve pending tasks for any of the tenant's users, with a GET of /api/admin/enterprises/{idEnterprise}/users/{idUsers}/action/pendingtasks.
Perform a POST on the continue link (tasks/{uuidTask}/action/continue) or cancel link (tasks/{uuidTask}/action/cancel).
If a message is provided the content will be stored as extradata with the key workflow.

URLs of Abiquo API workflow methods

The paths to access workflow through the API are:

Path	User	Comments

Path	User	Comments
api/object/task e.g. api/cloud/virtualdatacenters/{idvdc}/virtualappliances/{idvapp}/virtualmachines/{idvm}/tasks	Workflow user	Base of link that workflow connector uses to cancel or continue tasks
api/admin/enterprises/{identerprise}/user/{iduser}/action/pendingtasks	User	Get own tasks (user can then cancel own tasks, with the above link)
api/admin/enterprises/{identerprise}/action/pendingtasks	Tenant admin	User can get all tasks for the enterprise