Ruby 2.0.0 implementation of vCenter Orchestrator REST API

gem install vcoworkflows-ruby2 -v 0.2.3


Build Status Coverage Status Inline docs


Warning: This is a Fork of the vcoworkflows gem to make it compatible to ruby 2.0.0. We don't guarantee that this repo will work for any other ruby versions. So if you don't need ruby 2.0.0 support, please use the original gem.

vcoworkflows provides a Ruby API for finding and executing vCenter Orchestrator workflows. You can search for a workflow either by name or by GUID, populate the resulting VcoWorkflows::Workflow object's input parameters with the required values, and then request that the the configured workflow be executed by vCenter Orchestrator.

Under the hood, communcations with vCenter Orchestrator is done via its REST API, and all the REST heavy-lifting here is done by the fine and reliable rest-client gem. HTTP Basic authentication is used with vCenter Orchestrator, and the username and password can either be passed as command-line arguments or set as environment variables ($VCO_USER and $VCO_PASSWD).


  • rest-client is used for all the communications with vCenter Orchestrator.
  • thor is used for the command-line utilities.

The only external dependency is vCenter Orchestrator.


vcoworkflows is distributed as a ruby gem.

Add this line to your application's Gemfile:

gem 'vcoworkflows', github: 'wintermeyer/vcoworkflows-ruby2'

And then execute:

$ bundle

Or install it yourself as:

$ gem install vcoworkflows


Quick example:

require 'vcoworkflows'
workflow =
  'Request Component',
  url: '',
  username: 'jdoe',
  password: 's3cr3t'

All the necessary interactions with a Workflow in vCenter Orchestrator are available via the VcoWorkflows::Workflow class.


Configuration File

The configuration file format is a simple JSON document with the following keys:

  • url - (Required) The vCO server URL (i.e., '')
  • username - (Optional) User to authenticate as. Likely in the form DOMAIN\\username (be sure to escape backslashes). If not present, this can be provided via the command-line parameter --username or by setting $VCO_USER in the environment.
  • password - (Optional) Password to authenticate with. If not present, this can be provided via the command-line parameter --password or by setting $VCO_PASSWD in the environment.
  • verify_ssl - (Optional) Whether to perform TLS/SSL certificate validation. Defaults to true.

An example configuration file, then, would look like:

  "verify_ssl": true,
  "password": "s3cr3t",
  "username": "EXAMPLE\\jdoe",
  "url": ""

If url, username and password are not provided when created a new Workflow object, VcoWorkflows will look for a configuration file at:


Alternately, you can specify a different configuration file when constructing the Workflow object:

workflow =
  'My Workflow',
  config_file: '/tmp/vcoworkflow.json`

VcoWorkflows::Config class

For additional control, you can create a VcoWorkflows::Config object and hand that to the Workflow constructor. If you provide no parameters, it will attempt to load the default configuration file, as above:

config =
workflow ='My Workflow', config: config)

You can also specify a non-default configuration file:

config = '/tmp/myconfig.json')

And, of course, you can set all the required parameters yourself if you don't want or need to use a configuration file:

config =
  url: '',
  username: 'jdoe',
  password: 's3cr3t'
workflow ='My Workflow', config: config)

Selecting a Workflow

It is possible to select a Workflow by GUID (as divined by the vCenter Orchestrator client) or by specifying the Workflow's name. If specifying by name, however, an exception will be raised if either no workflows are found, or multiple workflows are found. Therefor, GUID is likely "safer". In either case, however, the workflow name must be given, as in the example above.

Selecting a workflow by GUID is done by adding the id: parameter when creating a new Workflow object:

workflow =
  'My Workflow',
  id: '6e04a460-4a45-4e16-9603-db2922c24462',
  url: '',
  username: 'jdoe',
  password: 's3cr3t'

Executing a workflow

To execute a workflow, set any input parameters to appropriate values (if required), then send call execute. This will return an execution ID from vCenter Orchestrator, which identifies the run you have requested. The execution ID is also preserved in the Workflow object for simplicity.

Setting parameters individually:

workflow.parameter('name', 'a string value')
worfklow.parameter('version', 2)
workflow.parameter('words', %w(fe fi fo fum))

Setting parameters via a hash:

workflow.parameters = { 'name'    => 'a string value',
                        'version' => '2',
                        'words'   => %w(fe fi fo fum) }

Then execute:


Checking an execution status

You can then get a Workflow Token from the Workflow, which will contain state and result information for the execution.

wf_token = workflow.token(workflow.execute)

The WorkflowToken can be used to determine the current state and disposition of a Workflow execution. This can be used to periodically check up on the execution, if you want to follow its status:

finished = false
until finished
  sleep 5
  # Fetch a new workflow token to check the status of the workflow execution
  wftoken = workflow.token
  # If the execution is no longer alive, exit the loop and report the results.
  unless wftoken.alive?
    finished = true
    wftoken.output_parameters.each { |k, v| puts " #{k}: #{v}" }

Fetching the execution log

For any workflow execution, you can fetch the log:

# ... some time later
log = workflow.log
puts log

If you have the execution ID from a previous execution:

log = workflow.log(execution_id)
puts log

Querying a Workflow from the command line

The vcoworkflows command line allows you to query a vCO server for a workflow, as well as executions and details on a specific execution.

$ vcoworkflows query "Request Component" \

Retrieving workflow 'Request Component' ...

Workflow:    Request Component
ID:          6e04a460-4a45-4e16-9603-db2922c24462
Version:     0.0.33

Input Parameters:
 coreCount (string) [required]
 ramMB (string) [required]
 onBehalfOf (string) [required]
 machineCount (string) [required]
 businessUnit (string) [required]
 reservation (string) [required]
 location (string) [required]
 environment (string) [required]
 image (string) [required]
 runlist (Array/string) [required]
 nodename (string) [required]
 component (string) [required]
 attributesJS (string) [required]

Output Parameters:
 result (string) [required]
 requestNumber (number) [required]
 requestCompletionDetails (string) [required]

You can also retrieve a full list of executions, or only the last N:

$ vcoworkflows query "Request Component" \
    --server= \
    --executions --last 5

Retrieving workflow 'Request Component' ...

Workflow:   Request Component
ID:           6e04a460-4a45-4e16-9603-db2922c24462
Version:      0.0.33

2014-12-19T20:38:18.457Z [ff8080814a1cb55c014a6445b85b7714] completed
2014-12-19T20:49:04.087Z [ff8080814a1cb55c014a644f925577cf] completed
2014-12-19T21:00:25.587Z [ff8080814a1cb55c014a6459f87278c0] completed
2014-12-19T21:25:04.170Z [ff8080814a1cb55c014a64708829797f] completed
2014-12-19T21:43:46.833Z [ff8080814a1cb55c014a6481a9927a78] completed

To get the logs from a specific execution:

vcoworkflows query "Request Component" \
    --server= \
    --execution-id ff8080814a1cb55c014a6481a9927a78 \

Retrieving workflow 'Request Component' ...

Fetching data for execution ff8080814a1cb55c014a6481a9927a78...

Execution ID:      ff8080814a1cb55c014a6481a9927a78
Name:              Request Component
Workflow ID:       6e04a460-4a45-4e16-9603-db2922c24462
State:             completed
Start Date:        2014-12-19 13:43:46 -0800
End Date:          2014-12-19 13:55:24 -0800
Started By:

Input Parameters:
 coreCount = 2
 ramMB = 2048
 onBehalfOf =
 machineCount = 1
 businessUnit = aw
 reservation = nonprodlinux
 location = us_east
 environment = dev1
 image = centos-6.6-x86_64-20141203-1
 runlist =
  - role[base]
  - role[api]
 nodename =
 component = api
 attributesJS =

Output Parameters:
 result = SUCCESSFUL
 requestNumber = 326.0
 requestCompletionDetails = Request succeeded. Created vm00378.

2014-12-19 13:43:46 -0800 info: jdoe: Workflow 'Request Component' has started
2014-12-19 13:43:59 -0800 info: jdoe: Workflow is paused; Workflow 'Request Component' has paused while waiting on signal
2014-12-19 13:55:23 -0800 info: jdoe: Workflow 'Request Component' has resumed
2014-12-19 13:55:24 -0800 info: jdoe: Workflow 'Request Component' has completed

Current limitations

General vCO REST API functionality

This gem is very specifically targeted at operation of workflows within vCO. As such, anything that was not necessary or required to be able to operate workflows has not yet been included.

Cancellation / Termination of running workflows

There is currently no facility to cancel a running workflow. This will be added at some point in the future.

Parameter Types

Currently, there is no included support for complex parameter types (i.e., anything other than Strings, Numerics, or Arrays of same). This is not to say they cannot be used, but you will need to marshall vCO object parameters into an appropriately-constructed Hash to pass as the parameter value, such that when the values are converted to JSON for the actual REST call, they are properly constructed for vCO.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

License and Authors

Copyright 2014 ACTIVE Network, LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.