PowerShell step
Run PowerShell scripts on remote machines from your ServiceNow instance through a MID Server.
PowerShell is built on the Windows .NET Framework and is designed to control and automate the administration of Windows machines and applications. ServiceNow supports PowerShell 3.0 to 7.4. PowerShell 3.0 does not support Windows 2003 Server.
PowerShell version
Roles and availability
Available as an Workflow Studio action step. Users with the action_designer role can create a custom action with one or more action steps.
Fields
| Field | Description |
|---|---|
| Connection | Type of connection to use.
To learn more about connections and credentials, see Introduction to credentials, connections, and aliases. |
| Connection Alias | Connection & Credential alias record that the system uses to run the action step. Users with the flow_designer or admin role can create or select an associated Connection record.
Using an alias eliminates the need to configure multiple credentials and connection information profiles when using an action in multiple environments. Likewise, if the connection information changes, you don't
need to update your custom action. To learn more about connections and credentials, see credentials, connections, and aliases.
The credential value is displayed as a Password (2 Way Encrypted) data pill on the data panel.
Note: This field is available when Use Connection Alias is selected from the Connection list. |
| Credential Alias | Credential alias that the system uses to run the action step. Users with the flow_designer or admin role can create or select an associated Connection record. Using an alias
eliminates the need to configure multiple credentials when using an action in multiple environments. Likewise, if the credential information changes, you don't need to update your custom action. To learn more
about connections and credentials, see credentials, connections, and aliases.
The credential value is displayed as a Password (2 Way Encrypted) data pill on the data panel.
Note: This field is available when Define Connection Inline is selected from the Connection list. |
| Host | Specify the fully-qualified domain name of the target host where the system runs the action step. For example, host.domain.com.
Note: This field is only visible when the Connection is Define Connection Inline. |
| Port | Specify the communications port on which the target host listens for connections. For example, 5985. Leave blank to use the default port. Note: This field is only visible when the Connection is Define Connection Inline. |
| MID Selection |
Option to select a specific MID Server or MID Cluster. Choose any one of the following options.
|
| MID Application | Specify the application the MID Server must support to be eligible for selection. The system runs the action step from a MID Server that supports the selected application. If you use a data pill for this field, the pill must reference the MID Application's name, not the MID Application record. This field is available when Define Connection Inline is selected from the Connection list and Auto-Select MID Server is selected from the MID Selection list. |
| Capabilities | Capabilities the MID Server must support to be eligible for selection. The system runs the action step from a MID Server that supports the selected capabilities. This field is available when Define Connection Inline is selected from the Connection list and Auto-Select MID Server is selected from the MID Selection list. |
| MID Server | Data pill containing a sys_id reference to a MID Server [ecc_agent_list] record. This field is available when Define Connection Inline is selected from the Connection list and Specific MID Server is selected from the MID Selection list. |
| MID Cluster | Data pill for the MID Cluster you want to use. This field is available when Define Connection Inline is selected from the Connection list, and Specific MID Cluster is selected from the MID Selection list. |
| Remoting Type | The location where the PowerShell script runs such as the MID or a remote server.
Note: To invoke a function in a PowerShell script command or PowerShell script file, the command must define the function param block if the function has input parameters. This requirement applies
to explicit and implicit remoting. For additional information on param block, see Microsoft's documentation on Windows Powershell parameters at https://technet.microsoft.com/. |
| Remote name prefix | The file path, excluding file names, to the modules to load from the remote server. Note: This field is only visible when the Remoting Type is Implicit Remoting
(Advanced). |
| Modules to import | The comma-separated list of modules to import from the remote server at the defined file path. Note: This field is only visible when the Remoting Type is Explicit Remoting
(Most Common) or Implicit Remoting (Advanced). |
| Test PowerShell Step | Button to test the configured credential for the PowerShell step. For more information, see Test a credential for the PowerShell step. |
| Script type | The type of script to run on the PowerShell host.
|
| MID Server Script | Pre-defined PowerShell script from the MID Server Script Files table [ecc_agent_script_file]. Note: This field is only available if the Script type is MID Server Script File. |
| Script path | Read-only path to the selected MID Server script. Note: This field is only visible when the Script type is MID Server Script File. |
| Input variables | The optional name-value pairs that represent the values of PowerShell script variables. You can use action inputs and data from other steps within the PowerShell script. Define the following fields for each
variable:
|
| Command | The inline PowerShell script to run on the target host. Note: This field is only visible when the Script type is Inline script. |
Action error evaluation
- If this step fails
- Data type: Choice
Option to continue running the next step or go to error evaluation. To use the step status code or message for a custom action error condition, see Action error evaluation.
PowerShell scripting variables
To access input variables from the Command field, you must call them using special syntax. The syntax you use depends on the value of a system property. If the Remoting Type is Run on a MID Server or have your script establish a remote session, some reserved variables are available in addition to input variables.
- Input variable syntax
By default, prefix variable names with a $ character. For example, if an input variable is named message, use $message to access the variable in script.
If the mid.powershell.command.script.parameter_passing parameter is set to false, prefix the variable name with $env:SNC_. For example, if an input variable is named message, use $env:SNC_message to access the variable in script. To learn more about the mid.powershell.command.script.parameter_passing parameter, see MID Server parameters.
- Reserved variables
When the Remoting Type is Run on a MID Server or have your script establish a remote session, the following variables are available for use in script. Reserved variables cannot be used as custom input variable names.
Reserved variable Description $computer Host IP address defined in the Connection alias record. $cred Credential object that contains the credentials defined in the connection record. Use this variable with any PowerShell cmdlet that supports the credential parameter. For example, New-PSSession -credential $cred.$log_info If the mid.property.powershell.log_info property is set to true, adds logging information to a PowerShell script. The following variable names are reserved for internal processing and should not be used as input variables.
- script
- useCred
- isMid
- isDiscovery
- debug
- user
- password
- executingScriptDirectory
- midScriptDirectory
- hresult