broadinstitute/servicenow-powershell

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

ServiceNow

This PowerShell module provides a series of cmdlets for interacting with the ServiceNow REST API, performed by wrapping Invoke-RestMethod for the API calls.

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

Version 1

The module has been renamed from PSServiceNow to ServiceNow for version 1. This change moves us away from the reserved "PS" prefix. Since the name change is a major change for the user base and the project was never incremented to v1 we've taken the opportunity to label it such.

In addition to the name change the following high level changes have been made:

Back End:

• The module structure has been updated to individual files for each function.
• The build process has been migrated from MAKE to psake with support of the BuildHelpers module.
• Pester testing has been expanded to cover more scenarios.
• Improved code formatting, removed aliases, fixed file encoding.

The gains are marginal in some aspects, but intended to allow for better management in the future.

Front End:

• The following fields are now returned in the DateTime format instead of string: 'closed_at','expected_start','follow_up','opened_at','sys_created_on','sys_updated_on','work_end','work_start' [v1.0.1 Update: This process now attempts to format the property as DateTime based off your local culture settings, a universal yyyy-MM-dd HH:mm:ss format, and finally leaves the property as a string if those two convert attempts fail].
• The formatting of returned data has been updated across all the Get functions except Get-ServiceNowTable. This means you'll see a handful of default properties returned and can use Format-List or Select-Object to view all other properties associated with the object.

These changes should improve your ability to filter on the right, especially by DateTime, as well as return more information in general.

Requirements

Requires PowerShell 3.0 or above as this is when Invoke-RestMethod was introduced.

Usage

Download the latest release and extract the .psm1 and .psd1 files to your PowerShell profile directory (i.e. the Modules directory under wherever $profile points to in your PS console) and run: Import-Module ServiceNow Once you've done this, all the cmdlets will be at your disposal, you can see a full list using Get-Command -Module ServiceNow.

Example - Using Set-ServiceNowAuth

Set-ServiceNowAuth -url InstanceName.service-now.com -Credentials (Get-Credential)

The URL should be the instance name portion of the FQDN for your instance. For if you browse to https://yourinstance.service-now.com the URL required for the module is yourinstance.service-now.com.

Example - Retrieving an Incident Containing the Word 'PowerShell'

Import-Module ServiceNow
Set-ServiceNowAuth
Get-ServiceNowIncident -MatchContains @{short_description='PowerShell'}

Example - Retrieving an Incident Containing the Word 'PowerShell' While Passing Authentication

Import-Module ServiceNow
Get-ServiceNowIncident -MatchContains @{short_description='PowerShell'} -ServiceNowCredential $PSCredential -ServiceNowURL $ServiceNowURL

Example - Update a Ticket

$Incident = Get-ServiceNowIncident -Limit 1 -MatchContains @{short_description='PowerShell'}
Update-ServiceNowIncident -SysID $Incident.Sys_ID -Values @{comments='Updated via PowerShell'}

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.

Cmdlets

• Get-ServiceNowChangeRequest
• Get-ServiceNowConfigurationItem
• Get-ServiceNowIncident
• Get-ServiceNowTable
• Get-ServiceNowUser
• Get-ServiceNowUserGroup
• New-ServiceNowIncident
• New-ServiceNowQuery
• New-ServiceNowTableEntry
• Remove-ServiceNowAuth
• Remove-ServiceNowTableEntry
• Set-ServiceNowAuth
• Test-ServiceNowAuthIsSet
• Update-ServiceNowChangeRequest
• Update-ServiceNowIncident
• Update-ServiceNowTableEntry

Tests

This module comes with Pester tests for unit testing.

Scope & Contributing

This module has been created as an abstraction layer to suit my immediate requirements. Contributions are gratefully received however, so please feel free to submit a pull request with additional features or amendments.

Author

Author:: Sam Martin ([email protected])