VMware vRealize Orchestrator User’s Manual
DO C U MENT T Y P E / 1
vRealize Orchestrator Coding
Design Guide
Development Guide
TE CH N I CA L W H IT E PA PE R
MA RC H 2 0 16
VE RS IO N 1. 0
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 2
Table of Contents
Introduction ...................................................................................................................................... 5
Design .............................................................................................................................................. 5
Solution Design ........................................................................................................................... 5
Bottom Up Approach ................................................................................................................... 6
Workflow Separation ................................................................................................................... 6
Individual Workflows .................................................................................................................. 7
What is the Purpose of the Workflow ..................................................................................... 7
Who Executes the Workflow................................................................................................... 7
What Steps are Necessary ....................................................................................................... 7
What Information is Required to Complete the Steps ............................................................. 7
Where is the Information ......................................................................................................... 7
Third-party Integrations ............................................................................................................... 8
Northbound Integration ........................................................................................................... 8
Southbound Integration ........................................................................................................... 8
Development .................................................................................................................................... 9
Clean Up Your Code .................................................................................................................... 9
Workflow Folders ........................................................................................................................ 9
Modules or Action Folders ........................................................................................................ 10
Naming Guidelines .................................................................................................................... 10
Workflows or Actions ........................................................................................................... 10
Scripting ................................................................................................................................ 10
Configuration Workflow ............................................................................................................ 11
Packaging .................................................................................................................................. 11
How to Clean Up the Package ............................................................................................... 12
How to Export the Read-Only Package ................................................................................. 12
Workflow Internals .................................................................................................................... 12
Readability ............................................................................................................................ 12
Attributes ............................................................................................................................... 13
Scriptable Tasks and Actions ..................................................................................................... 14
JavaScript Style ..................................................................................................................... 15
If Conditions .......................................................................................................................... 15
Loops ..................................................................................................................................... 17
Documentation .......................................................................................................................... 17
Workflow and Action Documentation .................................................................................. 17
Comments .............................................................................................................................. 18
UI Presentations ......................................................................................................................... 18
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 3
Configuration Elements ............................................................................................................. 18
Error Handling ........................................................................................................................... 19
Input Validation ......................................................................................................................... 20
Logging...................................................................................................................................... 21
Testing ....................................................................................................................................... 21
Unit Tests .............................................................................................................................. 21
Integration Tests .................................................................................................................... 22
vRealize Orchestrator Platform Awareness ................................................................................... 23
Serialization and Resuming Workflows .................................................................................... 23
Performance Considerations ...................................................................................................... 23
vCenter Plugin Querying ....................................................................................................... 26
Calling Actions ...................................................................................................................... 27
XML .......................................................................................................................................... 27
XML Header.......................................................................................................................... 27
XML Namespaces ................................................................................................................. 28
Navigating XML ................................................................................................................... 28
JSON & JavaScript objects........................................................................................................ 28
Recommended Reading ................................................................................................................. 29
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 4
DATE
VERSION
DESCRIPTION
March 2016
1.0
Initial version.
Revision History
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 5
Introduction
This document describes the best practices for using vRealize Orchestrator and its design, development, and
configuration functionality. The depth of coding design presented in this document is from a macro level, which
ensures that the design fits well within the greater architecture of products used, down to the micro level that includes
JavaScript coding guidelines to be used in vRealize Orchestrator. A full life cycle of vRealize Orchestrator
development involves a multi-phased approach that includes design, development, testing, and release best practices.
A clean code development approach was applied to vRealize Orchestrator development. This approach can be applied
to any programming language or product to help create well-written code. Many of the base concepts that are discussed
in the book Clean Code by Robert C. Martin are used in this document. It is recommended that you familiarize yourself
with the content in that book. For more book recommendations, see Recommended Reading.
Design
You should understand the different components and their interactions to design an overall solution. This section
provides guidance with different design process approaches and discusses several methods that you can consider for
the overall design as it transitions from the solution, to the subcomponents, to the individual workflow.
Solution Design
You should design the overall solution by using vRealize Orchestrator workflows as drop-in placeholders for the
necessary tasks and to use as stubs in the design process. You can use this approach to identify related tasks that can be
pulled out into separate, self-contained workflows or actions that can help you identify how much time to budget for
each high-level task. During the solution design, you should test the aggregate workflows for completion to achieve
the desired use cases from the solution. Each use case must be supported by one master workflow, which relies on
subsequent workflows to achieve the desired outcomes. Similarly, each component’s workflow, action, or resource,
contributes a specific well-defined function that supports one or more master workflows to deliver desired use cases.
During the design phase, a clear distinction is made between automation and orchestration workflows.
Automation
Orchestration
components to deliver results required for a specific use case.
Master workflow design must encompass and deliver on the full lifecycle considerations, including use cases for
provisioning, reconfiguring, and retiring resources in the VMware ecosystem. Additionally, the master workflow
should be designed for availability with validation performed between each step to enable pause, rollback, or failure
functionality.
This document uses many development details targeted at delivering a better solution, but a key guiding principle to the
overall design is that it should be done purposefully and with clear and expected outcomes between the different
components. This methodology is referred to as design by contract. For more information, see the Wikipedia definition
of design by contract. Although the solution for a single use case is often designed and developed by a single person, if
you considered that the various components of your solution could be developed by others, then an agreement would
be necessary between all of the developers with respect to what the expected inputs and outputs are to be, and what
type of error handling should be covered in each component. For example, if one of your actions is to provide an array
of objects to calling workflows, validating the code before sending it back can prevent the callers from validating it
themselves, such as not-null or not-empty checks, which results in precarious exceptions in the system elsewhere if the
callers did not remember to explicitly perform those checks. Additionally, you should use the
workflows or actions to document the behaviors of these edge cases or error conditions.
is achieved by an individual workflow, action, or resource to accomplish a discrete task.
is achieved by a Master Workflow that integrates and coordinates execution of such automation
Description
fields of the
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 6
Bottom Up Approach
To achieve the optimal design and clean code, consider how the components should be designed to work with each
other if the development is done from the bottom up, which is the recommended development approach. The design of
the solution will become clearer by constructing the fundamental building blocks for your solution, which are typically
the actions, which convert to the mid-level workflows, and finally are the main workflows that are the entry points to
your overall solution.
For example, if the goal is to integrate vCloud Director with a third-party SOAP system for a given VM life cycle
event, you should use the following guidelines:
Potentially use a separate SOAP tool to achieve some communication with the third-party system.
Create a workflow in vRealize Orchestrator that does a hard-coded SOAP call to the third-party system to validate
the communication and protocol compatibility.
Pick out elements of the hard-coded call and make them variables and inputs into the workflow, such as the SOAP
operation and the XML body.
Create a matching action which takes the same inputs and have your workflow call this action. The workflow itself
now became the basis for your Test suite, and should not be called on its own anymore now that the action is
available.
Create the mid-level workflows or actions that provide the business logic to achieve the simple inputs requested by
your SOAP action. For example, a mid-level workflow or action can be tailored to a specific SOAP call in the
third-party system, and it can take inputs and create the appropriate XML body to paste to the generic SOAP action
already created.
Create a workflow that takes a set of key-value pairs (as a Properties object) and calls your mid-level workflows.
This workflow should still not mention vCloud Director.
Create a workflow which is specific to vCloud Director that takes on vCloud Director objects and converts them to
simpler objects that can call the main system-agnostic workflow that you created.
Workflow Separation
Separate workflows into sets of smaller workflows and actions, preferably so that each one can be run standalone. This
prevents global variables, attributes or inputs, of a workflow from being intertwined with most workflow elements,
which makes it harder to read, debug issues, and perform testing.
Separating workflows also provides readers the ability to read your code more efficiently and be able to quickly locate
a particular use case, knowing that no other aspects are having an impact since it relies on a sub workflow or action.
Additionally, readers can take passes at your code so that someone who understands 40 percent of it can still
understand the entire functionality, while someone who understands 90 percent of it understands it in depth. If the
workflows are not separated into sub workflows or actions, then someone who has read 40 percent of your code
sequentially will only understand 40 percent of the functionality, and would need to read nearly 100 percent of the code
before understanding most of the functionality.
The structure of vRealize Orchestrator workflows or actions, and even code itself, is analogous to the structure of a
reference book. A book has a table of contents, where you can very quickly see what the book contains, and it has
chapters, headings, sub-headings, and finally the words. Each of these components provides a particular level of detail
when looked at holistically.
Actions can return only one item, while workflows can return multiple items, which might also influence your design.
However, avoid returning more than just a couple of items for workflows and consider breaking out the workflow into
separate workflows or actions, or combining the result into a logical object held in a Properties or JavaScript (Any)
object if multiple items are to be returned.
Sever the connection between products or interfaces as soon as possible, and only pass around vRealize Orchestrator
simple objects where possible. For example, workflows initiated by vRealize Automation tend to interact heavily with
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 7
vRealize Automation custom properties. Pull in these key values at the start of the workflow and pass around the
attributes into other workflow elements, workflows, or actions, so that any of those can be used separately for another
parent orchestrating product, such as vCloud Director or another external system calling into vRealize Orchestrator's
REST interface. This also simplifies unit testing, because the inputs to workflows can be easily mocked up.
Individual Workflows
For a single workflow, you should answer the questions presented in this section. Your answers will provide you with
an understanding of what the workflow looks like and what attributes you need. Determining what steps are necessary,
what information is needed for these steps, and where the information comes from is usually iterative, so you should
start with a high-level design that uses the required steps, then determine what information is not available directly, and
add another step before that.
What is the Purpose of the Workflow
Specify the tasks the workflow automates, the expected changes the workflow makes in the environment, and the
expected output. Also specify the expected circumstances. Your answer to this question becomes a candidate for the
Description field of the workflow.
Who Executes the Workflow
Workflows can be executed by human users such as in the vRealize Orchestrator client, vSphere Web Client, vRealize
Automation Advanced Service Designer. They can also be executed by a custom portal and the workflow scheduler,
policies, external systems by using the API such as vRealize Automation IaaS callouts, or other workflows such as
Library workflows.
Depending on your answer to this question, the workflow would have different input parameters and presentation. For
example, a workflow designed for human consumption should be as easy to use as possible, so fewer input parameters,
and a lot of presentation logic to support the user is desired. To allow flexible reuse in different situations, a library
workflow that is being called by other workflows has a lot of input and output parameters and no presentation logic
because this is not applied when calling the workflow from other workflows.
What Steps are Necessary
Specify the different steps needed to achieve what the workflow should do. Steps that might be helpful in another
context are good candidates to be modularized.
What Information is Required to Complete the Steps
The answer to this question provides an understanding about what attributes are needed for the workflow.
Where is the Information
Information can be hard-coded in workflow attributes or a script (not recommended), read from configuration
elements, passed to the workflow as an input parameter, or calculated dynamically by an additional logic step earlier in
the workflow.
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 8
Third-party Integrations
When designing integrations for third-party systems, it is important to understand the proper integration direction, and
the limitations of the external systems will dictate your development as well. For example, scalability limitations of
the system vRealize Orchestrator integrating with running many concurrent workflows within vRealize Orchestrator is
not a problem but does the third-party system support concurrent requests?
Northbound Integration
An external system calls vRealize Automation or vRealize Orchestrator, and likely controls the outcome of the
workflow. Example use cases:
External portal, like Service Now, or an existing customer portal calls vRealize Automation
Based on certain tickets in a helpdesk system, vRealize Orchestrator workflows should be executed
vCloud Director blocks tasks executing vRealize Orchestrator workflows
Monitoring system or vRealize Operations Manager calls vRealize Orchestrator workflows for automatic
remediation.
To resume vRealize Orchestrator workflow after calling out to the external system, southbound integration
asynchronously.
To implement such integrations, different strategies are possible:
Using the northbound REST API of vRealize Orchestrator or vRealize Automation, the external system has to
support making REST calls
Using cloud client, the external system has to support running CLI commands
Using vRealize Orchestrator plug-ins that provide trigger in combination with policies, SNMP, AMQP, and
vCenter plug-ins provide triggers
"Passive" integration: Implement a polling strategy into the external system to pick up work using vRealize
Orchestrator workflows, for instance using the workflow scheduler.
Southbound Integration
In this case vRealize Orchestrator workflows call out the external systems to automate tasks within those
systems. Example use cases:
As part of vRealize Automation lifecycle: Get an IP address from IPAM system, make some changes in Active
Directory, setup load balancer and firewall rules, create backup jobs, CRUD (Create, Read, Update, Delete) entries
in a CMDB (Change Management Database), include system in a monitoring solution, and so on.
Automation of hardware components like storage, network, for non-VM lifecycle related tasks. Very often in
combination with exposing these workflows to vRealize Automation portal by using Advanced Service Designer
Automation of day to day tasks in vSphere administration: Reporting, Snapshot handling, migrations
Using vRealize Orchestrator to “abstract” legacy systems and provide automation capabilities for them. One real
world example included a very old CMDB created in-house that did not provide proper “modern” web service API
via REST or SOAP, but only a limited command line interface in terms of scalability and reliability. Building a set
of vRealize Orchestrator workflows for common CMDB automation tasks allowed to use input validation, load
limitation and error handling within the workflows, so that other external systems can now use the vRealize
Orchestrator REST API to call this specific set of CMDB workflows.
vRealize Orchestrator Coding Design Guide
T E C H N I C AL W H I T E P A P E R / 9
Development
You should use the guidelines in this section as you develop your code.
Clean Up Your Code
You should strive to clean up your code as you develop, rather than waiting until the end, for the following reasons:
Waiting until the end to clean up your code is dangerous to the overall functionality that you worked hard to
achieve.
Five days of developing clean code and workflows produces much cleaner results than 4.5 days of coding plus 0.5
days of cleanup.
You often will not have time for cleanup if that is the only item remaining. If you spent 4.5 days developing clean
code, you still have 0.5 days of development time that could be used towards an actual portion of the use case so
that it cannot be ignored.
You cannot provide reusable unit tests since your code is unlikely to be cleaned up to a modular format.
You cannot valuably engage someone in a code review at the very end of your development as there is too much
risk to the overall functionality if any larger changes are proposed, and you might be hesitant or defensive about
making those changes because of how daunting the task is when it occurs at the end.
Similar to the way that nothing compares to coding because it can be challenging and it is fun to overcome the
challenges, developing clean code provides another opportunity to choose the paths that are more ideal than others. The
results are innumerable, yet the journey is very gratifying.
Workflow Folders
Organize workflows into a customer-specific folder for all work done for the customer, and a common folder for work
that can be reused without any changes. Create wrappers around library workflows or actions, if you want them to fit
your needs better and avoid copying them.
Loading...