PERL LogoThe goal of this tutorial is to create a simple workflow with a single string input that will be passed to a locally hosted Perl script for execution. The results of the script will be returned to vCO and stored in the workflow output. This could come in handy if you have existing systems that already have Perl based management scripts and you wish to incorporate their automation into your Orchestration policies.

 

Concepts Covered In this tutorial

The following concepts will be covered:

  • Enabling Local Process execution
  • Filesystem rights configuration
  • Use of the "command" object to execute a locally hosted PERL script

Tools Used

The following tools are used for this tutorial:

  • vCenter Orchestrator 5.1.1 Appliance (Perl is pre-installed in the appliance)
  • Simple Perl Script configured with at least 1 input parameter

vCenter Orchestrator Configuration

vCO requires special configuration considerations when dealing with local commands and filesystem access. The default settings of a vCO server limit access to specific local folders and prevents the execution of local processes. Local processes include scripts and commands hosted on the vCO Server.

Configure vCO to allow execution of local processes:

  • Go to /app-server/server/vmo/conf
  • Edit the vmo.properties file and add (if not already done) the following line to enable

com.vmware.js.allow-local-process=true
Configure vCO to allow filesystem access to scripts folder:

  • Go to /app-server/server/vmo/conf
  • Edit (or create if it does not yet exist) the js-io-rights.conf file
  • Assuming a folder name of "orchestrator" on an appliance, enter the following (adjust as desired for Windows):

+rwx /orchestrator

  • Add additional folders as desired. The line above adds (r)ead (w)rite e(x)ecute access to the /orchestrator folder to the vCenter Orchestrator Server service.

Once the two files have been edited as described above, restart the vCenter Orchestrator Server service.

Script Preparation

Script_Preparation.png

Prepare a simple script as an initial test to confirm things are setup properly. Once a simple script such as the example here is working, you can then try out more complex scripts/programs.

  • Create a new file named helloperl.pl in the /orchestrator folder
  • If using the appliance, be sure to set ownership on the file to the vco user/group: chown vco.vco /orchestrator/helloperl.pl
  • Also make the file executable: chmod 755 /orchestrator/helloperl.pl
#!/usr/bin/perl
print "Hello, ", $ARGV[0];

You now have a simple script and vCO configured with the ability to access and execute that script so it is time to create a workflow to do just that.

Create Workflow

Create_Workflow.png

Open the vCenter Orchestrator Client and create a new workflow called "Hello Perl"
Please use this exact name as it will be the subject of my next tutorial (described in the Summary and Next Steps section at the bottom of this tutorial.)

Add Scriptable Task

Add_Scriptable_Task.png

  1. Add a single scriptable task to the workflow
  2. Rename it from "Scriptable task" to something like "Run Script" if desired for better appearance

When complete, it should look like the screenshot above.

Create/Bind Inputs and Outputs

CreateBind_Inputs_and_Outputs.png

Since this is a simple test workflow, it will take two inputs and produce two outputs. We'll prompt for the name of a script and another input for the parameters. For this example we will have a single paramter. For a more complex script, you could dynamically build up a number of parameters in elements in earlier parts of a custom workflow, storing them in a workflow attribute and then bind that attribute as an input to the "run script" scriptable task.

Click on the Scriptable task and add the following inputs:
scriptName (string) - Create New Workflow Input Parameter
scriptParams (string) - Create New Workflow Input Parameter

Add the following Output:
scriptOutput (string) - Create New Workflow Output
scriptResult (number) - Create New Workflow Output

 

Confirm Bindings

Confirm_Bindings.png

Click on the "Visual Binding" tab of the "Run Script" to confirm the bindings are as shown in the above screenshot.

Set Presentation

Set_Presentation.png

  1. Click on the "Presentation" tab, then choose the "scriptName" input
  2. Add a new property to the input for default value
  3. Set the default value to "/orchestrator/helloperl.pl"
  4. Add a new property to the input for "Mandatory" and set to "Yes"
  5. Click "Save"

Code the Scriptable Task

Insert the following code into the scriptable task:

// Prepare Command line and parameters to execute:
cmd = scriptName + " " + scriptParams;
System.debug("executing cmd: " + cmd);

// Create and execute the command:
var command = new Command(cmd);
command.execute(true);

// Display command results and output 
var scriptResult = command.result;
System.debug("Script Result: " + scriptResult);

var scriptOutput = command.output;
System.debug("Script Output: " + scriptOutput);

How to use the output

The results and output could be passed to another scriptable task for parsing and additional actions if desired. In that case, you would need to move the "scriptOutput" and "scriptResult" Output Parameters to Attributes.

Save, Description, Version

Save__Description__Version.png

This completes the creation of the workflow so it should be saved.
When saving a workflow, be sure to provide a nice description (1) so that it is obvious what the workflow is designed to perform. Here, we'll add the following:
This workflow will execute a simple Perl script that takes a single parameter. The output of the workflow should be the result code and any script output generated.

In addition to a description, you should version your work (and increment the version each time you update the workflow.) Go ahead and do that now (2). When you set the version, you'll be prompted for a version comment. I typically start with something like: Initial Version.

Save and Close the workflow now, we're ready to run it.

Execute the Workflow using vCO Client

Execute_the_Workflow_using_vCO_Client.png

At this point, you should still have the vCO Client open and the "Hello Perl" workflow selected.

  • Right-Click on your workflow and select "Execute" (or use one of the other methods to start the workflow)
  • The "Script Name" should have the default value that was specified at design time
  • Enter your first name in the "Script Parameters" box
  • Click "Submit"

View Results: Variables

View_Results_Variables.png

After a successful run of the workflow, your results should appear similar to the above screenshot.

View Results: Logs

View_Results_Logs.png

After a successful run of the workflow, your results should appear similar to the above screenshot.

Summary and Next Steps

This tutorial has provided you with a foundation for utilizing existing scripts and programs that may reside on your vCO server. Although this example was done on a vCO appliance, the same principals and steps apply to the Windows version of vCO. Leveraging existing Command Line utilities within workflows is an excellent integration example for systems that may not have a proper API available.
For example:
Windows systems have .exe files such as the Active Directory tools dsadd.exe, dsmove.exe, dsquery.exe, etc...
Some IPAM software, portals, or other misc systems may ship with a set of Perl, Python, or other management scripts

Any of the above may be utilized in the same way we have run the sample Perl script in this tutorial.

In my next tutorial, you'll learn how to access and run this "Hello Perl" workflow via the REST API !

  • Locate the api documentation found on your vCO server
  • Find the workflow
  • Identify inputs, outputs, and the proper format
  • Work with XML based REST
  • Learn to force JSON for the input/output of REST Queries