Integrate vCO

0

Problems with AD-Plugin for vCO? Uninstall all old Microsoft-Plugin-Stuff!

By
Joerg Lew
– August 29, 2011Posted in: Powershell, Troubleshooting / Debugging

Some problems came up getting the ActiveDirectory-Plugin for Orchestrator run. Mostly the problems are related to wrong credential settings in the configuration:
http://communities.vmware.com/message/1748953

If you had the (old) Micrsoft-Plugin installed, you have to uninstall it completely. For details about how to do this, and some explanation, follow this discussion on the forums: http://communities.vmware.com/thread/319105

The new AD-Plugin has no WMI-support. Powershell has a good WMI-support. So the PowerSShell-Plugin might fit into the gap? Surely worth to figure out more and draft some ideas for the Roadmap…;-)   Stay tuned!

0

Integrating vCO: Access a Database (Overview)

By
Joerg Lew
– August 24, 2011Posted in: Best-Practices, Database, Integrate vCO, vCO Use-Cases, Workflow Design

VMware Orchestrator allows you to access SQL-Databases from within workflows. This post shows you common Use-Cases for that, explain technical background and introduces three-and-a-half ways how to implement the database-access.

Use-Cases

Accessing external databases within workflows is used to…

  • …integrate Your Workflows with external systems: You can retrieve or update information for an external system’s database (Ticket-System, Asset Management, CMDB, Documentation, Your VM-Deployment-System, ….
  • …build Your very own database-driven solution: If you create a larger “Suite” of workflows (like the VM-Deployment-System), expect that you have to deal with more and more metadata around the objects your workflows handle. A database is a good place to store this metadata, and it allows external systems to integrate easily with your Workflows in future.

Technical Background

The ability to integrate with external databases is presented by…. 😀


…the bundled  Database-Plugin. It provides a couple of Scripting-Objects for JDBC-Connections. So when you look for further reference information you can google for JDBC-Examples, they will fit (with some small limitations: Check the API Explorer of the vCO-Client to figure out the actual properties and methods of the JDBC-Objects).
In the bundled Workflow-Library you also find a Folder “JDBC Examples”, which provides a complete typical “lifecycle” of a database. Here you can also find a very useful Workflow called “JDBC Url Generator” which creates the correct complete JDBC-Connection-String you need to connect to the database.

Out-of-the-box, vCO supports Microsoft SQL-Server and Oracle-Databases, because for them the JDBC-Driver are pre-installed. However, it’s possible to add any other vendor’s JDBC-Driver; to get an idea, how to do this, see http://www.vmware.com/files/pdf/techpaper/vco-experimental-dbs-openldap-support.pdf.

Implementation Options

No matter, WHY you want to access external databases from your workflows, there are 3 (and a half) options to HOW do this:

1. Plain Database Access in Scripting Element

Just add a scripting element to your Workflow, and place the database operation in its JavaScript. This is useful, if you only call the database very rarely in defined workflows, and for single operations (For example: You want to update a documentation-database after deploying a new Virtual Machine).

2. Encapsulate Database Access to “DAO”-Actions

When you need database-calls more often in your workflows (Acutally, you should use this if you need it more than once :-)), you should encaplusate the database-calls into Actions. Typically you create pretty generic Actions for each CRUD-Operation, sometimes additional some “higher-level” Actions which do exactly the call you need often in the workflows.

(Side note: I call them DAO-Actions, compared to “Data-Access-Objects” in Software Engineering, when it comes to persistence and object-relational mapping in object-oriented software design.
Of course Actions are not “Objects”, but the idea is the same:)

So you create a single point/module, where all the database-related stuff is implemented. This makes it easier to do DRY-style developing, and rises the readability, re-useability, and maintain-ability of your works.
Consider the table-schema of the database you access is changing, so with DAO-Actions you only have to change the code in a single place.

Another big advantage using Actions to encasulate the database-access: You can use it in the Input Presentation of a Workflow! So you can get database-information even before the workflow starts. That can be used for example to make it easier for the end-user to start workflow which needs a VM as input, by providing a list of the current user’s VMs (and this information of course comes from the database):

.5 Call Stored Procedures

This is the “and-a-half” option, because it can be used in addition to the options above: JDBC allows you to call Stored Procedures of the database. This can be used e.g. if the vendor of an external system provide a bunch of Stored Procedures as an “API” for its database (or if you just want to pass all the SQL-work to the database-team :mrgreen: ).

See an example how to call a Stored Procedure in vCO.

3. Build Your own vCO-Plugin

The final option is the holy grail: Build Your own Plugin for the Orchestrator, which handles the integration to the external database. This of course is some effort, but it’s worth it if you integrate your workflows very frequently with this external database (or of course, if you build your own database-driven workflow-suite, see the second use-case above).

Building Your own custom Plugin allows you

  • to make database-entities accessible as JavaScript-Objects, and move all the database-specific stuff (table-layout, database connection details) to the Plugin. So the usage of the entities inside the Workflows and Actions is object-oriented, and all the SQL-stuff is hidden from the Workflow-Developer (see picture below).
  • to present database-entities as Inventory-Objects to the Orchestrator, which allows you to use these entities as Attributes and Input/Output-Parameters in Workflows. (Example: When integrating an Ticket-System, you can let the workflow-user select the actual Ticket for a certain workflow)

There are to flavors building such a Plugin:

1. Create the Plugin just with a vso.xml and some Hibernate-Mapping files (one for each entity you need in vCO). This allows you to present entites to the inventory, but you still have to wirte some generic JavaScript-Code in your Workflows & Actions.
On the other hand: You don’t need to develop a single line of Java-Code for the plugin 8-), and let the automatic Hibernate-Mapping-Feature of the Database-plugin do the work for you.

2. Create real Java-Objects in the Plugin and use the full vCO-Plugin API. This allows you to present your database-entities as real objects to the Workflows and Actions, and adds the full functionality of the API (like Triggers, …).
On the other hand: You have to develop Java-Code (a bunch of it), and you have to learn how the vCO-Plugin-API works. See the Solar-System-Plugin in the vco-examples-package an this presentation (Plugin-Development starts at ~28:45min) to get an idea of it. Good luck! 😈

Summary

The JDBC-Database-Plugin  provides very powerful integration-abilities for Your Workflows. You can start with a couple of JavaScript-lines for a simple integration, refactor them to DAO-Actions to have a clean Design when the need for integration grows, and unleash the full power of vCO by creating your own custom Plugin.

0

A WebService-Client for vCO: Running the samples

By
Joerg Lew
– August 22, 2011Posted in: Call Workflows from outside, Integrate vCO

VMware vCenter Orchestrator provides a SOAP-based Web-Service API, which you can use to start and monitor workflows from an external System. (This can also be used to create a webbased Client for vCO with something else than Webviews, see a detailed discussion here)

For a quick-start VMware provides a fully-functional Java-based Example-Client in the vco-samples.zip. In this post You will see how to build and run these examples.

You need:

  • A working Orchestrator Server
  • The Java Development Kit installed on Your Desktop
  • Ant
  • The vco-samples.zip, downloadable from the vCO-Documentation-Homepage

Prepare:

1. Download and install Ant (Don’t forget to set the environment variables JAVA_HOME, ANT_HOME and add the \bin-directories to your PATH!)

2. Download and unzip the vco-samples package.

3. Open a console, change to the webservice-example directory and run ant.

Use ant to build the examples

4. Edit the samples.properties-File and insert the connection details to Your vCO-Server:

5. Now you can run the Inventory.bat to check if the Sample-client can access the vCO-Server as expected (You sould see an “Ascii-Art – Representation of Your vCO’s Inventory):

(If something goes wrong here, it might be hard to read the error-messages. Double-check your connection-settings (including correct username/password) in the sample.properties!)

6. Most of the other samples in this Client access (hard-coded) Workflows. So you have to import the bundled Package to your vCO-Server: Open the vCO-Client, click on the small drop-down-Menu of the Packages-section, select “Import package…“, and import the com.vmware.samples.webservice.package from the WebServiceSample-Directory:

You should see a couple of new Workflows beeing added to your Workflow-Library:

7. Now you can run the other .bat-Files to Run a Workflow for instance (watch the vCO-client: You should see the new WorkflowToken appear!):

8. In the Example-client (built to samples.jar in step 3.) there are more calls, not all of them are a directly runable via a .bat-File. So for Your convenience you can copy the Inventory.bat to e.g. Samples.bat, and edit & replace the com.vmware.client.Inventory to com.vmware.client.%1 at the end of the (single) line. This allows you to call the other examples via the .bat instead of a long call with all the classpath-String.

To test, run Samples.bat FindAllByType (which should give you a list with all the VC:VirtualMachines in your Inventory):

A complete List with all examples:

  • FindAllByType
  • GetWorkflowEcho (broken, because of an hardcoded VC4:VirtualMachineGuestOsIdentifier … (you see: the examples-package contains some outdated stuff 😛  )
  • GetWorkflowOutput
  • Inventory
  • LaunchWorkflow
  • LaunchWorkflowWithInput

10. Now You can start examine, how the things work (or why not :mrgreen:  ) by digging into the sourcecode of the examples, which can be found in src/com/vmware/client:

Have fun! 😎

0

Wanted: Tester for Preview of my PowerSSHell-Plugin for vCO

By
Joerg Lew
– August 19, 2011Posted in: Integrate vCO, Plugins, Powershell

I’m looking for Tester for my first Plugin for the Orchestrator: The PowerSSHell-Plugin for vCO…

It allows you to execute Powershell Cmdlets and -Scripts from within workflows, without struggle with Security Context or painful parsing output text-data because it leverages the PowerShell SSH Server of powershell|inside and provides object-oriented results.

PowerSSHell-Plugin for Orchestrator - Architecture

So please Download the Plugin (it’s free, yet 😎 :-D), give it a try and share your comments on http://getsatisfaction.com/vcoportal

I’m looking forward to your feedback to create a further roadmap for the Plugin!

0

Small, but useful command-line tools for vCO Workflows

By
Joerg Lew
– August 17, 2011Posted in: Examples, Integrate vCO, Tools

In Orchestrator you can execute local commands on the vCO-Server using the Command-Object.

Usually it’s a good idea to place these commands together in a directory like c:\Orchestrator.
(
Don’t forget 1: Remember to configure your vCO-Server to allow the execution of local commands and to access these folder in case you have external scripts, temp-files,…:
Add com.vmware.js.allow-local-process=true to the vmo.properties-file, and configure the js-io-rights.conf, see vCO Administration Guide, section “Setting System Properties” for details.

Don’t forget 2: Remember to include this folder and all its file when you deliver your solution to production environment, customers, …! They are NOT included in any package you create inside your vCO content.

Don’t forget 3: The external tools are always executed in the security context of the Orchestrator Server (usually SYSTEM), and NOT in the security context of the user who starts the workflow. AFAIK there is no way to change this.
)

Some tools I call frequently:

curl

Download (the Amiga-Version…, just kidding :mrgreen: ) from http://curl.haxx.se/download.html, and call it e.g. with:


var url = "http://www.google.de";

var cmd = new String();
// 1st proof-of-concept example:
//cmd =  "c:\\vcoscripts\\curl.exe --help";
cmd = "c:/vcoscripts/curl.exe -o NUL -w %{http_code} " + url;

System.debug("executing cmd: " + cmd);
var command = new Command(cmd);
command.execute(true);

var resultNumber = command.result;
System.debug("resultNumber: " + resultNumber);
var curlResultNumber = resultNumber;

var resultOutput = command.output;
System.debug("resultOutput: " + resultOutput);
var curlResultHttpCode = resultOutput;

The resultNumber shows the result of the curl execution (e.g. if there are network problems), see the full list here: http://curl.haxx.se/libcurl/c/libcurl-errors.html
The -o NUL -w %{http_code} in the call configures curl only to return the HTTP-Status Code, which is then accessable via command.output.
For other possible parameters check the curl-Documentation: http://curl.haxx.se/docs/

Use it to check the availability of some Web-Resources, POST some data to external systems, GET information from external systems, or do the geeky hardcore way to access 3rd-party webservice (I rather suggest to use the new REST and SOAP-Plugin for the latter :-D).

AdFind

Download from http://www.joeware.net/freetools/tools/adfind/index.htm you can use this command to access the whole bunch of information on your Active Directory (without being limited to the small attributes accessible for a LdapUser-Object in vCO).

Example call:


var attribute = "sn"; //for surname, others see link in post

//hardcoded to use in workflow input presentation, otherwise I suggest to use a Configuration Element
var adfind = "c:/vcoScripts/adFind.exe";

//use-case here: get some information about the user running the workflow
var ldapuser = Server.getCurrentLdapUser();
var dn = ldapuser.dn;

var cmdString = adfind + " -list -b \"" + dn + "\" " + attribute;
var command = new Command(cmdString);
System.log("Executing System-Command: " + command);
var cmdReturn = command.execute(true);

System.log("...returns " + cmdReturn);

System.log("Output: \n" + command.output);

var output = command.output;

var outputStr = new String();

//remove blank lines at the end to have the answer in a clean string
if (output)  outputStr = output.replace(/^\s+|\s+$/g,"");
System.debug("outputStr: " + outputStr);

This example calls AdFind to get some attributes of the workflow-starter. (For a full list of Active Directory Attributes and their LDAP-Display-Name check http://msdn.microsoft.com/en-us/library/ms675090%28v=vs.85%29.aspx and the very convenient Excel-Sheet on http://www.rlmueller.net/UserAttributes.htm )
Use it to get the manager of the user for approval-workflow, document the telephone number in custom attributes in vCenter, or do usability-improving filters in input presentation.

However, AdFind is by far not limited to this use-case: Get some ideas what else you can get from your AD on the manpage: http://www.joeware.net/freetools/tools/adfind/usage.htm

cscript

Nobody really wants, but sometimes you have to… 😕 : If you have some existing VB-Scripts you want to execute, you can use cscript to start them in a console-context (without any windows, perfect for the headless vCO-Server). See the parameters here: http://technet.microsoft.com/en-us/library/bb490816.aspx

powershell

Command.execute() can be used to call PowerShell-Scripts, see an example on Calling PowerShell from vCO. However, you have to serialize input parameters and output results from  the script, which leads to very confusing command-strings and a lot of RegExp-Work to parse the output.
(Sneak Peek: I’m working on a better solution, watch for updates here)

…

Whenever you want to integrate your Workflow with external systems, you can search for CLI-tools of the external system (HP Lefthand CLIQ, DsShed.exe for Altiris, …) . They provide a quick (no need to learn/use any base-level API) but maybe dirty (the need for serialization to pass information, see above) way to achieve your goal.
Be creative!