Public/Set-iPilotTeamsUser.ps1
|
Function Set-iPilotTeamsUser { <# .Synopsis Updates a user in iPilot .Description Updates a user's iPilot properties with the provided User Principal Name .Parameter UserPrincipalName User's existing User Principal Name. .Parameter NewUserPrincipalName User's new User Principal Name. .Parameter FirstName User's First Name. .Parameter LastName User's Last Name. .Parameter NewTelephoneNumber TelephoneNumber (10-digits). .Parameter Note User's iPilot Note field value. .Parameter ApiVersion Version of the iPilot to use. Defaults to v1. .Parameter iPilotDomain iPilot Domain Name. .Example # Sets jdoe@contoso.com's iPilot note field to "Sales", First Name to John, and Last Name to Doe Set-iPilotTeamsUser -UserPrincipalName jdoe@contoso.com -FirstName "John" -LastName "Doe" -Note "Sales" .Example # Rename jdoe@contoso.com's UPN to jdane@contoso.com and change Last Name to Dane Set-iPilotTeamsUser -UserPrincipalName jdoe@contoso.com -NewUserPrincipalName jdane@contoso.com -LastName "Dane" #> Param ( [System.String] [Parameter(Mandatory = $true)] $UserPrincipalName, [System.String] $NewUserPrincipalName, [System.Int64] [ValidatePattern('\d{5,15}$')] [Parameter(Mandatory = $false, HelpMessage = 'Provide telephone number in E.164 format without the + character. Ex. 12223334444')] $TelephoneNumber, [System.String] [Parameter(Mandatory = $true)] $FirstName, [System.String] [Parameter(Mandatory = $true)] $LastName, [System.String] $Note, [System.String] $ApiUrl = "https://api.nuwave.com", [System.String] $ApiKey, [System.String] $ApiVersion = "v1", [System.String] $iPilotDomain, [System.Management.Automation.PSCredential] $Credential ) Begin { # UserPrincipalName validation if ($UserPrincipalName -and $UserPrincipalName -notlike "*@*.*") { throw "Check the formatting of the user's User Principal Name. Format should be jdoe@contoso.com" } # NewUserPrincipalName validation if ($NewUserPrincipalName -and $NewUserPrincipalName -notlike "*@*.*") { throw "Check the formatting of the user's new User Principal Name. Format should be jdoe@contoso.com" } # First Name Last Name validation if ($FirstName -and $LastName) { #Continue On, both are filled in } else { throw "Please include FirstName & LastName parameters" } # Set iPilot Domain if (!$global:IP_iPilotDomain -and !$iPilotDomain) { throw "Run Get-iPilotTeamsDomain or provide domain using -iPilotDomain" } elseif (!$iPilotDomain) { $iPilotDomain = $global:IP_iPilotDomain Write-Verbose "iPilot Domain: $iPilotDomain" } # else use passed in iPilotDomain } Process { # Verbose Switch if($PSBoundParameters.containskey("Verbose")) { $PreviousVerbosePreference = $VerbosePreference $VerbosePreference = "continue" } # Debug Switch if($PSBoundParameters.containskey("Debug")) { $PreviousDebugPreference = $DebugPreference $DebugPreference = "continue" } # Get/re-use OAuth Token $InitializeiPilotSessionSplat = @{ ApiUrl = $ApiUrl ApiVersion = $ApiVersion ApiKey = $ApiKey Credential = $Credential } if ($global:IP_Instance) { $InitializeiPilotSessionSplat += @{ Instance = $global:IP_Instance } } if ($VerbosePreference -eq "Continue") { $InitializeiPilotSessionSplat += @{ Verbose = $true } } if ($DebugPreference -eq "Continue") { $InitializeiPilotSessionSplat += @{ Debug = $true } } Initialize-iPilotSession @InitializeiPilotSessionSplat # Get user's iPilot ID Try { $User = Get-iPilotTeamsUser -FilterByUserPrincipalName $UserPrincipalName -ErrorAction Stop if ($null -eq $User.Id) { throw "$UserPrincipalName not found in iPilot. Verify user is able to be retreived using `'Get-iPilotTeamsUser -FilterByUserPrincipalName $UserPrincipalName`'" } Write-Verbose "User:`n$User" } Catch { Write-Error "Failed to retrieve $UserPrincipalName from iPilot`n`nURL: $($NewiPilotUserRequestUri)`nError: $($_)" break } # Build iPilot API Request $SetiPilotUserRequestUri = "$ApiUrl/$ApiVersion/msteams/$iPilotDomain/users/$($User.id)" if ($global:IP_Instance) { $SetiPilotUserRequestUri += "?instance=$global:IP_Instance" } Write-Verbose "SetiPilotUserRequestUri: $SetiPilotUserRequestUri" # Build Request Body Write-Verbose "Request Method: Put" #region Add each available field to update to the Request Body # Add NewUserPrincipalName to Body If ($NewUserPrincipalName) { Write-Verbose "Set UserPrincipalName to $NewUserPrincipalName" $SetiPilotUserRequestBody = @{ upn = $NewUserPrincipalName } } # Add FirstName to Body If ($FirstName) { Write-Verbose "Set FirstName to $FirstName" $SetiPilotUserRequestBody += @{ firstName = $FirstName } } # Add LastName to Body If ($LastName) { Write-Verbose "Set LastName to $LastName" $SetiPilotUserRequestBody += @{ lastName = $LastName } } # Add TelephoneNumber to Body If ($TelephoneNumber) { Write-Verbose "Set TelephoneNumber to $TelephoneNumber" $SetiPilotUserRequestBody += @{ TelephoneNumber = $TelephoneNumber } } # Add Note to Body If ($Note) { Write-Verbose "Set Note to $Note" $SetiPilotUserRequestBody += @{ note = $Note } } $CompletedSetiPilotUserRequestBody = @{ user = $SetiPilotUserRequestBody } #endregion Add each available field to update to the Request Body # Splat Invoke-RestMethod Parameters $SetiPilotUserInvokeParams = @{ Uri = $SetiPilotUserRequestUri Method = "Put" ContentType = "application/json" Headers = @{ "X-Access-Token" = $global:IP_iPilotOAuthToken.access_token "x-api-key" = $global:IP_iPilotApiKey } Body = $CompletedSetiPilotUserRequestBody | ConvertTo-Json } Write-Verbose "SetiPilotUserRequestUri: $SetiPilotUserRequestUri" # Execute the REST API Try { $SetiPilotUserResponse = Invoke-RestMethod @SetiPilotUserInvokeParams if ($SetiPilotUserResponse.statusCode -ne 200) { throw $SetiPilotUserResponse.status } return $SetiPilotUserResponse } Catch { Write-Error "iPilot user $($UserPrincipalName) could not be updated`n`nURL: $($SetiPilotUserRequestUri)`nBody: $($SetiPilotUserRequestBody | Format-Table | Out-String)`nError: $($_)" break } # Return Available Numbers if ($SetiPilotUserResponse.statuscode -eq 200) { Write-Output "Successfully updated iPilot User.`nUPN: $UserPrincipalName`nBody: $SetiPilotUserRequestBody" } else { Write-Error "Failed to update iPilot User.`n UPN: $UserPrincipalName`n Body: $SetiPilotUserRequestBody Exception: $($_.Exception.Message) Status:$($SetiPilotUserResponse.status)`n Error:$($SetiPilotUserResponse.data | Format-Table | Out-String)" } # Verbose Switch if($PSBoundParameters.containskey("Verbose")) { $VerbosePreference = $PreviousVerbosePreference } # Debug Switch if($PSBoundParameters.containskey("Debug")) { $DebugPreference = $PreviousDebugPreference } } } |