Getting Started with the Orchestrator SDK

  • Article

Applies To: System Center 2012 - Orchestrator, System Center 2012 R2 Orchestrator, System Center 2012 SP1 - Orchestrator

The topics in this section will help you get started with developing Orchestrator solutions.The Orchestrator SDK binaries are installed from the Orchestrator Integration Toolkit, and located in the “%ProgramFiles(x86)%\Common Files\Microsoft System Center 2012\Orchestrator\Integration Toolkit\Lib” folder (note: on 32-bit Windows 7 computers, the base directory is %ProgramFiles%).

Orchestrator SDK Requirements

Developing integrations using the Orchestrator SDK can be done in any language and tool that can produce .NET Framework 3.5 compatible binaries. All the examples and samples in the documentation were created by using Visual Studio 2010, targeting the .NET Framework 3.5.

System Requirements

SDK Binary Requirements

When creating a set of Orchestrator runbook activities, start by referencing the SDK binaries from your solution’s project. You will then create the code that Orchestrator will use to display and run your activities using the Orchestrator SDK interface and attribute classes.

Visual Studio Solution

When using Visual Studio to create a solution that uses the Service Manager SDK, note the following requirements:

  • You must target .NET Framework 3.5

  • You must be using one of the following Visual Studio versions:

    • Visual Studio 2010

    • Visual Studio 2008

Creating a “Hello World” Activity

In this section, you will create a new Orchestrator runbook activity that simply takes an input, modifies it, and returns an output to Published Data. Using this example, you will learn how to create a basic activity and understand the structure of input and output data and how to use the SDK classes to define the visual and non-visual aspects of the activity.

Getting Started

In order to create a new .NET-based activity using the Orchestrator SDK, you need to first create a new Class Library project in Visual Studio using .NET Framework 3.5. To do this, open Visual Studio and select File > New > Project. Then in the New Project dialog, select .NET Framework 3.5 in the drop down at the top of the window, ensure Class Library is selected (under the Visual C# category of templates). Name the project and location as desired, and click OK.

New Project

Next, the project needs to reference the Orchestrator SDK Library. In Solution Explorer, right-click the References folder and select Add Reference.

Add Reference

Browse to the directory where the library files are installed (typically “C:\Program Files (x86)\Microsoft System Center 2012\Orchestrator\Integration Toolkit\Lib”) and select Microsoft.SystemCenter.Orchestrator.Integration.dll. Your references folder should open and the new reference should be shown.

You will also need to add a using so that you can directly reference classes in the SDK without specifying the entire namespace path. Simply go to the Class1.cs file and enter the following text at the bottom of the using section:

using Microsoft.SystemCenter.Orchestrator.Integration;

Save class1.cs.

You are now ready to start creating your first activity!

Creating the Base Activity

Since “Class1” is not very descriptive as class names go, start first by renaming the class file to something fitting the activity being created. Right-click the Class1.cs file in Solution Explorer and select Rename. Rename the file to HelloWorldActivity.cs. A dialog prompt appears asking if you want to rename other elements. Click Yes.

Your .cs code should appear similar to the code below.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.SystemCenter.Orchestrator.Integration;

namespace OrchestratorSDKExample
{
    public class HelloWorldActivity
    {

    }
}

The first step in creating an Orchestrator Activity is to indicate to Orchestrator that it actually is an activity. You can do that by adding the [Activity] attribute just above the class definition. And, since you don’t want the name of the activity to be “HelloWorldActivity”, you’ll want to add a better name, which you can do by simply adding ("Hello World") to the attribute, so that it looks like the example below.

namespace OrchestratorSDKExample
{
    [Activity ("Hello World")]
    public class HelloWorldActivity
    {
        
    }
}

Next, you define the inputs, actions, and outputs of the class, just as you would any other class definition. For this example, the activity will read text input from a property named “Hello World Input”, and output to published data via a property named “Hello World Output”. You might notice that these property names are not actually valid property names because they contain spaces. These are actually the display names of the properties as they would appear in the activity or Published Data when seen in the Runbook Designer. The underlying property names that actually store the values in the code require valid C# property names.

Aside from the input and output, there will be some processing in the middle. This is to demonstrate the difference between portions of your class that represent visual aspects of the activity and the portions of your class that just represent data processing. In this example, we will take the string provided in input and reverse the characters before sending the string to the output property.

Next you’ll see how to put the concept into action.

Providing Input

In order to provide input, you’ll need a string property defined in the class with a public set method. You’ll then add the [ActivityInput] attribute to the string property to let Orchestrator know this is an input property to display. And, again since you want to display a nice string to the user, you’d modify the attribute to add a display name for the activity. The end result is shown below, using good programming practices to separate public and private properties.

namespace OrchestratorSDKExample
{
    [Activity ("Hello World")]
    public class HelloWorldActivity
    {
        private string hwinput;

        [ActivityInput ("Hello World Input")]
        public string HWInput
        {
            set { hwinput = value; }
        }
    }
}

Input parameters are limited to some fundamental types, which include:

  • Boolean

  • Integer, Float

  • String

  • DateTime

  • Enums

  • Classes with a conversion constructor taking a string parameter (discussed later in this document)

Providing Output

In order to show the user what happened when the activity ran, you have to provide some sort of output. In this example, you’ll return the modified string to the user via the “Hello World Output” property. Construction is similar to the input property, but you don’t need to store the property anywhere, so you just need a public string with the [ActivityOutput("Hello World Output")] attribute so Orchestrator knows it’s an output property.

Inside the get method, you perform the string reversal and output the new string. Your code should now look similar to the code below.

namespace OrchestratorSDKExample
{
    [Activity ("Hello World") ]
    public class HelloWorldActivity
    {
        private string hwinput;

        [ActivityInput ("Hello World Input")]
        public string HWInput
        {
            set { hwinput = value; }
        }

        [ActivityOutput("Hello World Output")]
        public string HWOutput
        {
            get
            {
                char[] arr = hwinput.ToCharArray();
                Array.Reverse(arr);
                return new string(arr);
            }
        }      
    }
}

Believe it or not, you’re done! That’s all there is to creating an activity. Now all you need to do is build your project and try it out in Orchestrator. To build your assembly, right-click the project name in the Solution Explorer and select Build. A new assembly will be built and put into the bin\Debug folder under your project directory. The simplest way to get there is to right-click the project name again and select Open Folder in Windows Explorer, then browse down to the bin\Debug folder. Find the DLL that was created (in this example, it’s OrchestratorSDKExample.dll) and copy it to a location where you can find it easily from the Runbook Designer.

Running Your Hello World Activity

If you have not yet installed the Integration Pack for Microsoft .NET, you will need to do that now. The Integration Pack is located in the Integration Packs directory under the Integration Toolkit installation path (typically C:\Program Files (x86)\Microsoft System Center 2012\Orchestrator\Integration Toolkit\Integration Packs”). Use Deployment Manager to register and deploy the IP to your Runbook Designer (no need to deploy it to a Runbook Server yet). For more information about how to install an Integration Pack, see How To Install an Integration Pack.

To run the activity

  1. Open Runbook Designer and create a new runbook.

  2. Find the Integration Toolkit category in the Activities pane and drag an Invoke .NET activity from that category into the new runbook. If you get a prompt to check out the runbook, click Yes.

  3. Double-click the Invoke .NET activity to open its properties.

  4. To load the assembly you just built into the activity, click the ellipsis (…) button to the right of the Assembly textbox and browse to the DLL that was created, then click Open.

  5. Next, click the ellipsis (…) button next to Class and select the class name created in the assembly (OrchestratorSDKExample.HelloWorldActivity).

  6. Click the Properties tab. You should see a property named Hello World Input.

  7. Type Hello World! into the property’s textbox.

    Invoke .NET Properties

  8. Click Finish to save your changes.

  9. In the Runbook Designer Toolbar, click Runbook Tester. The Runbook Tester opens.

  10. Click Run. The runbook is invoked and immediately returns a successful status.

  11. Click Show Details to see the published data from the activity. Notice the property named Hello World Output and that it shows the input string reversed.

    New Project

You have now successfully created, built and tested a custom activity that utilizes the Orchestrator SDK to handle input and output. In the next sections, you’ll learn more advanced concepts to make your activities more professional and secure.