Calling an Orchestrator Runbook from SMA – Part 1

Calling an Orchestrator Runbook from SMA – Part 1

  • Comments 13
  • Likes

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!

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Thanks for a great article Tiander.  I've been searching for ages on how to get this all up and running, and it's already a lot clearer to me.  Looking forward to the next article.

    Couple of things i noticed :

    "Select Add Connection" should be "Select Add Credential"

    Had to change the name of the first workflow from "Get-OrchestratorRunbook".  Presumably because otherwise it was trying to call itself instead of using the Get-OrchestratorRunbook command.

  • Hello Tim,

    Thank you so much for your sharp observations!

    I've corrected the article so that it shows "Select Add Credential", also I've renamed the first runbook to not have a conflict with the SMA Orchestrator cmdlet

    Thanks,

    Tiander.

  • Great article Tiander.  Is part 2 coming :)

    Also do you happen to know how to pass / access variables when runbooks are been called from things like the VM Clouds automation.  (small things like vmname :) so when you create / update / delete vm's you can find out what one to do it with)

    Thanks

    Davey

  • Hi Tiander,

    Great post! I was looking for an "end user portal" for my orchestrator runbooks.

    Can I start Orchestrator runbooks form the Windows Azure Pack directly or is it only possible in combination with an other task like "create VM" in SCVMM?

  • Hello Davey,

    I've just released Part 2: blogs.technet.com/.../calling-an-orchestrator-runbook-from-sma-part-2.aspx

    I think you will find the answer to your question right there.

    Thanks,

    Tiander.

  • Hi Koen,

    Thanks!

    You can start SMA Runbooks directly from the portal. You can start runbooks manually or test them before publishing, but not as a tenant though. I suspect your question is from the tenant's perspective?

    There are some possibilities though (which require a custom resource provider) to realize just that.

    With regards to your question on a self-service portal for Orchestrator:

    You can look at a blog post from my fellow PM Bruno Saille: blogs.technet.com/.../automation-orchestrator-back-to-basics-use-cases-spotlight-3-of-5.aspx

    Look at the bottom of his blog post if that perhaps can help you further.

    In addition you can also explore this solution:

    http://www.eupsco.nl/

    Thanks,

    Tiander.

  • Tiander, Yes I mean from a tenant perspecitive. I'll exploring the options, the eupsco looks good for now.