Update March 15, 2014: This type of functionality is now included in the product in vCO 5.5.1 See more here
vCO has very basic versioning built into the workflows. It works for simple mistakes from version to version, but isn’t great for cross environment and multiple developer use cases. Enter the vFLOWer Toolkit made by ByteLife. They are a VMware Partner that built, what I think is, a BCDR solution using a lot of Orchestrator workflows. When building their solution they found they really needed tighter control over versioning their work for their developers, so they built a solution and made it available. Now I know it’s a little bit of a hack, but it works great. Let’s look at how to use it here. This post will be screenshot heavy, but is worth it to illustrate what is going on and how you do it.
I wanted to post all my workflows for the Dinner as a Service project, so let’s walk through that here as an excercise. First you need to export your items from vCO. For this project, I used the instance of vCO embedded with the vCAC appliance. The URL for the client is https://fqdn_of_vcac_appliance:8281/vco/client/client.jnlp
Once we’ve logged in, switch to the administrator view. Click on the Package tab. If you aren’t already keeping your workflows in a package, go ahead and create one. Right click, Add Package.
Give it a name
Now we need to add items to the package, so right click “Edit”
Edit the package
Switch to the Workflows tab, click Insert Workflows and add the workflows you want to put into this package.
Add the good stuff
You’ll notice it captures all associated items with these workflows you specify. In my case for this project, it added an Action and Plugin for REST.
REST Operation action
Awesome, so we have the items we’re concerned about in a single package. Right click and export package.
Options for export. Note the “export the values of configuration settings” that I will call out later.
Now we have the package exported to the file system.
Now that we have our package exported, we need to convert it from the native binary format (I think?) to something that GitHub can use to do plain text revision control on. Follow the User Guide on the vFLOWer website here or continue reading for a more detailed step by step process.
We need to satisfy the requirements for vFLOWer which are – Apache ANT, Java, OpenSSL and Git.
Starting with ANT, download the package here. There is no installer for this one so we’re just going to extract it to our source dir at C:srcapache-ant-1.9.3 (use whatever path you want, but I’m going to use this src directory throughout).
ANT directory with the vCO package.
We need to edit our environment variables to include ANT. If you are unfamiliar with this process these steps will help as it’s not exactly an everyday activity. Right click on Computer, select Properties. (or Control Panel, ‘System and Security’, ‘System’).
Computer – Properties
Select ‘Advanced System Properties’.
Advanced System Settings
Select ‘Environment Variables’.
Click ‘New’. Add ‘ANT_HOME’ with our path to ‘C:srcapache-ant-1.9.3’.
This makes ANT_HOME available to the system but it’s not in the system path yet. Scroll down to Path, click ‘Edit’, and add ‘;%ANT_HOME%bin’ to the end.
Path for ANT
Test this by opening a new command prompt and type ‘ant -version’
That’s one down. Now we need a Java JDK. The newest at the time of this writing is jdk-7u51-windows-x64.exe and can be found here.
You want the JDK on the left.
Choose your flavor.
There is a windows installer for this one so it’s straight forward. When complete, similar to what we did for the ANT environment variables, add JAVA_HOME, set it to C:Program FilesJavajdk1.7.0_51
Test with a new command prompt ‘echo %JAVA_HOME%’ This does not need to be added to the system path. (EDIT: when I did this on Win7 it added automatically, on 2008 it didn’t. That’s annoying.)
One more down, a few to go. You may need to install the 2008 C++ Redistributable’s. I have never known what’s in here but they say you should use it. Kind of like vitamins. Find it here.
For OpenSSL, grab the pre-compiled windows version here and install. You may get a warning about the 2008 C++ package, this probably goes away if we would have rebooted – yay windows. Choose the defaults. Add to the system Path variable ‘;C:OpenSSL-Win32bin’ .
Test with the command ‘openssl version’ in a new command prompt.
Now we’re in the home stretch. We just need the windows git package from here.
Download GIT because you can’t get GIT without getting GIT first. GIT it?
Choose most of the defaults except two. On the PATH screen, simplify things and have the installer modify the variable for you by choosing ‘Run GIT from the Windows Command Prompt’
Adjusting PATH automatically
On the line ending option page choose: Checkout as-is, commit unix-style line endings.
Line Ending Conversions
And test git real quick with ‘git –version’
Alrighty. Now for the meat of it. Everything up until now was just prep. From here on out the vFLOWer doc is pretty descriptive.
You need to log into GitHub (create an account if you need to), and create a few ‘Fork’ of the vFLOWer repo. If you are new to git, what this does is creates a new copy of this repo that is now owned by you but still chained to the parent. If this was a real dev effort, we could push changes up to the parent if/when needed. This is how developers work on multiple ‘branches’ of a code base without stomping on each other in one single repo location. So login, browse to vFLOWer here, click fork.
Fork the original vFLOWer repo.
Now you have your own fork of vFLOWer. This will be where you store all your vCO stuff. Let’s make it your own by renaming and edit the README.md Click ‘Settings’ to rename.
We’ll want to name it something meaningful. For me, that always includes “stuff”:
When done, click ‘README.md’, click ‘edit’, add your own content. The read me file is similar to a index.html – we now see our new content at the root of the repo.
Enter your content
Add a comment before saving (we’ll talk more about comments later):
And refresh the main page to see it:
Now comes the real magic of Git. On the right hand of the main screen, copy the URL to the clipboard. Mine is https://github.com/jasper9/my-vco-stuff.git
Grab the URL
Back on the original windows machine we were on, change dir to our C:src directory and pull your Git repo. This downloads the full thing to a subdir of the same name.
git clone https://github.com/jasper9/my-vco-stuff.git
Check it out in windows explorer and it’ll look identical to the web interface.
We have files!
Back to the vCO package we originally exported. Copy this package into the /inout sub directory (C:srcmy-vco-stuffinout):
Package file in inout
This is where ANT comes in. From the root of the repo (not the inout dir) run ‘ant pre commit’ You should see a lot of text scroll and end with a success message.
Check the inout directory and you should see the package is removed:
InOut Dir now
Check the content directory and you should see items from vCO that is familiar to you. In my case I am looking at the Workflows dir. My workflows were in a folder in vCO and that structure is maintained here at C:srcmy-vco-stuffcontentWorkflowsx My Library
Open up one of the workflows and you will see what it looks like in clear text. One item of note is you might see values that were entered into parameters in vCO. In my case I have ones for the Pushover service that is sensitive (API keys). I want to remove these with placeholder values. If you wish, you can uncheck a box in the vCO export process to not include any parameter data – if you have a lot this could be handy, but could also limit you in other ways by requiring some manual work to re-setup.
Now back in the root directory of this repo, type ‘git status’ to see the current status of this repo we’re in. You’ll see a message complaining that there are new directories we weren’t expecting.
‘git status’ output
Add these automatically with the ‘git add .’ command. Alternatively you could add items one by one if you ever need to in the future.
Now run status again and you’ll see it’s a bit happier, reporting cleanly that we have some new files in this snapshot of your code base.
Happier git status
Remember when you edited the README.md file and we added a message describing what we did? That’s a comment. Like you learned in “BASIC programming 101″ comments are a wonderful thing. Maybe that was just me. (Oh yeah, I can’t talk about git commit comments without dropping this XKCD on you)
MY HANDS ARE TYPING WORDS
So that change to the README.md we could have done here if we wanted to by manually editing the file. To comment the changes we just made adding the vCO content type:
git commit –m "Adding my Dinner as a Service Workflows"
git comment attempt
Two problems arise here (only the first is currently shown there)
Problem 1 I sometimes encounter – cut/paste from PDF’s or other sources don’t always work. I blogged a little about it here
. In this case, it’s the PDF’s fault and the OSX setting didn’t fix it. Replace the hyphen looking character with a real hyphen and run it again.
Problem 2 Now your commit was probably successful but it complains you haven’t set your account up right. Let’s do that next.
Add your name and email with:
<!--?xml version="1.0" encoding="UTF-8" standalone="no"?-->git config --global user.email "email@example.com"
git config --global user.name "jasper9"
Then reset the author in the comment with:
git commit --amend --reset-author
My intention in this post isn’t to give a full primer on git (here’s one that looks good), so for the last part I’ll leave it simply at a high level explanation. We need to push our changes that we just committed to the server. We do so with the command:
Now if we refresh our github webpage, you should see the updates
Browse through the content and verify your workflows are there:
Awesome – now that’s how you export your packages, use this tool to convert them, and use Git to post them to GitHub. Now to show how you would pull it down again, I’ll flip over to a fresh environment (but with all the prereq’s met). This would be like if you were someone else and stumbled upon these workflows – how do I use someone else’s work. Because this is a public repo, this is unauthenticated.
git clone https://github.com/jasper9/my-vco-stuff.git
If you look into what was downloaded, it is as you would expect. There is a content directory with our vCO stuff in XML format and no inout directory.
Now we need to use ANT to convert it back into a format we can import into vCO.
And check into the inout directory, and behold our package!
Load up the vCO client now. Switch to the Administrator view. The packages tab. click the import button
Load it up!
You will see an SSL error you can ignore because the vFLOWer tool created a self signed cert for the process. You may see a conflict message like this one shown if anything exists already or is at a newer version:
And there you go. Now you can run your workflow in a different environment. Or in this case, make dinner in someone else’s datacenter?
Ready to go!