UcmPSTools

0.1.2-alpha

public/New-UcmTeamsResourceAccount.ps1

                                #PerformScriptSigning

Function New-UcmTeamsResourceAccount

{

    <#

            .SYNOPSIS

            Checks for and creates a new Microsoft Teams Resource Account for a Call Queue or AutoAttendant

            .DESCRIPTION

            Checks for and creates a new Microsoft Teams Resource Account for a Call Queue or AutoAttendant

            This function will also set the application ID depending on the setting of the ResourceType parameter

            .EXAMPLE

            New-UcmTeamsResourceAccount -UPN calebs@contoso.onmicrosoft.com -DisplayName 'Caleb Sills' -ResourceType CallQueue

            .PARAMETER UPN

            The UPN of the user you wish to create, eg: "button.mash@contoso.com"

            .PARAMETER DisplayName

            The Display Name of the user you wish to create, eg: "Button Mash"

            .PARAMETER ResourceType

            Used to set the ApplicationID of the new user

            Valid options are "AutoAttendant" or "CallQueue"

            .INPUTS

            This function accepts both parameter and pipline input

            .OUTPUT

            This Cmdet returns a PSCustomObject with multiple keys to indicate status

            $Return.Status

            $Return.Message

            Return.Status can return one of four values

            "OK"      : Created Resource Account

            "Warn"    : Resource Account already exists, creation was skipped

            "Error"   : Something happend when attempting to create the Resource Account, check $return.message for more information

            "Unknown" : Cmdlet reached the end of the fucntion without returning anything, this shouldnt happen, if it does please log an issue on Github

            Return.Message returns descriptive text showing the connected tenant, mainly for logging or reporting

            .LINK

            http://www.UcMadScientist.com

            https://github.com/Atreidae/UcmPsTools

            .ACKNOWLEDGEMENTS

            .NOTES

            Version:        1.1

            Date:            03/04/2021

            .VERSION HISTORY

            1.1: Updated to "Ucm" naming convention

            Better inline documentation

            1.0: Initial Public Release

            .REQUIRED FUNCTIONS/MODULES

            Modules

            Microsoft Teams                        (Install-Module MicrosoftTeams)

            UcmPSTools                            (Install-Module UcmPsTools) Includes Cmdlets below.

            Cmdlets

            Write-UcmLog:                         https://github.com/Atreidae/UcmPsTools/blob/main/public/Write-UcmLog.ps1

            New-UcmSFBOConnection                https://github.com/Atreidae/UcmPsTools/blob/main/public/New-UcmSFBOConnection.ps1

            .REQUIRED PERMISIONS

            'Teams Administrator' or better

    #>

    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseProcessBlockForPipelineCommand', '', Scope='Function')] #todo, https://github.com/Atreidae/UcmPSTools/issues/23

    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Scope='Function')] #Todo https://github.com/Atreidae/UcmPSTools/issues/27

    Param

    (

        [Parameter(ValueFromPipelineByPropertyName=$true, Mandatory, Position=1,HelpMessage='The UPN of the user you wish to create, eg: "button.mash@contoso.com"')] [string]$UPN,

        [Parameter(ValueFromPipelineByPropertyName=$true, Mandatory, Position=2,HelpMessage='The Display Name of the user you wish to create, eg: "Button Mash"')] [string]$DisplayName,

        [Parameter(ValueFromPipelineByPropertyName=$true, Mandatory, Position=3,HelpMessage='Used to set the ApplicationID of the new user, Valid options are "AutoAttendant" or "CallQueue"')] [ValidateSet('AutoAttendant', 'CallQueue')] [string]$ResourceType

    )

    #region FunctionSetup, Set Default Variables for HTML Reporting and Write Log

    $function = 'New-UcmTeamsResourceAccount'

    [hashtable]$Return = @{}

    $return.Function = $function

    $return.Status = "Unknown"

    $return.Message = "Function did not return a status message"

    # Log why we were called

    Write-UcmLog -Message "$($MyInvocation.InvocationName) called with $($MyInvocation.Line)" -Severity 1 -Component $function

    Write-UcmLog -Message "Parameters" -Severity 1 -Component $function -LogOnly

    Write-UcmLog -Message "$($PsBoundParameters.Keys)" -Severity 1 -Component $function -LogOnly

    Write-UcmLog -Message "Parameters Values" -Severity 1 -Component $function -LogOnly

    Write-UcmLog -Message "$($PsBoundParameters.Values)" -Severity 1 -Component $function -LogOnly

    Write-UcmLog -Message "Optional Arguments" -Severity 1 -Component $function -LogOnly

    Write-UcmLog -Message "$Args" -Severity 1 -Component $function -LogOnly

    #endregion FunctionSetup

    #region FunctionWork

    #Calculate the Application ID for the new account

    Switch ($ResourceType)

    {

        'AutoAttendant' {$ApplicationID ='ce933385-9390-45d1-9512-c8d228074e07'}

        'CallQueue' {$ApplicationID ='11cd3e2e-fccb-42ad-ad00-878b93575e07'}

    }

    #Check to see if we are connected to SFBO

    $Test = (Test-UcmSFBOConnection)

    If ($Test.Status -eq "Error")

    {

        #Test-UcmSFBOConnection returned an error, return an error

        Write-UcmLog -Message "Something went wrong creating user $UPN" -Severity 3 -Component $function

        Write-UcmLog -Message "Test-UcmSFBOConnection could not locate an SFBO connection" -Severity 2 -Component $function

        $Return.Status = "Error"

        $Return.Message = "No SFBO Connection"

        Return $Return

    }

    #Check to see if the requested account exists

    Write-UcmLog -Message "Checking for Existing Resource Account $UPN ..." -Severity 2 -Component $function

    #TODO, we should be checking if that UPN exists in general. https://github.com/Atreidae/UcmPSTools/issues/1

    $AppInstance = $null

    $AppInstance = (Get-CsOnlineApplicationInstance | Where-Object {$_.UserPrincipalName -eq $UPN})#TODO is there a better way to filter this? https://github.com/Atreidae/UcmPSTools/issues/2

    If ($AppInstance.UserPrincipalName -eq $UPN)

    {

        #We found a resource account with the same name, assume it already been made, return a warning and skip

        Write-UcmLog -Message "Resource Account already exists, Skipping" -Severity 3 -Component $function

        $Return.Status = "Warning"

        $Return.Message = "Skipped: Account Already Exists"

        Return $Return

    }

    Else

    {

        #Resource account doesnt exist, let's make them

        Try

        {

            Write-UcmLog -Message "Account not found. Creating user $UPN" -Severity 2 -Component $function

            [Void] (New-CsOnlineApplicationInstance -UserPrincipalName $UPN -DisplayName $DisplayName -ApplicationId $ApplicationID -ErrorAction Stop)

            #We created the account OK, return an OK result.

            Write-UcmLog -Message "Resource Account Created Sucessfully" -Severity 2 -Component $function

            $Return.Status = "OK"

            $Return.Message = "Resource Account Created"

            Return $Return

        }

        Catch

        {

            #Something went wrong making the resource account, return an error

            Write-UcmLog -Message "Something went wrong creating resource account $UPN" -Severity 3 -Component $function

            Write-UcmLog -Message $Error[0] -Severity 3 -Component $Function

            $Return.Status = "Error"

            $Return.Message = $Error[0]

            Return $Return

        }

    }

    #endregion FunctionWork

    #region FunctionReturn

    #Default Return Variable for my HTML Reporting Fucntion

    Write-UcmLog -Message "Reached end of $function without a Return Statement" -Severity 3 -Component $function

    $return.Status = "Unknown"

    $return.Message = "Function did not encounter return statement"

    Return $Return

    #endregion FunctionReturn

}

# SIG # Begin signature block

# MIIRwgYJKoZIhvcNAQcCoIIRszCCEa8CAQExCzAJBgUrDgMCGgUAMGkGCisGAQQB

# gjcCAQSgWzBZMDQGCisGAQQBgjcCAR4wJgIDAQAABBAfzDtgWUsITrck0sYpfvNR

# AgEAAgEAAgEAAgEAAgEAMCEwCQYFKw4DAhoFAAQUICj1TV98PoN9D6wTF2rw5yIY

# SROggg4OMIIGsDCCBJigAwIBAgIQCK1AsmDSnEyfXs2pvZOu2TANBgkqhkiG9w0B

# AQwFADBiMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYD

# VQQLExB3d3cuZGlnaWNlcnQuY29tMSEwHwYDVQQDExhEaWdpQ2VydCBUcnVzdGVk

# IFJvb3QgRzQwHhcNMjEwNDI5MDAwMDAwWhcNMzYwNDI4MjM1OTU5WjBpMQswCQYD

# VQQGEwJVUzEXMBUGA1UEChMORGlnaUNlcnQsIEluYy4xQTA/BgNVBAMTOERpZ2lD

# ZXJ0IFRydXN0ZWQgRzQgQ29kZSBTaWduaW5nIFJTQTQwOTYgU0hBMzg0IDIwMjEg

# Q0ExMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1bQvQtAorXi3XdU5

# WRuxiEL1M4zrPYGXcMW7xIUmMJ+kjmjYXPXrNCQH4UtP03hD9BfXHtr50tVnGlJP

# DqFX/IiZwZHMgQM+TXAkZLON4gh9NH1MgFcSa0OamfLFOx/y78tHWhOmTLMBICXz

# ENOLsvsI8IrgnQnAZaf6mIBJNYc9URnokCF4RS6hnyzhGMIazMXuk0lwQjKP+8bq

# HPNlaJGiTUyCEUhSaN4QvRRXXegYE2XFf7JPhSxIpFaENdb5LpyqABXRN/4aBpTC

# fMjqGzLmysL0p6MDDnSlrzm2q2AS4+jWufcx4dyt5Big2MEjR0ezoQ9uo6ttmAaD

# G7dqZy3SvUQakhCBj7A7CdfHmzJawv9qYFSLScGT7eG0XOBv6yb5jNWy+TgQ5urO

# kfW+0/tvk2E0XLyTRSiDNipmKF+wc86LJiUGsoPUXPYVGUztYuBeM/Lo6OwKp7AD

# K5GyNnm+960IHnWmZcy740hQ83eRGv7bUKJGyGFYmPV8AhY8gyitOYbs1LcNU9D4

# R+Z1MI3sMJN2FKZbS110YU0/EpF23r9Yy3IQKUHw1cVtJnZoEUETWJrcJisB9IlN

# Wdt4z4FKPkBHX8mBUHOFECMhWWCKZFTBzCEa6DgZfGYczXg4RTCZT/9jT0y7qg0I

# U0F8WD1Hs/q27IwyCQLMbDwMVhECAwEAAaOCAVkwggFVMBIGA1UdEwEB/wQIMAYB

# Af8CAQAwHQYDVR0OBBYEFGg34Ou2O/hfEYb7/mF7CIhl9E5CMB8GA1UdIwQYMBaA

# FOzX44LScV1kTN8uZz/nupiuHA9PMA4GA1UdDwEB/wQEAwIBhjATBgNVHSUEDDAK

# BggrBgEFBQcDAzB3BggrBgEFBQcBAQRrMGkwJAYIKwYBBQUHMAGGGGh0dHA6Ly9v

# Y3NwLmRpZ2ljZXJ0LmNvbTBBBggrBgEFBQcwAoY1aHR0cDovL2NhY2VydHMuZGln

# aWNlcnQuY29tL0RpZ2lDZXJ0VHJ1c3RlZFJvb3RHNC5jcnQwQwYDVR0fBDwwOjA4

# oDagNIYyaHR0cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0VHJ1c3RlZFJv

# b3RHNC5jcmwwHAYDVR0gBBUwEzAHBgVngQwBAzAIBgZngQwBBAEwDQYJKoZIhvcN

# AQEMBQADggIBADojRD2NCHbuj7w6mdNW4AIapfhINPMstuZ0ZveUcrEAyq9sMCcT

# Ep6QRJ9L/Z6jfCbVN7w6XUhtldU/SfQnuxaBRVD9nL22heB2fjdxyyL3WqqQz/WT

# auPrINHVUHmImoqKwba9oUgYftzYgBoRGRjNYZmBVvbJ43bnxOQbX0P4PpT/djk9

# ntSZz0rdKOtfJqGVWEjVGv7XJz/9kNF2ht0csGBc8w2o7uCJob054ThO2m67Np37

# 5SFTWsPK6Wrxoj7bQ7gzyE84FJKZ9d3OVG3ZXQIUH0AzfAPilbLCIXVzUstG2MQ0

# HKKlS43Nb3Y3LIU/Gs4m6Ri+kAewQ3+ViCCCcPDMyu/9KTVcH4k4Vfc3iosJocsL

# 6TEa/y4ZXDlx4b6cpwoG1iZnt5LmTl/eeqxJzy6kdJKt2zyknIYf48FWGysj/4+1

# 6oh7cGvmoLr9Oj9FpsToFpFSi0HASIRLlk2rREDjjfAVKM7t8RhWByovEMQMCGQ8

# M4+uKIw8y4+ICw2/O/TOHnuO77Xry7fwdxPm5yg/rBKupS8ibEH5glwVZsxsDsrF

# hsP2JjMMB0ug0wcCampAMEhLNKhRILutG4UI4lkNbcoFUCvqShyepf2gpx8GdOfy

# 1lKQ/a+FSCH5Vzu0nAPthkX0tGFuv2jiJmCG6sivqf6UHedjGzqGVnhOMIIHVjCC

# BT6gAwIBAgIQDyLHeeRvkUFg5QtSFTT8FjANBgkqhkiG9w0BAQsFADBpMQswCQYD

# VQQGEwJVUzEXMBUGA1UEChMORGlnaUNlcnQsIEluYy4xQTA/BgNVBAMTOERpZ2lD

# ZXJ0IFRydXN0ZWQgRzQgQ29kZSBTaWduaW5nIFJTQTQwOTYgU0hBMzg0IDIwMjEg

# Q0ExMB4XDTIzMDIyMzAwMDAwMFoXDTI2MDIyMzIzNTk1OVowXjELMAkGA1UEBhMC

# QVUxETAPBgNVBAgTCFZpY3RvcmlhMRAwDgYDVQQHEwdCZXJ3aWNrMRQwEgYDVQQK

# EwtKYW1lcyBBcmJlcjEUMBIGA1UEAxMLSmFtZXMgQXJiZXIwggIiMA0GCSqGSIb3

# DQEBAQUAA4ICDwAwggIKAoICAQC47oExh25TrxvApIYdMRYvjOdZCb8WwgeTemm3

# ZY7BElIWu6+gzRGqQe8RFsN7oIgin5pvjTYIToxt1CCag2A5o8L0NtULmxJEegc+

# VaF24DZQqI4qGQGH/Qnglqys6+yPkwLnfeSxpeWe4u49HUUGDFIxHCh42MlCLp/f

# fHT49QhhpO+LyeLnDoUs6DmahyIb6NeE2cW5AYRXEesW7GRNfXzygBSlVWJOgvcy

# V5Y4IvAZVx2hKKMTjYFIz4/RYMg7fwYZEJ2LRJ/GnVazobKAvh6ZBet5KwVNI9EI

# 29DtWQyK/RoPOguTRcB5VuiZVlv0xjBYM7iJuH2Soa3StQYVxL/5gjZCC9WOs4NR

# EIGU3XmHoogFDvoT1vf1izMPFQzdZfgPvy/XXsbgTVo5ncesJ6WtZwqwCXG1K0XW

# IPZqTHolc1MyU6K1bEHO+7YWLpKgM9THl644G7PEhcKpNDsHlfvLVQdYhI55UJtc

# iyMrTw11CNECvk3GK1mrluvKsrxdaH6G3Sp9VVHRtef6OZ5SlzkM5ID4egB2bXRb

# R/69bEuZr5hhm+v2lBSWIbZj/Mva6i/a/TAvy4vvPLo3DRcASkYZDC4T8gDMzmpG

# Xs4jAc9sfTL9z+o5u1PLJHFGRjJ+Wa2CgSftCdbKLjn+AY9m8ipc8jmOBKNY9yGI

# pQWapQIDAQABo4ICAzCCAf8wHwYDVR0jBBgwFoAUaDfg67Y7+F8Rhvv+YXsIiGX0

# TkIwHQYDVR0OBBYEFOBsg1xudlbXVSql8pWbiHoTyZS/MA4GA1UdDwEB/wQEAwIH

# gDATBgNVHSUEDDAKBggrBgEFBQcDAzCBtQYDVR0fBIGtMIGqMFOgUaBPhk1odHRw

# Oi8vY3JsMy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVzdGVkRzRDb2RlU2lnbmlu

# Z1JTQTQwOTZTSEEzODQyMDIxQ0ExLmNybDBToFGgT4ZNaHR0cDovL2NybDQuZGln

# aWNlcnQuY29tL0RpZ2lDZXJ0VHJ1c3RlZEc0Q29kZVNpZ25pbmdSU0E0MDk2U0hB

# Mzg0MjAyMUNBMS5jcmwwPgYDVR0gBDcwNTAzBgZngQwBBAEwKTAnBggrBgEFBQcC

# ARYbaHR0cDovL3d3dy5kaWdpY2VydC5jb20vQ1BTMIGUBggrBgEFBQcBAQSBhzCB

# hDAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AuZGlnaWNlcnQuY29tMFwGCCsGAQUF

# BzAChlBodHRwOi8vY2FjZXJ0cy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVzdGVk

# RzRDb2RlU2lnbmluZ1JTQTQwOTZTSEEzODQyMDIxQ0ExLmNydDAJBgNVHRMEAjAA

# MA0GCSqGSIb3DQEBCwUAA4ICAQBOh5vRXqTCQzv0T1F2EgDkq5VnljlHsa7Ov/d/

# lpOvr8NebBiatxbhfhPCnToY7BD2f7YVsUuQ+VDdcIYsskcU5spBHcFYidg2jGu4

# 59FGMaS765XStDwGGTN/360gEsNYSnKWYL4+8jYWHlzRO0jHloyWz+gF5dYWzdDJ

# u1dudLIJ0RgrEVJeLSgIBWygLL5EyIzOPlrxztsILMSbdPTQLeBIm7ipOk4EACx1

# hhBVUsUoCAlASH+yCKDU4v2HFd7SzrkRUrf7XJ2Na2YsiHjiTGqHIE86KyvxGDhT

# 3n2/jX23Nh/bkWHurHwTfaTCOQ44ZlAbnZQjBlmrFn5hPMXRpciiQFmrKTPD/nuo

# 9MVnCciHEpHJ63/JZNF/eno1122/wVkL7MuRlCVHN7L/wuNQxQk3ARdIju6OD/Gi

# Mwg0Qih6HVWJtkHK3ExoUKKKUZCOvIeHxzp+K6FWUupPZKUgWzn4AHMxm6zr+Sde

# laIAACqAkxYsDYKbM7WlNi3uIH2HeXqU9uSDt5tgPpImrog/ab4HrhpDfITRgT1c

# cxaWQezpJEPC+kqVD41T3wlEie1Qm4vYWg+oBVEMBxVLh6CYbeppCRTEXRGnAiCH

# /Ma1uwyWnNCWxrhd1uSi6sj4ISzgnFyGCvsI0gavKpS5AQhapJgk6/fULTFeS+Ee

# kRH9FDGCAx4wggMaAgEBMH0waTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDkRpZ2lD

# ZXJ0LCBJbmMuMUEwPwYDVQQDEzhEaWdpQ2VydCBUcnVzdGVkIEc0IENvZGUgU2ln

# bmluZyBSU0E0MDk2IFNIQTM4NCAyMDIxIENBMQIQDyLHeeRvkUFg5QtSFTT8FjAJ

# BgUrDgMCGgUAoHgwGAYKKwYBBAGCNwIBDDEKMAigAoAAoQKAADAZBgkqhkiG9w0B

# CQMxDAYKKwYBBAGCNwIBBDAcBgorBgEEAYI3AgELMQ4wDAYKKwYBBAGCNwIBFTAj

# BgkqhkiG9w0BCQQxFgQU04EZ5CDETL0hufkx8eOHXtRXBA4wDQYJKoZIhvcNAQEB

# BQAEggIAQgSY/e82QatgQTYYZiilIbQB2106V+KbDDMEpRUYnGQ2cZFIGDUMyaq/

# v+kTriUyY5q3Giv5zGnpsS8ujyo/w11UIfgarsw35kCrj0qdkK8Ps43gFmwy5Dzz

# UlpTXvXuf4A2T+FygA8NkY1DksgNw5wnS2mkTQgjcU7gx0imogzQ8ifn8MYv3Tos

# XDyKKt07GNE4fo0Pcs5gKRyi1fFYOKkBMqzn6T3+0lxfvrIGkVMXf/Wp2x8qY3I6

# RntoEPmXdqh1TT7f8aFOTD4uJhbMqqs+a5aMRu4S/O/Te40QwJg55p2Ehya+0g8/

# jR45t+h3ZnDP21cilChQh2jAuZR+JEpcwtFGn1srKg9wt3IzprSknobTgN7zksXX

# K1tfKtXiWEvNEL7msV4HzHeXJNpMKPGisA5b15Hvp7wok9tffMihaNpgBS0UcpA7

# 2Y/DDmjoruOofh8LkB656iZ2vsoEaD18gWtRQTneI2QujHjY9/04qUnJ7kokMKwm

# /5/YEneVMZ1X0CSqKQ2RTNcVJAzjTPVdohVRjLt4Q3/lbjuKJR2EEA9tNbYcISBl

# RvHmHJXt1mhIlE81+vbV+XvXQ3gx+UGDKFAak1a3rNBGaPEtrdkCEdNYnzIJ018i

# 2PmpSuaEXdkQxwgWlJkg7P+BArUXaI8p9hDYS1UP0LTZIO/+p4k=

# SIG # End signature block