Calling an Orchestrator Runbook from SMA – Part 1

Hello readers!

In this blog post I would like to show you how you can call an Orchestrator Runbook from within Service Management Automation (SMA). It demonstrates how you can use your current existing Orchestrator Runbooks and integrate those with SMA. In Part 2 I will be talking about more integration scenarios, for example how to integrate System Center 2012 Service Manager.

If you want to download and test the SMA Runbooks which I’ve used in this blog post, just click on the Download Button.

7266_BCDLButtonDark_22F105C6

Note: Before you import the SMA Runbooks, please be sure to check out Jim Britt’s blog post on SMART. Jim has built a cool automation solution around importing and exporting SMA Runbooks


Assumptions

I’m assuming that you have the following installed and configured:

  1. Windows Azure Pack, click here for more information on downloading and installing WAP
  2. SMA,  see our SMA primer blog post
  3. System Center 2012 Orchestrator (RTM or above)

Blog post objectives

We will accomplish the following in this blog post:

  1. Create an SMA credential setting for Orchestrator
  2. Create a simple Orchestrator Runbook to test against
  3. Create an SMA Runbook to test the connection to Orchestrator
  4. Create an SMA Runbook that invokes an Orchestrator runbook
  5. Create an SMA Runbook and pass values for an Initialize Data activity to an Orchestrator Runbook

Let’s get started!


1. Create an SMA Credential setting for Orchestrator

For SMA to talk to Orchestrator we first need to define a Credential, which is similar to an Orchestrator connection:

  1. Navigate to your WAP admin site, for example “https://YourWAPserver:30091/“
  2. Click on Automation
  3. Select Assets
  4. Click on Add Setting
image

image

 

5.  Select Add Credential

image

 

6.  Now walk through the wizard and fill in your own values where applicable and save the Credential:

image

 


2. Create an Orchestrator Runbook to test against

Before we can start testing, we obviously need an Orchestrator Runbook to test against. Let’s create a simple Orchestrator Runbook. Take notion of the following (as in the illustration below):

  • The Orchestrator folder name (in my example Building Clouds)
  • The runbook name (in my example My SCO Runbook)
  • An Initialize Data activity without parameters (we will come back to that later)
  • Add any activity to test if the runbook has ran successfully. In my example I’m writing an entry in the application event log
  • The Check in status of your runbook (needs to be checked in)

image


3. Create an SMA Runbook to test the connection to Orchestrator

Now that we’ve created a simple Orchestrator Runbook, let’s continue on the SMA side and test-drive our SMA Orchestrator connection by creating a new SMA Runbook. Within WAP click on New and select Quick Create to create a new runbook:

image

Give your runbook a name, mine is called Get-MyOrchestratorRunbook

image

Go to the Automation tab and edit the draft of your new created runbook and copy and paste the PowerShell script below. Please note that you need to modify the following values:

  • $PSCredName – needs to match the credentials you have added in step 1
  • $SCOserverName – needs to match your Orchestrator server name
001

002

003

004

005

006

007

008

009

010

011

012

013

014

015

016

017

018

019

020

021

022

023

024

025

026

027

workflow Get-MyOrchestratorRunbook 

{ 

    <#

    Project Name: Get Orchestrator Runbook

    Runbook Name: Get-MyOrchestratorRunbook

    Runbook Type: Process

    Runbook Tags: Type:Process, Proj:Get Orchestrator Runbook

    Runbook Description: Process Runbook for the "Get Orchestrator Runbook" Project

    Runbook Author: Tiander Turpijn

    Runbook Creation Date: 11/01/2013

    #>   

   

    $SCOserverName = "YourOrchestratorServerName"

    $PSCredName = "Contoso-Creds"

    $PSUserCred = Get-AutomationPSCredential -Name $PSCredName

    $MyRunbookPath = "\Building Clouds\My SCO Runbook" 

   

    # Get the url for the Orchestrator service

    $url = Get-OrchestratorServiceUrl -Server $SCOserverName

    # Get a Runbook by Path and Name

    $MyRunbook = Get-OrchestratorRunbook -serviceurl $url -credentials $PSUserCred -RunbookPath $MyRunbookPath 

      

# Show the Runbook information

$Myrunbook 

   

}

Testing the “Get-MyOrchestratorRunbook”

Let’s start the Get-MyOrchestratorRunbook and look at the output. Please note the following in the Output Pane illustration below:

  • Name of the runbook
  • The runbook GUID
  • The parameters URL

image

We will come back to the Url_Parameters section later on.


4. Create an SMA Runbook to invoke an Orchestrator Runbook

Now that we have tested that our SMA to Orchestrator connection works, let’s actually start an Orchestrator Runbook. Create another SMA Runbook and call it something like Invoke-OrchestratorRunbook. Copy and paste the following PowerShell script in your SMA Runbook as we did in step 3:

001

002

003

004

005

006

007

008

009

010

011

012

013

014

015

016

017

018

019

020

021

022

023

024

025

026

027

028

029

030

031

workflow Invoke-OrchestratorRunbook 

{ 

    <#

    Project Name: Invoke Orchestrator Runbook

    Runbook Name: Invoke-OrchestratorRunbook

    Runbook Type: Process

    Runbook Tags: Type:Process, Proj:Invoke Orchestrator Runbook

    Runbook Description: Process Runbook for the "Invoke Orchestrator Runbook" Project

    Runbook Author: Tiander Turpijn

    Runbook Creation Date: 11/01/2013

    #>

   

    $SCOserverName = "YourOrchestratorServerName"

    $PSCredName = "Contoso-Creds"

    $PSUserCred = Get-AutomationPSCredential -Name $PSCredName

    $MyRunbookPath = "\Building Clouds\My SCO Runbook" 

  

    # Get the url for the Orchestrator service

    $url = Get-OrchestratorServiceUrl -Server $SCOserverName

    # Get a Runbook by Path and Name

    $runbook = Get-OrchestratorRunbook -serviceurl $url -runbookpath $MyRunbookPath -credentials $PSUserCred 

   

    # Start the runbook

    $job = Start-OrchestratorRunbook -runbook $runbook -credentials $PSUserCred 

      

    # Show the Runbook job information

    $job 

   

} 

Save your runbook and let’s start the runbook by clicking on Test. Verify if your Orchestrator Runbook has ran successfully, you should see an event log entry on your Orchestrator server as well.


5. Pass “Initialize Data” values to an Orchestrator Runbook

In this section we will create a new SMA Runbook which will pass Orchestrator Initialize Data values to an Orchestrator Runbook.

Let’s edit our Orchestrator Runbook which we’ve created in step 2 and add parameters to our Initialize Data activity:

image

Also edit the Send Eventlog Message activity and write our new parameters out -  by utilizing the data bus – to the event log. Right click in the Message section and select Subscribe, Published Data:

image

Select the new parameters from the Initialize Data activity:

image

Add those to the Send Event Log Message activity and click on Finish.

image

Note: Be sure to check the runbook in again and switch back to your SMA server


Now let’s for the fun of it, run our SMA Runbook Get-MyOrchestratorRunbook one more time, as we’ve created in step 3, and copy and paste the URL_Parameters value from the output pane in a new browser window.

image

You should be seeing something like this:

image

Note: in the illustration above we can see our new 2 Initialize Data parameters (MyParameter1 and MyParameter2).

So let’s see how we can utilize those new parameters.


Create a new SMA Runbook, as we’ve done in step 3. Name your new SMA Runbook something like Invoke-OrchestratorRunbook2 and copy and paste the following PowerShell script into the runbook, please note the following:

  • Our Initialize Data parameters are stored in $param1name  and $param2name
  • Our Initialize Data parameter values are stored in $param1guid and $param2guid
001

002

003

004

005

006

007

008

009

010

011

012

013

014

015

016

017

018

019

020

021

022

023

024

025

026

027

028

029

030

031

032

033

034

035

036

037

038

039

040

041

042

043

044

045

046

047

048

049

050

051

052

053

workflow Invoke-OrchestratorRunbook2

{ 

    <#

    Project Name: Invoke Orchestrator Runbook

    Runbook Name: Invoke-OrchestratorRunbook2

    Runbook Type: Process

    Runbook Tags: Type:Process, Proj:Invoke Orchestrator Runbook

    Runbook Description: Process Runbook for the "Invoke Orchestrator Runbook" Project

    Runbook Author: Tiander Turpijn

    Runbook Creation Date: 11/01/2013

    #>

   

    $SCOserverName = "YourOrchestratorServerName"

    $PSCredName = "Contoso-Creds"

    $PSUserCred = Get-AutomationPSCredential -Name $PSCredName

    $MyRunbookPath = "\Building Clouds\My SCO Runbook" 

    

    # Get the url for the Orchestrator service

    $url = Get-OrchestratorServiceUrl -Server $SCOserverName

   

    #Provide the Initialize Data activity parameters:

    $param1name = "MyParameter1" 

    $param2name = "MyParameter2" 

    $param1guid = "" 

    $param2guid = "" 

    $runbook = Get-OrchestratorRunbook -serviceurl $url -runbookpath $MyRunbookPath -credentials $PSUserCred

   

    #Correlate the Initialize Data parameters with our values

    foreach ($param in $runbook.Parameters) 

    { 

        if ($param.Name -eq $param1name) 

        { 

            $param1guid = $param.Id  

        } 

        elseif ($param.Name -eq $param2name) 

        { 

            $param2guid = $param.Id  

        } 

    } 

       

        #Provide the values for our Initialize Data parameters

        [hashtable] $params = @{ 

            $param1guid = "Building Clouds is"; 

            $param2guid = "Cool!" 

        } 

        # Start the runbook with our params

         $job = Start-OrchestratorRunbook -runbook $runbook -parameters $params -credentials $PSUserCred

          

# Show the Runbook job information

$job 

   

} 

Save the new runbook and click on Test. You should now see a successful execution of your Orchestrator Runbook and should see our values written to the Orchestrator application event log, cool stuff right?


So what’s next, what is in part 2?

You might have noticed there’s a missing link in the scenario above (or not Smile) “Where are my Orchestrator data bus values dude!?”

A lot of Orchestrator runbooks utilize data bus values to be returned or to be written back somewhere. So in Part 2 we will be looking at the following scenario:

  1. Request a new Virtual Machine in WAP as a tenant
  2. Write the new Virtual Machine name in Service Manager’s CMDB, that’s right Service Manager’s CMDB Smile
  3. Retrieve a cost center from the Service Manager’s CMDB
  4. Return that cost center back to SMA
  5. Write the cost center in the Virtual Machine properties within Virtual Machine Manager

That’s it for now, I hope you found this guidance useful and that you have seen how you can light up your Orchestrator Runbooks through SMA in Windows Azure Pack.

And for more information, tips/tricks, and example solutions for PowerShell + System Center 2012 R2, be sure to watch for future blog posts in the Automation Track!