Runbook Authoring Best Practices

I always find a bit presumptuous to say these are best practices, so I will start saying that those are the best practices I could come up with after banging my head many times by not doing them.

Orchestrator, as you may have noticed, is a development tool. I heard people saying that it is scripting for dummies. I beg to differ, since to do a good job, you will need some gray matter in action.

That being said, you could say that some tasks may be automated more quickly without the need to know the script commands, logic structures and so on. It is true. Dragging and dropping the little “Lego” activities can ramp you up with some working pieces. It is like learning three chords on the guitar and being able to play all the rockabilly songs from the fifties and early sixties at once.

But once you start to need some more complex harmonies, your A-D-E chords won’t do. You will need to start going deep into how the logic works in the background, how to handle errors, loops, threads, etc.

So, here are a few tips that could make your life hopefully easier.

Plan your runbook

Before you start moving boxes into the blank white screen, try to sketch what you need to do. If you have been a programmer, you know what a fluxogram is and how they can organize your thoughts. It will sure help you with a good start.

Start small and carefully

Insert one activity at a time. There are many pitfalls when adding many activities at once, the main one being that once you see them there, you tend to believe they are already configured and working fine, when sometimes they are just sitting there. The same thing applies when you are importing existing runbooks. Everything may look as if is ready to run, but if you open the activity, it may be not only pointing to the wrong Connection but also pointing to non-existent activities (MS should give you an option to check your runbook for missing references…)

Test well and don’t write!

One of the ways to know for sure whether something is working is…by trying. But what if you’re attempt can re-write all your active directory user properties or disable of them. Well, I would be very careful. So, general rule, try to test well before enabling activities that actually write stuff back. Once the outputs before that activity are ok, then enable the “writing” activities and go on.

Use colors

Orchestrator allows you to set colors for the links. Just so you don’t have to change all of them, keep the original black for success and leave the Red for failure situations. You can also use another color for decisions, which may lead to one path or another.

Document the activities

Orchestrator will allow you to put names for activities and links, as well as comments for the activities. Do. You will thank yourself later, since after 2 or 3 months away from the runbooks, you will feel like Champollion when he first saw the hieroglyphs in the pyramids.

Separate the types of Runbooks

I like to separate my runbooks in categories, as follows:

– SCSM (or Service Manager) : then ones that I will sync with Service Manager, to be uses from Runbook Automation activities.

– Monitors – Always running runbook. These will monitor alerts, files, folders, etc. Anything that starts with a monitoring activity

– Tasks – Runbooks that you will run manually or by command line or via task scheduler

– Library – Runbooks that are support runbooks, that are used from one of the above.

– Test – Scratch pad. Quick things, just to accomplish something, like extracting an userinput field form a service request,etc.


Re-use Code

As stated above, I have a Library folder in my environments. The approach is the same as in code development. I try to reuse my runbooks, as if they were functions (and they are), just so I don’t have to re-write them completely all the time. If something can’t be adapted to be reused, then may a new library RB will be born.

Things like multiple user notification, extracting Workitem attachments, querying the XML from the userinput will be surely in my RB library.

Make backups

Whenever I go onsite to a customer, I will run a full back of the RB tree I will be working on and give it a date. If needed, I can do a full restore. If you’re likely to work on a single one for sure, or two, you can then export those specifically.

Beware IDs when working with SCSM

A final note: when working with SCSM and Orchestrator, you have two options in regards of the Runbook references: by ID or by Path. The first will allow you to move the runbooks freely inside the designer, but will make your life miserable when moving from one environment to another, since the runbooks will get new IDs and you won’t be able to easily refer back to them. There is no real supported way to do this, but there are scripts that will do that for you. The later will allow a full move from one environment to another (DEV to Production, for example), but you won’t be able to move them inside the runbook designer.

By practicing, your orchestrator skill, as well as the guitar ones, will allow you to play very complex songs and you can then be the Rock Start of your IT environment!

Rock on!