Orbit.Teams

0.9.3

Public/Support/CallQueue/Checkpoint-TeamsCallQueuePrompt.ps1

                                # Module:   Orbit.Teams

# Function: CallQueue

# Author:   David Eberhardt

# Updated:  06-AUG 2023

# Status:   Live

function Checkpoint-TeamsCallQueuePrompt {

  <#

  .SYNOPSIS

    Processes the Call Queue Prompt value given and returns an Object for further processing

  .DESCRIPTION

    Helper function to find the correct values to pass on to New-CsCallQueue and Set-CsCallQueue

  .PARAMETER Prompt

    Required. Either Overflow, Timeout or NoAgent

  .PARAMETER String

    Required. String as a Path for a Recording or a Text-to-Voice string. Function determines Type

  .EXAMPLE

    $TeamsCallQueuePrompt = Checkpoint-TeamsCallQueuePrompt -Prompt Overflow -String "Welcome to Contoso"

    Returns an Object with all relevant Prompt Data of a Text-to-Voice String for the CallQueue

    Except for Greeting, requires replacing of the * character of the Parameter key in the returned Object

  .EXAMPLE

    $TeamsCallQueuePrompt = Checkpoint-TeamsCallQueuePrompt -Prompt Overflow -String "c:\temp\Recording.wav"

    Imports the AudioFile and returns the CsOnlineAudioFile Object with all relevant Prompt Data for the CallQueue

  .INPUTS

    System.String

  .OUTPUTS

    System.Object

  .NOTES

    With the introduction of a third Exception type (NoAgent), refactoring of the CallQueue Cmdlets was necessary

    This functions allows for processing of Agent and Target in a concise manner covering the requirements depending on

    Function invoking this one.

    Please NOTE: The output of this CmdLet requires further manipulation before it can be applied to a Call Queue

    The Parameter Key is returned with a * in the name (except for the Greeting)

    requires replacing of the * character of the Parameter key in the returned Object

    The Value for Parameter will be the Provided Prompt (Overflow|Timeout|NoAgent) followed by a * and the type of Object

    For Example for an OverflowPrompt, the Parameter is returned as Overflow*AudioFilePrompt

    To apply this parameter to a CallQueue, replace the * with one of the non-default Actions:

    Disconnect, RedirectPerson, RedirectVoiceApp, RedirectPhoneNumber, RedirectVoicemail, SharedVoicemail

    New-TeamsCallQueueTrigger uses this, and will apply to all of the above with the Parameter 'SetPromptForAllTypes'

  .COMPONENT

    TeamsCallQueue

  .FUNCTIONALITY

    Determining the correct values to pass on to New-CsCallQueue and Set-CsCallQueue respectively

  .LINK

    https://github.com/DEberhardt/Orbit/tree/main/docs/Orbit.Teams/Checkpoint-TeamsCallQueuePrompt.md

  .LINK

    https://github.com/DEberhardt/Orbit/tree/main/docs/

  #>

  [CmdletBinding()]

  [OutputType([System.Object])]

  param(

    [Parameter(Mandatory, HelpMessage = 'Type of prompt to process')]

    [ValidateSet('Greeting', 'MusicOnHold', 'OverflowPrompt', 'TimeoutPrompt', 'NoAgentPrompt')]

    [string]$Prompt,

    [Parameter(Mandatory, HelpMessage = 'Main String. Path the the recording OR Text-to-Voice string')]

    [string]$String

  ) #param

  begin {

    Show-OrbitFunctionStatus -Level Live

    Write-Verbose -Message "[BEGIN  ] $($MyInvocation.MyCommand)"

    # Setting Preference Variables according to Upstream settings

    if (-not $PSBoundParameters['Verbose']) { $VerbosePreference = $PSCmdlet.SessionState.PSVariable.GetValue('VerbosePreference') }

    $DebugPreference = if (-not $PSBoundParameters['Debug']) { $PSCmdlet.SessionState.PSVariable.GetValue('DebugPreference') } else { 'Continue' }

    $InformationPreference = if ( $PSBoundParameters['InformationAction']) { $PSCmdlet.SessionState.PSVariable.GetValue('InformationAction') } else { 'Continue' }

    $OutputObject = @{

      Prompt    = $Prompt

      Parameter = $null

      Type      = $null

      Value     = $null

    }

  } #begin

  process {

    Write-Verbose -Message "[PROCESS] $($MyInvocation.MyCommand)"

    if ($String -match '.(wav|wma|mp3)$') {

      # Recording - File import handles file existence, format & size requirements

      $FileName = Split-Path $String -Leaf

      Write-Verbose -Message "$($MyInvocation.MyCommand) - $Prompt`: Parsing: '$FileName'"

      $AudioFile = Import-TeamsAudioFile -ApplicationType CallQueue -File "$String" -ErrorAction STOP

      Write-Verbose -Message "$($MyInvocation.MyCommand) - $Prompt`: Using:   '$($AudioFile.FileName)'"

      $OutputObject.Type = 'AudioFilePrompt'

      $OutputObject.Value = $AudioFile.Id

      $OutputObject.Parameter = switch ( $Prompt ) {

        'Greeting' { 'WelcomeMusicAudioFileId' }

        'MusicOnHold' { 'MusicOnHoldAudioFileId' }

        'OverflowPrompt' { 'Overflow*AudioFilePrompt' }

        'TimeoutPrompt' { 'Timeout*AudioFilePrompt' }

        'NoAgentPrompt' { 'NoAgent*AudioFilePrompt' }

      }

    }

    else {

      if ( $Prompt -eq 'MusicOnHold' ) {

        Write-Error -Message "$($MyInvocation.MyCommand) - $Prompt` must be an AudioFile'" -ErrorAction Stop

      }

      # Text-To-Voice is assumed if String does not end with a supported file extension

      if ( $String.length -gt 1000 ) {

        $String = $String.Substring(0, 999).Trim()

        Write-Warning -Message "$Prompt`: Message too long, cutting string at 1000 characters. Please validate!"

      }

      Write-Verbose -Message "$($MyInvocation.MyCommand) - $Prompt`: Using String as Text-to-Voice Prompt: '$String'"

      $OutputObject.Type = 'TextToSpeechPrompt'

      $OutputObject.Value = $String

      $OutputObject.Parameter = switch ( $Prompt ) {

        'Greeting' { 'WelcomeTextToSpeechPrompt' }

        'OverflowPrompt' { 'Overflow*TextToSpeechPrompt' }

        'TimeoutPrompt' { 'Timeout*TextToSpeechPrompt' }

        'NoAgentPrompt' { 'NoAgent*TextToSpeechPrompt' }

      }

    }

    return $OutputObject

  }

  end {

    Write-Verbose -Message "[END    ] $($MyInvocation.MyCommand)"

  } #end

} #Checkpoint-TeamsCallQueuePrompt