Export (0) Print
Expand All

Global Assets

Updated: October 27, 2014

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

Global Assets are available to all runbooks in an Automation environment. You create and configure them using either the Automation workspace in the management portal or with the appropriate cmdlets in Windows PowerShell. From a runbook, you can retrieve and set values for global assets with activities in the RunbookConstructs module. The Windows PowerShell cmdlets are available to use in runbooks in Service Management Automation, but the activities are recommended as they are more efficient.

An Automation Credential is either a username and password that can be used with Windows PowerShell commands or a certificate that is uploaded to the server. The properties for a credential are stored securely in the Automation database and can be accessed in the runbook with either the Get-AutomationPSCredential or Get-AutomationCertificate activity.

The cmdlets in the following table are used to create and manage credentials with Windows PowerShell in Service Management Automation.

 

Cmdlets Description

Get-SmaCertificate

Retrieves an Automation certificate.

Get-SmaCredential

Retrieves an Automation PowerShell credential.

Remove-SmaCertificate

Removes an Automation certificate.

Remove-SmaCredential

Removes an Automation PowerShell credental.

Set-SmaCertificate

Creates a new certificate or sets the properties for an existing certificate including uploading the certificate file and setting the password for a .pfx.

Set-SmaCredential

Creates a new Automation PowerShell credential or sets the properties for an existing credential.

The activities in the following table are used to access credentials in a runbook.

 

Activities Description

Get-AutomationCertificate

Gets a certificate to use in a runbook.

Get-AutomationPSCredential

Gets a username/password to use in a runbook.

noteNote
You should avoid using variables in the –Name parameter of Get-AutomationPSCredential and Get-AutomationCertificate since this can complicate discovering dependencies between runbooks and Automation variables.

  1. Select the Automation workspace.

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

  3. At the bottom of the window, click Add Setting.

  4. Click Add Credential.

  5. In the Credential Type dropdown, select PowerShell Credential.

  6. Type a name for the credential in the Name box.

  7. Click the right arrow.

  8. Type in values for each property.

  9. Click the check mark to save the credential.

  1. Select the Automation workspace.

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

  3. At the bottom of the window, click Add Setting.

  4. Click Add Credential.

  5. In the Credential Type dropdown, select Certificate.

  6. Type a name for the certificate in the Name box.

  7. Click the right arrow.

  8. Click Browse for File and navigate to either a .cer or .pfx file.

  9. If you selected a .pfx file, then provide its password.

  10. Click the check mark to save the certificate.

  • The following sample commands show how to create a new credential.

    $webServer = 'https://MyWebServer'
    $port = 9090
    $credName = 'MyCredential'
    $user = 'contoso\MyUser'
    $pwd = ConvertTo-SecureString -String 'P@$$w0rd' -AsPlainText -Force
    $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $user,$pwd
    Set-SmaCredential -WebServiceEndpoint $webServer -port $port -Name $credName -Value $cred
    

  • The following sample commands show how to create a new certificate by importing a certificate file.

    $webServer = 'https://MyWebServer'
    $port = 9090
    $certName = 'MyCertificate'
    $path = 'c:\certs\MyCertificate.pfx'
    $certPwd = ConvertTo-SecureString -String 'P@$$w0rd' -AsPlainText -Force
    Set-SmaCertificate -WebServiceEndpoint $webServer -port $port -Name $certName –Path $certPath –Password $certPwd
    

You retrieve a PowerShell Credential in a runbook with the Get-AutomationPSCredential activity. This returns a PSCredential object that you can use in the workflow.

  • The following sample commands show how to use a PowerShell credential in a runbook. In this example, the credential is used with an InlineScript activity to run a set of commands using alternate credentials.

    $myCredential = Get-AutomationPSCredential -Name 'MyCredential'
    InlineScript {
       <Commands>
    } -PSComputerName $ServerName -PSCredential $SampleCredential
    

An Automation Connection contains the information required to connect to a service or application from a runbook. This information is defined in the module for the application and typically includes such information as the username and password and the computer to connect to. Other information may also be required such as a certificate or a subscription Id. The properties for a connection are stored securely in the Automation database and can be accessed in the runbook with the Get-AutomationConnection activity.

The cmdlets in the following table are used to create and manage credentials with Windows PowerShell in Service Management Automation.

 

Cmdlets Description

Get-SmaConnection

Retrieves the values for each field in a particular connection.

Get-SmaConnectionField

Retrieves the field definitions for a particular connection type.

Get-SmaConnectionType

Retrieves the available connection types.

New-SmaConnection

Creates a new connection.

Remove-SmaConnection

Remove an existing connection.

Set-SmaConnectionFieldValue

Sets the value of a particular field for an existing connection.

The activities in the following table are used to access credentials in a runbook.

 

Activities Description

Get-AutomationConnection

Gets a connection to use in a runbook.

  1. Select the Automation workspace.

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

  3. At the bottom of the window, click Add Setting.

  4. Click Add Connection.

  5. In the Connection Type dropdown, select a connection type.

  6. Type a name for the connection in the Name box.

  7. Click the right arrow.

  8. Type in a value for each property.

  9. Click the check mark to save the connection.

  • The following sample commands create a new Virtual Machine Manager connection with the name MyVMMConnection. Note that we use a hashtable to define the properties of the connection. This is because different types of connections require different sets of properties. A connection of another type would use a different set of field values.

    For more information about hash tables, see about_Hash_Tables.

    $webServer = 'https://MyWebServer'
    $port = 9090
    $connectionName = 'MyConnection'
    $fieldValues = @{"Username"="MyUser";"Password"="password";"ComputerName"="MyComputer"} 
    New-SmaConnection –WebServiceEndpoint $webServer –port $port –Name $connectionName –ConnectionTypeName "VirtualMachineManager" –ConnectionFieldValues $fieldValues
    

Use the Get-AutomationConnection activity to use a connection in a runbook. This activity retrieves the values of the different fields in the connection and returns them as a hashtable which can then be used with the appropriate commands in the runbook.

For more information about hash tables, see about_Hash_Tables.

  • The following sample code shows how to use a connection to provide the computer name and credentials for an InlineScript block that runs commands on another computer.

    $con = Get-AutomationConnection -Name 'MyConnection'
    $securepassword = ConvertTo-SecureString -AsPlainText -String $con.Password -Force
    $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $con.Username, $securepassword
    InlineScript {
       <Commands>
    } -PSComputerName $con.ComputerName -PSCredential $cred
    

Automation variables are values that are available to all runbooks. They can be created, modified, and retrieved from the management portal, Windows PowerShell, or from within a runbook. Automation variables are useful for the following scenarios:

  • Share a value between multiple runbooks.

  • Share a value between multiple jobs from the same runbook.

  • Manage a value from the management portal or from the Windows PowerShell command line that is used by runbooks.

Automation Variables are persisted so that they continue to be available even if the runbook fails. This also allows a value to be set by one runbook that is then used by another, or is used by the same runbook the next time that it is run.

When a variable is created, you must specify its data type from the following list. You can only assign a value of the correct type to a variable.

  • String

  • Integer

  • Boolean

  • Datetime

When a variable is created, you can specify that it be stored encrypted. When a variable is encrypted, it is stored securely in the SMA database, and its value cannot be retrieved from the Get-SmaVariable cmdlet. The only way that the value can retrieved is from the Get-AutomationVariable activity in a runbook. You can store multiple values of the defined type to a single variable by creating a hashtable.

The cmdlets in the following table are used to create and manage variables with Windows PowerShell in Service Management Automation.

 

Cmdlets Description

Get-SmaVariable

Retrieves the value of an existing variable.

Set-SmaVariable

Creates a new variable or sets the value for an existing variable.

The activities in the following table are used to access credentials in a runbook.

 

Activities Description

Get-AutomationVariable

Retrieves the value of an existing variable.

Set-AutomationVariable

Sets the value for an existing variable.

noteNote
You should avoid using variables in the –Name parameter of Get-AutomationVariable since this can complicate discovering dependencies between runbooks and Automation variables.

  1. Select the Automation workspace.

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

  3. At the bottom of the window, click Add Variable.

  4. Click Add Variable.

  5. In the Type dropdown, select a data type.

  6. Type a name for the variable in the Name box.

  7. Click the right arrow.

  8. Type in a value for each property.

  9. Click the check mark to save the variable.

  • The Set-SmaVariable cmdlet both creates a new variable and sets the value for an existing variable. The following sample commands show how to create a variable of type string.

    $web = 'https://MySMAServer'
    $port = 9090
    Set-SMAVariable –WebServiceEndpoint $web –Port $port –Name 'MyVariable' –Value 'My String'
    

Use the Get-AutomationVariable activity to use a variable in a runbook.

  • The following sample code shows how to set and retrieve a variable in a runbook. In this sample, it is assumed that variables of type integer named NumberOfIterations and NumberOfRunnings and a variable of type string named SampleMessage have already been created.

    [int] $NumberOfIterations = Get-AutomationVariable -Name 'NumberOfIterations'
    [int] $NumberOfRunnings = Get-AutomationVariable -Name 'NumberOfRunnings'
    [string] $SampleMessage = Get-AutomationVariable -Name 'SampleMessage'
    Write-Output "Runbook has been run $NumberOfRunnings times."
    for ($i = 1; $i -le $NumberOfIterations; $i++) {
       Write-Output "$i`: $SampleMessage"
    }
    Set-AutomationVariable –Name NumberOfRunnings –Value (NumberOfRunngs += 1)
    

Automation Schedules are used to schedule runbooks to run automatically. This could be either a single date and time for the runbook to run once. Or it could be a recurring schedule to start the runbook multiple times. Schedules are typically not accessed from runbooks.

The cmdlets in the following table are used to create and manage variables with Windows PowerShell in Service Management Automation.

 

Cmdlets Description

Get-SmaSchedule

Retrieves a schedule.

Set-SmaSchedule

Creates a new schedule or sets the properties for an existing schedule.

  1. Select the Automation workspace.

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

  3. At the bottom of the window, click Add Setting.

  4. Click Add Schedule.

  5. Type a name for the variable in the Name box.

  6. Click the right arrow.

  7. Select One Time or Daily.

  8. Select a Start Time.

  9. For a Daily schedule, perform the following steps:

    1. If the schedule should not run indefinitely, select Schedule Expires On and specify an expiration date and time.

    2. In the Recur Every box, select the number of days the schedule should recur.

  10. Click the check mark to save the variable.

The Set-SmaSchedule cmdlet both creates a new schedule and sets the value for an existing variable. The following sample Windows PowerShell commands create a new schedule called My Daily Schedule that starts on the current day and continues for one year every day at noon:

$web = 'https://MySMAServer'
$port = 9090
$scheduleName = 'My Daily Schedule'
$startTime = (Get-Date).Date.AddHours(12)
$expiryTime = $startTime.AddYears(1)
Set-SmaSchedule –WebServiceEndpoint $web –Port $port –Name $scheduleName –ScheduleType OneTimeSchedule –StartTime $startTime –ExpiryTime $expiryTime –DayInterval 1

See Also

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