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

SCOrch 2012 R2 Single Server, Multiple Service Accounts – HowTo

While this has been mentioned multiple times on other blogs as a problem that has occurred after an upgrade from SP1 to R2, I wanted to throw this post up to let people know that I personally experienced the same thing during a fresh install of R2. In addition, I also was able to successfully use 3 completely separate service accounts on a single machine (for demo purposes). This is how I got it working:

The Setup

So we have a point of reference, here’s a quick overview of the setup, which was for a simple proof-of-concept lab demo I was working on:

  • SCOrch Server Operating System: Windows Server 2012 R2
  • Domain Controller/Exchange OS: Windows Server 2008 R2 SP1
  • SQL Server Version: SQL 2012 Standard w/SP1
  • Service Accounts:
    (3) – SCOrchMgmtSvc, SCOrchRBSvc, SCOrchWebSvc
  • Install Account Permissions:
    Domain Admin Rights/Local Admin/Sql Admin

The Install Order

I wanted to test setup that included service accounts for each component, so although I decided to do an all-in-one (including SQL) install into one demo box, I installed the components in a particular order individually, rather than selecting all items during the first installation.. Remember, if you install all of the components at once then the Management Service account will be used as the Runbook and Web Service Accounts, which may not jive with your organizations security requirements.

  • Installation Step 1: Management Server – Use CONTOSO\SCOrchMgmtSvc
  • Installation Step 2: Console/Web Service – Use CONTOSO\SCOrchWebSvc
  • Installation Step 3: Runbook Server – Use CONTOSO\SCOrchRBSvc
  • Installation Step 4: Install Runbook Designer


After the installation, all logs indicated a successful install, and the console launched from the runbook designer….

But then I recieved a couple of error popups:



Also, when trying to connect to the Web Service I saw this nasty little gem:

Post-Install Fixes I had to implement

After scouring the interwebs I decided to try the following tasks, as multiple sites indicated these steps after one fashion or another:

Step 1 – IIS Related Fixes
Source: TechNet Blogs – Travis Write – System Center Orchestrator Engineering Blog

The link above contains a few steps that I followed (despite the fact I wasn’t doing NLB as the blog post talks about) and summarized below:

  • A) Change the Web Application Pool Accounts for each IIS SCOrch Site:
  • B) Set the SPNs
  • C) Configure Web Service App Pool Credentials
  • D) Configure Orchestration Console Kernel Mode Settings

After I reset IIS – the problem still existed, so I moved on to the next set of instructions I found.

Step 2 – Database Permissions
Source: System Center Central – Request Error on Fresh SCOrch 2012R2 Install

Even though the suggestion from the source says that a workaround is to install all of the roles at the same time, I did not want to accept this.

Once I granted all three service accounts the db_owner role (more in a second on that), I restarted IIS, and lo and behold, both the console and the web service worked without issue:



Step 3 – “Tighten Up” Database Permissions

After I got them working, I wasn’t sure this was going to work, strictly speaking, as I wasn’t sure the runbook service actually needed the permissions. So naturally, being lazy and just playing around anyway, I decided to remove the permissions from the runbook service, reset IIS, and check again…

Web Service still comes up, check. And from other articles I read I knew I should leave the Mgmt Service as is. So now my lab is up and ready to rock!

As shown in this post, this information has been out there, but not mentioned usually with a “Fresh” install. Usually the instance occurred after the upgrade from SP1 to R2. So I just wanted to gather this information in one place and let people know that it definitely effects the clean install as well, when using multiple service accounts. And to mention that you don’t have to use a single service account for the demo labs or single server installations if you do not want to!

‘Till next time!