Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.

PowerShell step

Log in to subscribe to topics and get notified when content changes.

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 2.0 and above. PowerShell 3.0 does not support Windows 2003 Server.

Note: PowerShell step is not available in the base system and requires a separate IntegrationHub subscription. After the IntegrationHub plugin is activated, the step is visible under Integrations.

Roles and availability

  • Available as an Action Designer action step. Subject matter experts use the action_designer role to create a custom action with one or more action steps.

Fields

Field Description
Connection Type of connection to use.
  • Define Connection Inline: Define connection information within the action step.
  • Use Connection Alias: Define connection information using the Connection Alias table. 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 do not have to update your custom action.

To learn more about connections and credentials, see credentials, connections, and aliases.

Connection Alias Specify the Connection & Credential alias record the system uses to run the action step. Requires a flow designer or admin to 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 do not have to update your custom action. To learn more about connections and credentials, see credentials, connections, and aliases. Outputs the credential value to the data pane as a Password (2 Way Encrypted) data pill.
Note: This field is only visible when the Connection is Use Connection Alias.
Credential Alias Specify the credential alias the system uses to run the action step. Requires a flow designer or admin to create or select an associated Credential 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 do not have to update your custom action. To learn more about connections and credentials, see credentials, connections, and aliases. Outputs the credential value to the data pane as a Password (2 Way Encrypted) data pill.
Note: This field is only visible when the Connection is Define Connection Inline.
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 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.
Note: This field is only visible when the Connection is Define Connection Inline.
Capabilities Specify the 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.
Note: This field is only visible when the Connection is Define Connection Inline.
Remoting Type The location where the PowerShell script runs such as the MID or a remote server.
  • Explicit Remoting (Most Common): Establish a connection with and run the script on a remote server.
  • Implicit Remoting (Advanced): Run a script on a MID Server while importing necessary modules from a remote server. If selected, define the Remote name prefix and Modules to import fields. For optimal performance, only import modules necessary to the step. If blank, all available modules are imported from the server.
  • Run on a MID Server or have your script establish a remote session: Run a script directly on a MID Server, or define remoting specifications within the script. This value is the default.
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).
Script type The type of script to run on the PowerShell host.
  • Inline script: Enter the script to run in the Command field of the step.
  • MID Server Script File: Select the PowerShell script to run from the MID Server Script Files [ecc_agent_script_file] table. This is the default value and separates scripting logic from the action, enabling you to update the script without having to modify and redeploy the action.
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:
  • Name: The name of the script variable to pass a value to. The name cannot match a reserved or prohibited PowerShell variable. Some variable names are reserved for internal processing and should not be used as input variables. See Reserved variables in PowerShell scripting variables.
  • Type: The type of PowerShell variable. Select plain text, encrypted, or boolean. If encrypted is selected, the value appears in plain text in this field and is only encrypted when it passes to the ECC Queue.
  • Value: The value to map to the variable. Manually enter a value, or drag a data pill into the field.
Command The inline PowerShell script to run on the target host.
Note: This field is only visible when the Script type is Inline script.

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
Feedback