prep for release, help updates

Author: gdbarron

CHANGELOG.md

@@ -1,3 +1,11 @@
+## v2.0
+- Although still in the module for backward compatibility, `Set-ServiceNowAuth` is being replaced with `New-ServiceNowSession`.  With this comes OAuth support, removal of global variables, and much more folks have asked for.  The ability to provide credentials directly to functions has been retained for this release, but will be deprecated in a future release in favor of using `New-ServiceNowSession`.
+- Support for different api versions.  `Set-ServiceNowAuth` will continue to use v1 of the api, but `New-ServiceNowSession` defaults to the latest.  Check out the `-ApiVersion` parameter of `New-ServiceNowSession`.
+- `Remove-ServiceNowAuth` has been retained for this release, but as global variables have been removed, there is no longer a need for it; it will always return `$true`.  It will be removed in a future release.
+- `-PassThru` added to remaining `Update-` and `New-` functions.  Depending on your code, this may be a ***breaking change*** if you expected the result to be returned.
+- Pipeline support added to many functions
+- Standardizing on coding between all functions
+
 ## v1.8.1
 - Update links to reference the new GitHub organization this project will be moved to.  Module functionality unchanged.
 

Readme.md

@@ -6,6 +6,16 @@ This PowerShell module provides a series of cmdlets for interacting with the [Se
 
 **IMPORTANT:** Neither this module nor its creator are in any way affiliated with ServiceNow.
 
+## Version 2
+
+Building on the great work the community has done thus far, a lot of new updates with this release.
+- Although still in the module for backward compatibility, `Set-ServiceNowAuth` is being replaced with `New-ServiceNowSession`.  With this comes OAuth support, removal of global variables, and much more folks have asked for.  The ability to provide credentials directly to functions has been retained for this release, but will be deprecated in a future release in favor of using `New-ServiceNowSession`.
+- Support for different api versions.  `Set-ServiceNowAuth` will continue to use v1 of the api, but `New-ServiceNowSession` defaults to the latest.  Check out the `-ApiVersion` parameter of `New-ServiceNowSession`.
+- `Remove-ServiceNowAuth` has been retained for this release, but as global variables have been removed, there is no longer a need for it; it will always return `$true`.  It will be removed in a future release.
+- `-PassThru` added to remaining `Update-` and `New-` functions.  Depending on your code, this may be a ***breaking change*** if you expected the result to be returned.
+- Pipeline support added to many functions
+- Standardizing on coding between all functions
+
 ## 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.
@@ -108,12 +118,11 @@ The `Connection` parameter accepts a hashtable object that requires a username,
 * Get-ServiceNowUserGroup
 * New-ServiceNowChangeRequest
 * New-ServiceNowIncident
+* New-ServiceNowSession
 * New-ServiceNowQuery
 * New-ServiceNowTableEntry
 * Remove-ServiceNowAttachment
-* Remove-ServiceNowAuth
 * Remove-ServiceNowTableEntry
-* Set-ServiceNowAuth
 * Test-ServiceNowAuthIsSet
 * Update-ServiceNowChangeRequest
 * Update-ServiceNowIncident

ServiceNow/Public/Get-ServiceNowChangeRequest.ps1

@@ -4,48 +4,48 @@ function Get-ServiceNowChangeRequest {
     Param(
         # Machine name of the field to order by
         [Parameter()]
-        [string]$OrderBy = 'opened_at',
+        [string] $OrderBy = 'opened_at',
 
         # Direction of ordering (Desc/Asc)
         [Parameter()]
         [ValidateSet('Desc', 'Asc')]
-        [string]$OrderDirection = 'Desc',
+        [string] $OrderDirection = 'Desc',
 
         # Maximum number of records to return
         [Parameter()]
-        [int]$Limit,
+        [int] $Limit,
 
         # Fields to return
         [Parameter()]
         [Alias('Fields')]
-        [string[]]$Properties,
+        [string[]] $Properties,
 
         # Hashtable containing machine field names and values returned must match exactly (will be combined with AND)
         [Parameter()]
-        [hashtable]$MatchExact = @{},
+        [hashtable] $MatchExact = @{},
 
         # Hashtable containing machine field names and values returned rows must contain (will be combined with AND)
         [Parameter()]
-        [hashtable]$MatchContains = @{},
+        [hashtable] $MatchContains = @{},
 
         # Whether or not to show human readable display values instead of machine values
         [Parameter()]
         [ValidateSet('true', 'false', 'all')]
-        [string]$DisplayValues = 'true',
+        [string] $DisplayValues = 'true',
 
         [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)]
         [ValidateNotNullOrEmpty()]
         [Alias('ServiceNowCredential')]
-        [PSCredential]$Credential,
+        [PSCredential] $Credential,
 
         [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)]
         [ValidateScript( { $_ | Test-ServiceNowURL })]
         [Alias('Url')]
-        [string]$ServiceNowURL,
+        [string] $ServiceNowURL,
 
         [Parameter(ParameterSetName = 'UseConnectionObject', Mandatory)]
         [ValidateNotNullOrEmpty()]
-        [hashtable]$Connection,
+        [hashtable] $Connection,
 
         [Parameter(ParameterSetName = 'Session')]
         [ValidateNotNullOrEmpty()]

ServiceNow/Public/New-ServiceNowSession.ps1

@@ -6,6 +6,7 @@ Create a new ServiceNow session
 Create a new ServiceNow session via credentials, OAuth, or access token.
 This session will be used by default for all future calls.
 Optionally, you can specify the api version you'd like to use; the default is the latest.
+To use OAuth, ensure you've set it up, https://docs.servicenow.com/bundle/quebec-platform-administration/page/administer/security/task/t_SettingUpOAuth.html.
 
 .PARAMETER Url
 Base domain for your ServiceNow instance, eg. tenant.domain.com
@@ -25,6 +26,31 @@ Specific API version to use.  The default is the latest.
 .PARAMETER PassThru
 Provide the resulting session object to the pipeline as opposed to setting as a script scoped variable to be used by default for other calls.
 This is useful if you want to have multiple sessions with different api versions, credentials, etc.
+
+.EXAMPLE
+New-ServiceNowSession -Url tenant.domain.com -Credential $mycred
+Create a session using basic authentication and save it to a script-scoped variable
+
+.EXAMPLE
+New-ServiceNowSession -Url tenant.domain.com -Credential $mycred -ClientCredential $myClientCred
+Create a session using OAuth and save it to a script-scoped variable
+
+.EXAMPLE
+New-ServiceNowSession -Url tenant.domain.com -AccessToken 'asdfasd9f87adsfkksk3nsnd87g6s'
+Create a session with an existing access token and save it to a script-scoped variable
+
+.EXAMPLE
+$session = New-ServiceNowSession -Url tenant.domain.com -Credential $mycred -ClientCredential $myClientCred -PassThru
+Create a session using OAuth and save it as a local variable to be provided to functions directly
+
+.INPUTS
+None
+
+.OUTPUTS
+Hashtable if -PassThru provided
+
+.LINK
+https://docs.servicenow.com/bundle/quebec-platform-administration/page/administer/security/reference/r_OAuthAPIRequestParameters.html
 #>
 function New-ServiceNowSession {
 

ServiceNow/Public/Test-ServiceNowAuthIsSet.ps1

@@ -1,7 +1,7 @@
 function Test-ServiceNowAuthIsSet{
-    if($script:ServiceNowSession.Credential){
-        return $true;
+    if ( $ServiceNowSession.Credential -or $ServiceNowSession.AccessToken ){
+        return $true
     }else{
-        return $false;
+        return $false
     }
 }

ServiceNow/ServiceNow.psd1

@@ -5,7 +5,7 @@
 RootModule = 'ServiceNow.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.8.1'
+ModuleVersion = '2.0.0'
 
 # ID used to uniquely identify this module
 GUID = 'b90d67da-f8d0-4406-ad74-89d169cd0633'