SCORCH HTML Documentation Tool Part 2: The Script

Recap of Part 1

To recap Part 1 – We basically walked through the example runbook used in this guide. Now that we have a basic understanding of what our Example Runbook does(Creates a folder, creates a file, writes data to file and also logs event log messages), we will now walk through the process of prepping this runbook to be documented with the script.

First things first. click this link to go to my git-hub repository or click this link to directly download the zip of all included materials including the script source code.

Export the Runbook – then Create the Images

What I mean by that is that if you have been a good little Sysadmin – and have done the recommended reading for System Center Orchestrator Best Practice information:

…then you know this is due to the fact that all of that information (i.e. objects with system generated GUIDs – GUIDs that don’t exist anywhere other than your export source’s Orchestrator Database) needs to be “scrubbed” from the export (which is not one of those things you just LOVE to do each time you export a runbook…) if you ever plan to import that runbook into another environment that is not the EXACT same environment you exported it from in the first place!

For our purposes though, we will check every option. Unlike an export used for transfer to different environments, this export’s sole purpose is to provide enough information as possible (i.e. least calls to the database for the script necessary) so we can generate some useful reports that we can refer others to later without them needing Runbook Designer access (initially) or expertise.

A special item to note at this point is that – the runbook I included for an example does not have any connection to any variables or globally scoped environment variables – so I have not included that information in the example runbook.

If I HAD included global variables (like connection information, globally accessible server names, etc.) then they would have had their GUIDs updated to be a little more understandable to the reader as well.

Export the Runbook

So first, select the root folder (where the master runbook resides) where you want to capture all the runbooks contained within the sub-folders of the root document:

Runbook Designer Folder Location

Then, from the Runbook Designer menu, select “Actions” > “Export“:

Export Runbook

For the File Location, save the file as whatever you want:

Save Export

Check the “Export the runbooks in subfolders” option:

Export Settings

When you have all your options configured, click the Finish button to complete the export.


Now that we have an export, we need to get our “Snipping” hat on and get our Runbook images

Create the Activity Icons

Next, we want to make sure our documentation contains no broken or confusing images, so we need to create our “activity icons“.

The documentation supplied with the source code contains the steps involved with creating additional icons. For your reference (so you don’t think I’m leaving you high and dry) – I have a “starter set” already going. Here’s a quick breakdown of Activity Icons already included with the script:


Create the Runbook “Map” Images

The last thing we need to do before we run the script is create the images that we will use to create an interactive runbook “Map” that will use some CSS and JavaScript to provide jump-points to other activity reports for a certain runbook.

These steps are also outlined in my documentation for the script – but I will be extra clear here:

Snip the image from the upper most left corner of the runbook image, but do NOT include the “black border” or the “runbook tab” when taking the snip. i.e.:

Good Snip of Runbook

Bad Snip of Runbook

Name your images exactly as the runbooks are named, but by removing spaces.

For example, the runbook image for “2.00 – Write Information to Text File” would be named like so:

Naming Runbook Images

The resulting image for each runbook we will be reporting on in the Example Runbook we are using will look like so:

Example Runbook Image Names

Once we have our images in place and our export is ready, we are finally ready to run the script!

Tip: If you’re images end up with some hot spots way off the mark, then make sure that the runbook image you snipped was actually “Checked In” in the Runbook Designer before you export the runbooks. I did that a couple times and spent a while digging through code before realizing the code wasn’t wrong, it was the fact that I had moved the activities x,y positions in the Runbook Designer after taking the snips and then had checked in the runbooks.

I should have checked in the Runbooks (ALL of them you have images for!) prior to taking the Snips, then everything would have been fine…

Finally – Running The Script!

First off, note the location of the runbook export you want to use, and open up the “Parse.OIS.Exports.config” file in your favorite text editor (I use Notepad++ most of the time). Edit the [Genera] > OISExportFile value with the path to your runbook OIS_Export file:

Configuration Settings

Ensure your database authentication (Integrated Auth) has been set, and your paths to the rest of the variables match the root directory of your script.

Once everything is in place, just right click the script and run it!

Run in PowerShell

Now, just wait…

PowerShell Executing

By using CMTrace.exe or Trace32.exe log viewing utilities, you can also open up the log file and watch the more verbose info as the script executes:

Log Viewing with CMTrace

When the script is complete you will see the “Script Execution Complete!” message and the PoSH Command Prompt asking you to press a key to continue (this will close the PowerShell console window):


Looks like we generated 91 pages of documentation (interactive docs no less) in less than 5 minutes!!! Not Bad!!!

Resulting Report Files

Now go to your Reports and start checking them out!!!!

Please, please read the documentation!

I spent a good amount of time trying to document every component I think could be that wasn’t the script itself (aside from the “Creating your own Activity Icons” procedure – which requires touching one piece of the script). I wanted to answer every question I could think of and cite any sources or links I used during my process.

These references, explanations, and links should all be in the user documentation available in my git-hub repository.

If you still can’t find the answers to your questions after reading the supplied documentation, then by all means drop a comment on the site (under this blog) and I will try my best to give a useful answer!! 😉

I hope this was useful in one fashion or another!!! ‘Till next time!!!