PowerShell probe

  • Release version: Zurich
  • Updated July 31, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of PowerShell probe

    The PowerShell Probe enables ServiceNow customers to execute PowerShell V2 scripts directly on the MID Server host. It is implemented as a probe of typeProbeby specifyingPowerShellas the ECC queue topic. This capability allows automation and custom scripting on Windows hosts managed through ServiceNow.

    Show full answer Show less

    Key Features

    • Script execution: You define PowerShell scripts as parameters, specifying the script filename to run on the MID Server.
    • Parameter passing: Supports passing parameters to scripts either as environment variables or via command line, with automatic environment variable availability for all parameters.
    • Secure parameters: Differentiates between encrypted and non-encrypted script parameters using distinct prefixes powershell (encrypted) and powershellparam (unencrypted).
    • Debug options: Enables debug logging and credential troubleshooting output to assist with probe execution issues.

    Using Parameters

    Key parameters include:

    • source: Required. Specifies the initial host to connect to.
    • <script name>.ps1: Required. The PowerShell script filename to execute.
    • powershellcommandparameterpassing: Controls command line parameter passing; environment variables are always available to scripts.
    • powershellparam<param name> and powershell<param name>: Pass additional parameters to scripts as environment variables with prefix $env:SNC. Choose the correct prefix to avoid execution errors.
    • debug and credentialsdebug: Enable detailed logging and credential troubleshooting output.

    Scripting Requirements

    Custom PowerShell scripts must be adapted to receive non-Boolean parameters via environment variables. This involves redefining script parameters by checking for corresponding environment variables with the prefix SNC. Non-Boolean command line parameters in the Param() block should be replaced by variables assigned from these environment variables. Boolean parameters remain in the Param() block as is.

    For example, a script originally defined as:

    Param([string]$computer, [string]$user, [boolean]$debug)

    Should be rewritten to:

    Param([boolean]$debug)if (test-path env:\SNCcomputer) { $computer = $env:SNCcomputer }if (test-path env:\SNCuser) { $user = $env:SNCuser }

    Creating Custom PowerShell Probes

    ServiceNow customers can create and configure their own PowerShell probes by defining the appropriate probe parameters and supplying custom PowerShell scripts that comply with the environment variable parameter passing conventions. This allows tailored automation workflows executed on MID Server hosts.

    The PowerShell Probe executes PowerShell V2 scripts on the MID Server host.

    PowerShell scripts are defined as probe parameters with the filename as the parameter name. It is available as a Probe probe type by specifying PowerShell as the probe's ECC queue topic.

    PowerShell probe parameters

    Parameter name Description
    source [Required] The initial host to connect to.

    Default: None

    <script name>.ps1

    		 [Required] The filename of the PowerShell script to run. Replace <script name> with a valid filename prefix.

    Default: None

    powershell_command_parameter_passing

    Specifies whether to pass script parameters on the command line. Regardless of this parameter's value, ServiceNow makes all script parameters on the command line automatically available to PowerShell scripts as environment variables.

    Default: false
    powershell_param_<script parameter name> Passes additional parameters to the PowerShell script to be executed. Each parameter will appear to the script as an environment variable in the format $env:SNC_<script parameter name>. Parameters with this prefix are not considered encrypted and are passed through to the script untouched. Make sure you select the appropriate parameter between powershell_param_<script parameter name> and powershell_<script parameter name>. Using the wrong prefix results in errors in the PowerShell execution, which is passed back to the instance in the ECC queue input.

    Default: None

    powershell_<script parameter name>

    		 Passes additional parameters to the PowerShell script to be executed. Each parameter will appear to the script as an environment variable in the format $env:SNC_<script parameter name>. The MID Server assumes that any parameter with this prefix is encrypted and attempts to decrypt it. Make sure you select the appropriate parameter between powershell_param_<script parameter name> and powershell_<script parameter name>. Using the wrong prefix results in errors in the PowerShell execution, which is passed back to the instance in the ECC queue input

    Default: None
    debug Enables debug log output during the probe.

    Default: false
    credentials_debug Displays a <credentials_debug> section in the ECC queue, which can help you troubleshoot credentials. If you set this property to true, credential troubleshooting information is output to the ECC queue, even if the credentials succeed.

    Default: false

    Scripting requirements

    Any custom PowerShell scripts must use environment variables to pass any non-Boolean command line parameter. Replace non-Boolean parameters in the Param() portion of the script with script variables of the same name. Define the script variable as part of the environment with an SNC_ prefix. So a string parameter such as this:

    Param([string]$paramName)

    Becomes a script variable such as the following:

    if(test-path env:\SNC_paramName) {
    $paramName = $env:SNC_paramName
}

    For example, this parameter definition from the PSScript.ps1 script contains several string parameters that need to be redefined as script variables:

    Param([string]$computer, [string]$script, [string]$user, [string]$password, [boolean]$useCred, [boolean]$isDiscovery, [boolean]$debug)

    Defining the non-Boolean parameters as script variables would result in this type of script:

    Param([boolean]$useCred, [boolean]$isDiscovery, [boolean]$debug)
 
# Copy the environment variables to the params
if(test-path env:\SNC_computer) {
  $computer=$env:SNC_computer
}
 
if(test-path env:\SNC_script) {
  $script=$env:SNC_script
}
 
if(test-path env:\SNC_user) {
  $user=$env:SNC_user
  $password=$env:SNC_password
}