/servicenow-powershell

PowerShell module to automate ServiceNow service and asset management. This module can be used standalone, with Azure Automation, or Docker.

Primary LanguagePowerShellApache License 2.0Apache-2.0

ServiceNow

PowerShell Gallery Version PowerShell Gallery GitHub license

This PowerShell module provides a series of cmdlets for interacting with the ServiceNow REST API.

IMPORTANT: Neither this module nor its creator are in any way affiliated with ServiceNow.

Requirements

Requires PowerShell 5.1 or above.

Requires authorization in your ServiceNow tenant. Due to the custom nature of ServiceNow your organization may have REST access restricted. The following are some tips to ask for if you're having to go to your admin for access:

  • Out of the box tables should be accessible by granting the ITIL role.
  • Custom tables may require adjustments to the ACL.
  • The Web_Service_Admin role may also be an option.

Usage

The ServiceNow module should be installed from the PowerShell Gallery with Install-Module ServiceNow.

A docker image is also available with Microsoft's PowerShell base image and the ServiceNow module preinstalled. The following environment variables should be used:

  • SNOW_SERVER: the ServiceNow instance, eg. instance.service-now.com
  • SNOW_TOKEN: pre-generated oauth token. Provide this or SNOW_USER/SNOW_PASS.
  • SNOW_USER: username to connect to SNOW_SERVER
  • SNOW_PASS: password for SNOW_USER

When using the docker image, creating a new session is not required.

Creating a new session

Creating a new session will create a script scoped variable $ServiceNowSession which will be used by default in other functions.

Basic authentication with just a credential...

$params = @{
    Url = 'instance.service-now.com'
    Credential = $userCred
}
New-ServiceNowSession @params

Oauth authentication with user credential as well as application/client credential. The application/client credential can be found in the System OAuth->Application Registry section of ServiceNow.

$params = @{
    Url = 'instance.service-now.com'
    Credential = $userCred
    ClientCredential = $clientCred
}
New-ServiceNowSession @params

Note: ServiceNow's API does not support SSO

All examples below assume a new session has already been created.

Getting incidents opened in the last 30 days

Get-ServiceNowRecord -Table incident -Filter @('opened_at', '-ge', (Get-Date).AddDays(-30))

Retrieving an Incident Containing the Word 'PowerShell'

Get-ServiceNowRecord -Table incident -Description 'powershell'

Update a Ticket

Get-ServiceNowRecord inc0010002 | Update-ServiceNowRecord -InputData @{comments='Updated via PowerShell'}

Creating an Incident with custom table entries

$params = @{
    Caller = "UserName"
    ShortDescription = "New PS Incident"
    Description = "This incident was created from Powershell"
    InputData = @{
        u_service = "MyService"
        u_incident_type = "Request"
        urgency = 1
    }
}
New-ServiceNowIncident @params

Azure Connection Object (Automation Integration Module Support)

The module can use the Connection parameter in conjunction with the included ServiceNow-Automation.json file for use as an Azure automation integration module. Details of the process is available at Authoring Integration Modules for Azure Automation.

The Connection parameter accepts a hashtable object that requires a username, password, and ServiceNowURL.

Scope & Contributing

Contributions are gratefully received, so please feel free to submit a pull request with additional features or amendments.

Authors