Export (0) Print
Expand All

Runbook and Module Operations

Updated: April 3, 2014

Applies To: System Center 2012 R2 Orchestrator, Windows Azure Pack for Windows Server

The steps for creating and working with Automation runbooks are different depending on whether you using a management portal or Windows PowerShell. The basic steps for various common operations using both methods are provided in the following sections.

When you create a runbook with the Windows Azure Pack management portal or the Microsoft Azure management portal, you first create an empty runbook and then later edit it with the Automation editor to create the script. With Windows PowerShell, you import an existing script file to create the runbook.

  1. Select the Automation workspace.

  2. If you are using Azure, then select an Automation account.

  3. At the bottom of the window, click New.

  4. Click Quick Create.

  5. Type a name for the runbook in the Runbook Name box taking into account the Naming recommendations.

  6. Optionally, type a description in the Description box.

  7. If you are using Service Management Automation, optionally type in one or more tags separated by commas. If you are using Azure, then you can add tags by Editing Runbook Properties after it has been created.

  8. Click Create.

  9. Follow one of the procedures in Editing a Runbook to edit the runbook’s contents.

  • When you create a runbook with Windows PowerShell, you use the editor of your choice to write the workflow script. You then use the Import-SmaRunbookcmdlet to import the script file and create the runbook. The name of the script file must match the name of the workflow, and this name will be used for the runbook.

    When you create the runbook, you can use the –Tag parameter to set a tag on the runbook. You cannot set the tag with Windows PowerShell after the runbook has been created.

    The following sample commands show how to create a runbook. This example

    $webServer = 'https://MyServer'
    $port = 9090
    $runbookPath = 'c:\runbooks\Sample-TestRunbook.ps1'
    Import-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Path $runbookPath
    

Properties of a runbook include its description and logging properties in addition to a tag that may be required for the runbook to be accessed by certain services. You can edit these properties with the management portal for administrators or with the Set-SmaRunbookConfiguration cmdlet. The Tag property cannot be modified for an existing runbook with Windows PowerShell but can only be set when the runbook is created with Import-SmaRunbook.

  1. Select the Automation workspace.

  2. If you are using Azure, then select an Automation account.

  3. At the top of the window, click Runbooks.

  4. Locate the runbook to edit and click on its name.

  5. At the top of the window, click Configure.

  6. Set any properties that should be changed.

  7. Click Save when your edits are complete.

  • The following sample commands show how to set the properties for a runbook. In this example, the Description and Debug Logging properties are modified.

    $webServer = 'https://MyServer'
    $port = 9090
    $runbookPath = 'c:\runbooks\Sample-TestRunbook.ps1'
    $runbookName = 'Sample-TestRunbook'
    Set-SmaRunbookConfiguration –WebServiceEndpoint $webServer –Port $port –Name $runbookName –Description "Sample runbook" –LogDebug $true
    

One a runbook has been created, you can edit the draft version of its workflow. You later Publishing a Runbook the Draft version so that it is available to be run in production.

The management portal for administrators includes an editor that you can use to view and edit runbooks. In addition to providing text editing capabilities, the editor provides the ability to automatically insert code for Global Settings, Activities, and Runbooks.

The Automation editor includes a feature to insert code for Activities, Settings and Runbooks into a runbook. Rather than typing in the code yourself, you can select from a list of available assets and have the appropriate code inserted into the runbook.

  1. Select the Automation workspace.

  2. If you are using Azure, then select an Automation account.

  3. At the top of the window, click Runbooks.

  4. Locate the runbook to edit and click on its name.

  5. At the top of the window, click Author.

  6. Click Draft.

  7. Perform the required editing.

  8. Click Save when your edits are complete.

  1. Open the runbook in the management portal editor.

  2. At the bottom of the screen, click Insert and then Runbook.

  3. Select the runbook to insert from the center column and click the right arrow.

  4. If the runbook has parameters, they will be listed for your information.

  5. Click the check button.

  6. Code to run the runbook will be inserted into the runbook.

  7. If the runbook requires parameters, provide an appropriate value in place of the data type surrounded by braces <>.

  1. Open the runbook in the management portal editor.

  2. At the bottom of the screen, click Insert and then Setting.

  3. In the Setting Action column, select the type of code that you require

  4. Select from the available assets in the center column.

  5. Click the check button.

  1. Open the runbook in the management portal editor.

  2. At the bottom of the screen, click Insert and then Activity.

  3. In the Integration Module column, select the module that contains the activity.

  4. In the Activity pane, select an activity.

  5. In the Description column, note the description of the activity. Optionally, you can click View detailed help to launch help for the activity in the browser.

  6. Click the right arrow.

  7. If the activity has parameters, they will be listed for your information.

  8. Click the check button.

  9. Code to run the activity will be inserted into the runbook.

  10. If the activity requires parameters, provide an appropriate value in place of the data type surrounded by braces <>.

Note that only activities from modules that are imported into Automation are available from the Insert feature. In Service Management Automation, any cmdlet from a module installed on the Worker servers can be used in a runbook, but if they are not imported into Automation, then the editor has no knowledge of them. For further details, see the Modules section of this guide.

To edit a runbook with Windows PowerShell, you edit the script using the editor of your choice and save it to a .ps1 file. You can use the Get-SmaRunbookDefinitionto retrieve the contents of the runbook and then Edit-SmaRunbookcmdlet to replace the existing script with the modified one.

  • The following sample commands show how to retrieve the script for a runbook. In this example, the Draft version is retrieved. It is also possible to retrieve the Published version of the runbook although this version cannot be changed.

    $webServer = 'https://MyServer'
    $port = 9090
    $runbookPath = 'c:\runbooks\Sample-TestRunbook.ps1'
    $runbookName = 'Sample-TestRunbook'
    $content = Get-SmaRunbookDefinition –WebServiceEndpoint $webServer –Port $port –Name $runbookName –Type Draft
    

  • The following sample commands show how to replace the existing contents of a runbook with the contents of a script file.

    $webServer = 'https://MyServer'
    $port = 9090
    $runbookPath = 'c:\runbooks\Sample-TestRunbook'
    $runbookName = 'Sample-TestRunbook'
    Edit-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Name $runbookName –Path $runbookPath
    

You can test the Draft version of a runbook before publishing it. This allows you to validate its operation before making it available in production by overwriting the existing Published version. When you test the runbook, the Draft version is run and any output sent to the Output Pane in the management portal for administrators.

When a runbook is tested, its output is written more quickly to the Automation database than a production run of the runbook since it is assumed that an administrator is interacting with the test version. Also, Debug, Verbose, and Progress streams are disabled for test runs regardless of their settings in the runbook configuration. You can turn them on in the script by setting the appropriate Preference variable.

  1. Select the Automation workspace.

  2. If you are using Azure, then select an Automation account.

  3. At the top of the screen, select Runbooks.

  4. Locate the runbook to edit and click on its name.

  5. At the top of the screen, click Author.

  6. Click Draft.

  7. At the bottom of the screen, click Test.

  8. Click Yes to the verification message.

  9. If the runbook has parameters you will be presented with a dialog box to provide values for each.

  10. Inspect the output in the Output Pane.

Each runbook has a Draft and a Published version. Only the Published version is available to be run, and only the Draft version can be edited. The Published version is unaffected by any changes to the Draft version. When the Draft version should be made available, then you publish it which overwrites the Published version with the Draft version.

  1. Select the Automation workspace.

  2. If you are using Azure, then select an Automation account.

  3. At the top of the screen, select Runbooks.

  4. Locate the runbook to edit and click on its name.

  5. At the top of the screen, click Author.

  6. Click Draft.

  7. At the bottom of the screen, click Publish.

  8. Click Yes to the verification message.

  • The following sample commands show how to publish a runbook.

    $webServer = 'https://MyServer'
    $port = 9090
    $runbookPath = 'c:\runbooks\Sample-TestRunbook.ps1'
    $runbookName = 'Sample-TestRunbook'
    Publish-SmaRunbookDefinition –WebServiceEndpoint $webServer –Port $port –Name $runbookName
    

  1. Select the Automation workspace.

  2. If you are using Azure, then select an Automation account.

  3. At the top of the window, click Assets.

  4. Inspect the assets in the list with a Type of Module.

  • The following sample commands retrieve all modules installed in Automation.

    $webServer = 'https://MyWebServer'
    $port = 9090
    Get-SmaModule –WebServiceEndpoint $webServer –Port $port
    

An Integration Module is a package that contains a Windows PowerShell Module. For information on writing a Windows PowerShell Module, see Writing a Windows PowerShell Module. An Integration Module can contain any of the valid Module Types specified in Windows PowerShell Modules. This includes Script Modules (.psm1), Binary Modules (.dll), and Manifest Modules.

The Integration Module package is a compressed file with the same name as the module and a .zip extension. It contains a single folder also with the name of the module. The Windows PowerShell module and any supporting files, including a manifest file (.psd1) if the module has one, must be contained in this folder.

If the module should contain a Connection type, it must also contain a file with the name <ModuleName>-Automation.json that specifies the connection type properties. This is a json file with the following format.

{ 
   "ConnectionFields": [
   {
      "IsEncrypted":  false,
      "IsOptional":  false,
      "Name":  "ComputerName",
      "TypeName":  "System.String"
   },
   {
      "IsEncrypted":  false,
      "IsOptional":  true,
      "Name":  "Username",
      "TypeName":  "System.String"
   },
   {
      "IsEncrypted":  true,
      "IsOptional":  false,
      "Name":  "Password",
   "TypeName":  "System.String"
   }],
   "ConnectionTypeName""DataProtectionManager",
   "IntegrationModuleName""DataProtectionManager"
}

 

Folder Files

MyModule

MyModule.psd1 or

MyModule.psm1 or

MyModule.dll

MyModule-Automation.json

A module is a compressed file with a .zip extension that contains a folder which includes one of the following file types:

  • A module (psm1 file)

  • A module manifest (psd1 file)

  1. Select the Automation workspace.

  2. At the bottom of the window, click Import Module.

  3. Click Browse for File.

  4. Select the module file and click OK.

  5. Click the checkmark button on the dialog box.

  • The following sample commands show how to import a module.

    $webServer = 'https://MyWebServer'
    $port = 9090
    $modulePath = 'C:\Modules\MyModule.psm1'
    Import-SmaModule –WebServiceEndpoint $webServer –Port $port –Path $modulePath
    

  1. Select the Automation workspace.

  2. If you are using Azure, then select an Automation account.

  3. At the top of the window, click Assets.

  4. Locate the module and select it.

  5. Scroll to the bottom of the Module Details screen and inspect its activities.

  6. Optionally, click the magnifying glass icon to filter for particular activities.

  1. The following sample commands show how to retrieve the activities in a particular module.

    $webServer = 'https://MyWebServer'
    $port = 9090
    $moduleName = 'MyModule'
    $module = Get-SmaModule –WebServiceEndpoint $webServer –Port $port –Name $moduleName
    $module.Activities
    

  • The following sample commands show how to retrieve the activities in all modules installed in Automation.

    $webServer = 'https://MyWebServer'
    $port = 9090
    $modules = Get-SmaModule –WebServiceEndpoint $webServer –Port $port
    $modules | foreach {$_.Activities} | sort Name,ModuleName | ft Name,ModuleName,Description
    

See Also

 
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft