Product documentation Docs
    • English
    • Deutsch
    • 日本語
    • 한국어
    • Français
  • More Sites
    • Now Community
    • Developer Site
    • Knowledge Base
    • Product Information
    • ServiceNow.com
    • Training
    • Customer Success Center
    • ServiceNow Support Videos
  • Log in

Product documentation

  • Home
How search works:
  • Punctuation and capital letters are ignored
  • Special characters like underscores (_) are removed
  • Known synonyms are applied
  • The most relevant topics (based on weighting and matching to search terms) are listed first in search results
Topics are ranked in search results by how closely they match your search terms
  • A match on the entire phrase you typed
  • A match on part of the phrase you typed
  • A match on ALL of the terms in the phrase you typed
  • A match on ANY of the terms in the phrase you typed

Note: Matches in titles are always highly ranked.

  • Release version
    Table of Contents
    • Now Platform capabilities
Table of Contents
Choose your release version
    Home Orlando Now Platform Capabilities Now Platform capabilities Flow Designer Action Designer PowerShell step

    PowerShell step

    • Save as PDF Selected topic Topic & subtopics All topics in contents
    • Unsubscribe Log in to subscribe to topics and get notified when content changes.
    • Share this page

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

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

    Roles and availability

    • Available as an Action Designer 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.
    • 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 don't need to update your custom action.

    To learn more about connections and credentials, see 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 pane.
    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 pane.
    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 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.
    Note: This field is only visible when the Connection is Define Connection Inline.
    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.
    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

    Tags:

    Feedback
    On this page

    Previous topic

    Next topic

    • Contact Us
    • Careers
    • Terms of Use
    • Privacy Statement
    • Sitemap
    • © ServiceNow. All rights reserved.

    Release version
    Choose your release version

      PowerShell step

      • Save as PDF Selected topic Topic & subtopics All topics in contents
      • Unsubscribe Log in to subscribe to topics and get notified when content changes.
      • Share this page

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

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

      Roles and availability

      • Available as an Action Designer 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.
      • 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 don't need to update your custom action.

      To learn more about connections and credentials, see 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 pane.
      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 pane.
      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 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.
      Note: This field is only visible when the Connection is Define Connection Inline.
      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.
      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

      Tags:

      Feedback

          Share this page

          Got it! Feel free to add a comment
          To share your product suggestions, visit the Idea Portal.
          Please let us know how to improve this content

          Check any that apply

          To share your product suggestions, visit the Idea Portal.
          Confirm

          We were unable to find "Coaching" in Jakarta. Would you like to search instead?

          No Yes
          • Contact Us
          • Careers
          • Terms of Use
          • Privacy Statement
          • Sitemap
          • © ServiceNow. All rights reserved.

          Subscribe Subscribed Unsubscribe Last updated: Tags: January February March April May June July August September October November December No Results Found Versions Search preferences successfully updated My release version successfully updated My release version successfully deleted An error has occurred. Please try again later. You have been unsubscribed from all topics. You are now subscribed to and will receive notifications if any changes are made to this page. You have been unsubscribed from this content Thank you for your feedback. Form temporarily unavailable. Please try again or contact  docfeedback@servicenow.com  to submit your comments. The topic you requested does not exist in the release. You were redirected to a related topic instead. The available release versions for this topic are listed There is no specific version for this documentation. Explore products Click to go to the page. Release notes and upgrades Click to open the dropdown menu. Delete Remove No selected version Reset This field is required You are already subscribed to this topic Attach screenshot The file you uploaded exceeds the allowed file size of 20MB. Please try again with a smaller file. Please complete the reCAPTCHA step to attach a screenshot
          Log in to personalize your search results and subscribe to topics
          No, thanks Login