How to Initiate a Runbook from PowerShell and Orchestrator Web Service THE EASY WAY

There is an article on the MSDN site demonstrates how to initiate a runbook using both C# and PowerShell (Start a Runbook from C# or PowerShell ), but it does not provide an easy and reliable method for finding the GUIDs for runbook and runbook parameters. It demonstrates a process using a URL in IE, which I find neither easy nor intuitive. In this article, I am going to show you how to  make preparing your script to initiate a runbook from outside Orchestrator quick, simple and repeatable.

How? Using Excel with PowerPivot.

Steps

The step-by-step laid out in this article:

  • Prerequisites
  • Connecting Excel to the Orchestrator Web Service
  • Retrieving the ID (GUID) of Your Runbook
  • Retrieving the IDs (GUIDs) of Your Runbook Parameters
  • Updating the Sample Script
    • Fixing the Case Issue
    • Updating Script Values
  • Running the Script

Prerequisites (aka “What you will need”)

Let me tell you a secret. The easiest way to retrieve the runbook and runbook parameter GUIDs you will need to launch runbooks from PowerShell or .Net is by using Excel and PowerPivot to retrieve the info from the Orchestrator web service. You will need to enable PowerPivot in Excel 2013, which is present, but not enabled by default.

How to Enable PowerPivot in Excel 2013

PowerPivot is present, but not enabled by default. How to enable is explained at the URL below

http://office.microsoft.com/en-us/excel-help/start-powerpivot-in-excel-2013-add-in-HA102837097.aspx?CTT=5&origin=HA101959985

Sample PowerShell and C# for launching a runbook

You are also going to need the sample PowerShell script for launching runbooks via the Orchestrator web service. If you have ever wanted to initiate a runbook in Orchestrator programmatically, you may have found this page on the MSDN website:

 Start a Runbook from C# or PowerShell

Sample Runbook

You will of course need a runbook to launch. Here is the most simple example you could create to test the process, which logs the message of your choice to the Windows Application Event Log. You can build this yourself in about five minutes.

image

The one input (captured by the Initialize Data activity) is the message you would like to write to the log.

image

The Send Event Log Message activity will consume the message captured by the Initialize Data activity and log Event ID 1 (source: OrchestratorTask) to the Application Event Log.

image

Connecting Excel to the Orchestrator Web Service

In order to launch a runbook using PowerShell and the Orchestrator web service, you need the GUID of the runbook as well as each of the runbook parameters. This information is easy to retrieve with Excel and PowerPivot.

To connect to the Orchestrator Web Service with Excel:

  1. Launch Excel 2013
  2. Go to the PowerPivot tab
  3. Click on the PowerPivot Window button

image

Select the From Other Sources button to launch the Table Import Wizard.

image

On the Table Import Wizard screen, select Other Feeds.

image

Next, provide a friendly name for the connection and the URL to your Orchestrator web service. If you accepted the default ports during install, the URL should be in the format http://servername:81/Orchestrator2012/orchestrator.svc

Click Test Connection and if successful, continue on.

image

On the Select Tables and Views screen, select Runbooks and Runbook Parameters.

image

The data retrieval process may take a few seconds, depending on how many runbooks and runbook parameters you have in your Orchestrator environment.

image

On the Runbooks worksheet, click the Table Properties button. On the Edit Table Properties screen, select ID, FolderID and Name.

image

 

Retrieving the GUID of Your Runbook

To get the GUID of your runbook, select the Runbooks worksheet in your Excel workbook.

On the Name column, filter on the runbook name.

image

In this example, our runbook name is ‘Call from Web Service’, as shown in the image below.

image

Copy the runbook ID (GUID)

image

Retrieving the GUID of runbook parameters

Next, switch to the RunbookParameters worksheet.

Click on the drop down and select the Text Filters option.

image

Paste in the runbook ID from the previous step, as shown in the image below.

image

The result is a list of the runbook parameter ID (or IDs if your runbook has multiple parameters).

image

 

Updating the PowerShell Script

Microsoft provides a sample PowerShell script for initiating runbooks from outside Orchestrator at http://msdn.microsoft.com/en-us/library/hh921685.aspx

HOWEVER, before you update the script, heed the following warning:

The letters in the IDs of your runbook parameters MUST BE IN LOWERCASE or Orchestrator web service returns a 500 error!

Fixing the ID Case Issue

There are two easy methods to convert your runbook and runbook parameters IDs to lower case.

In the PowerShell ISE

$string = “AACA2CAF-26BA-4BF1-8BC7-B4591DE215DA”
$string.ToLower()

In Excel

In Excel, you can use the Lower() function in a formula to do the same, as shown in the figure below

image

Updating the Script

Here are the lines and values you need to update in the sample script. The values of importance are:

  • Runbook ID – The GUID of the runbook we’re going to initiate
  • Runbook Parameter ID* – The GUID for each parameter in the runbook
  • Runbook Parameter Value*  – The value you want to pass in (the message to be logged in our example runbook)
  • Orchestrator Web Service – The URL of the Orchestrator web service with the /Jobs URI

image

*If you have multiple parameters, simply separate the parameter ID and value pairs with semi-colons ;

Running the Script

Run your script from a PowerShell prompt. If the job is started successfully, the script will return a success message with the job ID.

image

Here is the event logged by our sample runbook, triggered by the PowerShell script!

image

One thought on “How to Initiate a Runbook from PowerShell and Orchestrator Web Service THE EASY WAY

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.