***DRUMROLL***  Let me introduce ……***DRUMROLL***… Christian Strijbos as co-author for vcoportal!

Christian works as Senior IT-Architect for a VMware Consulting Partner in Germany, helping customers of all sizes and all industries to design, implement, automate and orchestrate (obviously  ) their VMware environments. He holds VCDX3 and VCDX4 certifications (magic number: 64).

Current work in progress: Wavemaker and Orchestrator and (better(?): versus  )  LDAP, much more in the pipeline… So, stay tuned for great articles coming soon!

“…how to use orchestrator to change the Video Card Setting of a VM to “Auto-detect settings” the next time the VM reboots?” (read the full thread here: http://communities.vmware.com/message/2040860#2040860)

That is a typical task for a workflow developer: Automate something you can easily click in vSphere Client, but it maybe hard to figure out, how to automate it.

ONYX to the rescue!

See this video how to get to the solution in less than 15 minutes  … (You can download the resulting workflow below, but that shouldn’t be necessary anymore !)

It’s a quick shot screencast, so no audio….

If you like the style, drop me a comment, and I will create more videos (with explanations  ) in future!

Change VM Video Settings Workflow
Change-VM-settings-to-auto-detect-video-memory.workflow

This workflow changes the video settings of a VM. It was created using Onyx

Author:	Joerg Lew
Category:	Workflows, Actions and Packages
Date:	May 10, 2012

2.1 KiB
Details...

The need for unmaintainable workflows

As an external consultant as well as permanent employee it’s always a good idea to make yourself indispensable for your customer/company. This ensures ongoing engagement/a safe job.

In IT in general you can achieve this by devloping unique solutions nobody else except yourself can understand (and maintain). I’m sure: You all can instantly give at least one example for an IT-component where youself/your teammates/everybody else follow the policy: “Never touch a running system“.

 <buzzword-for-the-robots>The modern term for this is NoOps.</buzzword-for-the-robots>

 As a workflow developer you also can follow some simple rules to make sure: You, and only you, will be able to maintain, re-use or even exand your workflows!

Here we go…:

Documentation, Labeling, Description Fields

Avoid Documentation, and use the default labels for workflow elements. So one has really click into each element, read the code, see the bindings to figure out what happens here.

When naming workflows and actions, and their parameters and attributes: Don’t be too obvious! A simple “name” or “vm” or “theArray” is enough.

Be aware of the Description fields! They are shown in so  many different places (when you re-use the elements, mouse-over in the schema, for documentation, …), that your really want to avoid this disclosure of “what this element is for”.

Logging

For the usage of System.log(), System.debug() and co. you have the choice:

• Don’t log at all! Your NoOps-Team will thank you for that.
• Log everything! It’s always a good challenge for the NoOps-Team to find the really important messages in hundrets of lines with traced-out variables (Eastern is coming!)…
• Just log values! The value of a variable is what’s interesting. Nobody wants to know what variable it is… System.log(myVariable) does the trick.
• Pro-Tip: You can even improve confusion by logging WRONG things, e.g. when you copy&paste scripts to re-use it in another context.

Workflow Design

Especially important for Library-Workflows which are intended to be called by other Workflows:
Hardcoding values in the script, not exposing important parameters as INPUT-parameters and  creative usage of  the data types ANY and Properties (of course whithout proper documentation) will ensure that it’s you, and only you, who can re-use the workflow.

In General:
Use the default names “actionResult” and “errorCode” when binding Action elements and Exception paths…

Forget about the “Add note…”-Feature! Structuring workflow part with coloured background just creates a better visual structure for the workflow.

Workflow Organization

Duplicate Workflows for small adjustments! This helps to keep your work big if something has to change in there for the next version.

Don’t use too many Workflow Folders, or clear labes for them! Leave it to the user to figure out which workflows are intended to be called manually, and which ones are just the “drivers” for them.

Create hidden dependencies! Calling Actions or nested Workflows not via the corresponding Elements, but within scriptable tasks creates nice surprises if one is changing the called.

Optimize your JavaScript coding style

You can find a long list of tips for that here: http://thc.org/root/phun/unmaintain.html

Forget vCO, just do scripting!

Who needs the visual, self-explaning graphical flowcharts of vCenter Orchestrator when you can to something like this??:

Pro-Tip: Use the PowerShell-Plugin or the PowerSSHell-Plugin to combine the best of both worlds. This will garantuee your job forever!

HAPPY APRIL FOOLS’ DAY!!!

Special Greetings to my mates in Sofia : Please do not take that criticism of some parts of the vCenter-Plugin-Library personal! I know it’s an hard challenge to maintain this inherited aged content . You do a great job, especially with all the new “written-from-scratch” Plugins! Keep them coming!!!

Got more?

Comment on the post and share your finest ideas  how to create poor workflows!

What happend?
I tried to update my vCO Appliance to the current Version 4.2.1 using the built-in update-feature (that’s what we have an appliance for). It stucked with the screen “Installing vCO Appliance – 4.2.1.0 Build 612841, please wait…”, and the vCO service was not running anymore. Even a reboot of the appliance didn’t bring the service up again.

To save you this troubleshooting time:
This behaviour is not really expected, but documented in the Known Issues-Section of the vCenter Orchestrator 4.2.1 Release Notes…

Therefore, the complete process to

Update the vCO Appliance to version 4.2.1

1. Login to the Appliance Configuration page

2. Start the Update in the “Update“-Tab

3. Leave the Update-Tab open, and oen a new browser tab with the Orchestrator Configuration, goto Database, confirm that there is a problem (“Mismatching database version”)

4. On the top of the Database-Section, click to “Update”

5. Start the vCO Service in Startup Options

6. Confirm in Appliance Configuration / Update-Tab the new vCO version

7. Orchestrate again!

http://140byt.es

There you find functions and other small examples of JavaScript code in Tweet-length. Mostly very elegant solutions, sometimes hard to understand directly, but always with a longer, annotated version.

Most functions can be used as-is in vCO Scriptable elements, like this one to figure out the ordinal suffix of a number (the “st” of 1st, “nd” of 2nd and so on):

function b(a){return["th","st","nd","rd"][(a=~~(a10&&a3?0:a]}

In a vCO Scriptable Element (or an Action) the annotated long version would look like this (theNumber is an IN-Parameter of type Number):

var ret = ordinal(theNumber);
System.log(theNumber + ret);

function ordinal(
a                         // number
){
return[
"th","st","nd","rd"     // array of ordinal suffixes
][
(a=~~                   // floor the value for usable index (integer)
(a10&&a3                      // all digits above 3 return "th"
?0                      // return "th" for above cases
:a                      // return "th", "st", "rd" for others
]
}

Just be aware that some of the snippets use the prototype-Feature of JavaScript (to extend basic objects with new methods). This is not available in vCO and you will get an error like

“Cannot add a property to a sealed object: ….“

But there are enough other functions for lots of nice use-cases in vCO. Enjoy!

Original Post:

You all know VMware vCenter Orchestrator Appliance as the quickest way to get started with vCO.

You all have learned (maybe the hard way) that the vCO Appliance uses 4 (in words: FOUR) different credentials…

The vCO Appliance user credentials

• One for the root-user Appliance it self: This is used if you select the “Login”-Button on the console of the appliance (or via SSH, if you enabled SSH login for root (google for “ssh PermitRootLogin”)) and for the webbased  “Appliance Configuration” (on port 5480) . Change it with the passwd command on the console.
• One for the “Orchestrator Configuration” webpage (port 8283). It can be changed using the “Change Password”-Tab in the General-section of the configurator (username is always vmware):
  
  
• And finally, the (ldap-based) users to login with the vCO Smart Client or the weboperator (port 8281). Default: vcoadmin with password vcoadmin and vcouser with password vcouser. This article shows how to change their credentials…

Typically the default webpage asks you for new passwords for the appliance’s root-user and the vmware-user of the configuration when you click  on the links for the first time.

Change the default passwords for vcoadmin and vcouser:

For the vcoadmin & vcouser it’s not that easy: Because they are users defined in the local OpenLDAP-installation of the appliance, you have to use some ldap tools for this…

1. Login to the appliance on the console (or via SSH if PermitRootLogin is enabled)

2. Type following command:

ldappasswd -D “cn=vcoadmin,ou=vco,dc=appliance” -W -S

3. Type in the NEW Password for the vcoadmin-user (twice), and the OLD one once (when being asked for LDAP password)

(optionally: repeat the steps for cn=vcouser,ou=vco,dc=appliance”)

4. Because you changed the password of the vcoadmin, you have to reconfigure all settings which are using this password:
The password to browse the ldap-directory (in LDAP)

The password for user vcoadmin which is used to install Plugins in PLUGINS)

5. RESTART THE vCO SERVICE!
(It took me for a complete cup of coffee to troubleshoot that I forgot that step)

6. Voila: Test the new passwords in LDAP / “Test Login”-Tab and just by logging in with the vCO Client.

References

• ldappassword man-page:
  http://www.centos.org/docs/5/html/CDS/cli/8.0/Configuration_Command_File_Reference-Command_Line_Utilities-ldappasswd.html
• Discussion in the Forums:
  http://communities.vmware.com/thread/335136
• @vCO Developer Team: Feel free to add this description to the next version of the
  vCO Appliance User Guide

“In computer science, reflection is the process by which a computer program can observe (do type introspection) and modify its own structure and behavior at runtime.” says Wikipedia.

The Orchestrator also provides a kind of reflection for workflows: Using the keyword “workflow” in a JavaScript Element a workflow can access its current runtime state. This article explains the basic understanding about Workflows and WorkflowToken, script examples and common use-cases for that.

The Basics

An important conecpt of vCO is to create a so called Workflow Token for every single time a workflow gets executed. Only so it’s possible to keep track of multiple in-parallel runs of the same workflow, what’s absolutely possible. (Currently supported in vCO 4.2: 150 concurrent running workflows).

In the vCO Smart Client you can see all the workflow token (=past executions) in the Workflow library, as leafs under the workflow itself:

If you are familiar with object-oriented programming, consider the Workflow as a class (description), the WorkflowToken is an actual instance of this class.

When you select a workflow token in the tree, you can see its details in the main window, most important:

• the state (e.g. running, failed, completed, waiting)
• the current vlaues of the workflow attributes
• the log output (done via System.log() or System.debug())
• (if there is one:) the error message at the bottom of the Variables-Tab

<Additional Technical Background>: All information about the state of a workflow token is stored in vCO’s database (the state, the attributes, the current element,…). So it’s possible for vCO to continue the workflow even after a crash of the server (Checkpointing).
For a quick & (really!) dirty ( & completly unsupported!) monitoring you could do SQL-cram against the vCO database like that:

ALTER trigger [dbo].[monitor] on [dbo].[VMO_WorkflowToken]
AFTER UPDATE
AS
SET NOCOUNT ON
IF EXISTS ( SELECT * FROM Inserted I WHERE I.globalState = 'failed')
BEGIN
/* ***DEMO ONLY:** */ Insert into dbo.fails VALUES ('adsf'); # send a mail, wake somebody up...
END

</Additional Technical Background>

How to…

Back to topic: You can also access the runtime information about the current workflow execution “from inside”, by using the keyword “workflow” (small-caps, remember: JavaScript is case-sensitive!) in a scriptable element.
This keyword returns an object of type WorkflowToken.  This object now represents the current instance of the workflow. This object provides some attributes, see the script below for examples…

Important: If you want to access the Workflow-object (the (class/description/definition), you have to use the rootWorkflow-Attribute of the WorkflowToken (eg. “var theWorkflow = workflow.rootWorkflow”; theWorkflow will be of type Workflow). (Yeah, that’s what I meant with “beyond the obvious”)

The following script examples shows all that stuff: First we get some information about the current instance (you got it, the WorkflowToken). Starting in line 10 we access the Workflow, the last part from line 23 uses the WorkflowToken again.

//get the current workflow token /"instance"
 var token = workflow;
 System.debug(token);

//get some details about the current workflow token/execution/instance
 System.debug("startDate: " + token.startDate);
 System.debug("businessState: " + token.businessState);

//get the Workflow-"Class" of the current token
 var rootWorkflow = workflow.rootWorkflow;
 System.debug(rootWorkflow);

// get "declaraction": Array of Input Parameters of the workflow in general
 var inParams = rootWorkflow.inParameters;
 System.debug("inParams: " + inParams);
 //loop through array and print out details for each parameter
 for (var i in inParams) {
 loopParam = inParams[i];
 //print out in type:::name:::description
 System.debug(loopParam.type + ":::"+ loopParam.name + ":::" + loopParam.description);
 }

// get the current token's inParameters (they include the values, and are returned as Properties
 //(key : values tuples)
 var curInParams = token.getInputParameters();
 System.debug("curInParams: " + curInParams);
 //crawl through the Properties
 var keys = curInParams.keys;
 for (var i in keys) {
 var curKey = keys[i];
 //print out properties in format key :::: value
 var curValue = curInParams.get(curKey)
 System.debug(curKey + " :::: " + curValue );
 }

All that happens just in the script, there are no workflow attributes bound to this scriptable element. The Workflow you can download below has one INPUT Parameter, just to see something in the logs . It’s not used anywhere.

The script produces output like this:

Use-Cases

Now, what to use all that stuff for?

• Obviously, if you need some of the information, like the startDate, later in the workflow
• If your workflow has an User Interaction element, you can send an URL to answer it via email (there is a complete example in Library / Mail)
• It’s possible to change the User context the workflow runs, using the changeCredential()-Method
• If you are working with the Business State field of workflow elements, you eventually want to read this in script.

Not really related to the “Reflection”, but useful anyway:
The same objects are used when you access past workflow tokens not of the current workflow, but of other workflows. This can be used for instance to create Healthcheck Workflows which monitor the vCO Server for failed or canceled workflow runs (a much cleaner & more reliable ( & supported) way to replace the SQL-cram mentioned above!).
Insider Tip: See the Actions provided by the module “com.vmware.web.webview” for a lot of useful scripts! They have many more use-cases than only within webviews…

Now, finally:

Download the example!

It should just run out of the box…

Workflow Reflection example
WorkflowReflection.workflow

This workflow just prints out some information about itself...

Author:	Joerg
Category:	Workflows, Actions and Packages
Date:	March 8, 2012

1.8 KiB
Details...

http://communities.vmware.com/docs/DOC-18638

Find the original post also on http://cloudnutz.com/2012/03/07/using-vmware-vco-to-manage-vmware-view/

And don’t miss some (unofficial, but don’t blame me (this time ) ) additional PowerCLI cmdlets for VMware View: http://velemental.com/2012/02/04/unofficial-advanced-vmware-view-powershell-cmdlets/

And Dear VMware View Team: Please give us a full (and documented) (and official) API!

Or even better: What about a View-Plugin for vCO?
I know a lot of customer having use-cases for it (and a lot of people having to use workarounds like this for now). Desktop-as-a-Service and Cloud Desktops need Orchestration (just to add the buzzwords for the robots )

So it’s possible to loop through all the attributes even if you don’t know their identifier (yet). Following example in Javascript does exactly that, to trace out all attributes of a VM-Object (Type: VcVirtualMachine) and its Datastores. (you can download the full example below)

The script

//print out properties of a VM-object

//loop through all properties (leverage Javascript's
// "object is an associative array" characteristic)
for (var i in vm) { (//vm is an input parameter of Type VcVirtualMachine
	//we have to catch some 'not defined' errors if object has
	//an attribute of type "dynamic property")
	try {
	//print out in form "propertyname:::value"
		System.debug(i + ":::" + vm[i]);
	} catch (ex) {
		//just ignore error and continue with next iteration(=property)
		continue;
	}
}

//other example: For a datastore
System.debug("================================");
System.debug("====NOW FOR THE DATASTORE===");
System.debug("================================");
var vmsDatastores = vm.datastore;
System.debug("VM's Datastore(-object): " + vmsDatastores);
//vm.datastore return an ARRAY OF DATASTORES itself, so we have
//wrap it in another loop
for (var k in vmsDatastores) {
	var curDatastore = vmsDatastores[k];
	System.debug("******** NEXT DATASTORE: *****");
	System.debug("curDatastore: " + curDatastore);

//same loop as above for each datastore
//play it again, Sam!
for (var j in curDatastore) {
	try{
		System.debug(j + ":::" + curDatastore[j]);
	} catch (ex) {
		continue;
	}
}
//end same loop as above  

} //end loop through Datastore-Array

The results

The output looks like this:

To interpret the results, an example line of the output:

[2012-03-06 09:45:23.844] [D] resourcePool:::DynamicWrapper (Instance) : \\
    [VcResourcePool]-[class com.vmware.vmo.plugin.vi4.model.VimResourcePool] \\
    -- VALUE : ResourcePool<resgroup-98>

The first part resourcePool is the name of the attribute.
After the ::: separator you get the object type [VcResourcePool] of this attribute, the providing class in the vCenter-Plugin of vCO,
and finally after the – separator you get the value of the attribute, in this case it’s with ResourcePool<resgroup-98> a Moref (Managed Object Reference) to the resource pool the VM is located in.

Now you can use the .-Operator in JavaScript to access the attributes, as in line 21 in the script where we do the cram again for all Datastores the VM is related to.

Only caveat: Just from the System.debug()-Output it’s NOT possible to see if an attribute is just a single object or an Array!
(read carefully the example again: vm.datastore (line 21) returns and Array of VcDatastores, but you cannot see this just from the output of line 22)

Conclusion:

Always have the vSphere API Reference open in background when working with vCenter objects in vCO!

Download the example:

Workflow: Trace Out Object Properties
trace out object properties.workflow

Example how to System.debug() out properties of object in vCO JavaScript. Should run out of the box :-)

Author:	Joerg
Category:	Workflows, Actions and Packages
Date:	March 6, 2012

2.3 KiB
Details...

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!  

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! )

(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 )
• 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
de.vcoportal.snapshothunter.package

These Workflows search your inventory for certain Snapshots, and call the clickatell-API to send a text message to your mobile if they found some.
(They will NOT run out-of-the-box, see corresponding post for details!)

Languages:	Englisch
Author:	Joerg
Platforms:	vCO 4.x
Category:	Workflows, Actions and Packages
Date:	March 5, 2012

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!