Using vFLOWer and GitHub to bring (better) version control to vCO

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

vCO Login

vCO Login

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.

Create package

Create package

Give it a name

Give it a name

Now we need to add items to the package, so right click “Edit”

Edit the package

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

Add the good stuff

Screen Shot 2014-03-02 at 9.37.47 AM

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

REST Operation action

REST Plugin

REST Plugin

Awesome, so we have the items we’re concerned about in a single package.   Right click and export package.

Export Package

Export Package

Options for export.  Note the "export the values of configuration settings" that I will call out later.

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 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.

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

Computer – Properties

Select ‘Advanced System Properties’.

Advanced System Settings

Advanced System Settings

Select ‘Environment Variables’.

Environment Variables

Environment Variables

Click ‘New’.   Add ‘ANT_HOME’ with our path to ‘C:srcapache-ant-1.9.3′.

ANT_HOME

ANT_HOME

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

Path for ANT

Test this by opening a new command prompt and type ‘ant -version’

ant -version
Test ANT

Test ANT

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.

You want the JDK on the left.

Choose your flavor.

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

JAVA_HOME

JAVA_HOME

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

echo %JAVA_HOME
Testing JAVA_HOME

Testing JAVA_HOME

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’ .

Update Path

Update Path

Test with the command ‘openssl version’ in a new command prompt.

openssl version
Testing OpenSSL

Testing OpenSSL

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?

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

Adjusting PATH automatically

On the line ending option page choose: Checkout as-is, commit unix-style line endings.

Line Ending Conversions

Line Ending Conversions

And test git real quick with ‘git –version’

git --version
Testing GIT

Testing GIT

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.

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.

Screen Shot 2014-03-02 at 2.54.24 PM

We’ll want to name it something meaningful.  For me, that always includes “stuff”:

my-vco-stuff

my-vco-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.

Click Edit

Click Edit

Enter your content

Comments Rock.

Comments Rock.

Add a comment before saving (we’ll talk more about comments later):

Screen Shot 2014-03-02 at 12.51.38 PM

And refresh the main page to see it:

Screen Shot 2014-03-02 at 12.51.51 PMNow 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

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
git clone

git clone

Check it out in windows explorer and it’ll look identical to the web interface.

We have files!

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

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.

ant precommit
Text...text...DONE!

Text…text…DONE!

Check the inout directory and you should see the package is removed:

InOut Dir now

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

Workflow Content

Workflow Content

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.

XML Content

XML Content

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
'git status' output

‘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.
git add .
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

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

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

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.
Successful, kinda

Successful, kinda

Add your name and email with:

git config --global user.email "myemail@mydomain.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:

git push origin master
Git push

Git push

Now if we refresh our github webpage, you should see the updates

Ch-cha-cha-cha-changes

Ch-cha-cha-cha-changes

Browse through the content and verify your workflows are there:

New stuff!

New stuff!

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
git clone

git clone

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.

Fresh bits

Fresh bits

Now we need to use ANT to convert it back into a format we can import into vCO.

ant build
Yay!

Yay!

And check into the inout directory, and behold our package!

vCO Package

vCO Package

Load up the vCO client now.  Switch to the Administrator view.  The packages tab.  click the import button

Load it up!

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:

Warning(s)

Warning(s)

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!

Ready to go!

Tagged , , , , , ,

One thought on “Using vFLOWer and GitHub to bring (better) version control to vCO

  1. […] I posted a walkthrough of using a 3rd party framework called vFLOWer to convert packages exported from vCO to text format […]

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>