Automation-Exporting SMA Runbooks to TFS on a Schedule in Windows Azure Pack with SMART

Hello readers / viewers.  I have a topic that I think will be valuable for folks looking to ensure they are backing up their SMA Runbook investments to the fullest extent within WAP (Windows Azure Pack) and storing those in TFS (Team Foundation Server) for any changes (for rollback / DR / etc.).  If you look at the below diagram, it gives you a basic idea of what this scenario is end to end.


  1. Leveraging SMART - SMA Runbook Toolkit for Import and Export to manage your Runbooks in SMA – download the latest [bug fixed on 2/6/2014]
  2. Parent Runbook in SMA will be scheduled on a daily basis for this all up solution documented here – I’ve provided a Runbook as a good starting point
  3. Runbook exports your Runbooks to a TFS directory that is mapped to be synched with TFS – example process provided leveraging SMART Open-mouthed smile
  4. A nested Runbook that is triggered at the end to synchronize your TFS source to ensure any updates have been committed to TFS – also provided so don’t worry!

Download the supporting Runbooks for this solution here 


And ensure you have SMART for Runbook Import and Export (required for the end to end solution)BC-DLButtonDark

STEP 1 – Install Visual Studio (or Team Explorer 2012 – Free and Lightweight!)

Install Visual Studio (or Team Explorer 2012) on the SMA Runbook Worker

The easiest way to populate the GAC (Global Assembly Cache) for the TFS DLLs we are using is to install Team Explorer for Microsoft Visual Studio 2012 on the Runbook Workers.  This gives you the ability to connect to TFS and execute the actions within the Runbook Invoke-TFSSourceUpdate.  You could of course do a remote PSSession but you’ll also need to bounce back to the SMA server to capture the Runbooks. 

Download: Team Explorer for Microsoft Visual Studio 2012

Note    This post assumes you are executing this from the SMA Runbook Worker. Of course it may make more sense in your environment to use a UNC path to copy the files to and leverage a PS Session to execute the PowerShell remotely on that remote server so that all the TFS GAC requirements are localized to another machine. That’s out of scope for this blog post. You can also copy the GAC directly for TFS and avoid installing the Team Explorer (or Visual Studio) as another option.

My good friend Yao ( Zhenhua Yao) has a great blog post that discusses a few other options and he talks about getting those GAC files in the right place if you want to avoid installing anything on your Runbook workers. TFS Integration Pack and Scripting using PowerShell. Yao – thanks for your support on some random questions on this TFS PowerShell topic. As always you are an awesome engineer to bounce things off of and your assistance was huge for this thank you!

STEP 2 – Connect to TFS with SMA Service Account and Map a Local Path

Map a local folder on your SMA Runbook Worker that will hold your specific folder you want to source your SMA Runbooks in.  Make sure this is setup with the Service Account for SMA or whatever ID you are actually using to update TFS (for this example, the service account is assumed).  Ensure this account has rights in TFS, rights in SMA, and has a local TFS mapping on the SMA box to be leveraged by this account for syncing content with TFS (see next section).  This is an easy step to miss and you will be kicking yourself later if you don’t actually do a “Run As” on Team Explorer as the service account for SMA and map your local path you’ll be using to update TFS.

Note    You do not need to synchronize your entire TFS source down to your SMA box. You only need to map the specific folder for your Runbooks you are sourcing and updating in TFS. See below for more details.

Brief steps to mapping TFS local paths

Initially, you’ll see that nothing is mapped locally.  This means you can browse existing content on the TFS server but can’t checkout / update / put files up on the TFS location.


Click on the Not mapped hyperlink to select a local folder to map to.  I generally grab a root folder of a drive with plenty of space and name it the same as the main source root (ex: WSSC_CAT would be c:\WSSC_CAT)


Then just click Map and away you go!  You could map lower down such as “SMARunbooks” in the above example and then you only need to worry about one folder – I chose to do it at the top in case I want to actually place some Runbooks in other locations.  Think in terms of projects and using tags to tag your Runbooks by project and then sourcing those Runbooks in TFS by project.  Do what makes sense for your company – the flexibility is there Smile.

This next screen shows that if you click Yes it is going to download all source – answer appropriately.  Yes downloads everything – no makes you do a right click, Get Latest Version when you get into Source Explorer.  You can also be specific and only get source on a specific folder so answering No here may be best if you want to be granular on what you are pulling down to your SMA server.


Finally, you should see your directory mapped properly indicating things are setup and ready for the Imported parent Runbook in this solution to use SMART to export files to this location.


STEP 3 – Go Download SMART for Runbook Import and Export and Install it!

Click the Download Button to Get SMART for Runbook Import and Export.  You’ll want to leverage this to get the most out of your exports from SMA.  This solution will grab the pieces of a Runbook that are outside of just the standard PowerShell contained within. 


To read more about this solution: Automation–Service Management Automation–SMA Runbook Toolkit Spotlight–SMART for Runbook Import and Export

STEP 4 – Go Download the Runbooks for Automating your Export and TFS Sync

Download the supporting Runbooks for this solution here 



This download contains the following Runbooks:

  1. Invoke-ScheduleSMARunbookExport: This Runbook is the parent Runbook for this solution and will kick off the export of your Runbooks as well as synchronize your TFS source.
  2. Update-TFSSource: This Runbook contains the necessary commands to synchronize TFS leveraging the Team Explorer DLLs for TFS.

STEP 5 – Install the Runbooks in this Post and Customize

Review the Runbook Details section below to understand how these Runbooks are designed and ensure they are updated according to what you have in your environment.

  1. Locate your download and extract the source to your SMA server (if done remotely, just ensure you update the $WebServiceEndpoint variable to the proper URL)

  2. Right click on the Install-SMARunbooks.PS1 and select Run with PowerShell to install into SMA.  This process could take anywhere from 30 seconds to 1.5 mins.  The reason for the variance in install time depends upon whether your web service is “awake” and ready to take requests.  Hit WAP to ensure SMA has been access and run the script to speed up the install.  Otherwise, just right click and Run with PowerShell and the script will take care of waking up IIS for you Smile.


STEP 6 – Define a Schedule for Invoke-ScheduleSMARunbookExport

If you are interested in having your Runbooks export on a schedule (so you don’t have to worry about keeping up with it) I highly recommend setting a schedule daily.  The execution of this solution is very lightweight and has no real impact on your environment.  Setting the schedule ensures you get a backup daily, and you can still execute this Runbook on demand at your whim if you are doing some updates and want to ensure you have a fresh backup.  Run it a bunch of times if you want Smile.  The value here is that the source on TFS only gets updated if there has truly been a change in your PowerShell (or characteristics of your Runbook).

Setting a Schedule

To set a schedule

  1. Go to the SCHEDULE tab of the Invoke-ScheduledSMARunbookExport Runbook.
  2. Select the SCHEDULE icon at the bottom and select Add New or Use Existing to add a schedule

Runbook Details


Variables Defined

First we have to establish the “environmentals”.  This would be TFS server, collection, and source path you are going to source your files to.   If you used the install wrapper explained in Step 5 above, it created the variables for you. Update these variables in SMA to ensure they reflect your target environment.


Note    If you didn’t use the install wrapper to import these Runbooks (or if you opted to not import assets) ensure you either create these variables or update them with proper static values.  

Runbook Export


Check in Pending Changes to TFS

Finally, we need to ensure that our updates are refreshed on the TFS server.  The nice thing about this process is that if the Runbook literally looks the same as what is already on the TFS server, no update actually gets pushed.  You will only update Runbooks that have had modifications.



You can now track changes in TFS for your Runbooks (right down to who changed what) and roll back changes if you need to!



Small Footnote Here    If someone happens to delete a Runbook in SMA, it will stay in TFS unless you remove it via Visual Studio or Team Explorer.  Probably a good thing. Open-mouthed smile



We start with the parameters that are leveraged within the Runbook to connect and check in changes for TFS.


Connect to TFS and Establish Directory to Sync

Next we load the necessary assemblies and get connected to your TFS instance and location you are interested in updating


Check in Your Runbook Source Files into TFS

Then finally we check in our Runbooks into TFS for safe keeping Smile.



This section describes a couple of potential issues you may run into after implementation or while getting things setup.  These are issues I ran into as I put this into production in our environment. 


Exception calling “CheckIn” with “2” argument(s)…

This can occur if one of the Runbooks has been deleted on the TFS server but your local source directory still has the Runbook, an update is made, and the Runbook is attempting to be checked in.



Launch TFS on the SMA server as the SMA service account and resolve the conflict by selecting “Get Latest Version” on the folder in question and answering the prompts to resolve the issue.



Exception calling “GetWorkspace” with “1” argument(s)…..

This can happen if you fail to map a local path for TFS for the account you are using in the SMA Runbook to synchronize with TFS.


Note     You can only have one account mapping to local source on a machine. Ensure you are not mapping with your “interactive logged on account you use for administration and use the account that is synchronizing with TFS on your SMA box.


See STEP 2 above Winking smile.

Well that’s it for this post.  I hope you get some value out of this solution for your dev/QA/Production environments where you are leveraging SMA.

Until next time – Happy Automating! Hot smile

And for more information, tips/tricks, and example solutions for SMA, be sure to watch for future blog posts in the Automation Track on!