v3 - Major release

[gdbarron]

Hi all. A lot of work went into this release and I hope it's useful. There are some breaking changes, but I've tried to keep them to a minimum as I move through some cleanup and consolidation. Please let me know if you find the new functionality helpful or any issues you might find given the number of changes.

• New functionality in Get-ServiceNowRecord
  • Add Id property to easily retrieve a record by either number or sysid.
  • Add ParentId property to easily retrieve records based on the parent number or sysid. For example, to retrieve catalog tasks associated with a requested item execute Get-ServiceNowRecord -Table 'Catalog Task' -ParentId RITM01234567.
  • Add Description property to retrieve records based on a table specific description field. For many tables this field will be short_description, but will be different for others. For example, when performing this against the 'User' table, the description field is 'Name'.
  • Add ability to provide a known prefixed Id without providing Table, Get-ServiceNowRecord -Id inc0010001. To see the list of known prefixes, execute $ServiceNowTable.NumberPrefix after importing the module.
  • Add alias gsnr. With the above change, a Get can be as simple as gsnr inc0010001.
• Add autocomplete for Table parameter in Add-ServiceNowAttachment and Get-ServiceNowAttachment.
• Add Id parameter to Add-ServiceNowAttachment and Update-ServiceNowRecord which accepts either number or sysid. Just as with Get-ServiceNowRecord you can now provide just Id if it has a known prefix.
• Add ability to Get-ServiceNowAttachment to get attachments either via associated record or directly from the attachments table when you want to search all attachments.
• Add advanced filtering and sorting functionality to Get-ServiceNowAttachment which can be really useful when searching across the attachments table.
• Convert access and refresh tokens in $ServiceNowSession from plain text to a credential for added security.
• Pipeline enhancements added in many places.
• Add Change Task and Attachments to formats.
• Update-ServiceNowNumber has been deprecated and the functionality has been added to Update-ServiceNowRecord. An alias has also been added so existing scripts do not break.
• Prep for removal of all Get- functions except for Get-ServiceNowRecord and Get-ServiceNowAttachment. Table specific Get functions have been deprecated. Get-ServiceNowRecordInterim has been created and all table specific Get functions have been aliased so existing scripts do not break. Please start to migrate to Get-ServiceNowRecord as these functions will all be deprecated in the near future.
• As communicated in v2.0, authentication cleanup has occurred. This involves removal of Credential/Url authentication in each function in favor of ServiceNowSession. You can still authenticate with Credential/Url, but must use New-ServiceNowSession. Set-ServiceNowAuth, Remove-ServiceNowAuth, and Test-ServiceNowAuthIsSet have been deprecated.
• Breaking change: rename Get-ServiceNowAttachmentDetail to Get-ServiceNowAttachment.
• Breaking change: rename Get-ServiceNowAttachment to Export-ServiceNowAttachment.
• Breaking change: Get-ServiceNowTable and Get-ServiceNowTableEntry have been deprecated. Use Get-ServiceNowRecord.

---

This discussion was created from the release v3 - Major release.

[brettmillerb]

Top work @gdbarron

Will need to take the new version for a spin internally. Really pleased to see the progress being made with breaking changes also 🎉

[gdbarron]

Thanks @brettmillerb! Not often you see 'really pleased' and 'breaking changes' in the same sentence 😄 Look forward to any feedback you are able to provide.

[brettmillerb]

I got a bit carried away with my pull request and had earmarked a lot of the breaking changes as a requirement. Unfortunately life got in the way before I got the opportunity. Glad someone is though 😄

[wwwb0n3zcom]

The following doesn't seem to work as intended or understood:

Get-ServiceNowRecord -Table incident -Filter @('assigned_to' -eq 'UserNameHere') -Verbose
(Replace 'UserNameHere' with my actual ServiceNow assigned user name)
Instead this returns back incidents that are not even assigned to me.

I also want the ability to have multiple filters. The following doesn't seem to work either:
Get-ServiceNowRecord -Table incident -Filter @{('assigned_to' -eq 'UserNameHere') -and ('state' -eq 'Open')} -Verbose

Even a command like the following doesn't work:
Get-ServiceNowRecord -Table incident -Filter @('state' -eq 'Open') -Verbose
Instead it returns back 10 incidents where the state field shows "Closed Complete".

Is there something I'm missing? (Using ServiceNow module version 3.0.0 with PowerShell version 5.1)

[gdbarron]

For assigned_to, you should be able to 'dot walk' the value like
Get-ServiceNowRecord -Table incident -Filter @('assigned_to.user_name', '-eq', 'UserNameHere'). If you don't dot walk it and just try to filter on assigned_to, it will match on the sys_id of the referenced record, in this case from the sys_user table.

Off the top of my head, I don't know how to reference State by its name. You can run Get-ServiceNowRecord with -DisplayValues all and it will give you the display_value and value for each property. Get the value for the state you want and replace the name with the value, eg. Get-ServiceNowRecord -Table incident @('state', '-eq', '1').

2 other items of note. I don't think 'open' is a standard state for incidents; it's typically new, in progress, etc. Also, -Filter is a list of strings, not a powershell expression. In my example above I've fixed that.

Feel free to provide any feedback to make this module easier to use.

[wwwb0n3zcom]

Thank you @gdbarron - this module and support has been amazing!

So I got a bit further with your help. I now use the following:
#Get users system ID
$user_name = 'User Name Here'
$user_id = (Get-ServiceNowRecord -Table 'User' -Filter @('name', '-like', "$user_name")).sys_id

#Get assigned incidents
Get-ServiceNowRecord -Table 'Incident' -Filter @('assigned_to', '-eq', "$user_id") -Verbose

Now I just need to understand how to put multiple string items into the filter (such as combining the following):
Get-ServiceNowRecord -Table 'Incident' -Filter @('state', '-eq', '1') -Verbose

I did a bit a research to find out in our ServiceNow environment we have the following for state:
1 = [INC][REQ]Open
2 = ?
3 = [INC][REQ][CHG]Closed Complete
4 = [CHG]Closed Cancelled, [REQ]Closed Incomplete
5 = ?
6 = ?
7 = [INC][REQ]Closed Skipped
8 = [CHG]In Progress
9 = [CHG]Pre-Deployment

[gdbarron]

@wwwb0n3zcom, you don't need to get the sysid first if you 'dot walk' the property,

$user_name = 'user name here'
Get-ServiceNowRecord -Table incident -Filter @('assigned_to.user_name', '-eq', $user_name)

I updated my comment above, not sure if you saw it. You could certainly do it the way you have it, but it's an extra api call that's not needed.

I have an example in the help which describes how to combine multiple filters.

Here's how you would execute for your needs:
Get-ServiceNowRecord -Table incident -Filter @('assigned_to.user_name', '-eq', $user_name), 'and', @('state', '-eq', '1')

[wwwb0n3zcom]

1st Thank YOU @gdbarron for the lesson and response. It's opening my eyes to how filters works with arrays which have been a challenge for me.

Using the following shows the following properties: display_value, link, value
(Get-ServiceNowRecord -Id CHG4908900 -DisplayValue all).assigned_to

Also the assigned_to doesn't show with the normal @{display_value, value} when using the following:
Get-ServiceNowRecord -Id CHG4908900 -DisplayValue all

So instead I tried to use the -like $User_Name and combined it all using your great lesson on -filter <ArrayList>:
#Set variable for credentials using email address with domain password
If (-not($Cred))
{
$Cred = Get-Credential
}

#Set params for session and connect
$SessionParams = @{
Url = 'ReplaceWithURL.com'
Credential = $Cred
}
New-ServiceNowSession @SessionParams

#Get user name
$User_Name = 'ReplaceWithUserName'

$Filter = @('assigned_to', '-like', $User_Name),
'-and', @('state', '-ne', '3'),
'-and', @('state', '-ne', '4'),
'-and', @('state', '-ne', '7')

Get-ServiceNowRecord -Table 'Change Request' -Filter $Filter

It's too bad we can't filter based upon the display_value or maybe I just don't know how. Maybe a feature request? Filter by either value or display_value by specifying a switch parameter.