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.
Now we need to add items to the package, so right click “Edit”
Switch to the Workflows tab, click Insert Workflows and add the workflows you want to put into this package.
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.
Awesome, so we have the items we’re concerned about in a single package. Right click and export package.
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).
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’).
Select ‘Advanced System Properties’.
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.
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.
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.
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’
On the line ending option page choose: Checkout as-is, commit unix-style line endings.
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.
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
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.
Back to the vCO package we originally exported. Copy this package into the /inout sub directory (C:srcmy-vco-stuffinout):
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:
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 add .
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)
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"
Two problems arise here (only the first is currently shown there)
Add your name and email with:
git config --global user.email "firstname.lastname@example.org" git config --global user.name "jasper9"
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:
git push origin master
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
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?