This article explains in detail how workflows can be started by cloud users, operators or automatically in a vCloud Director context.
What is needed to start a vRealize Orchestrator workflow?
Contents
To start a workflow, the vRealize Orchestrator engine needs three pieces of information:
- The workflow id. In the workflow library of an orchestrator server there are typically hundreds of workflows, sorted in a tree structure. It is possible (though not recommended) to have multiple workflows with the same name. All workflows however are identified by a unique id, which is shown in the “General” tab of the client.
- An authenticated user. No matter what mechanism is used to start the workflow, they all require a user being authenticated against the vRO service. vRealize Orchestrator can be configured to authenticate against the Identity Management Service of a vSphere Platform Service Controller or a vRealize Automation IDM.
- The workflow’s input parameter values. The workflow developer can specify input parameters needed within the workflow logic. These parameters contain of a type and a description, the values have to be provided by whoever starts the workflow.
Start a workflow from vRealize Orchestrator Client
vRealize Orchestrator (vRO) comes with a stand-alone java-based client application that can be installed on an operator’s system, or started directly from browser via Java WebStart technology. This client is the main tool to develop the workflows in first place, but it also allows to run and monitor workflows.
When workflows are being started from the vRealize Orchestrator client, the user logged-in to the client has to provide values for the input parameters. All input presentation logic defined for the workflow is processed before the workflow starts.
Starting a workflow from the vRO client allows the workflow developer to run the workflow in debug mode. In this mode the workflow can be interrupted by breakpoints, and manually proceeded element-by-element. In debug mode it’s also possible to watch and even manipulate the values of workflow attributes during runtime.
In a vCloud Director environment the workflows are mostly part of an end-to-end automation, so the option to start workflows from the vRO client is only used during workflow development, or for a few special workflows targeted to a limited group of administrators who have direct access to the vRO client.
Most of the workflow executions are being triggered automatically by one of the following mechanisms.
Starting Workflows from via the REST API
vRealize Orchestrator provides a comprehensive REST API that allows external systems to automate all sorts of tasks. It is possible for example to access the inventory of installed plugins, or import or export workflow packages. And of course it is possible to browse the workflow library and run workflows via the REST API.
The REST API is documented on the vRO server itself with a Swagger based documentation environment, you can access the documentation by browsing to https://your.vroserver:8281/vco/api/docs.
An http POST request to the url https://your.vroserver:8182/vco/api/workflows/<workflow-id>/executions starts the workflow. The request body has to contain the values for the input parameters.
If the call is successful, the API returns with a status 202 ACCEPTED response that contains the workflow execution id in the Location Header.
If there is an error, for instance missing input parameters or a wrong format for them, the API returns with a status 4xx response.
The easiest way to figure out the proper syntax for input parameters is to look at a past workflow execution of the same workflow, by accessing the URL https://your.vroserver:8281/vco/api/workflows/<workflow-id>/executions/<execution-id>, and check the <input-parameters> section of the response there.
Calling vRealize Orchestrator workflows via the REST API is also used under the hood for the workflows that are being published into the vCloud Director Service Library. Here vCloud Director automatically creates a form for the input parameters, and uses the credentials defined by the administrator during registration of the vRO server in vCloud Director to start the workflow.
Scheduling Workflows
For some use-cases, like maintenance or reporting tasks, it is useful to run workflows automatically at certain times. The vRealize Orchestrator server comes with a built-in workflow scheduler, that allows you to schedule workflow executions. When defining the workflow schedule, you also have to specify the input parameters and the user that is used to start the workflow when it’s time.
The workflow scheduler is accessible via the vRO client, or via the REST API with the url https://your.vroserver:8281/vco/api/tasks.
Trigger Workflows via AMQP messages
To use orchestrator workflows as part of the vCloud Director extensibility framework it is needed to start workflow using AMQP messages. As stated in the first article of the series, vCloud Director Blocking Tasks and Service Extensibility both use AMQP as protocol to communicate with external systems. vCloud Director sends AMQP messages to the AMQP broker with routing keys dependent on the situation, the AMQP broker put them into the queues according the configured bindings.
In vRealize Orchestrator you then can configure the AMQP Plugin to subscribe to certain queues of the AMQP broker. With that the subscriptions appear in the AMQP inventory of vRO, and can be used in the policy mechanism of vRO to trigger workflows.
A Policy can be used in vRO to either start a workflow, or to run some javascript logic based on events. These events, like a SNMP trap or an AMQP message are provided by the corresponding plugin. In the definition of the policy, you select the AMQP:Subscription as policy element, and then the “onMessage” event. In the policy details you then can either specify the javascript logic or select the workflow that will be executed whenever a message is received on the queue of the subscription.
It is even possible to have some javascript logic that then calls a workflow programmatically. This allows some more flexibility to dynamically select the workflow based on content of the AMQP message, but also makes the architecture more complex and harder to troubleshoot.
Run Workflows within Workflows
One powerful concept of vRealize Orchestrator is the possibility to modularize and reuse existing workflows and actions. So it is absolutely possible to run workflows within a workflow. There are several ways to do this:
Synchronous call to a workflow element
By using the “Workflow Element” in the palette of the schema editor you can add an existing workflow into the logic of your workflow. Alternatively you can browse the workflow in the “All Workflows” section and drag&drop it onto the schema. When adding the workflow, you have to bind the input parameters of the workflow to call to attributes of your workflow, same for the output parameters of the called workflow.
In this scenario the logic of the included workflow will be executed as part of the calling workflow, within the same execution context. This creates no overhead, the calling workflow will continue when the logic of the included workflow has been completed.
Asynchronous start of a workflow
It is also possible to call other workflows asynchronously, by using the “Asynchronous Workflow”. The called workflow will be started in its own execution context, so a new workflow token will be generated for the called workflow. In the calling workflow you get the id of the created workflow token, so you can add some logic to monitor its status, if needed.
Nested workflow element
The “Nested workflows” element from the palette allows you to select one or more workflows, which will be started in their own execution context. However, in contrary to the asynchronous call here the calling workflow will only continue when all the called workflows are completed.
All the options mentioned above require to select the to-be-called workflow at development time.
Run a workflow from a javascript element
If you want to select the workflow to call dynamically at runtime, you need to start it from a scriptable task element using JavaScript. First you get the object representing the workflow to call, either by specifying it in an attribute or input parameter, or by finding it in the workflow library or identifying by its id. Next you create a properties object that contains the input parameters for the workflow. Then you can use the workflowObject.execute(inputParameters) method to start the workflow. This will return a workflow token object that represents the started workflow, which then can be processed for instance to monitor the status of the workflow execution (more details about this in the next article of the series).
The code below shows an example of this logic. It gets the workflow object by id (in this example a workflow from the vCloud Director Plugin Library “Clone a vApp”), creates the needed input parameters in a properties object and starts the workflow.
|
1 2 3 4 5 6 7 8 9 10 11 |
var cloneVAppWorkflow = Server.getWorkflowWithId(“CE8080808080808080808080808080808080808001266312685778e677578588f”); var workflowInputs = new Properties(); workflowInputs.put(“vapp”, sourceVApp); workflowInputs.put(“vdc”, destinationOrgVdc); workflowInputs.put(“name”, nameOfClonedVApp); workflowInputs.put(“description”, “cloned by vRO workflow”); workflowInputs.put(“deleteSource”, false); workflowInputs.put(“powerOn”, true); workflowInputs.put(“linkedClone”, true); var cloneToken = cloneVAppWorkflow.execute(workflowInputs); |
Because vRealize Orchestrator can run multiple workflows (even multiple instances of the same workflow) in parallel, calling workflows asynchronously is a nice strategy to parallelize tasks. But be aware that each creation of a workflow execution creates load on the vRO server itself, and of course it might create a bottleneck on the endpoint the workflow calls.
Using the Multi-node plugin for vRealize Orchestrator it is even possible to start a workflow on a remote vRO host. More on this in a later article of the series.
Conclusion
vRealize Orchestrator provides different mechanisms to start workflows manually and automatically. Manual start of workflow through the vRO Client is mainly used during workflow development. Publishing workflows into the vCloud Director Service Library uses the vRO REST API in background, while vCloud Director Blocking Tasks can trigger workflows using AMQP. The scheduler is useful for repeating workflows, e.g. for reporting or maintenance processes. For a workflow developer there are different ways available to call existing workflows synchronously and asynchronously.
No matter which mechanism is used to start the workflow, always proper authentication is needed, and the workflow input parameters have to be provided. The result of a workflow execution is a workflow token, which contains the runtime information like status, start time and error messages of the specific workflow run.
In next article of the series will dig deeper into workflow executions, and how to access and monitor their information.
The articles of this series:
