Orchestrator Runbook Jumpstart (Part 3)–Bridging Gaps, Extending Capabilities, Best Practices

In the third installment in the Orchestrator Runbook Jumpstart series, we will take a deep dive into advanced runbook authoring concepts, best practices and  options for extending native Orchestrator functionality.

In the Series

The series will consist of the following articles.

HAND ON LABS: As a reminder, to reinforce the concepts covered in this installment, you will find a pointer to accompanying hands-on lab exercises (on Microsoft’s TechNet Virtual Labs) that reinforce the concepts discussed here. These labs are largely Opalis 6.3 labs, but the authoring experience (interface, runbook concepts, etc.) in Orchestrator is basically unchanged from that of Opalis (although some terminology has been updated). In fact, the runbooks used in these Opalis labs all work in Orchestrator 2012.

In This Installment

This installment of this five part series delves into other Opalis / Orchestrator functionality, discussing these runbook authoring topics:

  • Complex Link Logic (Advanced Branching)
  • Bridging the Gaps with PowerShell
  • Extending Your Capabilities with Community-Developed IPs
  • Runbook Authoring Best Practices
  • Additional Resources

Orchestrator 2012 includes a number of features that facilitate creation of more complex, modular runbooks, which are described here. New to Orchestrator? Go back and read part 1 and part 2 in the series before continuing.

Complex Link Logic (Advanced Branching)

The default logic on a runbook link in Orchestrator is success, meaning that when the upstream activity in the runbook runs successfully, the next activity in the runbook is triggered. However, the filtering logic available in runbook links lets you configure link conditions to evaluate published data (both numeric and string data) to add filtering and decision-making capabilities to runbooks. When an activity runs, it can produce one or more data items. Each data item is evaluated by every link (attached to the source activity), and each one of their link conditions. Only data items that satisfy the link conditions are passed to the downstream activities.

For example, the Query Database activity runs and retrieves five rows of data from the database. These five rows of data will be evaluated by the link conditions. If only two of the data items satisfy the link conditions, the following activity will run two times. That activity does not need to subscribe to the previous activity’s data for this execution to happen. This was discussed in the “Rules of the Databus” section in part 1 of this series.

While the default link condition simply looks for successful execution of the previous activity, more specific criteria can be configured, based on data output from the activity-specific Published Data or through use of Common Published Data. Link logic options include:

  • Date/Time Comparison: Allows comparison of date / time values including full date or date parts (second, minute, hour, month, year). Using the Include / Exclude tabs, you can configure a link to match a static date range.
  • Include / Exclude Logic: Link filtering includes both Include and Exclude tabs. A positive result (match) on the Include tab allows activities to pass while a positive result on the Exclude tab filters activities from passing to the next activity.

Note: AND Logic is not configurable. If AND Logic is needed, you can use a combination of Include and Exclude logic to create logic similar an AND statement.

  • RegEx Pattern matching on text-based activity output: If the output is a string, you can configure RegEx pattern matching including options such as an exact match and wildcard.
  • Numeric Comparisons: If the output is numeric, you can compare the output against a desired value (equals, greater than, less than, and so on).
  • Matching based on multiple criteria: On the Include tab, you can check for multiple conditions. Since this uses OR logic, any matched expression will be considered successful.

Bridging the Gaps with PowerShell

When reading datasheets related to Orchestrator, you will see mention of “without scripts” and “no scripting required” and these are true most of the time. However, at some point, you will encounter an automation need for which there is no Orchestrator activity. Fortunately, Orchestrator includes the Run .Net Script activity as a Standard Activity; this can run scripts written in VB.Net, JScript, C#, and Windows PowerShell. The Run .Net Script activity is compatible with .Net CLR version 2.0 and later, and is an excellent way to create a custom activity to bridge a feature gap when no activity exists to address a specific need.

Understanding how to publish data from a Run .Net Script activity is the key to using this activity effectively. While you can process loads of data using PowerShell, by default no script-specific data is published from a Run .NET Script activity . If you want to make the data output of your PowerShell scripts available to other activity on the databus, you must add each of the data elements that you want this activity to publish on the Published Data tab of the Run .NET Script activity.

Published data elements consist of three values (described here and shown in Figure 1):

  • Name: A label for the variable data being published.
  • Type: The data type contained in the variable (e.g. string, integer, or date/time).
  • Variable: The variable from within the script. This can be a variable containing a single value or an array of values. You can publish multiple variables from a single script, making multiple data sets available from a single Run .NET Script activity.


Figure 1 – The Published Data Tab of the Run .Net Script Activity

Data elements published from your PowerShell scripts in a Run .Net Script activity can be single data items or data arrays. The Run .Net Script activity automatically correlates multi-valued data from different items by aligning them. For example, if you choose to publish two items labeled “Cities” and “Prices” as collections, the Run .Net Script will try to line up each item in the Cities collection with each item in the Prices collection. If the collections are not sized equally, the Run .Net Script activity will create blank values when it encounters a null value in the collection.

Note: The alignment of array data is demonstrated in the PowerShell scripted integrated runbook included in the code download with this article.

An Example: Using PowerShell and Conditional Links in Orchestrator Runbooks

A sample Orchestrator runbook demonstrating how to configure data publishing from the Run .Net Script activity (shown in Figure 2) is available in the code download accompanying this article. This example will run in Opalis 6.3 as well as the new System Center Orchestrator 2012.

  • The runbook shown in Figure 2 monitors for changes to a file containing wheat prices for cities in Texas, and logs an informational or warning event to the Windows Application Event Log depending on the price.
  • The Monitor File activity monitors for changes to c:\labfiles\wheatprices.csv. If a change is detected, it triggers the next activity in the runbook – a Run .Net Script activity.
  • The Run .Net Script activity contains a PowerShell script that imports the contents of the file and publishes the city and price values using the techniques described in this article and shown in Figure 1.


Figure 2 – Runbook incorporating Run .Net Script and associated data file

  • Using conditional links, the runbook follows the success branch (the green link) and logs informational event to the Windows Application Event Log for all cities for prices less than $2.
  • Alternatively, if the link data published from the Run .Net Script is greater than or equal to $2, the other conditional branch (the red link) triggers the Send Event Log Message labeled Log High Price (Warning).

Note: Notice that the entry for Lubbock in the file has no price data (a null value). Try to run the runbook in your own test environment to see how Orchestrator handles the null value.

Extending Your Capabilities with Community-Developed IPs

There are times where you will encounter a scenario in which a Microsoft-developed integration pack (IP) does not exist. Fortunately, you can find many Orchestrator IPs developed by members of the Opalis / Orchestrator community and published on CodePlex (http://opalis.codeplex.com). A few of the more notable community-developed IPs on CodePlex include:

  • Microsoft SharePoint – Activities in this IP enable you to manipulate SharePoint Lists and Libraries (e.g. Document Libraries, Image Libraries etc.) to add, modify and remove entries, files and attachments.
  • VMware vSphere: The activities in this IP map to a subset of about 25 of the PowerShell cmdlets in the vSphere PowerCLI. With activities like ‘New VM,’ ‘New Hard Disk,’ and ‘New Network Adapter,’ this IP is intended to facilitate automation of virtual machine provisioning in vSphere.
  • Service Manager Extension IP: This pack includes a number of activities to automate incident, problem, and change management. It focuses on work items that have slipped through the cracks – such as past due and unassigned change requests and unassigned incidents. It includes activities to close completed or resolved incidents, changes, and problems.

These are just the tip of the iceberg. You can find a complete list of Orchestrator-related IPs and code samples on CodePlex at

Runbook Authoring Best Practices

There are a number of best practices to keep in mind when authoring Orchestrator runbooks . Here are several.

  • Create Modular runbooks : By creating smaller, modular runbooks that serve a specific function (such as error handling), you can reap a number of benefits:
    • Reduced Complexity: Following the logic and branches within runbooks containing dozens of activities can be difficult. Using smaller nested runbooks (connected through use of the Invoke Runbook activity), you can ease the troubleshooting and ongoing authoring processes.
    • Easy reuse: You can easily reuse runbooks in multiple workflows, minimizing the effort of rewriting activities you have written previously.
  • Establish Runbook Naming Conventions: Work with your fellow administrators to establish naming conventions for runbooks, variables, schedules, and groups, and use description fields to add additional information. This should eliminate confusion about the purpose of activities and allow greater reuse across runbooks and among multiple authors.
  • Define a Folder Structure: Similar to runbook naming conventions, using intuitive folder structures for runbooks, variables, schedules, and groups can eliminate confusion.
  • Export Runbooks Periodically: While Orchestrator requires that you check runbooks in and out, it does not include a runbook versioning functionality to accommodate rollback. On a recurring basis, export all your Orchestrator runbooks so you can recover them if necessary.

You can find more information on runbook authoring and publishing best practices in System Center Opalis Integration Server 6.3 Unleashed (Sams, 2011).

Additional Resources

Orchestrator is a powerful platform for process automation and the native integration within the System Center suite ups the ante considerably. It is also a surprisingly easy product to learn. You can learn more about Orchestrator at http://technet.microsoft.com/en-us/evalcenter/hh505660, where you can download the 180 day trial version and related product documentation.

You can find several System Center-integrated runbook samples on the Internet, including:

You can also learn about Orchestrator in depth by reading System Center Opalis Integration Server 6.3 Unleashed, which is now available for purchase. For a PDF version of the book, check out http://www.informit.com/store/product.aspx?isbn=0672335611.

Hands-On Lab

UPDATE 3/12/2013: These labs are currently unavailable. I’ll update this article when replacements are online and working.

Now, you’re ready to apply what you’ve learned in the creation of more advanced Orchestrator runbooks. As with the hands-on labs in part 1, the runbooks in these labs will run equally well in Opalis and Orchestrator.


  • Authoring experience and interface in Opalis and Orchestrator is basically the same.
  • Policies in Opalis are what we now call Runbooks in Orchestrator….same concept, new terminology.
  • Foundation Objects are now called Standard Activities….same concept, new terminology.

Get Orchestrator Unleashed

Pete Zerger is an author for the upcoming System Center 2012 Orchestrator Unleashed (http://www.amazon.com/System-Center-2012-Orchestrator-Unleashed/dp/0672336103). This book is authored by an expert team of current and former Microsoft MVPs who also wrote the industry’s leading guide to Opalis 6.3, Orchestrator 2012’s predecessor product.

2 thoughts on “Orchestrator Runbook Jumpstart (Part 3)–Bridging Gaps, Extending Capabilities, Best Practices

Leave a Reply

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