Pipes and Variable Substitution

  • Posted on: 30 January 2015
  • By: David La Motta

Integra has a a powerful mechanism for actions to consume the results of other actions.  With the help of pipes, you can feed an action's results to one or more actions when combined in a workflow.  This blog post gives you examples of how to make the most of Integra's piping mechanism, and also how to use variable substitution--or inlining, as we affectively refer to it.  The examples used in this post assume you are familiar with Integra and that you have it installed and running.  If you do not, take a moment to familiarize yourself with Integra first.


The way intra-provider communication takes place is handled by Integra.  This means that you can have, for example, the SmartCharts provider producing results, and having another provider such as the Notification provider consuming those results.  The same principle applies to all providers in Integra; in short, the marshaling / unmarshaling of data is taken care of for you.  Lets set up 3 providers so we can see this in action.

Providers



We are going to list VMs and feed that output to both the SmartCharts and the Notification providers.  Additionally, we are going to inline a couple of variables so we can see how that works.

Actions

The first thing we'll do is configure the action that lists the VMs:



As you see in the image above, executing that action returns 4 VMs.  The output object that is returned is called 'vmDetails', which contains several fields (cpu, dsName, memory, etc).  It is those fields that, once piped into another action, can be used with the ${variable} or @{variable} construct.  Hang tight, we'll show you how to leverage that in just a moment.

Next up, lets configure the charting action:



The first usage of a variable appears in the chart's filename.  Integra has several reserved variables that will be replaced without using pipes.  In this example, we add the timestamp to the filename so that it is unique.

The last action we need to configure is for sending out an email.



This action is making use of two variables:  a reserved variable called ${integra.user} and a regular field called @{type}.  As mentioned earlier, the @{variable} construct inlines that value with an array.  In this example we are going to list all of the operating systems found in the VMs returned by the first action.  The first variable, ${integra.user} will be replaced with the user which is currently running the operation.  This is particularly useful when executing workflows using the self-service portal; at runtime, the username of the user logged in to the portal will replace ${integra.user}.

Workflows

Let us craft a workflow so we can see piping in action.



The List VMs action will send its output to the Create Chart and Send Email actions.  As you saw earlier, this means that all fields from the vmDetails object are available to both actions 2 and 3.  If you recall from the images above, we are using the @{type} variable so we can list operating system names in our email.

When using pipes to feed raw output to an email action, that output will be automatically sent as an attachment in JSON format.  The Create Chart also sends its output to the Send Email action, but something implicit is also taking place in this scenario.  Any action in Integra that produces a 'file' object has the ability of sending that file as an attachment in an email.  There is nothing to configure, nothing to use in terms of variables; the mere fact that a 'file'-producing action is piped to an 'email' action is enough.  The email will take the file and send it as an attachment.

Results

Lets execute the action via the portal and see what we receive in our email.

                    

The image on the left shows the user we are logging in with.  If you recall, we used ${integra.user}@emitrom.com in the To: field of the email action.  As you may suspect, at runtime this is going to be replaced with support@emitrom.com, and thus we should get our email without much trouble.  The image on the middle shows the Execute button, which needs to be tapped to trigger execution of the Get VMs by OS workflow.  The image on the far right shows that our workflow executed successfully. 

We should have an email in our inbox with a few interesting things:
  • List of operating system names
  • A bar chart attached to the email
  • A JSON file with VM details also attached to the email
Lets see what we have below.




Summary

Everything looks as expected, which is great.

In this short blog post you saw how to make use of the Integra variables (${variable} and @{variable}), including Integra's reserved variables.  We also showed how to pipe one or more outputs to other actions and how to consume them.  In the special case of the email action, it is capable of accepting raw piped output and attaching it as a JSON file, or if an action produced a file it will automatically be attached to the email.

If you'd like to learn more about variable inlining, visit the Integra user guide where this and many other topics are discussed in detail.

Happy automating.

--