Understanding SCOrch Runbooks and PowerShell

If you’re not familiar with “SCOrch”, it stands for System Center Orchestrator. Orchestrator serves the role as the “automater” in Microsoft’s System Center suite, and it’s used to create “Runbooks” which are basically workflows that are used to complete a series of tasks.

While there are many options to build a Runbook through the GUI, sometimes you might want to be able to do more with your Runbooks. This is where integrating your own PowerShell scripts can come in handy. In this article, I’ll be showing you how to integrate some of your own PowerShell scripts into an Orchestrator 2012 SP1 Runbook.

The example I’ll be showing below (with a multitude of pictures to help out) will be a simple little Boolean checker that will switch various Boolean arguments to either “true” or “false”. It will then return the result to the Runbook so that we can use it to create some branches with other Runbooks.

Here is a copy of the PowerShell script we’ll use:

PowerShell Script

You can copy/paste from here:

$bool= ""

function setTrue {return "true"}
function setFalse {return "false"}

$bool = $bool.ToString()
$bool = $bool.toLower()

switch ($bool)
"true" {$bool = setTrue}
"t" {$bool = setTrue}
"yes" {$bool = setTrue}
"y" {$bool = setTrue}
"1" {$bool = setTrue}

default {$bool = setFalse}

Let’s quickly go over what this script is doing:

First of all, PowerShell scripts can have parameters to receive arguments from the Orchestrator Runbook (as seen on lines 1-3). Each parameter needs to be separated by a comma. On lines 5-6, I have created a couple of simple functions to return a string value for setting the Boolean true or false. Lines 8-9 massage the $bool variable to ensure that it is a string and that it’s lowercase. Finally, the switch statement starting on line 11 will change the $bool variable to true or false depending on a few different cases.

Here is how everything will flow together:

  1. A string value will be passed to 1.1.1 Boolean Checker
  2. We will pass that value to our PowerShell script. The script will switch it to either “true” or “false”
  3. Then “Return Data” will return this value so that we can reference it from other Runbooks.

The first thing we need to do is create the Runbook and add some basic parts:

  1. “Initialize Data” – This acts as the starting point for the Runbook and is mandatory
  2. “Run .Net Script” – This is where our PowerShell script will go. Be sure to set the Language Type to “PowerShell”
  3. “Return Data” – This will return a value from my PowerShell example below to the Runbook.

After I’ve added these items, I changed the name of the “Run .Net Script” step to “Check Bool Value”. I also linked the steps together in the order that they’ll execute.

Now, the Runbook is looking like this:

Check Bool Value

Our PowerShell script above will take one argument for the Boolean to check. So let’s add a parameter called “booleanValue” to the “Intialize Data” step:

Initialize Data Properties

Next, we’ll add the PowerShell script to the “Check Bool Value” step:

Check Bool Value Properties

Next, we need to associate the parameter from “Intialize Data” to the “$bool” variable in our PowerShell Script. Here is how to do that:

Place the cursor between the quotation marks and right click to open the menu -> Subscribe -> Published Data:

Published Data

Select the “booleanValue” variable from the “Initialize Data” step:

Initialize Data

Here is what it should look like:

Boolean Value Initialize Data

Once everything looks as it should, go to the “Published Data” option and enter the variable then hit Finish:

Check Bool Value Published Data

Next, we need to set a “Returned Data” variable. To do this, right click the tab of the Runbook and go to properties:

Returned Data

Under the “Returned Data” option, I’ve created a variable called “returnedBoolean”.

Define Returned Data

Now that we’ve added a return variable to our Runbook, you’ll notice that the properties of the “Return Data” step will show this variable:

Returned Data Details

Now let’s set the published “bool” variable from the “Check Bool Value” step:

Return Data Properties

Set Bool Value from Check Bool Value

Set Bool Value from Check Bool Value 2

After you hit finish, it will be armed and ready to go. Don’t forget to check in your Runbook!

Now, I’ll test using this Runbook inside of another Runbook. As an added bonus, I’ll create a simple if/else branch in the workflow! Here is a simple Runbook I’ve put together called “1.1.2 Raise Flag”:

Raise Flag

To create the if/else branch, I’ve changed the properties of the Link between the 1.1.1 step and the “Raise Flag” and “Don’t Raise Flag” steps as shown below:

Filter Properties

Include Filters

Now let’s put this to the test in the Runbook Tester. First I’ll try setting the “raiseFlagBool” variable to true:


As expected it only ran the “Raise Flag” step.

Initialize Data Parameters

Now let’s test the “Don’t Raise Flag” path by setting the Boolean value to false:

Set Boolean Value to False

As expected, it only ran the “Don’t Raise Flag Step”:

Dont Raise Flag Variable

So, to recap:

I demonstrated how to integrate your own PowerShell script into an Orchestrator 2012 SP1 Runbook.

I also showed how to pass variables from your Runbook to your PowerShell script, and also how to publish variables from the PowerShell script back to the Runbook. To top it all off, I also showed how to setup an if/else branch in a Runbook using the example that we used today.