diff --git a/MAKE.ps1 b/MAKE.ps1 index 3fd9365..83efac1 100644 --- a/MAKE.ps1 +++ b/MAKE.ps1 @@ -66,7 +66,7 @@ $PackageFilePatternExclusions = @( $here = Split-Path -Parent $MyInvocation.MyCommand.Path -$Version = "0.1.2" +$Version = "0.1.12" $ModuleName = "PSServiceNow" $PackageName = "$ModuleName-v$($version).zip"; diff --git a/PSServiceNow-Automation.json b/PSServiceNow-Automation.json new file mode 100644 index 0000000..04fdc45 Binary files /dev/null and b/PSServiceNow-Automation.json differ diff --git a/PSServiceNow-Changes.psm1 b/PSServiceNow-Changes.psm1 index 4625f04..2efe73a 100644 --- a/PSServiceNow-Changes.psm1 +++ b/PSServiceNow-Changes.psm1 @@ -2,36 +2,79 @@ function Get-ServiceNowChangeRequest { param( # Machine name of the field to order by [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$OrderBy='opened_at', # Direction of ordering (Desc/Asc) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("Desc", "Asc")] [string]$OrderDirection='Desc', # Maximum number of records to return [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [int]$Limit=10, # Hashtable containing machine field names and values returned must match exactly (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchExact=@{}, # Hashtable containing machine field names and values returned rows must contain (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchContains=@{}, # Whether or not to show human readable display values instead of machine values [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("true","false", "all")] - [string]$DisplayValues='true' - ) + [string]$DisplayValues='true', + + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection + ) + $private:Query = New-ServiceNowQuery -OrderBy $private:OrderBy -OrderDirection $private:OrderDirection -MatchExact $private:MatchExact -MatchContains $private:MatchContains - - $private:result = Get-ServiceNowTable -Table 'change_request' -Query $private:Query -Limit $private:Limit -DisplayValues $private:DisplayValues; + + + if ($Connection -ne $null) { + $private:result = Get-ServiceNowTable -Table 'change_request' -Query $private:Query -Limit $private:Limit -DisplayValues $private:DisplayValues -Connection $Connection + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) { + $private:result = Get-ServiceNowTable -Table 'change_request' -Query $private:Query -Limit $private:Limit -DisplayValues $private:DisplayValues -ServiceNowCredential $ServiceNowCredential -ServiceNowURL $ServiceNowURL + } + else { + $private:result = Get-ServiceNowTable -Table 'change_request' -Query $private:Query -Limit $private:Limit -DisplayValues $private:DisplayValues + } # Add the custom type to the change request to enable a view $private:result | %{$_.psobject.TypeNames.Insert(0, "PSServiceNow.ChangeRequest")} return $private:result -} \ No newline at end of file +} + diff --git a/PSServiceNow-ConfigurationManagement.psm1 b/PSServiceNow-ConfigurationManagement.psm1 index e525e9c..427c5c1 100644 --- a/PSServiceNow-ConfigurationManagement.psm1 +++ b/PSServiceNow-ConfigurationManagement.psm1 @@ -2,34 +2,76 @@ function Get-ServiceNowConfigurationItem { param( # Machine name of the field to order by [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$OrderBy='name', # Direction of ordering (Desc/Asc) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("Desc", "Asc")] [string]$OrderDirection='Desc', # Maximum number of records to return [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [int]$Limit=10, # Hashtable containing machine field names and values returned must match exactly (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchExact=@{}, # Hashtable containing machine field names and values returned rows must contain (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchContains=@{}, # Whether or not to show human readable display values instead of machine values [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("true","false", "all")] - [string]$DisplayValues='true' + [string]$DisplayValues='true', + + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) $Query = New-ServiceNowQuery -OrderBy $OrderBy -OrderDirection $OrderDirection -MatchExact $MatchExact -MatchContains $MatchContains - - $result = Get-ServiceNowTable -Table 'cmdb_ci' -Query $Query -Limit $Limit -DisplayValues $DisplayValues; + + if ($Connection -ne $null) { + $result = Get-ServiceNowTable -Table 'cmdb_ci' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -Connection $Connection + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) { + $result = Get-ServiceNowTable -Table 'cmdb_ci' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -ServiceNowCredential $ServiceNowCredential -ServiceNowURL $ServiceNowURL + } + else { + $result = Get-ServiceNowTable -Table 'cmdb_ci' -Query $Query -Limit $Limit -DisplayValues $DisplayValues + } + # Set the default property set for the table view $DefaultProperties = @('name', 'category', 'subcategory') diff --git a/PSServiceNow-Incidents.psm1 b/PSServiceNow-Incidents.psm1 index 92e66d2..3ac7082 100644 --- a/PSServiceNow-Incidents.psm1 +++ b/PSServiceNow-Incidents.psm1 @@ -15,35 +15,82 @@ function Get-ServiceNowIncident{ param( # Machine name of the field to order by [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$OrderBy='opened_at', # Direction of ordering (Desc/Asc) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("Desc", "Asc")] [string]$OrderDirection='Desc', # Maximum number of records to return [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [int]$Limit=10, # Hashtable containing machine field names and values returned must match exactly (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchExact=@{}, # Hashtable containing machine field names and values returned rows must contain (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchContains=@{}, # Whether or not to show human readable display values instead of machine values [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("true","false", "all")] - [string]$DisplayValues='true' + [string]$DisplayValues='true', + + # Credential used to authenticate to ServiceNow + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + # The URL for the ServiceNow instance being used + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) $Query = New-ServiceNowQuery -OrderBy $OrderBy -OrderDirection $OrderDirection -MatchExact $MatchExact -MatchContains $MatchContains - - $result = Get-ServiceNowTable -Table 'incident' -Query $Query -Limit $Limit -DisplayValues $DisplayValues; + if ($Connection -ne $null) + { + $result = Get-ServiceNowTable -Table 'incident' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -Connection $Connection + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) + { + $result = Get-ServiceNowTable -Table 'incident' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -ServiceNowCredential $ServiceNowCredential -ServiceNowURL $ServiceNowURL + } + else + { + $result = Get-ServiceNowTable -Table 'incident' -Query $Query -Limit $Limit -DisplayValues $DisplayValues + } + # Set the default property set for the table view $DefaultProperties = @('number', 'short_description', 'opened_at') $DefaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet(‘DefaultDisplayPropertySet’,[string[]]$DefaultProperties) @@ -62,43 +109,91 @@ function Get-ServiceNowIncident{ -Comment "Comment" -ConfigurationItem "bee8e0ed6f8475001855fa0dba3ee4ea" ` -Caller "7a4b573a6f3725001855fa0dba3ee485" ` #> - function New-ServiceNowIncident{ Param( # sys_id of the caller of the incident (user Get-ServiceNowUser to retrieve this) - [parameter(mandatory=$true)] + [parameter(ParameterSetName='SpecifyConnectionFields', mandatory=$true)] + [parameter(ParameterSetName='UseConnectionObject', mandatory=$true)] + [parameter(ParameterSetName='SetGlobalAuth', mandatory=$true)] [string]$Caller, # Short description of the incident [parameter(mandatory=$true)] + [parameter(ParameterSetName='SpecifyConnectionFields', mandatory=$true)] + [parameter(ParameterSetName='UseConnectionObject', mandatory=$true)] + [parameter(ParameterSetName='SetGlobalAuth', mandatory=$true)] [string]$ShortDescription, # Long description of the incident [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$Description, # sys_id of the assignment group (use Get-ServiceNowUserGroup to retrieve this) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$AssignmentGroup, # Comment to include in the ticket - [parameter(mandatory=$false)] + [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$Comment, # Category of the incident (e.g. 'Network') - [parameter(mandatory=$false)] + [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$Category, # Subcategory of the incident (e.g. 'Network') [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$Subcategory, # sys_id of the configuration item of the incident [parameter(mandatory=$false)] - [string]$ConfigurationItem + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] + [string]$ConfigurationItem, + + # custom fields as hashtable + [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] + [hashtable]$CustomFields, + + # Credential used to authenticate to ServiceNow + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + # The URL for the ServiceNow instance being used (eg: instancename.service-now.com) + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) + $Values = @{ 'caller_id' = $Caller 'short_description' = $ShortDescription @@ -109,8 +204,24 @@ function New-ServiceNowIncident{ 'subcategory' = $Subcategory 'cmdb_ci' = $ConfigurationItem } - - New-ServiceNowTableEntry -Table 'incident' -Values $Values + + if($CustomFields) + { + $Values += $CustomFields + } + + if ($Connection -ne $null) + { + New-ServiceNowTableEntry -Table 'incident' -Values $Values -Connection $Connection + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) + { + New-ServiceNowTableEntry -Table 'incident' -Values $Values -ServiceNowCredential $ServiceNowCredential -ServiceNowURL $ServiceNowURL + } + else + { + New-ServiceNowTableEntry -Table 'incident' -Values $Values + } } diff --git a/PSServiceNow-Tables.psm1 b/PSServiceNow-Tables.psm1 index 9a64f70..a5ec8ae 100644 --- a/PSServiceNow-Tables.psm1 +++ b/PSServiceNow-Tables.psm1 @@ -4,25 +4,69 @@ function Get-ServiceNowTable Param ( # Name of the table we're querying (e.g. incidents) - [parameter(mandatory=$true)] + [parameter(ParameterSetName='SpecifyConnectionFields', mandatory=$false)] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$Table, # sysparm_query param in the format of a ServiceNow encoded query string (see http://wiki.servicenow.com/index.php?title=Encoded_Query_Strings) - [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields', mandatory=$false)] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$Query, # Maximum number of records to return - [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields', mandatory=$false)] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [int]$Limit=10, # Whether or not to show human readable display values instead of machine values - [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields', mandatory=$false)] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("true","false", "all")] - [string]$DisplayValues='false' + [string]$DisplayValues='false', + + # Credential used to authenticate to ServiceNow + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + # The URL for the ServiceNow instance being used + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) - if(! (Test-ServiceNowAuthIsSet)){ - Write-Error "You must run Set-ServiceNowAuth prior to executing this cmdlet in order to provide credentials" + #Get credential and ServiceNow REST URL + if ($Connection -ne $null) + { + $SecurePassword = ConvertTo-SecureString $Connection.Password -AsPlainText -Force + $ServiceNowCredential = New-Object System.Management.Automation.PSCredential ($Connection.Username, $SecurePassword) + $ServiceNowURL = 'https://' + $Connection.ServiceNowUri + '/api/now/v1' + + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) + { + $ServiceNowURL = 'https://' + $ServiceNowURL + '/api/now/v1' + } + elseif((Test-ServiceNowAuthIsSet)) + { + $ServiceNowCredential = $Global:ServiceNowCredentials + $ServiceNowURL = $global:ServiceNowRESTURL + } + else + { + throw "Exception: You must do one of the following to authenticate: `n 1. Call the Set-ServiceNowAuth cmdlet `n 2. Pass in an Azure Automation connection object `n 3. Pass in an endpoint and credential" } # Populate the query @@ -32,8 +76,9 @@ function Get-ServiceNowTable } # Fire and return - $Uri = $global:ServiceNowRESTURL + "/table/$Table" - return (Invoke-RestMethod -Uri $uri -Credential $global:ServiceNowCredentials -Body $Body -ContentType "application/json").result + $Uri = $ServiceNowURL + "/table/$Table" + + return (Invoke-RestMethod -Uri $Uri -Credential $ServiceNowCredential -Body $Body -ContentType "application/json").result } function New-ServiceNowTableEntry{ @@ -41,22 +86,69 @@ function New-ServiceNowTableEntry{ ( # Name of the table we're inserting into (e.g. incidents) [parameter(mandatory=$true)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$Table, # Hashtable of values to use as the record's properties [parameter(mandatory=$false)] - [hashtable]$Values + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] + [hashtable]$Values, + + # Credential used to authenticate to ServiceNow + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + # The URL for the ServiceNow instance being used + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) - if(! (Test-ServiceNowAuthIsSet)){ - Write-Error "You must run Set-ServiceNowAuth prior to executing this cmdlet in order to provide credentials" + + #Get credential and ServiceNow REST URL + if ($Connection -ne $null) + { + $SecurePassword = ConvertTo-SecureString $Connection.Password -AsPlainText -Force + $ServiceNowCredential = New-Object System.Management.Automation.PSCredential ($Connection.Username, $SecurePassword) + $ServiceNowURL = 'https://' + $Connection.ServiceNowUri + '/api/now/v1' + + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) + { + $ServiceNowURL = 'https://' + $ServiceNowURL + '/api/now/v1' + } + elseif((Test-ServiceNowAuthIsSet)) + { + $ServiceNowCredential = $Global:ServiceNowCredentials + $ServiceNowURL = $global:ServiceNowRESTURL + } + else + { + throw "Exception: You must do one of the following to authenticate: `n 1. Call the Set-ServiceNowAuth cmdlet `n 2. Pass in an Azure Automation connection object `n 3. Pass in an endpoint and credential" } + $Body = $Values | ConvertTo-Json; + #Convert to UTF8 array to support special chars such as the danish "�","�","�" + $utf8Bytes = [System.Text.Encoding]::UTf8.GetBytes($Body) + # Fire and return - $Uri = $global:ServiceNowRESTURL + "/table/$Table" - return (Invoke-RestMethod -Uri $uri -Method Post -Credential $global:ServiceNowCredentials -Body $Body -ContentType "application/json").result + $Uri = $ServiceNowURL + "/table/$Table" + return (Invoke-RestMethod -Uri $uri -Method Post -Credential $ServiceNowCredential -Body $utf8Bytes -ContentType "application/json" -UseBasicParsing).result } <# @@ -64,18 +156,64 @@ function New-ServiceNowTableEntry{ Untested #> function Remove-ServiceNowTableEntry{ - [CmdletBinding(ConfirmImpact='High')] +[CmdletBinding(ConfirmImpact='High')] Param( # sys_id of the entry we're deleting [parameter(mandatory=$true)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$SysId, # Table containing the entry we're deleting [parameter(mandatory=$true)] - [string]$Table + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] + [string]$Table, + + # Credential used to authenticate to ServiceNow + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + # The URL for the ServiceNow instance being used + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) + #Get credential and ServiceNow REST URL + if ($Connection -ne $null) + { + $SecurePassword = ConvertTo-SecureString $Connection.Password -AsPlainText -Force + $ServiceNowCredential = New-Object System.Management.Automation.PSCredential ($Connection.Username, $SecurePassword) + $ServiceNowURL = 'https://' + $Connection.ServiceNowUri + '/api/now/v1' + + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) + { + $ServiceNowURL = 'https://' + $ServiceNowURL + '/api/now/v1' + } + elseif((Test-ServiceNowAuthIsSet)) + { + $ServiceNowCredential = $Global:ServiceNowCredentials + $ServiceNowURL = $global:ServiceNowRESTURL + } + else + { + throw "Exception: You must do one of the following to authenticate: `n 1. Call the Set-ServiceNowAuth cmdlet `n 2. Pass in an Azure Automation connection object `n 3. Pass in an endpoint and credential" + } + # Fire and return - $Uri = $global:ServiceNowRESTURL + "/table/$Table/$SysID" - return (Invoke-RestMethod -Uri $uri -Method Delete -Credential $global:ServiceNowCredentials -Body $Body -ContentType "application/json").result + $Uri = $ServiceNowURL + "/table/$Table/$SysID" + return (Invoke-RestMethod -Uri $uri -Method Delete -Credential $ServiceNowCredential -Body $Body -ContentType "application/json").result } \ No newline at end of file diff --git a/PSServiceNow-Users.psm1 b/PSServiceNow-Users.psm1 index 0d9e89d..934afcc 100644 --- a/PSServiceNow-Users.psm1 +++ b/PSServiceNow-Users.psm1 @@ -8,38 +8,88 @@ function Get-ServiceNowUserGroup{ param( # Machine name of the field to order by [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$OrderBy='name', # Direction of ordering (Desc/Asc) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("Desc", "Asc")] [string]$OrderDirection='Desc', # Maximum number of records to return [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [int]$Limit=10, # Hashtable containing machine field names and values returned must match exactly (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchExact=@{}, # Hashtable containing machine field names and values returned rows must contain (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchContains=@{}, # Whether or not to show human readable display values instead of machine values [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("true","false", "all")] - [string]$DisplayValues='true' + [string]$DisplayValues='true', + + # Credential used to authenticate to ServiceNow + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + # The URL for the ServiceNow instance being used + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) + $Query = New-ServiceNowQuery -OrderBy $OrderBy -OrderDirection $OrderDirection -MatchExact $MatchExact -MatchContains $MatchContains - - $result = Get-ServiceNowTable -Table 'sys_user_group' -Query $Query -Limit $Limit -DisplayValues $DisplayValues; + + + if ($Connection -ne $null) + { + $result = Get-ServiceNowTable -Table 'sys_user_group' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -Connection $Connection + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) + { + + $result = Get-ServiceNowTable -Table 'sys_user_group' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -ServiceNowCredential $ServiceNowCredential -ServiceNowURL $ServiceNowURL + } + else + { + $result = Get-ServiceNowTable -Table 'sys_user_group' -Query $Query -Limit $Limit -DisplayValues $DisplayValues + } # Set the default property set for the table view $DefaultProperties = @('name', 'email', 'sys_id') - $DefaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet(‘DefaultDisplayPropertySet’,[string[]]$DefaultProperties) + $DefaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet('DefaultDisplayPropertySet',[string[]]$DefaultProperties) $PSStandardMembers = [System.Management.Automation.PSMemberInfo[]]@($DefaultDisplayPropertySet) $Result | Add-Member MemberSet PSStandardMembers $PSStandardMembers return $result @@ -53,38 +103,85 @@ function Get-ServiceNowUser{ param( # Machine name of the field to order by [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [string]$OrderBy='name', # Direction of ordering (Desc/Asc) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("Desc", "Asc")] [string]$OrderDirection='Desc', # Maximum number of records to return [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [int]$Limit=10, # Hashtable containing machine field names and values returned must match exactly (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchExact=@{}, # Hashtable containing machine field names and values returned rows must contain (will be combined with AND) [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [hashtable]$MatchContains=@{}, # Whether or not to show human readable display values instead of machine values [parameter(mandatory=$false)] + [parameter(ParameterSetName='SpecifyConnectionFields')] + [parameter(ParameterSetName='UseConnectionObject')] + [parameter(ParameterSetName='SetGlobalAuth')] [ValidateSet("true","false", "all")] - [string]$DisplayValues='true' + [string]$DisplayValues='true', + + # Credential used to authenticate to ServiceNow + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [PSCredential] + $ServiceNowCredential, + + # The URL for the ServiceNow instance being used + [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [string] + $ServiceNowURL, + + #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance + [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] + [ValidateNotNullOrEmpty()] + [Hashtable] + $Connection ) $Query = New-ServiceNowQuery -OrderBy $OrderBy -OrderDirection $OrderDirection -MatchExact $MatchExact -MatchContains $MatchContains - - $result = Get-ServiceNowTable -Table 'sys_user' -Query $Query -Limit $Limit -DisplayValues $DisplayValues; + + if ($Connection -ne $null) + { + $result = Get-ServiceNowTable -Table 'sys_user' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -Connection $Connection + } + elseif ($ServiceNowCredential -ne $null -and $ServiceNowURL -ne $null) + { + $result = Get-ServiceNowTable -Table 'sys_user' -Query $Query -Limit $Limit -DisplayValues $DisplayValues -ServiceNowCredential $ServiceNowCredential -ServiceNowURL $ServiceNowURL + } + else + { + $result = Get-ServiceNowTable -Table 'sys_user' -Query $Query -Limit $Limit -DisplayValues $DisplayValues + } # Set the default property set for the table view $DefaultProperties = @('name', 'email', 'sys_id') - $DefaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet(‘DefaultDisplayPropertySet’,[string[]]$DefaultProperties) + $DefaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet('DefaultDisplayPropertySet',[string[]]$DefaultProperties) $PSStandardMembers = [System.Management.Automation.PSMemberInfo[]]@($DefaultDisplayPropertySet) $Result | Add-Member MemberSet PSStandardMembers $PSStandardMembers return $result diff --git a/PSServiceNow.psd1 b/PSServiceNow.psd1 index c3f74af..f8c79b5 100644 --- a/PSServiceNow.psd1 +++ b/PSServiceNow.psd1 @@ -12,7 +12,7 @@ RootModule = 'PSServiceNow.psm1' # Version number of this module. -ModuleVersion = '0.1.2' +ModuleVersion = '0.1.12' # ID used to uniquely identify this module GUID = 'b90d67da-f8d0-4406-ad74-89d169cd0633' diff --git a/Readme.md b/Readme.md index 043c309..4aacfc7 100644 --- a/Readme.md +++ b/Readme.md @@ -1,5 +1,5 @@ # PSServiceNow -[![GitHub release](https://img.shields.io/github/release/Sam-Martin/servicenow-powershell.svg)](https://github.com/Sam-Martin/servicenow-powershell/releases/latest) [![GitHub license](https://img.shields.io/github/license/Sam-Martin/servicenow-powershell.svg)](LICENSE) ![Test Coverage](https://img.shields.io/badge/coverage-87%25-yellowgreen.svg) +[![GitHub release](https://img.shields.io/github/release/Sam-Martin/servicenow-powershell.svg)](https://github.com/Sam-Martin/servicenow-powershell/releases/latest) [![GitHub license](https://img.shields.io/github/license/Sam-Martin/servicenow-powershell.svg)](LICENSE) ![Test Coverage](https://img.shields.io/badge/coverage-70%25-yellowgreen.svg) This PowerShell module provides a series of cmdlets for interacting with the [ServiceNow REST API](http://wiki.servicenow.com/index.php?title=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. @@ -18,6 +18,17 @@ Set-ServiceNowAuth Get-ServiceNowIncident -MatchContains @{short_description='PowerShell'} ``` +### Example - Retrieving an Incident Containing the Word 'PowerShell' While Passing Authentication +``` +Import-Module PSServiceNow +Get-ServiceNowIncident -MatchContains @{short_description='PowerShell'} -ServiceNowCredential $PSCredential -ServiceNowURL $ServiceNowURL +``` + +### Azure Connection Object (Automation Integration Module Support) +The module can use the `Connection` parameter in conjunction with the included `PSServiceNow-Automation.json` file for use as an Azure automation integration module. Details of the process is available at [Authoring Integration Modules for Azure Automation](https://azure.microsoft.com/en-us/blog/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