Examples

0

Let your vCO Workflow text you! Yes, via SMS!

Working on another blogpost on some design best-practices for workflows (stay tuned…) a promising idea came into my mind:

What about sending text messages to my mobile from workflows?

I guessed there are many SMS-Gateway-Services out there which provide any kind of SOAP or REST-API… (I want to leverage an existing plugin for vCO for quick results). So google came up with this nice discussion:

http://stackoverflow.com/questions/2383542/recommendations-for-sms-gateways-with-api-support

I decided to give https://www.clickatell.com a try, because they

  • provide interational service
  • provide multiple kinds of API
  • seem to be reliable and widely used
  • don’t force you in a contract/monthly plan for my limited test usage

What you need to reproduce this example:

  • a clickatell account (I think it will work with most of the other SMS-Gateway services in a comparable fashion)
  • the REST-Plugin for vCO installed in your Orchestrator environment (see details here: http://www.vmware.com/support/pubs/vco_plugins_pubs.html (Select HTTP-REST for the plugin-download and a bunch of examples)

Step-by-step…

I quickly signed-up for an account, used the web-form to send a test message to German) mobile number, and prepaid for some credits to be able to send via the API.

After that, I created a new access for the “HTTP”-API of clickatell (no special settings):

(You may open clickatell’s API Documentation now in background if you’re a read-first-try-then kind of guy.)
For myself I just started my vCO client and ran the “Add a REST host”-Workflow from the library, providing just a name and http://api.clickatell.com as URL:

The workflow finished sucessfully, I confirmed the new host in the Inventory:

Now I called the “Add a REST operation”-Workflow to invoke the API-Call to clickatell (based on their example given when creating the API account):

(instead of hardcoding my credentials I used the generic {parameter}-notation of the REST-plugin for all the necessary parameters like username, password, API-Id, …, so that I can re-use the  operation later flexibly). The full “Template URL” value is:


/http/sendmsg?user={username}&password={password}&api_id={apiid}&to={tonr}&text={message}

When the operation was created (again: Confirm in Inventory-Tree) I started the “Invoke a REST operation” workflow providing all the input parameters:

aaand voila,  😎 seconds later the text messgae arrived on my mobile!   :mrgreen:

Now, the real-world use-case:

Well, sending generic messages to a mobile from a vCO workflow is cool|geeky, but what for? For a realistic example I used the Workflow-Generation of the REST-Plugin to let vCO generate my very own “Invoke ‘send a text message'”-Workflow in my very own Workflow folder for easy re-usage:

So I was able to re-use the created workflow in my Snapshot-Hunter-Workflow… (you know the pain with backup software which accidentally forgets to cleanup the VM snapshots! :evil:)

(The first element to find these workflows leverages the xpath-filter of the VcPlugin.getAllSnapshots()-Method, see the discussion here: http://communities.vmware.com/thread/342686 and http://communities.vmware.com/message/1673575 )

At the end: After scheduling the workflow as Scheduled Task in vCO, starting from tomorrow I will get waked-up by my mobile receiving an text message from vCO when there are leftover snapshots from the nightly backups!

Summary

  • Don’t fear any tasks integrating vCenter Orchestrator! When the external system provides an API, chances are that you get in run in a few minutes…
  • Remember: less and simple workflow inputs make it easy to use, many and generic workflow inputs make it easy to re-use! (referencing the “Workflow Development Best Practices”-session as a shameless plug :mrgreen:)
  • Sometimes it IS good to be creative|distracted when drafting a blog-post (expect the post I actually was working on soon…)
  • Turn off your mobile when you want to sleep in!
  • …and thank god I’m too tired to think about other use-cases for this…
    (I will not make an Orchestrator & Ringtone joke!
    I do not plan to provide a monthly subscription for my content, just text a SMS with “vCO Rockz!” to …..
    And I better not search for an API for Asterisk (“If you want to execute workflow XYZ, press 1; for all other requests press 2” 8-O)

Download the example

SnapshotHunter Package
SnapshotHunter Package
de.vcoportal.snapshothunter.package
23.3 KiB
Details...

Be aware that it will NOT run out-of-the-box, because you have to add the REST-Host and the Operation in your environment! And: Don’t forget to set the necessary values for username, password, mobilenr, … in the configuration elements.You know that blogpost whith a great description of Configuration Elements, don’t you! 😛

0

How to find Inventory Objects when calling vCO Workflows via the SOAP API

When calling an Orchestrator workflow from outside via the SOAP-API, things get dirty if your workflow have input parameters (see details here: http://www.vcoportal.de/2011/06/updated-calling-vco-workflows-from-powershell/ ). And things get really dirty, if the input parameter is an Inventory Object (like a Virtual Machine, provided by the vCenter Plugin).

The reason for that:
Before you can finally call the actual workflow, you have to get the vCO-internal ID of the object, usually by calling other API-methods before. In the vCO WebService documentation you can find following flow-chart, I marked the step we’re talking about:

Depending on what information the workflow caller has, you can call the findForId, or the find method with an xpath-expression. (expecially when working with the vCenter-plugin, always remember: The managed object Id in vCenter or the name of the Virtual Machine is not necessarily unique in vCO, because you always can have connections to multiple vCenter-Hosts!)

Thanks to David (@creativeview) and Igor a full example in Powershell:

$vcoWS = New-WebServiceProxy -Class VCO -Namespace VCO -Uri http://mycoolvcoappliance:8280/vmware-vmo-webcontrol/webservice?WSDL
#find the workflow
$workflows = $vcoWS.getWorkflowsWithName("Start virtual machine and wait", "vcoadmin" , "vcoadmin")
#find the virtual machine
$result = $vcoWS.find("VC:VirtualMachine", "xpath:name='TheVM-Name'", "vcoadmin" , "vcoadmin")
if ($result.TotalCount -gt 0)
{
#$result
$finderResult = $result.Elements[0]
$stringObjectRepresentation = $finderResult.DunesUri
#Write-Host $stringObjectRepresentation
}
$workflow = $workflows[0]
# print out input Parameters
$workflow.inParameters
# generate Array with Input PArameters (WorkflowTokenAttribute - Objects)
$inparams = @()
# fill the array, one entry for each input parameter
$inparams += New-Object -TypeName VCO.WorkflowTokenAttribute
$inparams[0].name = "VM"
$inparams[0].type = "VC:VirtualMachine"
$inparams[0].value = $stringObjectRepresentation
# Exectue workflow
$workflowToken = $vcoWS.executeWorkflow($workflow.id, "vcoadmin" , "vcoadmin", $inparams)
(be careful with the ‘ and ” surrounding the xpath-expression, depending on which programming language you use)

See the full discussion in the forums (some Java lines included as well 🙂 ):
http://communities.vmware.com/message/1889504#1889504

My original example how to call vCO Workflows via Powershell (with plain data types for input only :oops:):
http://www.vcoportal.de/2011/03/powershell-vco/

You can also find some examples about this in the vco-examples-package, more information how to get started with this:
http://www.vcoportal.de/2011/08/sample-webservice-client-for-vco/

And an unofficial tip at the end: Rumors are that the next major release of vCO contains a new REST-based API, so don’t spend too much time learing this legacy stuff, if you don’t need to…

0

VMwareTV: Getting Started with Workflow Development

The Orchestrator Developer Team at VMware created a great series of video tutorials on youtube how to “Develop your first workflow” with vCenter Orchestrator:

Find more links on the Resources Page

0

Small, but useful command-line tools for vCO Workflows

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!

0

vCO Use-Case: Extend vSphere Functionality: Clone from Snapshot

Why?

One possible Use-Case for vCenter Orchestrator is to provide some kind of User Interface to vSphere Features which are not directly usable from vSphere Client.

The vCenter-Plugin bundled with vCO provides access to the complete vSphere API (even though some of the Library Workflows and Actions are not complete to the current version). So it is possible to create a Workflow that uses API-Calls that are not visible in the standard vSphere Client.

Example needed?

The vSphere API allows you to create Linked Clones of Virtual Machines.
This feature is not exposed to the vSphere Client (for some good reasons I guess 😆 , think about all the “Pebkac”-issues even with usual snapshots 🙄  ).

However, in vCO there are some Workflows to create Linked Clones (in Library / vCenter / Virtual Machine Management / Clone / Linked Clone):

Other Example: Clone from Snapshot

vSphere Client olny allows you to clone the current state of a Virtual Machine, even if the Virtual Machine has one or more Snapshots.

However, often you want to clone the old state of a Virtual Machine, which is “conserved” in a Snapshot:

  • in Lab/Dev/Demo/Test-environments you want to roll out several “branches” from the same state of a VM,
  •  in production environments you recognize the “bad-practice” to keep a lot of Snapshots, but before deleting them you want to clone these old states for later usage,
  • everywhere you have a snapshot, but you don’t know the reason and state why it was created, and you want to go for sure before deleting it,
  • …..

The vSphere-API allows you (since 4.1) to clone a Virtual Machine from a snapshot state by specifying the snapshot in the VirtualMachineCloneSpec.

For this there is no bundled Workflow in the Library, so can take my package with the solution:

How to use it?

1. Download the Package from http://www.vcoportal.de/download/workflow/com.vcoportal.snapclone.package

2. Import the Package to Your Orchestrator:
(depending on the Version of Your vCO-Server it will ask to import some used library-Actions as well…):

3. Start the new “vcoportal.de // Clone from Snapshot”-Workflow:

4. Select the source Virtual Machine, one of its Snapshots, all the target information as for a usual clone task, and watch the progress in vSphere Client 😎 !

How does it work?

(Well, the package allows you to inspect the content, so see for yourself 😛  )
The Package contains a Workflow and two Actions, all duplicated from original Library-content bundled with vCO. The only extension I did was to add the “snaphot”-Parameter to the Action which provides the VirtualMachineCloneSpec and extend the “Clone VM”-Action to allow filling this parameter.

A possible improvement: Add a “filter” to the Input Presentation to show only Virtual Machines which have at least one Snapshot.
Another possible improvement: Add some validation, that the Snapshot really belongs to the Virtual Machine (here it is done by the “tree-root”-Property of the Input Presentation of the Snapshot Parameter. However, if you call this workflow from other workflows, the input presentation is not been processed…).

Do you have ideas for more improvements of the package?
Or are you looking for other workflows with functionality the API provides but is not usable from vSphere Client?
Leave a comment, insert a coin (or spend a drink at VMworld 🙂 ) and be patient!

Clone from old Snapshot-Package
Clone from old Snapshot-Package
com.vcoportal.snapclone.package
31.3 KiB
Details...