MID Server PowerShell files

  • Release version: Xanadu
  • Updated August 1, 2024
  • 4 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 MID Server PowerShell files

    PowerShell functions for the MID Server are organized in script files (.ps1) and PowerShell Script module files (.psm1). These scripts support various ServiceNow orchestration activity packs, including Active Directory, Exchange, and SCCM. The key script,PSScript.ps1, handles credential testing, password encryption, and executing configured PowerShell scripts or commands on target hosts.

    Show full answer Show less

    PowerShell Credential Handling

    The MID Server uses different credential types (credType) to test access to remote hosts. These include WMI, Exchange, Active Directory (AD), and SCCM credentials. If no credential type is specified, WMI is used by default. The credential testing occurs through specific functions defined in the credentials.psm1 module, which attempts to authenticate using each credential stored in the MID Server’s credentials table before falling back to the MID Server service account if all tests fail.

    • testCredentialWMI: Uses Get-WMIObject for general credential testing.
    • testCredentialAD: Uses DirectoryEntry for Active Directory testing.
    • testCredentialExchange: Uses PowerShell remoting with WinRM for Exchange servers.
    • testCredentialSCCM: Uses PowerShell remoting with WinRM for SCCM servers.

    When the target host is the MID Server itself, the MID Server service account is used directly, bypassing credential table checks.

    Key MID Server PowerShell Modules

    • PSScript.ps1: Orchestrates credential testing and script execution, using credentials.psm1 for access validation.
    • credentials.psm1: Contains functions to test various credential types on target hosts.
    • DiagnosticsUtil.psm1: Provides logging utilities to assist debugging PowerShell orchestration activities, including functions to log debug messages, function parameters, and obfuscate sensitive values.
    • ActiveDirectory.psm1, Exchange.psm1, SCCM.psm1: Contain activity pack-specific PowerShell functions tailored for those environments.

    Exit Codes and Diagnostics

    PSScript.ps1 returns specific exit codes that are logged on the MID Server for monitoring script execution status:

    • 0: Successful execution of PowerShell command/script.
    • 1: Test succeeded but script failed to execute.
    • 2: Syntax error in script command.
    • 3: All credentials, including the MID Server service account, failed.
    • 4: Execution succeeded but returned an error (e.g., user not found).

    The DiagnosticsUtil.psm1 module enhances troubleshooting by enabling detailed logging of debug information and parameter values, while securing sensitive data through obfuscation.

    Practical Impact for ServiceNow Customers

    This PowerShell scripting framework within the MID Server enables secure, credential-aware remote execution of orchestration activities across different systems such as Active Directory, Exchange, and SCCM. Customers can expect streamlined credential management, detailed logging for debugging, and reliable execution with clear exit codes for error handling. Understanding how the MID Server selects credentials and leverages these PowerShell modules helps in configuring and troubleshooting orchestration workflows effectively.

    PowerShell functions are stored in script files (*.ps1) that use a PowerShell Script module (*.psm1) file name extension.

    The PowerShell functions are used by the PowerShell MID Server script files included in these activity packs:
    • Active Directory
    • Exchange
    • SCCM
    • PowerShell

    PSScript.ps1

    This script performs a few tasks, such as credential testing, password encryption, and the execution of scripts configured in the Orchestration Activity Designer or in MID Script Files. However, this document focuses on how PSScript.ps1 uses the credential.psm1 module for testing access to remote hosts.

    The PowerShell variables are generally used directly in the PowerShell execution command or as arguments in the MID Server script file you specify. There are special variables that are passed to PSScript.ps1, such as credType.
    Figure 1. Using credType in execution parameters
    Using credType in execution parameters

    PowerShell credTypes

    The PowerShell credential types:

    Type Description
    WMI testCredentialWMI
    Exchange testCredentilExchange
    AD testCredentilAD
    SCCM testCredentilSCCM

    If no credential type is passed to the PSScrip.ps1 script, the MID Server defaults to the WMI test function to test access to the target host. If there is a credential type used, the MID Server runs the corresponding test function for that credential type.

    Exit codes

    These exit codes are returned from the PSScript.ps1 script and logged in the MID Server log file.

    Table 1. PSScript.ps1 exit codes
    Type Test function
    0 PowerShell command/script ran successfully.
    1 Test finished successfully, but the command/script failed to execute.
    2 Incorrect syntax passed to script.
    3 All credentials including MID Server service account failed to execute the command/script.
    4 Passed test and executed the activity, but an error was returned. Example user cannot be found.

    DiagnosticsUtil.psm1

    The MID Server uses this module file to perform PowerShell logging that assists debugging any Orchestration activity using PowerShell scripting. You can also add debugging statements directly to custom scripts.
    Table 2. PowerShell diagnostic utilities
    Utility Description
    SNCLog-DebugInfo Log a debug message for a PowerShell script or PowerShell Orchestration activity. Examples:
    • SNCLog-DebugInfo -message "My debug message..."
    • SNCLog-DebugInfo "My debug message"
    SNCLog-ParameterInfo Log a function parameter value. For "function getHostName{ param( [String] $target )", the first value to the PowerShell hashtable is a string to indicate which function executes, and the values for each of the function parameters. Examples:
    • Function with single parameter: SNCLog-ParameterInfo @("Running getHostName", $target)
      Note:
      The debug message shows, 'Running getHostName $target:[actual value of $target]'.
    • Function with multiple parameters: SNCLog-ParameterInfo @("Running functionName", $param1, $param2, $param3)
    SNCObfuscate-Value Use this utility to encrypt values for security purposes. The function displays "$variableName":***, where *** is the obfuscated value. Example:
    SNCObfuscate-Value $password
    Note:
    The debug message reads: "$password : ***".

    Credentials.psm1

    The MID Server uses this module file to test access to a target host. The MID Server loops through all Windows credentials stored in its credentials table using the following access type functions, unless the PowerShell activity has a credential type (credType) defined. All ServiceNow® authored PowerShell activities are hard-coded to use a specific credential type. As a result, the MID Server only tests credential access against the designated function.
    Table 3. PowerShell test functions
    Function Description
    testCredentialWMI Tests the given user and password on the target host using the Get-WMI object.
    testCredentilAD Tests the given user and password on the target host using the built-in DirectoryEntry object.
    testCredentialExchange Tests the given user and password to create a session on an Exchange host. This test uses the built-in PowerShell remoting feature on a remote host. WinRM is configured on Exchange servers by default.
    testCredentialSCCM Tests the given user and password to create a session on an SCCM server. This test uses the built-in PowerShell remoting feature on a remote host. This test requires WinRM to be configured.
    testNoCredentialAccessWMI Tests the given user and password on the target host, using the Get-WMI object. This test is used when no credType is used.
    Note:
    If the test passes using one of these functions, that credential is used to run the PowerShell script/command. If the tests fail to access the target host using these functions, the MID Server runs the PowerShell script/command under the account of the MID Server service.

    This diagram illustrates the dependency of the credential selection behavior on the host being targeted by the PowerShell activity. If the target host is the IP address or host name of the MID Server, the MID Server bypasses all credentials in the Credentials table and uses the account of the MID Server service. If the target host is not the MID Server, then all Windows credentials are used first. If all credentials in the Credentials table are unsuccessful in running the PowerShell activity, then the MID Server uses the MID Server service account.

    Figure 2. PowerShell credential selection criteria
    PowerShell credential selection criteria

    ActiveDirectory.psm1

    This module file stores the functions used by the PowerShell scripts shipped with the Active Directory activity pack.

    Exchange.psm1

    This module file stores the functions used by the PowerShell scripts shipped with the Exchange activity pack.

    SCCM.psm1

    This module file stores the functions used by the PowerShell scripts shipped with the SCCM activity pack.