Orchestration PowerShell Activities

From ServiceNow Wiki
Jump to: navigation, search
Discovery
Orchestration
Related Topics
Get the Book
Knowledge.gif Discovery
Knowledge.gif Data Collected by Discovery
Knowledge.gif Orchestration for VMWare

1 Overview

PowerShell is built on the Windows .NET Framework and is designed to control and automate the administration of Windows machines and applications. PowerShell must be installed on any MID Server that uses these activities. MID Servers using PowerShell must be installed on a supported Windows operating system. ServiceNow supports PowerShell 2.0 and 3.0.

The ServiceNow Orchestration plugin adds these PowerShell activities to Workflows.


2 Change Service State

The Change Service State activity starts or stops a Windows service on a remote system.

2.1 Input Variables

Field Description
Hostname Hostname or IP address of the target Windows machine on which the service is installed. Use the Resolve DNS activity to resolve hostnames into IP addresses.
Service Name of the Windows Service to start or stop. The service parameter is the service name, not the display name of the service affected.
State There are two actions to select for a service state change: Start or Stop.

3 Install Windows App

The Install Windows App activity installs an application, from an MSI package, on a Windows target machine. Observe the following setup requirements:

  • The WMI Windows Installer Provider must be installed on the target machine. See WMI Providers for a list of Windows operating systems that provide this by default.
  • The MID Server, the target machine, and the installer source machine must be on the same Active Directory domain or, if these computers are on separate domains, those domains must have a trust relationship established between them.
  • If the installer path is a UNC file sharing machine, the Active Directory account of the target computer must be trusted for delegation. For instructions on this configuration, see the posting on the community for installing and uninstalling Windows applications.

To enable the WMI Windows Installer Provider:

  1. Open the Control Panel.
  2. Go to Add or Remove Programs.
  3. Select Add/Remove Windows Components.
  4. Double-click Management and Monitoring Tools.
    This action opens a secondary window displaying additional selections.
  5. Select WMI Windows Installer Provider check box.
  6. Click OK to return to the Windows Components Wizard window.
  7. Click Next.
    You might be asked for the Windows installation CD to complete this process.

3.1 Result Values

The success or failure of the PowerShell commands used to install the application determines the result value of the Install Windows App activity. Possible result values are:

  • Success
  • Failure

3.2 Input Variables

Field Description
Hostname Hostname or IP address of the target Windows machine on which the service is installed. Use the Resolve DNS MID Server capability to resolve hostnames into IP addresses. In versions prior to October 2011 Preview 2, only the IP address is a valid value.
Installer Path Path to the installer. The installer can be on any machine that is visible to both the MID Server and the target machine (local drive, UNC path, mapped drive, etc.).
Installer Name of the installer file, such as winzip150.msi. The installer must be an MSI package.
Arguments The parameter that contains the command line arguments to the MSI package. These are name=value pairs, separated by a space. For example, the argument might appear as: INSTALLDIR=c:\myinstallfolder ADDDESKTOPICON=0. These arguments are dependent on the what the actual MSI being installed defines. If there are no arguments, leave the field empty.

3.3 States

The activity state tells the workflow engine what to do with the activity.

State Description
Executing The workflow engine knows to start the onExecute function of the activity.
Finished The activity finished running. See the result value for the outcome of the activity.
Cancelled This activity, or the workflow that contains this activty, was cancelled.

4 Run PowerShell

The Run PowerShell activity executes Windows PowerShell commands on a MID Server.

4.1 Result Values

The workflow designer can assign a result value using activity.result from within a script field of the activity. By default, the success or failure of the PowerShell commands used determines the result value of the Run PowerShell activity. Possible result values are:

  • Success
  • Failure

4.2 Scratchpad Entries

Information written to stdout by the executing script is captured and returned to the activity in the activity.output variable. This information can be parsed, processed, or saved (to a scratchpad variable, for example) for future processing in the activity’s sensor script.

An example would be to run the get-date command to get the MID Server’s current time. This sensor script saves the full output received, but we can process it to return and save only the time.


RBA_Powershell_Activity.png‎


Note
Note: This is an over-simplified example. In most cases, the script operates against some remote Windows computer. However, the principal is the same – whatever is written to stdout is returned in activity.output and available to process.


4.3 Input Variables

Field Description
Hostname IP address of the target Windows machine. This value is mapped to the $computer variable for use in commands (see the example in the Command field). A PowerShell credential variable called $cred that is based on information in the ServiceNow Credentials table will authenticate on the computer pointed to by Hostname.
Command Enter the PowerShell command to run. For example, to execute a simple WMI query against a remote machine pointed to by the hostname variable, the command is:
get-wmiobject <class> -computer $computer -credential $cred

If no credentials authenticate on the computer, the command runs in the context of the MID Server user.

You cannot run both a command and a script file. Specifying a command hides the Script file variable.

Sensor script The script to run using the results of the probe. The output from the probe is contained in a variable called output. Any error from the probe is contained in a variable called error.
Script file The MID Server script file to run. You cannot run both a script file and a command. Selecting a script file hides the Command variable.
PowerShell script variables Additional parameters, in JSON format, used by the specified script file.

4.4 States

The activity state tells the workflow engine what to do with the activity.

State Description
Executing The workflow engine knows to start the onExecute function of the activity.
Finished The activity finished running. See the result value for the outcome of the activity.
Cancelled This activity, or the workflow that contains this activty, was cancelled.

4.5 Example

Add workflow variables for the command line using the normal workflow variable syntax. In the example above, if the <class> was in a workflow input variable called myclass, the command would look like:

get-wmiobject ${workflow.inputs.myclass} -computer $computer credential $cred
Similarly if the variable is a scratchpad variable named myclass, the command would look like:
get-wmiobject ${workflow.scratchpad.myclass} -computer $computer credential $cred

5 Join Domain

The Join Domain activity joins a Windows computer to a domain. If the computer is already a member of a domain, this activity completes without modifying the computer.

Joining a domain requires a username and password. This user must have domain administration privileges or privileges to join a computer to the domain.

5.1 Result Values

  • Success: the computer joined the domain successfully.
  • Failure: the computer failed to join the domain, or the computer is already in a domain.

5.2 Input Variables

Field Description
Hostname Hostname or IP address of the Windows server that is joining the domain.
Domain Name of the domain to join.
Domain User The name of a user who has domain administration privileges or privileges to join a computer to the domain.
Domain User Password The password for the user who has domain administration privileges or privileges to join a computer to the domain.

6 Restart Windows Server

The Restart Windows Server activity restarts a Windows server using PowerShell.

6.1 Result Values

  • Success: the server restarted successfully.
  • Failure: the server failed to restart.

6.2 Input Variables

Field Description
Hostname Hostname or IP address of the Windows server to restart.

7 Uninstall Windows App

The Uninstall Windows App activity uninstalls an application from a Windows target machine. The only applications that can be uninstalled using this activity are those that were installed by a Windows Installer.

7.1 Result Values

The workflow designer can assign a result value using activity.result from within a script field of the activity. By default, the success or failure of the PowerShell commands used to uninstall the application determines the result value of this activity. Possible result values are:

  • Success
  • Failure

7.2 Input Variables

Field Description
Hostname Hostname or IP address of the Windows target machine on which to uninstall an application.
Product The name of the application to uninstall exactly as it appears in the Windows Add/Remove Programs list.

7.3 States

The activity state tells the workflow engine what to do with the activity.

State Description
Executing The workflow engine knows to start the onExecute function of the activity.
Finished The activity finished running. See the result value for the outcome of the activity.
Cancelled This activity, or the workflow that contains this activty, was cancelled.

8 Using HResult Codes

When a PowerShell script encounters an error, the Windows machine may return an HResult code as part of the error message. PowerShell activities can read and interpret this code (Dublin). Not all PowerShell errors include an HResult code. In the event of a failed PowerShell script, you can use the HResult code to move the workflow through a specific condition.

For example, when resetting an Active Directory password to a password that does not meet policy requirements, such as minimum length or complexity, the PowerShell script returns the HResult code -2146022651. To use this code, create an activity condition with the Condition value of activity.hresult = -2146022651. If the PowerShell script returns this code when the activity runs, the workflow transitions through this new condition.

Was this article helpful?
Yes, I found what I needed
No, I need more assistance