Triggering Orchestrator Runbook from Service Manager


The default syncing mechanism for integrating Service Manager and Orchestrator is based on discovery through connectors and initiation by Runbook Guid. This is great for demos and simple implementations of Service Manager and Orchestrator, you just connect the two, click on a Runbook and say create Runbook Automation Activity template and you are off to the races.

The problems begin to arise if your environment is a bit more complicated. In our environment we have 8 Orchestrator development environments, 1 Orchestrator quality assurance environment and 2 mirrored production environments (web services behind a F5 VIP that points to the currently active environment). In this sort of staged out environment things become less clear, how do you update your Runbook activity templates when the environment moves from a development environment to the QA environment while minimizing the configuration changes? How can you initiate a Runbook in a mirrored production environment where the Guids between the two environments are different but everything else is the same?

Solution: A new Activity Type to replace Runbook Activity Templates

The cool part about most Microsoft products lately is that if you don’t like the default functionality you are not stuck with it. What we did was create a new class (OrchestratorRunbook) that is based on the activity class. This class has a number of properties that are specific to the Runbook, what Web Service URL should be used to initiate it, what is its path, what is the path to a command line tool for initiating the Runbook and 20 string properties for mapping input values to.

There is then a workflow that fires off when an instance of the activity is changed to the ‘In Progress’ or ‘Re-Run’ status

This workflow runs a PowerShell script that calls the ScorchLauncher command line utility for initiating Runbooks through the Orchestrator web service which has built-in retry logic if the web service is temporarily un-available.

The script it is running is


write-host “Scorch Launcher Path: $scorchLauncherPath”

write-host “Webserver URL: $orchestratorSVCUrl”

write-host “Runbook Path: $runbookPath”

write-host “ReferenceID: $ReferenceID”


if($userName -and $userDomain -and $userPassword) {

Write-Host “Passed Username [$Username] Domain [$userDomain] and Password”

Write-Host $scorchLauncherPath -WebServerURL “$orchestratorSVCUrl” -RunbookPath “$runbookPath” -InputParameters “ReferenceID|$ReferenceID” -Username “$userName” -Domain “$userDomain” -Password “Password” -WaitForExit $true

& $scorchLauncherPath -WebServerURL “$orchestratorSVCUrl” -RunbookPath “$runbookPath” -InputParameters “ReferenceID|$ReferenceID” -Username “$userName” -Domain “$userDomain” -Password “$userPassword” -WaitForExit $true


else {

Write-Host “Not Passed User Name”

Write-Host $scorchLauncherPath -WebServerURL “$orchestratorSVCUrl” -RunbookPath “$runbookPath” -InputParameters “ReferenceID|$ReferenceID” -WaitForExit $true

& $scorchLauncherPath -WebServerURL “$orchestratorSVCUrl” -RunbookPath “$runbookPath” -InputParameters “ReferenceID|$ReferenceID” -WaitForExit $true





As you can see the script passes a single parameter to the target Runbook called “ReferenceID” (you need to have a initialize data on your connecting Runbook with this input parameter defined). The unique Guid of this activity will be passed to your Runbook, from there you can use objects from the SCSM 2012 integration pack to get the rest of your data. Specifically you can use the ‘Get Object’ to read the rest of the input values or ‘Get Related Object’ to get the related Service Request and its properties.



Creating the SCSM Request Offering Suite

Now that we have the class created in a sealed management pack we can create instances of it in any other management pack! Internally we have a best practice to make a new management pack per service offering, so, for testing and demo purposes I will create a new unsealed management pack. Each unsealed management pack will need one template instance of this OrchestratorRunbook class created initially, after that you simply add an instance of that template to each new Service Request Template instance and configure it to the Service Request specifications (target it at the correct Runbook and Web Service)

Creating the Initial OrchestratorRunbook Activity Template

Since I am making a new Service Offering for this example I need to create a new OrchestratorRunbook template instance


In our base template we set the Activity status to Pending initially, this is to avoid a race condition inside of Service Manager (discussed here We can also change the default Orchestrator Web Service URL or Runbook Path, both of these properties can and be over written when an instance of this template is added to a Service Request.

Creating the service request

Now that we have the activity template created we can create our Service Requests and add in instances of this OrchestratorRunbook activity to trigger off our runbooks!

Just like normal, when we want to trigger a Runbook we go to the ‘Activities’ portion of the SR Template and add in a new instance the OrchestratorRunbook Activity template class we created. We can now define, on a SR to SR basis (and update easily) what web service it is initialized through (huge for multi-instance Orchestrator deployments) and the path of the Orchestrator Runbook!

Creating the Service Request Offering

Now that we have the Service Request setup we can create a Service Request Offering to display the SR on the self-service portal

Setup your input prompts as normal

The OrchestratorRunbook Activity has 20 fields to map inputs to.

Use the Request Offering!

Now that the Request Offering is created you can do all of your normal activities, add it to a Service Offering, secure who can access it and initiate it!


So, what does all this mean? We have a new way to trigger Runbooks that is not tied to the ‘connector’ framework and Runbook Activity Template model from Microsoft.

  • This gives us a more flexible solution for environments with Multiple Orchestrator and / or Service Manager environments
    • All that is stored in these classes is strings, not references to connectors which are Service Manager and Orchestrator environment specific).
  • We can reduce the number of steps to create a Request offering down to two
  1. Create Service Request
    1. add and configure OrchestratorRunbook activity
  2. Create Request Offering
  • If we need to change what environment a Runbook is triggered from we don’t have to re-create anything. Just find the Service Request that references it, open up the OrchestratorRunbook Activity instance and change the web server URL
  • We can utilize ‘Cool’ functions inside of Service Manager, like Copy Request Offering to make QA / Production versions of our Request Offerings
    • This creates a new Request Offering and New Service Request
      • We can point the new Service Request to a QA / Production Orchestrator environment by just switching the web service URL
      • Easy way to create ‘dev / qa / production’ versions of everything from the UI (Service Manager Request Offerings) to tie to our Orchestrator Tiers


So, how do you go about getting all of this setup? The management pack / InitiateRunbook.dll file is available on the Orchestrator public integration pack codeplex site at — as with everything this is a use at your own risk solution, try it in a development / test environment first.

Step 1: Register MP

  • Just like normal register the integration pack into your environment, both the sealed and unsealed versions are available on the codeplex site
    • Register a sealed version so you can reference it from unsealed management packs

Step 2: Deploy the InitiateRunbook.dll

  • Since this MP relies on a workflow there is a .dll file that needs to be deployed to your service manager management server.
  • Stop your Management Service

  • Copy the .dll file out to the Service Manager installation folder

  • Start your Management Service

Step 3: Deploy the scorchLauncher Utility

Copy the scorchLauncher utility and its dependencies to the path that you will reference with your OrchestratorRunbook template. By default this is c:\Orchestrator\ScorchLauncher.exe on your Service Manager Management server


Step 4: Enjoy and Give Feedback

Feedback can be given on the project!

Tagged with: , , , ,
Posted in Infrastructure
3 comments on “Triggering Orchestrator Runbook from Service Manager
  1. […] We add 4 activities, an OrchestratorRunbook (our way of calling out to Orchestrator discussed at and 3 Manual […]

  2. Nick says:

    Instead of doing all of this, why don’t you just use the ‘Runbook Automation Activity’ class within SCSM…

    • randorfer says:

      Hey Nick,

      There are a lot of inherent problems with the built-in ‘Runbook AUtomation Activity’ class that you will probably run into if you try to use it in an enterprise environment, here are a few of the reasons we moved away from it

      * Tied to Runbooks by GUID not Path
      ** Everytime you update a runbook you have to do a fair amount of work in service manager to re-sync
      ** Does not allow for moving between Pre-Prod and Prod Orchestrator environments (GUID changes during import)
      ** Challenging for moving between Pre-Prod and Prod Service Manager and keeping in sync with the correct Orchestrator Environment
      * Cannot ‘Copy Request Offering’ if it has an attached RAAT
      * Have to do discovery of Runbooks
      * Passing of Parameters is tied by GUID not Parameter name, if you change inputs to your runbook you have to re-map everything

      I am sure there are more but those are the ones that come to mind quickest. Good luck!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: