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.
The step-by-step laid out in this article:
- 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
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:
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.
The one input (captured by the Initialize Data activity) is the message you would like to write to the log.
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.
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:
- Launch Excel 2013
- Go to the PowerPivot tab
- Click on the PowerPivot Window button
Select the From Other Sources button to launch the Table Import Wizard.
On the Table Import Wizard screen, select Other Feeds.
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.
On the Select Tables and Views screen, select Runbooks and Runbook Parameters.
The data retrieval process may take a few seconds, depending on how many runbooks and runbook parameters you have in your Orchestrator environment.
On the Runbooks worksheet, click the Table Properties button. On the Edit Table Properties screen, select ID, FolderID and Name.
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.
In this example, our runbook name is ‘Call from Web Service’, as shown in the image below.
Copy the runbook ID (GUID)
Retrieving the GUID of runbook parameters
Next, switch to the RunbookParameters worksheet.
Click on the drop down and select the Text Filters option.
Paste in the runbook ID from the previous step, as shown in the image below.
The result is a list of the runbook parameter ID (or IDs if your runbook has multiple parameters).
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”
In Excel, you can use the Lower() function in a formula to do the same, as shown in the figure below
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
*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.
Here is the event logged by our sample runbook, triggered by the PowerShell script!