Integra

From Emitrom

Jump to: navigation, search
Integra.png

Contents

Getting Started

Welcome

Integra is designed to making your life easier as an IT administrator. By giving you the necessary tools to automate and orchestrate your infrastructure, you can free resources, reduce errors, and empower your users.

Integra allows you to focus on the “what”, not on the “how”. In other words, your role in the automation world becomes one of constructing workflows by combining different actions via simple operations such as drag and drop. Integra shields you from having to write any code; instead, Integra provides you ready-to-consume actions that you use to craft an IT-blessed workflow. Providing input to those actions is the extent of your involvement as far as actions are concerned.

IT-blessed workflows now become an extremely important piece of your infrastructure. Typical operations that would normally involve multiple parties are now automated and ready to be consumed by your users. Integra frees resources, preventing you or your staff from having to perform manual operations repeatedly. If it can be done once, Integra can automate it. With more time in their hands, IT administrators are now free to concentrate on more pressing issues.

Having more time to do other things is great, but knowing the fact that Integra will perform the exact same operations you configured guarantees that errors will be reduced--if not removed completely. To err is human, and when you take the human factor out of the equation the chances for success increase dramatically.

Scheduling your workflows to run at any given moment in time is a given, but Integra gives you more than that. Integra puts the power of execution at your fingertips, and at those of your users. You have the means to empower your users by allowing them to execute your workflows whenever they need, from wherever they are.

With Integra you are the automator, you are in control. Rule your IT world.

Intended Audience

If you would like to automate an operation in your infrastructure, this guide is for you. You may be an IT administrator that is crossing into the realm of automation, or you may be a seasoned Automation Architect; either way, this document will take you through how to make the most of Integra.

Using This Guide

This guide is divided into several sections with the intent of giving you the most pertinent information as quickly and as concisely as possible.

Release Notes - the very first thing we want you to know is what’s new in the version of Integra that you are using. Refer to the Release Notes to learn about differences between versions.

Setting Up Integra - this section revolves around installing and uninstalling Integra, installing and uninstalling providers on remote machines, and basic configuration.

Integra Building Blocks - in this section we discuss Integra’s four main building blocks: Providers, Actions, Workflows and Schedules. This section contains all the material that you need to understand the pillars that make Integra, and how to automate key operations in your infrastructure.

Accessing Integra - here we break down all of the different mechanisms that you can use to make Integra work for you. This includes the vCenter plugin, the command-line interface and the mobile user interface.

Best Practices - the section title is self-explanatory, as the section covers fine tuning Integra to make the most of it, including networking, security and logging.

Appendix A - the first appendix gives you all the information you need to learn specifically about each Provider: actions that are exposed, version of the target, etc.

Appendix B - here you can find details about Integra’s programmable APIs. Integra includes 7 SDKs and a REST API. This section includes some examples of how to make use of the APIs.

Appendix C - The full End User License Agreement for Integra is included in this section.

System Requirements

The requirements in this section apply strictly to the Integra Reactor. Look at Appendix A for each provider’s own requirements. If you run several providers alongside the Reactor be sure to provide a combined amount of memory and disk space for everything to work in parallel.

Details
Reactor Version 1.1.0
Operating System Any OS where Java 1.7 is supported
Software Required Java Development Kit (JDK) 1.7
Hardware Required 2048 MB of memory; 10 GB of disk space
Default Port 8080 (non-secure) and 8443 (secure)

Common Terms

The following is a list of terms commonly used in Integra.

Terms
Reactor The central component of Integra, orchestrates and streamlines communication between the different client access mechanisms and the providers. The Reactor is responsible for all scheduling and data management.
Provider A provider is a stateless micro-service that encapsulates an end target. You may also think of a provider as a proxy or an agent, whose sole purpose is to expose functionality from an end target. For a list of providers see Appendix A.
Action A provider exposes a set of actions from its end target. Actions represent steps in an Integra workflow.
Workflow An Integra workflow is a collection of one or more actions, which can execute in sequence, in parallel or both.
Task A task is another term for a moment in time when one or more workflows execute. Tasks can run once or they can be repeated. Repeatable tasks have a start and end date.
Schedule A schedule in Integra represents a collection of workflows that execute in parallel. Also, a schedule is a collection of zero (the schedule never runs) or more tasks (all workflows are executed when all tasks are set to run).
Portal Integra’s mobile self-service portal, or portal for short.

Release Notes

What's New in Version 1.1.1 - September 20, 2015

Version 1.1.1 is strictly a bug fix release, as no new features have been added. This version brings even more stability to the Integra Reactor and the Godwit provider, namely:

What's New in Version 1.1.0 - June 22, 2015

Integra 1.1 sets the stage for massive scalability via AWS EC2 Container Services or Google Compute Engine through Docker containers. Additionally, you have even more control over the things that you can accomplish with workflows with the introduction of the Apply Logic action. See below for a complete list of new features and bugs fixed in the 1.1 release.

New features:

Bug fixes:

What's New in Version 1.0.3 - April 21, 2015

New features:

And important bug fixes:

What's New in Version 1.0.2 - March 10, 2015

1.0.2 has several bug fixes and a new provider for SSH. Several of the major fixes included are:

What's New in Version 1.0.1 - February 20, 2015

1.0.1 contains improvements on the Integra installer, log and configuration file locations, and minor enhancements in the vCenter UI--most notably being able to display version information for the providers and the Reactor.

What's New in Version 1.0 - February 2, 2015

1.0 is the first release of Integra and all of the providers listed in Appendix A.

Setting Up Integra

Online Installer

The online installer has been carefully designed to work on Red Hat-based Linux distributions. From a terminal, as root, execute the following command:

$ bash <(curl -s http://integra.install.emitrom.com)
Help: Can't locate Term/ReadKey.pm

If you face the error below, do not panic, it is a Perl dependency that is not installed on your system. This typically occurs on 'minimal' or 'server' installations of Linux.

Can't locate Term/ReadKey.pm in @INC (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 
/usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl  /usr/lib64/perl5 /usr/share/perl5 .) at integra-unix-deployer line 7.
BEGIN failed--compilation aborted at integra-unix-deployer line 7.

To solve, install the dependency:

yum install perl-TermReadKey.x86_64

The installer will be downloaded and you will get asked a few questions. The very first thing you need to do is select the version of Integra you are going to install:

Select version to install: 

Enter the number as it is displayed in the list.

Before proceeding, you must agree to the license agreement. Type 'y' at the prompt to continue:

> y

After accepting the license agreement, you are presented with 3 options. Once done with the selected option, you will be presented with the same menu again, giving you the opportunity to select another option:

1. Install vCenter Plugin
2. Install providers and reactor
3. Exit

Installing the vCenter Plugin

Selecting 1. from the installation menu guides you through the necessary steps to install the Integra vCenter plugin. You will have to provide a few other details, including vCenter version and credentials to vCenter.

Enter vCenter Version ‘5.1.0’, ‘5.5.0’, ‘6.0.0’:

Type the vCenter version as it is displayed in the question; for instance, 5.5.0

Enter vCenter URL. Example: [https://vcenter.emitrom.com]

After entering the URL (include https://) for your vCenter server you will be prompted for the vCenter credentials.

Enter vCenter username:
Enter vCenter password:

Installing the Reactor and Providers

If you select option 2. from the installation menu, the online installer will install the Integra Reactor and all of its Providers (on the same host). Unix services will be created for the Reactor and all of the providers so that you can check their running status. The command line interface (CLI) is installed as part of the Reactor.

The download of the Integra Reactor and the providers will start immediately; upon completing the download, services are created and started.

Verifying the Installation

After all the questions have been answered, and assuming the vCenter plugin, Reactor and providers are installed, the installer will proceed to download the Integra packages and install them in vCenter and in the host where you are running. The installer largely depends on the bandwidth available for the download, but on a typical broadband connection installation can take approximately 1 to 2 minutes.

The Reactor and the Providers are be copied to the /usr/sbin directory. Provider configuration files are copied to the /etc/integra directory.

In order to verify if the Reactor is running, issue the following command, as root.

$ service integra-reactor status

And to verify all providers are running, issue the following command, as root.

$ service integra-providers status

You may also verify that the Integra CLI is installed by issuing any of the CLI commands. The installer creates an executable file called integra-cli under /usr/sbin, so you can invoke the CLI by typing integra-cli. This will display the online help for the CLI.

$ integra-cli

If you installed the vCenter plugin, logout of any open session you may have and login again. Upon doing so, the Integra icon should be visible, as in the image below.

VCenter-Integra-icon.jpg

Manual Installation

Integra can also be installed manually by downloading the package from:

https://go.emitrom.com/{build number}/build/integra.zip

Where {build number} is the number of the build you wish to install. Visit http://emitrom.com to get the latest version of Integra, which is distributed as a Zip file--approximately 400 MB in size. Contrary to the online installer, a manual installation does not create Unix services. Instead, in order to start the Reactor and all of the providers, Integra comes with pre-built scripts that can be used to start things up. Refer to the section below on running Integra manually for more details.

Extract Integra

Navigate to the desired directory where you would like Integra to be installed. The example below assumes Integra was downloaded to the user's Downloads directory.

$ mkdir -p /opt/integra
$ cd /opt/integra
$ unzip ~/Downloads/integra.zip
$

This will extract two new Zip files:

$ ls -la /opt/integra
-rw-r--r--@  1 root  admin  341368748 Jan  9 21:20 integra-reactor.zip
-rw-r--r--@  1 root  admin   49109690 Jan  9 21:16 integra-ui.zip
$

The Reactor and all of the providers are packaged in integra-reactor.zip. The vCenter plugin is packaged in integra-ui.zip. To deploy the vCenter plugin, login to your vCenter host as root and:

$ cd /var/lib/vmware/vsphere-client/vc-packages/vsphere-client-serenity/
$ mkdir com.emitrom.integra.ui-1.0.0
$ cd to com.emitrom.integra.ui-1.0.0

Go back to your original shell in /opt/integra, and copy the integra-ui.zip file to the directory you created above:

$ scp integra-ui.zip [vCenter]:/var/lib/vmware/vsphere-client/vc-packages/vsphere-client-serenity/com.emitrom.integra.ui-1.0.0

Back in the vCenter shell:

$ service vsphere-client stop
$ unzip integra-ui.zip

Edit plugin-package.xml and ensure the line containing the vCenter version matches your vCenter instance:

  <dependencies>
   <pluginPackage id="com.vmware.vsphere.client" version="5.5.0" />
  </dependencies>
$ service vsphere-client start

Allow sufficient time for vCenter to start and then login to the web client using your browser.

Installing Remote Providers

The Integra providers can come in a variety of programming languages. Currently most providers are Java based with the exception of the VSS provider, which is Windows based.

To install a provider:

$ java -jar [provider-file].jar &

Configuration

Creating Users

Integra allows you to create users for easily tracking and auditing your operations. This is particularly useful for the Self-Service Portal. When your end user login to the portal you will be able to monitor who is executing any of the different workflows you have configured.

Adding / Editing Users

Users are kept in a file called servlet-context.xml inside the Reactor's .jar file. The next few steps show you how to edit the file and add users.

In the section Reserved Variables you will learn of a reserved variable called ${integra.user}. This special variable can be used in your workflows and will be replaced at runtime with the username of the user executing the workflow.

Run the following commands as root:

$ service integra-reactor stop

It is imperative you stop the service before you modify the file below, so make sure Integra is stopped.

$ cd /usr/sbin
$ jar xvf rest-[version]-uber.jar servlet-context.xml

Note: the jar command is available as part of the Java Development Kit, not the Java Runtime Environment.

This will extract the file servlet-context.xml file in the current directory (/usr/sbin). Edit the file in your favorite text editor, and navigate to the section <security:authentication-manager>:

<security:authentication-manager>
      <security:authentication-provider>
               <security:user-service>
                      <security:user name="admin" password="integra" authorities="ROLE_USER, ROLE_ADMIN" />
                      <security:user name="user" password="integra" authorities="ROLE_USER" />
               </security:user-service>
      </security:authentication-provider>
</security:authentication-manager>

Add or edit users as you see fit, either assigning them the ROLE_ADMIN role or the ROLE_USER role. In Integra version 1.0, roles are not used.

Once you have edited and saved the file, you may re-insert it into the .jar file with the following command:

$ jar uvf rest-[version]-uber.jar servlet-context.xml

Remove the .xml file from the current directory:

$ rm -rf servlet-context.xml

Make sure rest-[version]-uber.jar is still executable:

$ chmod 755 rest-[version]-uber.jar

Finally, start the Integra Reactor again:

$ service integra-reactor start
Deleting Users

To delete a user, follow the same procedure above to edit the file servlet-context.xml. Deleting a user is accomplished by deleting the line where the user is defined. Remember to stop the Reactor, modify permissions, and start the Reactor as part of this process; all operations must be performed as root.

$ service integra-reactor stop
$ cd /usr/sbin
$ jar xvf rest-[version]-uber.jar servlet-context.xml
$ vi servlet-context.xml
$ jar uvf rest-[version]-uber.jar servlet-context.xml
$ rm -rf servlet-context.xml
$ chmod 755 rest-[version]-uber.jar
$ service integra-reactor start

Database Setup

Integra ships out of the box with an embedded relational database. It is however not limited to a single database type and can support most of the relational databases in the market.

To configure Integra to use a different relational database, contact support@emitrom.com for details.

Schedule Results

Schedule results are the product of schedules that have been ran by the reactor scheduler or by a manual invocation from a user in the vCenter or Mobile Portal GUI. As you would imagine, the total number of schedule results can grow substantially over time. The total number is dependent upon the number of schedules and frequency of the tasks that have been setup in your system.

As an Integra administrator you have the ability to control how many schedule results you keep in the reactor database. The default schedule result clean-up task is set to:

 schedule.results.cron  						= 0 30 1 * * ?
 schedule.results.max   						= 1000

which means that every day at 1:30 am, the integra reactor will run a task and ensure there are no more than 1000 schedule results in the system. If there are more, it'll simply delete the older ones.

The two properties depicted above can be found in core.properties inside the rest-[version].jar.

Node: in addition to the schedule results, Integra also keeps an additional table with the entire history of all schedule results that ever ran. You can modify the properties shown above and be assured that you will always have the entire execution history--should you ever need it.

Integra Building Blocks

The Integra architecture was designed with scalability and flexibility in mind. Each and every one of the Integra clients (vCenter plugin, mobile, and others) accesses the Integra core, dubbed the Reactor, via REST. From that point forward, the Reactor communicates with all of the providers securely; in short, there is no direct access to any of the providers unless it is through the Reactor.

Integra-Architecture.png

Reactor

The Reactor is the brain of the operation; it is responsible for all secure communications between clients and providers, it is responsible for scheduling and workflow execution, and it also takes care of storing all the data in a database local to the Reactor itself. This gatekeeper is capable of scaling elastically as demand increases or decreases. We encourage you to read the Best Practices section to learn how to configure Integra and its providers in the best possible manner.

Providers

An Integra provider is a stateless micro-service that provides a means of interacting with a particular platform. Providers can be written in any programming language; this brings a tremendous amount of flexibility in terms of the platforms that can be exposed. You may have a provider that interacts with a hardware device, say, an Oculus Rift; or you may have a provider that interacts with Oracle; or you may have a provider that interacts with Azure. Providers are written independently of one another, which translates to tremendous agility and speed of delivery. Since providers are self-contained entities, they can be developed, patched, installed and upgraded without disrupting anything else in the Integra ecosystem.

It is the providers that lay at the foundation of Integra: providers work together and complement each other, and in doing so give you the ability to create powerful combinations that would otherwise be impossible to achieve. In addition, providers may run in an agent or agentless fashion. Traditional provider execution can take place alongside other providers, or even the reactor itself. However, the Integra architecture is such that it allows providers to run remotely if they must. A good example of a provider running remotely is an Integra provider called the VSS Requester, which runs as a Windows service. If the Reactor and all of the other Java-based providers run on a Linux machine, the VSS Requester may still run on Windows and all of the communication between the provider and the Reactor is taken care of by Integra.

Appendix A contains the current list of providers currently available in Integra, along with the actions that each provider exposes.

Actions

Actions are operations that can be performed on a provider's target platform; for example, turn on a virtual machine, upload a file to Amazon S3, send an email, etc. Naturally, in order for most actions to run successfully they need input provided to them. This is a key role for you as the automation architect: providing input to those actions so they can be used and re-used in many different workflows.

Integra-Provider-Actions.png

Integra has the ability to run actions in sequence, in parallel, scheduled or on demand. Running actions in parallel is detailed in the Parallel Processing section; as mentioned, actions can be executed dynamically in order to test them out. After you have provided all the inputs necessary for an action to run, clicking the green "play" button in the toolbar will execute that particular action. This is very useful when you want to test actions and see the type of output they return.

Integra-Action-Play.png

Rollback

Every action in Integra has a rollback mechanism; should an action encounter an error during execution, Integra immediately rolls back every action that has executed thus far in the workflow the action belongs to. In some cases, the rollback implementation is empty due to the nature of the action, but this rollback mechanism is triggered automatically when a failure is encountered. Integra has other mechanisms for dealing with failure; see Workflow Chains for more details.

Variable Inlining

Often times you want an action's input to be dynamic. Integra has the ability to inline variables in text-based input fields. Single line variables can be entered as ${variable}, and scalar (i.e., array) values can be entered as @{variable}. At runtime, Integra will evaluate any variable that it finds and it will replace it with the appropriate value. There are 2 sources from where inlined variables get their values:

Reserved Variables

Reserved variables are special keywords that Integra recognizes and replaces at runtime:

  1. ${integra.user} - this is the username that can be used to login to the portal. This variable is only valid and available when an HTTP session exists. When the workflow runs as part of a schedule the variable is replaced with integra.reactor
  2. ${integra.timestamp} - as its name indicates, Integra replaces occurrences of this variable with the current time / date, in the format yyyyMMddHHmmss. For example, 20150202120001.
  3. ${integra.tx} - Integra workflows are associated with a unique transaction ID, which can be used for auditing and tracking purposes. This variable will be replaced with the current operation's transaction ID. For example e31d80a4-768c-4f77-8f12-935c4a1b9223
  4. ${integra.output.count} - the number of outputs an action has after a successful invocation. For example, when looking for virtual machines, this variable will contain the number of virtual machines returned.
Piped Variables

Integra has the ability to redirect output from one action as input to one or more actions. And, an action may receive many outputs from different actions at the same time. See the section Input / Output Demultiplexing for more details and how it relates to inlining variables at runtime.

Applying Logic

The logic functionality packed as Integra actions gives you tremendous control over your workflows. All Java-based providers contain the Apply Logic action; Microsoft VSS and PowerShell providers do not. There are three different types of logical actions: filters, go-to, and advanced. Each will be discussed next.

The languages that Integra currently supports are Groovy and ECMAScript. It should be noted that when using Groovy, you have access to Groovy Grapes. For those unfamiliar with Groovy, this means you have access to any library that resides in well-known repositories. As you may imagine, this opens the door for a world of possibilities. You are not constrained to software dependencies; instead, simply rely on Groovy's @Grab directive and reference those libraries when you need them.

Filter Variables

Filtering is possible on any output from any action from any provider. You can create interesting conditional statements, manipulate Strings, and as long as the block of code you wrote evaluates to True, the object being inspected will be available to the next workflow action. The image below shows what a conditional Filter looks like.

Integra-Filters.png

The {parent.child} nomenclature tells Integra to replace those values at runtime before the script is executed. This means that anything that gets piped into the new Apply Logic action can get extracted and / or inspected. You have full access to all of the inputs piped in, and you can use them to build conditionals, evaluate expressions and even alter values as you will see below.

Go-To

Integra's Go-To functionality allows you to skip ahead in a workflow. You may also have elaborate conditionals that check different fields from piped input, and as long as the script returns a number then it will be used to skip ahead to that step. If the step number does not exist, an error will be raised at runtime.

Integra-Go-To.png

Advanced

The advanced type of Apply Logic operation provides the opportunity for doing free form scripting. While this block of code is not intended to replace a full-blown scripting environment, the script written will be interpreted dynamically just as it would in a traditional setting. If there are values piped in to this action, the script will be executed as many times as there are inputs. If no input is piped into this action, the script block will be executed only once.

There is a reserved word in the Apply Logic action, called 'input'. This variable represents a map and it can be used tap into the fields of input objects in order to modify their values based on conditionals. The image below shows how we are altering the value of the vmDetails.memory field. These values are kept in memory but may be consumed by other actions when you pipe the output of this operation to other actions.

Integra-Advanced.png

Workflow-Scoped Variables

In order to create a set of workflow-scoped variables, you can rely on the Advanced operation as described above. Simply define a new map and populate it with key-value pairs. The keys will be the names of the variables that you wish to define; during workflow execution, you can pipe the output of this action to those actions that may want to use the variables. Those actions can refer to the variables as described in the Input / Output Demultiplexing section.

Integra-Workflow-Variables.png

Workflows

Workflows are the lifeblood in Integra; it is with workflows that you build and elaborate multi-provider, multi-action sequences to address your IT's infrastructure needs. And you do so by visually building those workflows, dragging and dropping pre-configured actions into a set of steps that execute in sequence or in parallel. There are several key aspects to workflows that make them such an intricate and powerful player in the Integra ecosystem, as you'll see in the next several sections.

Input / Output Demultiplexing

As mentioned in the Variable Inlining section, Integra has the ability to re-direct the output of one action as the input of one or more actions; conversely, one action may receive as input the outputs of one or more actions. This re-direction is often referred to as Pipes; however, the proper analogy for what is taking place behind piping input / output can be best described by the Multiplexer / Demultiplexer concept.

When an action (A) is piped into another (B), the receiving action (B) has at its disposition the output of the originating action (A). Take, for example, an action in Integra's XenServer provider called Get Virtual Machines. This action produces an object called virtualMachine. You can easily find the output objects and fields that each action returns; in the vCenter plugin, select the action and focus on the bottom portion of the table. For Get Virtual Machines you will see the following:

Integra-Output-Example.png

The object name is virtualMachine and it contains 3 fields that can be referenced from other actions: name, powerState, uuid. The fields can be used with the ${variable} or @{variable} as explained above in any text-based input field. So, if we were to add a new action that sends out an email, we can include in the body of the email all the VM names that were found:

Integra-Variable-Use-Example.png

Here, you can see that we are using the field name from the virtualMachine object, and we are referencing to that variable as an array: @{name}

The final step to take in order to do a Mux/Demux of output/input is use the Pipe checkbox when you are building a workflow. After you drag and drop actions into the Workflow Steps table, check the Pipe checkbox next to the action whose output you want to redirect, and then edit the destination steps that will take that output. In the example below, the output from list-vms is piped to the email action. When the Reactor executes this workflow it is responsible for piping the output and inlining variables.

Integra-Workflow-Pipes.png

Some actions return objects of type file (see Bar Chart action in the SmartCharts provider). If these actions pipe their output to other actions, such as the email action from the Notification provider, Integra will add that file as an attachment to the email. Additionally, any action that pipes their outputs to the email action will result in attachments of .json files, containing all the raw data from the output. This is particularly useful for post-processing the data at a later time.

Variable Disambiguation

There are cases where workflows may use actions that have the same output objects, or the same output field names. This can happen if the action being used is the same (with or without different inputs), or if the actions are different but coincidentally share the same output fields. To illustrate this example, lets use the SSH provider.

The SSH provider has output that is dynamic in nature; the only thing we can count on is that the output returned by the SSH provider will be split on every new line. If we have output with 3 output fields, it will be returned like this:

Action 1:
  SSH Response:
    line.00001
    line.00002
    line.00003

If you were to use variables as mentioned in this User Guide, you could reference the previous output in another SSH action like this:

echo ${line.00001}

Now lets make things more interesting and say you had yet another SSH action, Action 2, that also returned some output:

Action 2:
  SSH Response:
    line.00001
    line.00002
    line.00003
    line.00004
    line.00005

You may already start to see the conundrum forming. We have two outputs with the same name (SSH Response) and 3 pairs of inputs fields with the same name as well (line.00001, line.00002, line.00003). If you were to add one of the fields from the second action to our echo example above, we may end up in a situation like this:

echo ${line.00001} ${line.00001}

Which variable belongs to Action 1, and which one belongs to Action 2?

As of Integra 1.0.3, there is a powerful disambiguation mechanism to get out of situations like this. Every action has a unique name, so variables can be made unique by tapping into the name of the action they came from. As such, our echo example would now look like this:

echo ${Action 1.SSH Response.line.00001} ${Action 2.SSH Response.line.00001}

Our echo command will use the first line from the output of Action 1 followed by the first line of output from Action 2, and now our ambiguity between the 2 ${line.00001} variables is gone.

In summary, as long as output fields are different, you may continue to use variables as described through out this guide. If, however, there is ambiguity as to which variable from which output from which action will be used, leverage the unique names associated with each action. The pattern to follow for variables would be:

${actionName.outputName.outputField}

Concurrent Processing

Integra executes steps in a workflow in sequence by default, but it also has the ability to execute one or more actions in parallel. This is particularly useful in situations where you need things taking place at the same time. The way you configure concurrent operations in Integra is by assigning the same Step number to those actions you wish to run at the same time. For example, the image below is going to take 3 different storage array snapshots at the same time:

Integra-Parallel-Actions.png

It is only when those 3 concurrent actions finish that the next action, Send Email, is executed. In addition to running actions concurrently, you can continue to use pipes in any of the steps as described in the previous section.

Visibility

As you will see in the Self-Service Portal section, Integra gives you the ability to execute workflows from the convenience of your mobile device. As an Automation Architect, however, you may want to restrict certain workflows from being exposed in the portal. You can achieve that with the Visible indicator in a workflow. The default value is true, which means the workflow will be visible by your users on the portal. If you would rather hide the workflow from the portal, simply uncheck the Visible checkbox when creating the workflow.

The Visible indicator means only that: it is either visible or not in the portal. You can continue to schedule and execute workflows, hidden or not, from the vCenter plugin. Additionally, if at a later date you wish to make hidden workflows visible, you can change the visibility level by simply editing the workflow and selecting the value that you desire.

The image below indicates the visibility of your workflows:

Integra-Workflow-Visibility.png

Workflow Chains

As mentioned in the Actions section, every action has the ability to rollback in case of an error. In the same way, workflows have the ability of executing other workflows when they finish successfully (forward chains) or when they fail (backward chains). Workflow chains are of extreme importance in environments where workflows map to business processes. There are processes to achieve a certain goal, but there are certain processes that are executed if things go wrong. It is worth noting that when an error takes place during workflow execution, that workflow will rollback all of the actions up to the point of failure (including the action that failed), and if any backward chains are specified then those workflows will be executed as well.

There is no limit to the number of workflows that you can chain together, either on success (forward) or on failure (backward). Additionally, Integra prevents you from creating a workflow chain that may result in a never-ending, circular reference. You may choose to have a forward chain but no backward chain, or vice-versa. You may choose to have both forward and backward chains; or, you may choose to have neither and rely on single action rollback only. Regardless of these combinations, Integra gives you the flexibility to have one, both, or neither.

Workflow chains are, as its name implies, sequences of workflows. In order to create a workflow chain, you will have to create those workflows that you want to execute on success or on failure. However, since Integra does not impose chains to exist, you can edit existing workflows at a later time and create workflow chains as your requirements evolve.

Forward Chains

Forward chains are created when a workflow executes after another workflow finishes successfully. When you create a workflow in Integra you are given the opportunity to select another workflow for an "On Success" outcome.

Integra-On-Success-Workflow.png

Backward Chains

Conversely, backward chains are created when a workflow executes after another workflow encounters an error. The mechanism to specify an "On Failure" workflow is similar to the positive case detailed above. When presented with the option, select the workflow you wish to execute "On Failure" of the original workflow.

Integra-On-Failure-Workflow.png

Workflow Source Control

Once you have created your workflows and tested them to your satisfaction, starting with Integra 1.1 you have the ability to persist them in a version control repository. This not only gives you the ability to version and protect your workflows, but it gives you the means for sharing your workflows with other Integra users.

Integra allows you to use JSON, XML or YAML to export and import workflows.

Exporting Workflows

Integra uses GitHub as the SCM repository of choice when exporting workflows. As a preferred partner, you can elect to store your workflows in Emitrom's Integra Workflow repository; however, Integra also gives you the option to export to any GitHub repository, so long as you have the proper authorization to do so.

Integra-Export-Workflow.png

Importing Workflows

Importing workflows is as simple as exporting them, except the import operation allows you to select one or more workflows. Now you have the ability to consume workflows shared by others, or import your own workflows after changes have been made. The import operation allows you to overwrite existing workflows.

Integra-Import-Workflow.png

Schedules

Schedules play an integral role in the world of automation. Via schedules, you can set workflows to execute at any given moment in time so they do the heavy lifting on your behalf. Integra is quite peculiar in the way that it defines schedules: an Integra schedule is an execution set whose elements are one or more workflows which run in parallel during the execution of more or more tasks.

Having the ability to execute one or more workflows at the same time means less schedules to maintain. Additionally, having one or more tasks per schedule gives you the granularity and control that you need to define exactly when the schedule's workflows will execute.

Tasks

Integra brings to the table 8 different tasks. With the exception of the first from the list below (Run Once), every other task has a beginning and end date, and is reoccurring. All tasks have the ability to be enabled or disabled, so if at a later date you would like to stop a task from executing, you do not have to delete anything: simply disable it and that task will not run. See Managing Schedules for more details.

  1. Run Once - As its name suggests, this tasks runs only once and never again.
  2. Seconds - Executes all workflows in a schedule every given number of seconds.
  3. Minutes - Executes all workflows in a schedule every given number of minutes.
  4. Hours - Executes all workflows in a schedule on an hourly basis.
  5. Daily - Executes all workflows in a schedule on a daily basis. This task gives you the option to execute all workflows every weekday, or every given number of days.
  6. Weekly - Executes all workflows in a schedule every week, on the days that you specify on the task.
  7. Monthly - Executes all workflows in a schedule in a monthly basis. This task gives you the option to execute all workflows on the given day of the month, or you may specify the given weekday of every month.
  8. Cron - Last but not least, you may enter a cron expression and Integra will interpret it and execute it.

Workflows

You have already seen everything there is to know about workflows, but it is worth repeating that all workflows in a schedule execute in parallel when any of the tasks in the schedule run. Needless to say, this prevents you from having to create multiple schedules that would otherwise run at the same time, only to execute different workflows.

Accessing Integra

Integra has different ways of accessing and interacting with it. In this section we will discuss the non-programmatic ways of using Integra, and will reserve Appendix B for details on using Integra from a programmatic point of view. We will discuss Integra's vCenter Plugin, the Command Line Interface, and the Self-Service Portal.

vCenter Plugin

Integra provides a vCenter plugin, which as you saw in Installing the vCenter Plugin, is extremely simple to install. Now that you know the concepts behind the Integra Building Blocks, this section will focus on using Integra from vCenter.

Configuring the Integra License

After Setting Up Integra, upon clicking the Integra icon for the first time a dialog window will be displayed where you must provide the following information:

Integra-Settings-Dialog.png

You may verify the number of providers and workflows your license is capable of, as well as the expiration date by navigating to the Settings tab in the vCenter plugin. You can modify any of the fields in this tab; make sure to hit the Save button in the toolbar for your changes to take effect.

Integra-Settings.png

Managing Providers

Adding Providers

Providers are the very first things you should add after entering your Integra license information. You may do so by navigating to the Providers tab, and then clicking on the green plus sign in the toolbar:

Integra-Adding-Providers.png

You must enter:

Editing Providers

Once a provider has been successfully added, you can edit any of its fields by clicking on the edit button. A dialog appears with all of its fields pre-populated; change any value you desire and click Save to persist your changes.

Integra-Editing-Providers.png

Cloning Providers

Integra gives you the ability to clone a provider to speed up data entry. Click the clone button in the toolbar and provide the name of the new provider. Click the Save button when done and you will see the new provider in the list.

Integra-Cloning-Providers.png

Deleting Providers

You may delete a provider, as long as none of its actions are being used in a workflow and all of its actions are removed from the Actions tab. In other words, the provider may not be in use at all for deletion to be successful. Select the provider you wish to delete and click the delete button in the toolbar, then click Ok on the confirmation dialog to proceed.

Integra-Deleting-Providers.png

Searching Providers

You can search for providers by entering text in the Search textbox. Search is context sensitive. Search will begin as soon as you finish typing and press enter. Those providers with any fields matching the search criteria will be listed in the table. Searching is case sensitive.

Managing Actions

Adding Actions

Once you have added providers, you may add and configure actions. These actions will be used later on to build your workflows, so configuring actions correctly is of essence. You can add actions only if you have previously added providers.

To add an action, navigate to the Actions tab and click on the green plus sign to add a new action:

Integra-Add-Action.png

Editing Actions

Once an action has been successfully added, you can edit any of its fields by clicking on the edit button. A dialog appears with all of its fields pre-populated; change any value you desire and click Save to persist your changes.

Integra-Edit-Action.png

Cloning Actions

Integra gives you the ability to clone an action to speed up data entry. Click the clone button in the toolbar and provide the name of the new action. Click the Save button when done and you will see the new action in the list.

Integra-Clone-Action.png

Deleting Actions

You may delete an action, as long as it is not being used in a workflow. In other words, the action may not be in use at all for deletion to be successful. Highlight the action you wish to delete and click the delete button in the toolbar, then click Ok on the confirmation dialog to proceed.

Integra-Delete-Action.png

Action Tags

Integra allows you to create one or more tags so you can categorize actions. When there are hundreds, even thousands of actions tagging becomes extremely useful for grouping common sets of actions. You create your own tags; there is no set standard or even a recommendation. Use your best judgment for what makes sense to you. You may add more than one tag to a single action; as such, actions can belong to one or more tag groups.

Using the tag drop down menu (pictured below) you can create, edit, or delete tags. Simply highlight the action that you wish to tag, and click on the tag button in the toolbar.

Integra-Tag-Action.png

Once you have tagged one or more actions, you may only display those actions with certain tags. For that, simply select the tag(s) you wish to use as filter; as you check the boxes, only those actions that match your tagging criteria will be displayed in the Actions table.

Integra-Tag-Search.png

Searching Actions

You can search for actions just like you search for providers, by entering text in the Search textbox. Search is context sensitive. Search will begin as soon as you finish typing and press enter. Those actions with any fields matching the search criteria will be listed in the table. Searching is case sensitive and works in addition to the tag filtering mentioned above.

Executing Actions

Actions may be executed in a stand-alone fashion by clicking the green execute button in the toolbar. Once you have configured an action by providing all of the necessary input, you can test the action to see if it provides the results you are expecting. This is recommended so you can be certain your configured actions will execute without any errors during workflow execution.

Some actions depend heavily on the output of other actions in order to execute successfully. In those cases, for testing, you will have to rely on creating a workflow (see Managing Workflows below), using the piping mechanism (see Input / Output Demultiplexing) and executing that workflow on demand (see Executing Workflows or Executing Schedules).

Once you execute an individual action, any output that it produces will be displayed in the bottom section of the Actions tab. You may copy individual rows from the output table by highlighting the row and using your operating system's keyboard combination for copying text.

Integra-Executing-Actions.png

Managing Workflows

Creating Workflows

Now that you have created and configured actions, it is time to put them to good use. In order to create a new workflow, create the green plus sign in the toolbar and provide the information requested.

Integra-Create-Workflow.png

After you click the Save button, you are ready to add steps to the workflow. Highlight the newly created workflow, and drag and drop actions from the list on the far right to the Workflow Steps table in the middle.

Integra-Drag-Actions-To-Workflow.png

By default, each action you add gets automatically assigned an incremental step number. To re-arrange step priorities simply double click on the step you wish to modify and enter the new step number. If you wish steps to execute in parallel, give them the same step number.

You saw earlier how to use pipes (see Input / Output Demultiplexing): click the box on the step you wish to pipe, and manually enter a comma-separated list of step numbers. Those steps will receive the output of the step you elected to pipe.

Integra-Pipe-Action.png

New in version 1.0.2, each workflow step has the ability to specify an individual timeout. Highlight the step you would like to modify the timeout value, double click on the Timeout cell and provide a value (in milliseconds). Once satisfied with the timeout value, hit the Enter key.

Integra-Edit-Workflow-Step-Timeout.png

Once you have configured steps, timeouts, pipes and targets, click the Save icon to persist your changes.

Integra-Save-Workflow.png

Editing Workflows

To edit a workflow, click the edit button in the toolbar. You are given the opportunity to change any of the main properties of the workflow: name, description, visibility, and forward / backward chains.

If you would like to change any of the steps, you may do so by highlighting the workflow you wish to modify. Alter step numbers, pipes, and targets as you see fit, or even add or remove steps. Once you are done, click the Save icon to persist your changes.

Cloning Workflows

To clone a workflow, click the clone button in the toolbar and provide the name of the new workflow. Click the Save button when done and you will see the new workflow in the list.

Integra-Clone-Workflow.png

Deleting Workflows

You may delete a workflow, as long as it is not being used in a schedule. In other words, the workflow may not be in use at all for deletion to be successful. Highlight the workflow you wish to delete and click the delete button in the toolbar, then click Ok on the confirmation dialog to proceed.

Integra-Delete-Workflow.png

Searching Workflows

You can search for workflows just like you search for providers or actions, by entering text in the Search textbox. Search is context sensitive. Search will begin as soon as you finish typing and press enter. Those workflows with any fields matching the search criteria will be listed in the table. Searching is case sensitive.

Export Workflow Steps

Integra gives you the ability to copy the steps of your workflow as comma-separated value (CSV) text. This is useful if you would like to quickly share the steps in a workflow without having to commit the entire workflow to SCM.

To export workflow steps click the spreadsheet button in the Workflow Steps table's toolbar, and paste the contents of the clipboard into your favorite text editor.

Export Workflow to GitHub

In addition to saving the steps of a workflow to a CSV file as described above, you may export a workflow and all its dependencies to GitHub. This method of exporting is much more powerful than saving the workflow steps to a CSV file, as any workflow that is stored in GitHub can be imported by any instance of Integra running 1.1 and higher. Workflows can be exported in JSON, XML, or YAML.

Exporting a workflow is extremely simple. Highlight the workflow you wish to export, and click on the export button in the Workflows toolbar. You'll be presented with a dialog that requests the name of the GitHub repository and your credentials for that repository. Clicking on the connect button will log you in to GitHub; if successful, you can proceed to selecting the destination for your workflow. Click on the Export button to upload the workflow in GitHub.

Note: the underlying SDK that Integra relies on for communicating with GitHub does not accept spaces in file names. The file created in GitHub will have the same name as the workflow you are exporting; if it contains spaces, make sure to either remove them or replace them with a hyphen (-).

Integra-GitHub-Export.png

Import Workflow from GitHub

Importing workflows is equally simple. You may import one or more workflows in one single operation, and you can choose to overwrite existing workflows. The formats allowed for an import are the same as in the export (JSON, XML, YAML).

The import operation will import the workflow, any actions associated with it, and configure the providers those actions belong to. Once the import is finished, you may need to verify the providers imported are running in the specified host.

To import one or more workflows, click on the import button in the Workflows toolbar, select the GitHub repository you wish to connect to and provide credentials for that repository. Once logged in, you may select the workflows you wish to import and if you would like to overwrite them. Clicking the Import button in the dialog will download and optionally overwrite your workflows.

Integra-GitHub-Import.png

Executing Workflows

As of version 1.0.2, you can execute workflows directly without the need to creating a schedule. Similarly to how actions are executed, highlight the action that you would like to execute and click on the green icon in the toolbar. Upon executing the workflow, you will be taken to the Schedule Results view so you can see the execution status of your workflow.

Integra-Executing-Workflows.png

Managing Schedules

Creating Schedules

Creating schedules is the last step to get the most out of your workflows. Here, you can create several tasks so the schedule's workflows can execute at different times.

Note: adding tasks to the schedule is not required.

If you choose to not add any tasks to the schedule, the only mechanism to run the schedule is by hand. See Executing Schedules below for more details.

To create a schedule, navigate to the Schedules tab and click on the green plus sign in the toolbar.

Integra-Creating-Schedules.png

You are asked to provide:

Click on the Save button to create a new schedule without workflows and without tasks.

To add one or more workflows to the schedule, highlight the schedule of choice and click the green plus sign in the workflows toolbar on the bottom portion of the Schedules tab. The dialog that appears allows you to select the workflow you wish to add to the schedule.

Integra-Add-Workflows-To-Schedule.png

After adding one or more workflows to the schedule, click on the save button in the toolbar to persist your changes. At this point the schedule Sample Schedule exists, but it does not contain tasks. To add a task, highlight the schedule of choice and click on the clock icon with the green plus sign in the tasks panel. This will bring up a choice of 8 tasks:

Integra-Tasks.png

  1. Run Once - As its name suggests, this tasks runs only once and never again.
  2. Seconds - Executes all workflows in a schedule every given number of seconds.
  3. Minutes - Executes all workflows in a schedule every given number of minutes.
  4. Hours - Executes all workflows in a schedule on an hourly basis.
  5. Daily - Executes all workflows in a schedule on a daily basis. This task gives you the option to execute all workflows every weekday, or every given number of days.
  6. Weekly - Executes all workflows in a schedule every week, on the days that you specify on the task.
  7. Monthly - Executes all workflows in a schedule in a monthly basis. This task gives you the option to execute all workflows on the given day of the month, or you may specify the given weekday of every month.
  8. Cron - Last but not least, you may enter a cron expression and Integra will interpret it and execute it.

You can add one or more tasks in a schedule, or none as mentioned earlier. All tasks have start and end dates, except Run once. Once you have added a task, click the save button to persist those changes to your schedule.

Once a schedule has tasks, each task will execute all workflows in parallel when the Reactor's scheduler runs the task.

Editing Schedules

Editing a schedule is straightforward. Clicking on the edit button in the toolbar displays a dialog where you have the chance of changing the schedule's name, description and enabled status.

Independently of the edit button, you may add or remove workflows from a schedule, or modify (add, edit or delete) tasks that belong to a schedule. The only critical step is to click on the save button on the toolbar after any changes have been made to the schedule.

Deleting Schedules

Deleting schedules is the first thing you must to in order to delete workflows, actions, and providers. By removing a schedule you remove references to workflows, and thus enable deletion of those workflows. To delete a schedule highlight the desired schedule and click on the delete button in the toolbar. Click on the Ok button to delete the schedule.

Once a schedule is deleted, any tasks future tasks scheduled to run are removed, and any workflows that were part of the schedule will no longer be executed as part of the schedule. Any results generated from previous executions of the schedule's tasks remain in the Schedule Results. This is done for auditing and traceability purposes.

Integra-Delete-Schedule.png

Executing Schedules

To execute a schedule on demand, you can do so by clicking on the green execute button in the toolbar. This operation is asynchronous; it kicks off the schedule and it is done. At this point, you may check the Schedule Results tab to see the results produced by the workflows in the schedule.

Being able to execute schedules is useful for testing your end-to-end automation operations. In other words, executing schedules by hand, in addition to being able to execute actions by hand, gives you an end-to-end mechanism to test your automated actions before running them in production. On demand execution is an excellent mechanism for debugging your workflows.

Searching Schedules

You can search for schedules just like you search for workflows, providers or actions, by entering text in the Search textbox. Search is context sensitive. Search will begin as soon as you finish typing and press enter. Those schedules with any fields matching the search criteria will be listed in the table. Searching is case sensitive.

Schedule Results

The Schedule Results tab contains a historical log of everything that has executed in Integra. As you see in the image below, every schedule is associated with a unique transaction ID to make auditing easier. You can also verify that workflows that belong to the same schedule execute at the same time; the table shows when a workflow started and when it finished.

There are 3 different states that a result may have:

The chart on the right hand side of the tab will display all 3 different states so you can have a visual representation of the results your workflows are generating. On the bottom of the screen, successful workflows will display the outputs they produced, if any.

The Configuration section details how to set the maximum number of results displayed in this tab.

Integra-Schedule-Results.png

Self-Service Portal

Another means of interacting with Integra is through the mobile self-service portal. Access to the portal can be granted to the users you choose, or to nobody but you; the decision is yours.

In addition to granting access to the portal via users (see Creating Users), you have the prerogative of which workflows to expose through the portal (see Visibility). Integra gives you as much control as possible over who accesses the portal, and what those users get to execute.

The portal is installed as part of the Reactor, so it is ready to be used from the onset--no configuration needed other than users and workflows as mentioned above. To access the Integra portal, open a browser in your preferred mobile device and navigate to the same host where the Reactor is running. The URL is the same you entered when you configured the Integra license (see Configuring the Integra License).

Logging In

Users must provide the credentials you created in the Creating Users section. By navigating to the host where the Reactor is running, they will be presented with a login screen:

Integra-Portal-Login.png

Executing Workflows

After logging in successfully, only those workflows you specified as visible are displayed in the portal. The example below shows 3 workflows, but one of them has its visibility not set. As you can see, only the 2 workflows whose visibility is enabled are displayed in the portal.

To execute a workflow, select it and tap the Execute button in the upper right hand corner of the device.

Integra-Portal-Workflow.png

Workflow Results

Like the vCenter plugin, the portal has the ability to show the outcome of executing a workflow. Albeit less detail is shown, it is easy to see via the portal if a workflow's execution succeeded or failed.


Integra-Portal-Results.png

Command Line Interface

Integra has a CLI where you can replicate all of the operations performed by the vCenter plugin. The easiest way to see what the CLI can do is by typing integra-cli:

 $ integra-cli
 Usage: java -jar cli-1.1.0-uber.jar <connection parameters> <action> <actions parameters>

 Connection Actions                      Description                                                           
 -listCredentials                        Lists connection information and stored credentials                   
 -addCredentials                         Adds authentication credentials e.g. hostname, port, protocol, username, and password
 -removeCredentials                      Removes authentication credentials                                    


 Connection Parameters                   Description                                                           
 -hostname [http|https]                  Hostname or IP of the Integra server                                  
 -port                                   Port number of the Integra server                                     
 -protocol                               Protocol [http|https]                                                 
 -username                               Username of the Integra server                                        
 -password                               Password of the Integra server                                        


 Provider Actions                        Description                                                           
 -listProviders                          Returns a list of providers                                           
 -listProviderActions                    Returns a list of provider actions                                    
 -addProvider                            Adds a new provider                                                   
 -removeProvider                         Removes a new provider                                                


 Provider Parameters                     Description                                                           
 -providerId                             The provider id returned from listProviders                           
 -name                                   The object name                                                       
 -desc                                   The object description                                                
 -providerHostname                       The provider hostname or IP                                           
 -providerPort                           The provider port number                                              
 -timeout                                A timeout in milliseconds                                             
 -secured                                Secured provider                                                      


 Schedule Actions                        Description                                                           
 -listSchedules                          Returns a list of schedules                                           
 -listScheduleResults                    Returns a list of schedule results                                    
 -listTasksForSchedule                   Lists tasks for a schedule                                            
 -listScheduleTaskDetails                List details for a schedule task                                      
 -addSchedule                            Adds a schedule                                                       
 -addHourlyTaskToSchedule                Adds a hourly task to given schedule id                               
 -addDailyTaskToSchedule                 Adds a daily task to given schedule id                                
 -addWeeklyTaskToSchedule                Adds a weekly task to given schedule id                               
 -addMonthlyTaskToSchedule               Adds a monthly task to given schedule id                              
 -addCronTaskToSchedule                  Adds a cron task to given schedule id                                 
 -addWorkflowToSchedule                  Adds workflow to schedule                                             
 -removeSchedule                         Removes a schedule                                                    
 -removeTaskFromSchedule                 Removes a task from a schedule                                        
 -removeWorkflowFromSchedule             Removes a workflow from a schedule                                    
 -runSchedule                            Runs a schedule                                                       


 Schedule Parameters                     Description                                                           
 -scheduleId                             The scheduleId returned from listSchedules                            
 -name                                   The object name                                                       
 -desc                                   The object description                                                
 -schedulePriority                       The schedule priority [integer]                                       
 -scheduleEnabled                        Enables or disables a schedule [true|false]                           
 -taskId                                 The task id                                                           
 -taskStartDate                          The start date for task [YYYY/MM/DD]                                  
 -taskEndDate                            The end date for task [YYYY/MM/DD]                                    
 -taskStartHour                          The hour when task will start                                         
 -taskStartMin                           The minute when task will start                                       
 -reoccurHours                           Interval of reoccurence in hours                                      
 -reoccurDays                            Interval of reoccurence in days                                       
 -dayOfWeek                              The day of the week 0-6                                               
 -dayOfWeek                              The day of the week 0-6                                               
 -dayOfMonth                             The day of the month 1-31                                             
 -cronExpr                               The cron expression                                                   
 -taskEnabled                            Enables or disables a task [true|false]                               
 -taskStartPeriod                        The task period [AM|PM]                                               


 Workflow Actions                        Description                                                           
 -listWorkflows                          Returns a list of workflows                                           
 -listWorkflowSchedules                  Lists all schedules for a workflow                                    
 -listWorkflowSteps                      Returns a list of workflow actions                                    
 -listWorkflowActions                    Lists workflow actions                                                
 -listWorkflowActionDetails              Lists details for a workflow action                                   
 -listWorkflowActionOutputFields         Lists all output fields for a given workflow action                   
 -listWorkflowsForSchedule               Returns a list of workflows based on scheduleId                       
 -addWorkflow                            Adds a workflow                                                       
 -addWorkflowAction                      Adds a workflow action (interactive)                                  
 -addScheduleToWorkflow                  Adds a schedule to a workflow                                         
 -addStepToWorkflow                      Adds a workflow step to a workflow                                    
 -addPipeToWorkflowStep                  Adds an output pipe for a workflow step                               
 -removeWorkflow                         Removes a workflow                                                    
 -removeWorkflowAction                   Removes a workflow action                                             
 -removeScheduleFromWorkflow             Removes a schedule from a workflow                                    
 -removeStepFromWorkflow                 Removes a workflow step from a workflow                               
 -removePipeFromWorkflowStep             Removes an output pipe for a workflow step                            
 -runWorkflowAction                      Runs a workflow action                                                
 -importWorkflow                         Import workflow from Repository                                       
 -exportWorklow                          Export workflow to Repository                                         


 Workflow Parameters                     Description                                                           
 -workflowId                             The workflowId returned from listWorkflows                            
 -workflowActionId                       The workflowActionId returned from listWorkflowActions or listWorkflowSteps
 -workflowStep                           The workflow step number                                              
 -workflowTargetStep                     The workflow target step number                                       


 Configuration Actions                   Description                                                           
 -listLicenses                           Lists licenses                                                        
 -addLicense                             Adds a license                                                        
 -removeLicense                          Removes a license                                                     


 Configuration Parameters                Description                                                           
 -license                                The license                                                           
 -licenseId                              The license id                                                        


 Additional Parameters                   Description                                                           
 -debug                                  Prints additional debug information, useful for troubleshooting       
 -version                                CLI version                                                           
 -help                                   Additional help for given action, e.g. -listProviders -help

Best Practices

Reactor

The Reactor takes 3 optional command-line parameters:

-port         Non-secure port, default 8080
-securePort   Secure port, default 8443
-config       Name of the configuration file where syslog details can be specified

Networking

In addition to the Reactor's ports (8080 and 8443), each provider interacts with the Reactor via a specific port. If you used the Online Installer, configuration files for all Java-based providers are kept in /etc/integra/[name]-provider.conf.

You can modify ports in any of the providers' configuration file. When you do, make sure to restart the provider you modified and update the Reactor via the vCenter plugin or the CLI.

Security

The Integra reactor supports HTTP and HTTPS. Whenever possible we recommend using HTTPS. This will ensure that you have a 100% secured layer from the Integra UI or Client all the way down to the providers.

Logging

All integra providers as well as the reactor log messages under ${user.home}/integra for the user running the providers or reactor.

It is highly advised to configure and point the Integra providers to a system that supports syslog. To do so, edit the provider configuration file for each of the providers you have installed and set:

 # Syslog can be configured by specifying the host and port where your syslog
 # daemon is running.  If the port is omitted, the default used will be 514.
 syslog_host=localhost
 syslog_port=514

Restart the providers affected by this change, and use a tool such as logstash or Splunk to see your logs.

Local file-based, rotating logs are also generated by Integra. Those logs will be placed on the ${user.home}/integra directory by default. If you wish to modify the location, edit the log4j.properties file inside each provider .jar file. As root:

$ cd /usr/sbin
$ jar xvf [provider].jar log4j.properties
$ vi log4j.properties

In this file you may change the logging level (INFO is set by default on all providers and the Reactor), and also the location of the .log files. Modify the line:

log4j.appender.file.File=[provider].log

With your preferred filename and location. Save the file, package it in the provider .jar and restart the provider.

$ jar uvf [provider].jar log4j.properties
$ chmod 755 [provider].jar
$ service integra-providers restart

Workflow Names

The underlying SDK that Integra relies on for communicating with GitHub does not accept spaces in file names. The file created in GitHub will have the same name as the workflow you are exporting; if it contains spaces, make sure to either remove them or replace them with a hyphen (-).

Appendix A: Providers

Application

IBM DB2

Details
Provider Version 1.1.0
Target Version 9.5 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9773


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Inventory Inventory db2 database
Quiesce Quiesces the DB
Unquiesce UnQuiesces the DB
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


MySQL

Details
Provider Version 1.1.0
Target Version 5.1 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9777


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Inventory Inventory mysql database
Quiesce Quiesces the database
Unquiesce Unquiesces the database
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Oracle

Details
Provider Version 1.1.0
Target Version 10g and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9783


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Archive Archive log switch of db
Inventory Inventory oracle database
Quiesce quiesces the db
Unquiesce unquiesces the db
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Postgres

Details
Provider Version 1.1.0
Target Version 9.2 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9785


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Inventory Inventory postgresql database
Quiesce quiesces the db
Unquiesce unquiesces the db
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


SAP MaxDB

Details
Provider Version 1.1.0
Target Version 7.8 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9776


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Inventory Inventory maxdb database
Quiesce quiesces the db
Unquiesce unquiesces the db
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Sybase

Details
Provider Version 1.1.0
Target Version 15.7 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9788


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Inventory Inventory sybase ase database
Quiesce Quiesce the database
Unquiesce Unquiesce the database
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Cloud

AWS

Details
Provider Version 1.1.0
Target Version N/A
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9771


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Glacier Backup Backup all files to amazon Glacier
Glacier Inventory Download Download the Glacier vault inventory for a specific vault
Glacier Inventory List List Glacier archives for a given vault based on last inventory downloaded
Glacier Restore Restores an archive from Glacier
Glacier Vault List List all glacier vaults for a region
S3 Backup Backup all files to amazon S3
S3 Backup List List all S3 backups
S3 Backup Retention Perform backup retention for S3 backups
S3 Restore Restore all files from amazon S3
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


You can control certain transfer settings for AWS in /etc/integra/aws-provider.conf. The default setings are:

# AWS connection timeout in seconds
connectionTimeout=300
# Timeout after connection is established
socketTimeout=300
# Number of attempts after an error has occurred
maxRetryCount=5
# Chunk transfer size
sendBufferSizeBytes=2048000
receiveBufferSizeBytes=2048000

Azure

Details
Provider Version 1.1.0
Target Version N/A
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9772


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Backup Backup all files to azure blob storage
Backup List List all azure blob backups
Backup Retention Backup retention for existing backups
Restore Restore all files from azure backup to restore path
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Kubernetes

Details
Provider Version 1.1.0
Target Version 2.0.37
Software Required Java 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9798


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create Kubernetes Pod Create Kubernetes Pod
Create Kubernetes Replication Controller Create Kubernetes Replication Controller
Create Kubernetes Service Create Kubernetes Service
Delete Kubernetes Pod Delete Kubernetes Pod
Delete Kubernetes Replication Controller Delete Kubernetes Replication Controller
Delete Kubernetes Service Delete Kubernetes Service
Execute Command Executes an OS Command
Inventory Kubernetes Minions Inventory Kubernetes Minions
Inventory Kubernetes Pods Inventory Kubernetes Pods
Inventory Kubernetes Replication Controllers Inventory Kubernetes Replication Controllers
Inventory Kubernetes Services Inventory Kubernetes Services
Sleep Introduces a sleep (ms)


Microsoft

VSS Requester

Details
Provider Version 1.0.3
Target Version Windows x64
Software Required .NET 4.5
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9801


Actions
CreateComponentSnapshot Backup VSS Writer Components
ListComponents List VSS Writer Component Metadata
ListSnapshots List Snapshots
ListWriters List VSS Writers


Help: Could not load file or assembly 'AlphaVSS.60.x64.dll' or one of its dependencies. The specified module could not be found

If you encounter the error above when using Integra's VSS requester, you must install the Microsoft Visual C++ 2010 SP1 Redistributable Package (x64) on the host where the VSS Requester is running. You can download that package directly from Microsoft.


PowerShell

Details
Provider Version 1.0.3
Target Version Windows x64
Software Required .NET 4.5
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9802


Importing a PowerShell Module

To import any PS module into the Integra PowerShell Provider, simply create an Import-Module action and provide the name of the PS module you would like to import. In some instances, you may need to ease the restrictions, which you can accomplish by creating and executing a Set-ExecutionPolicy action with a value of Unrestricted, or Bypass.

Help: My Module Doesn't Show

If your newly imported module doesn't appear in Integra, check the installation path of the PowerShell module and make sure you have the correct permission on the files.

Another alternative is to verify the value of the environment variable %PSModulePath% In some cases, it is not enough that the files are under the Windows\system32 folder and it appears to be a part of %PSModulePath%. Instead, copy the .ps files in question and place them in a directory under %USERPROFILE%. Then, make sure that directory is part of %PSModulePath%.

Once all the directory issues are resolved, proceed to import the module again from Integra and it should be visible.


Miscellaneous

Archive

Details
Provider Version 1.1.0
Target Version N/A
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9770


Actions
Copy To Secondary Copy archive files from primary to secondary location
Delete Primary Delete archives on primary location according to policy
Delete Secondary Delete archives on secondary location according to policy
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Notification

Details
Provider Version 1.1.0
Target Version N/A
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9781


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Email Sends an email to the specified parties
Twilio SMS Sends a SMS to the specified parties using Twilio
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


SmartCharts

Details
Provider Version 1.1.0
Target Version N/A
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9793


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Bar Chart Creates a bar chart
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


SSH

Details
Provider Version 1.1.0
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9796


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)
SSH Command The command that will be executed over SSH


Storage

EMC Isilon

Details
Provider Version 1.1.0
Target Version OneFS 7.0 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9791


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create Container Snapshot Creates a container's snapshot from the storage controller
Delete Container Export Delete the /ifs export
Delete Container Snapshot Deletes a container's snapshot from the storage controller
Enforce Snapshot Count Retention Enforces snapshot count retention, deleting snapshots until desired count is reached, oldest first
Export Container To Host Export the /ifs path to a host
Get Container Export List Gets a container's export list from the storage controller
Get Container Snapshot Gets a container's snapshot from the storage controller
Get Container Snapshot List Gets a container's snapshot list from the storage controller
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


EMC ViPR

ViPR currently supports many different storage platforms.

EMC:

Third-Party:


Details
Provider Version 1.1.0
Target Version 2.0 or higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9792


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create Container Creates a container
Create Container Snapshot Creates a container snapshot
Create SMB Share Creates a smb share
Delete Container Deletes a container
Delete Container Snapshot Deletes a container snapshot
Enforce Snapshot Count Retention Enforce snapshot retention by count for container
Export Block Container Exports a block container
Export File Container Exports a file container to a host
Export File Container Snapshot Exports a file container snapshot to a host
Get Block Container List List block containers
Get Container NFS Export List List container nfs exports
Get Container SMB Export List List container smb exports
Get Container Snapshot List List container snapshots
Get File Container List List file containers
Get Projects List projects
Get Virtual Arrays List virtual storage arrays
Get Virtual Pools List virtual storage pools
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


NetApp Data ONTAP 7-mode

Details
Provider Version 1.1.0
Target Version ONTAP 7.3.3 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9778


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create Container From Snapshot Creates a container from a snapshot in the storage controller
Create Container Snapshot Creates a container's snapshot from the storage controller
Delete Container Deletes a container in the storage controller
Delete Container Snapshot Deletes a container's snapshot from the storage controller
Export Container To Host Exports a container in the storage controller to a host or CIDR
Get Container Snapshots Gets a container's snapshot list from the storage controller
Get Containers Gets a list of containers from the storage controller, which match the provided regular expression.
Map Container To iGroup Maps a container (a LUN) to an iGroup
Restore Container Snapshot Restores a container's snapshot from the storage controller
Retain By Age Retains a container snapshot for as long as the retention days specified
Retain By Count Retains container snapshots up to a certain limit
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


NetApp clustered Data ONTAP

Details
Provider Version 1.1.0
Target Version ONTAP 8.2 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9779


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create Container From Snapshot Creates a container from a snapshot in the storage controller
Create Container Snapshot Creates a container's snapshot from the storage controller
Delete Container Deletes a container in the storage controller
Delete Container Snapshot Deletes a container's snapshot from the storage controller
Export Container To Host Exports a container in the storage controller to a host or CIDR
Get Container Snapshots Gets a container's snapshot list from the storage controller
Get Containers Gets a list of containers from the storage controller, which match the provided regular expression.
Map Container To iGroup Maps a container (a LUN) to an iGroup
Restore Container Snapshot Restores a container's snapshot from the storage controller
Retain By Age Retains a container snapshot for as long as the retention days specified
Retain By Count Retains container snapshots up to a certain limit
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Virtualization

KVM

Details
Provider Version 1.1.0
Target Version KVM 17 and higher (Linux Kernel 2.6.21)
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9794


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Craete Virtual Machine From Template Create Virtual Machine from Template File or XML
Delete Virtual Machine Delete Virtual Machine
Delete Virtual Machine Snapshot Delete Virtual Machine Snapshot
Get Virtual Machine Snapshots Virtual Machine Snapshots
Get Virtual Machine Template Get Virtual Machine Template
Inventory Storage Pools Inventory Storage Pools
Inventory Virtual Machines Inventory Virtual Machines
Quiesce Quiesce Virtual Machine
Unquiesce Unquiesce Virtual Machine
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


RHEV

Details
Provider Version 1.1.0
Target Version 3.4 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9795


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create VM From Template Create VM From Template
Delete VM Delete VM
Get Snapshots List Virtual Machine Snapshots
Inventory Clusters Inventory Clusters
Inventory Data Centers Inventory Data Centers
Inventory Hosts Inventory Hosts
Inventory Storage Domains Inventory Storage Domains
Inventory VM Templates Inventory VM Templates
Inventory Virtual Machines Inventory Virtual Machines
Quiesce Create Snapshot of Virtual Machine
Restore Snapshots Restore Snapshot of Virtual Machine
Start Virtual Machine Start a Virtual Machine
Stop Virtual Machine Stop a Virtual Machine
Unquiesce Delete Snapshot of Virtual Machine
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


vSphere

Details
Provider Version 1.1.0
Target Version vCenter 5.1 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9789


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create Virtual Machine From Template Creates Virtual Machines based on an existing template
Delete Virtual Machines Deletes one or more virtual machines
Inventory Inventory vCenter Environment
Inventory Datastores Inventory Datastores
Inventory Hosts Inventory ESX Hosts
Inventory Templates Inventory Templates
Inventory Virtual Machines Inventory Virtual Machines
Quiesce Quiesce virtual machine or datastore, creating vmware snapshot
Reconfigure Virtual Machines Reconfigure Virtual Machines
Restore Restore virtual machine or datastore residing on vmfs or nfs
Set Virtual Machines Power State Modify Virtual Machines Power State
Unquiesce UnQuiesce virtual machine or datastore, removing vmware snapshot
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


XenServer

Details
Provider Version 1.1.0
Target Version 6.2 and higher
Software Required JDK 1.7
Hardware Required 128 MB of memory; 100 MB of disk space
Default Port 9790


Actions
Apply Logic Execute scripts dynamically, apply filters, or go-to other steps in a workflow
Create Virtual Machine From Template Creates Virtual Machines based on an existing template
Create Virtual Machine Snapshots Snapshot Virtual Machines
Delete Virtual Machine Snapshots Delete virtual machine snapshots
Delete Virtual Machines Deletes one or more virtual machines
Export Virtual Machine Export Virtual Machines
Get Storage Repositories Get all storage repositories in the host
Get Virtual Machine Snapshots Gets all virtual machine's snapshots
Get Virtual Machines Gets all virtual machines in the host
Restore Virtual Machine Restore virtual machine
Set Virtual Machines Power State Modify Virtual Machines Power State
Execute Command Executes an OS Command
Sleep Introduces a sleep (ms)


Appendix B: Programmable API

Integra provides a REST API and SDKs in several languages. The object model, samples and SDKs may be downloaded from http://docs.emitrom.com/docs/integra/latest/

Appendix C: License

Integra is licensed under a commercial, non-open source license, which can be found at http://emitrom.com/commercialLicense

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox