SCORCH HTML Documentation Tool Part 1: The Example Runbook

Little bit of a hiatus

Apologies for not adding anything new in a while. I’ve been working on a tool that I feel is in a state of flux. It could be something much greater but it is going to satisfy my needs for now. With the recent additional duties and the increased demand of my time during my day job, I have decided to release the code I’ve been working so that – hopefully – at least one of the following outcomes could be achieved:

• It will spark someone who can take it and “polish” it to achieve more than my time allows
• Could be reviewed by MS and the report “friendliness” concepts could be enhanced by them for future releases of their own toolsets.
• Can be of educational value to those curious on how to marry Orchestrator runbooks and web design concepts for easier navigation through runbook documentation sets.

Hopefully the following 2 part blog (and script – released in the next post) will help some people out there wanting to get a handle on how to possibly create some more useful “documentation” on how a particular runbook works. I hope these reports can act not only as a nice troubleshooting tool, but as a “platform” to help SCORCH-Less Systems Admins and Junior System Admins ( indeed – all padawans alike!) in grasping runbook concepts quicker without handing them the lightsaber – I mean Runbook Designer…sorry – been a long week already!

Chapter 1…it all began on a warm late-summer afternoon…

A couple of months ago – during my attempt to better understand the processes used in Orchestrator Runbook Design (and to ensure I did not have to spend hours of time creating documentation for runbooks that I would eventually design) – I began researching utilities and/or scripts I could use to automate the “documentation” process for a particular runbook.

[ Rant ]

I mean – really – I just spent x days/weeks creating and designing the whole thing – who has the mental stamina to go back to the very beginning and then re-live those moments over again back to back! Or – on the flip side – who would want to spend the extra weeks designing the runbooks while pausing for periods of 2-5 minutes in between runbook design steps in order to take snapshots, add comments into a Word document, etc.

AND THEN… try to return back to your design – only to realize you can’t remember that perfect solution for problem X you had figured out – because you were so focused on documenting the stupid ‘Initialize Data’ activity!???!!

[ /Rant ]

That’s when I happened to stumble upon the S.M.A.R.T Documentation and Conversion Helper 2.0 Toolkit (Formerly the Orchestrator Documentation Script).

I absolutely loved the concept and was very excited when I first downloaded and ran it against my Orchestrator Lab environment. Besides – the fact that it was created completely in my favorite go-to administration tool – PowerShell – made it doubly cool.

Short-Lived Romance

BUT – I have to admit – while I can see how the tool had very valuable use for instances where it came to converting runbooks to SMA runbooks, etc., I was let down by the resulting documentation in the end.

“But Why?”, do you ask? Most of the information you need to understand the runbooks and how they operate are there, and the links even follow the proper workflow paths that your runbooks use. “What,” might you ask, “…is the problem good sir??!”

The problem, you see – is that I want to be able to provide a set of documentation / reports / information for my runbooks that allow not just those who have attended a two-week boot-camp on System Center Orchestrator 2012 R2 Runbook Design to understand if they need to quickly review at a high level how a particular runbook.

I want an especially-adept Operator or a versatile Systems Administrator (i.e. grasps basics regarding systems automation, workflows, basic scripting language and theory, etc.) to be able to “browse” through my runbook “documentation” and come out with the information they need to do any “standard checks”.

Most importantly…I want to provide all these things by doing the least amount of work possible…

GIMME THE DANG SCRIPT

After two months of tinkering, I believe I have come to a point where I can at least share what I’ve learned with the community. I hope someone as curious as myself can take this and solidify it to something worthy of the TechNet Script Repository, and maybe someday it will become a staple of many more SCOrch Admin’s toolkits other than my own.

A download of my final resulting script will be shown in the next post. For this post, I want to prepare you for the tool by first walking through the basic runbook I am using as an example for you to review.

Example Runbook – Creating Files and Logging the Info

Before we get to the good part – the script itself – I want to provide a basic runbook we can use to generate some docs and so I can include as an example of the results I was able to generate using the included ExampleRunbookv1.0.OIS_Export file.

This blog focuses on the design of this example runbook and as a quick reference for anyone interested in why I did some of the things I did. For instance – I KNOW these runbooks can be condensed quite a bit to streamline the workflow…but by doing it this way I tried to provide a demo that included the versatility of the script (i.e. the ability to process multiple runbooks within a folder, etc.)

The design for this runbook is intended to be simple, yet contain enough complexity that you can use your own imagination to extrapolate how you can extend these concepts into your own runbook design strategy.

So let’s get down to business and walk through the design structure for the runbook example:

Runbook: 1.00 – Create Directory

This simple runbook takes a single parameter (DirectoryPath) and will attempt to create the directory using the default runbook service credentials. It will then return any information we provide from the local data bus to the master runbook’s data bus.

If the activity creating the folder fails, an event will be logged in the servers Event Log, and then a PowerShell script runs that will force the runbook to fail (otherwise, the “Log Event” activity can return a “success” and will be interpreted incorrectly by the runbook for the rest of the workflow).

The data returned to the data bus from this runbook is as follows:

Runbook: 1.01 – Create Text File in Folder

This simple runbook takes two parameters (FileRootFolder and TextFileName) and will attempt to create a blank text file using the default runbook service credentials. It will then return any information we provide from the data bus.

If the activity creating the text file fails, an event will be logged in the servers Event Log, and then a PowerShell script runs that will force the runbook to fail (otherwise, the “Log Event” activity can return a “success” and will be interpreted incorrectly by the runbook for the rest of the workflow).

The data returned to the data bus from this runbook is as follows:

Runbook: 2.00 – Write Information to Text File

This simple runbook checks for the existence of a file. If the file exists, then we will add the line:

[ Example Runbook v1.0 Test ]: Successfully Completed Append Test!”

If the activity that appends data to the text file fails, or if the file does not exist, then an event will be logged in the servers Event Log, and then a PowerShell script runs that will force the runbook to fail (otherwise, the “Log Event” activity can return a “success” and will be interpreted incorrectly by the runbook for the rest of the workflow).

The data returned to the data bus from this runbook is as follows:

Runbook: 3.00 – Log Runbook Success

This simple runbook checks for the existence of a file. If the file exists, then we will add the line:

[ Example Runbook v1.0 Test ]: Successfully Completed Append Test!”

If the activity that appends data to the text file fails, or if the file does not exist, then an event will be logged in the servers Event Log, and then a PowerShell script runs that will force the runbook to fail (otherwise, the “Log Event” activity can return a “success” and will be interpreted incorrectly by the runbook for the rest of the workflow).

The data returned to the data bus from this runbook is as follows:

Master Runbook

The Master Runbook we will call “Example Runbook – Create File and Log v1.0“

This runbook will be a runbook that is comprised solely of “Invoke Runbook” activities ( [ INSERT IMAGE 10 ] ) that link the following sub-runbooks together to create the whole workflow:

This simple runbook checks for the existence of a file. If the file exists, then we will add the line:

[ Example Runbook v1.0 Test ]: Successfully Completed Append Test!”

If the activity that appends data to the text file fails, or if the file does not exist, then an event will be logged in the servers Event Log, and then a PowerShell script runs that will force the runbook to fail (otherwise, the “Log Event” activity can return a “success” and will be interpreted incorrectly by the runbook for the rest of the workflow).

The data returned to the data bus from this runbook is as follows:

SCOrch Tip of the Day: Making Link Activities Easier to Understand

When creating the link objects, you should include the logic you use in the description for the link activity. This way – it will be easier for people to read your resulting documentation. The script DOES provide a method for you to see all the link conditions (see second example below), but anyone unfamiliar with basic programming theory may have a difficult time translating the way we convert the values by default from within the tool (sorry – didn’t want to take the time to modify).

Example Downloads: Runbook and Resulting Reports

Download the following zip to see the exported runbook I used, as well as the resulting HTML reports. The next post will walk through the process I used to create the reports you can download below:

Click these links to download the example runbook and report files

When you unzip the reports, the root folder itself doesn’t matter, but keep all the runbook export folders in the same directory for the link structure to work properly. Also, you may get a warning about running some content in IE (because of my JQuery code) – so just click “Allow blocked content” when asked:

As mentioned above, you should download the example runbook and the reports I was able to generate with the script – and see if it’s sparked some interest! In the next day or two I will be posting the second part of this adventure, and will also post the source code and additional documentation I have created to hopefully help you document your own runbooks!!!

In case you were so caught up in the potential for these reports, I must iterate the fact that each html report is self contained – and all necessary CSS, JavaScript, and Images (in the form of base64 strings) are embedded into each html file – so the files can be easily transferred to alternate locations without having to worry about taking extra images or javascripts, etc. with you!

‘Till next time!!!