V3 Refactor

[Celerium]

Quite a bit got over with this but I've overhauled the ITGlueAPI module. I did this simply because this module got me into writing API wrappers/other PowerShell projects and I wanted to give back to the community as a way of saying thank you.

I have tested every function and the majority of their associated parameters/parameter sets and have not run across any issues yet. With that being said there are a lot of changes and I easily could have missed some things. I have also supplied some generic test scripts in the "examples" folder to help perform general tests when it comes to creating, updating, & deleting data in ITGlue. I labeled this as v3 because while I did my best with backward compatibility, the amount of changes in this PR could cause some breaking changes.

I have working examples for all the changes in my branch over at my repo. This should help with any of the GitHub pages & Azure DevOps pipeline questions. Adjustments will need to be made accordingly if this PR is accepted as GitHub Pages, Azure DevOps, and ReadMe links are dependent on these resources and their specific web URLs.

I am not married to any of the proposed changes I am suggesting and encourage any conversations on anything that could be adjusted.

Issues this PR should resolve

1. UTF-8 Encoding Error #167 (fixed from previous Specify UTF-8 in API requests to support Unicode characters #162 )
2. Enable tab completion support for -include parameter #155 (tab completion added to all supported commands with reference documentation on allowed values depending on parameter set user)
3. Audit module against current IT Glue API documentation #154 (manual tracking CSV, since ITGlue doesn't offer an API spec)
4. Consider PascalCase Parameter Aliases #153 (All commands and parameters have been converted to PascalCase with backward compatibility in the form of aliases)
5. Return Related Items from configurations / flexible assets #132 (Added to applicable functions)
6. Troubleshooting New-ITGlueAttachments Forbidden #108 (Validated/updated attachment functions, everything should be gtg)
7. Addition of Comment Based help #56 (All comment based help should now be in place/up-to-date)
8. Support Revision History Parameters #30 (I believe this is in place now with all the updated function parameters)

Interesting discovery

OTP Passwords
#138 (This endpoint showed up a while ago but disappears off and on randomly from their documentation page. ITGlue might be trying to support this but as of 2024-10-07 it is no longer on their developer page again.)

Changes

• Not an exhausted listed

Pester Tests

1. Built out more robust tests
2. Should be compatible with cross-platform
3. The "tests" folder was moved out of the ITGlueAPI module folder into the root of the repo

GitHub Pages

1. PowerShell help now redirects to GitHub pages with secondary links going to ITGlues developer documentation
2. This will have to be turned on for the ITGlue repo "Settings > Pages > Deploy from branch > Master > docs"
3. Examples found at My repo
4. Links/formats will need to be adjusted to ITGlue repo. I think I converted the links correctly but it is a little hard to test other repos pages in my PR ;)

Azure DevOps (Pipelines)

1. Runs cross-platform build tests for various items. Pester tests, help updating, module building...etc
2. Examples found at My Azure DevOps page

Other changes

1. Switched from "Internal" & "Resources" to "Public" & "Private"
2. Module is now compiled into a single "psd1" & "psm1" (See "build > ITGlueAPI > Version#" for details)
3. Verbose output added to all commands to help with troubleshooting.
4. Each command will save general function data to global variables to also help with troubleshooting.

• Example Get-ITGlueUser -ID 8675309
• $Invoke_ITGlueRequest_Parameters = Information about the API call
• $Get_ITGlueUser_Parameters = Information about the parameters users
• $Get_ITGlueUser_ParametersQuery = Information about the query filters used

6. Functions that modify data now support "ShouldProcess" (Might need some tweaks here)
7. All functions now have a begin, process, & end to support input processing methods
8. Some functions now have pipeline support

• Example 8675309,123456 |Get-ITGlueUser

9. Examples are consolidated into a single "examples" folder instead of having two different repos.
10. ReadMe page updated with new information and format (pictures, links..etc)
11. New and updated Issue & PR templates

[adrianwells]

@Celerium this is an impressive contribution. Thank you! Will attempt to review.

[adrianwells]

Looks like an email address is desired here, thoughts?

[Celerium]

Ya there are a few placeholder items throughout this commit that I couldn't populate as I didn't know if this proposed change would be accepted plus what item to use in its place.

[adrianwells]

OK. Just noting them for now.

[adrianwells]

Another email address placeholder and bonus period at end of line

[Celerium]

oops, that'll be an easy fix, and ya another placeholder from a canned security readme

[adrianwells]

Another email address placeholder for consideration

[davidhaymond]

Thanks for this massive contribution, @Celerium! I'll attempt to review it this week.

[cksapp]

While we are possibly introducing some slightly breaking changes in this PR, might I suggest updating the ApiKey parameter from a string to [System.Security.SecureString] to allow piping directly a secure string object for the API key directly to the function.

This would help to prevent possible capture by logging, and a few additional benefits as well. Please let me know if there are any thoughts, thx.

Suggested change

	Add-ITGlueAPIKey -ApiKey (ConvertTo-SecureString 'some_api_key' -AsPlainText)
	Will use the seucre string entered into the [ -ApiKey ] parameter
	.EXAMPLE
	(ConvertTo-SecureString '12345' -AsPlainText) | Add-ITGlueAPIKey
	Will use the secure string passed into it as its API key
	.NOTES
	N/A
	.LINK
	https://itglue.github.io/ITGlue-PowerShellWrapper/site/Internal/Add-ITGlueAPIKey.html
	.LINK
	https://github.com/itglue/powershellwrapper
	#>
	[CmdletBinding()]
	[Alias('Set-ITGlueAPIKey')]
	Param (
	[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
	[AllowEmptyString()]
	[Alias('Api_Key')]
	[securestring]$ApiKey
	)
	begin {}
	process{
	Set-Variable -Name 'ITGlue_API_Key' -Value $ApiKey -Option ReadOnly -Scope Global -Force
	}

[Celerium]

Hi everyone

I just wanted to check in and see if this is something that would like to be done. Is there anything I can help with or better explain?

I would also like to throw out that if this isn't something that interests the community I will not take offense if you say thank you but we're good and close it.

[davidhaymond]

@Celerium Once again, I thank you for your contribution. I wonder if it would be better to open a new PR for each independent change you'd like to make. Keeping each change separate will help with review, community discussion, and keeping a clean commit history. This PR is difficult to review because it is such a significant overhaul, and I haven't had the time yet to parse through it all.

@adrianwells, thoughts on this?