TeamsFunctions

21.1.10-prerelease

Public/Functions/AutoAttendant/New-TeamsAutoAttendantCallFlow.ps1

# Module: TeamsFunctions
# Function: AutoAttendant
# Author: David Eberhardt
# Updated: 12-DEC-2020
# Status: RC




function New-TeamsAutoAttendantCallFlow {
  <#
  .SYNOPSIS
    Creates a Call Flow Object to be used in Auto Attendants
  .DESCRIPTION
    Creates a Call Flow with optional Prompt and Menu to be used in Auto Attendants
    Wrapper for New-CsAutoAttendantCallFlow with friendly names
    Combines New-CsAutoAttendantMenu, New-CsAutoAttendantPrompt
  .PARAMETER Name
    Optional. Name of the Call Flow if desired. Otherwise generated automatically.
  .PARAMETER Greeting
    Optional. A Prompts Object, String or Full path to AudioFile.
    A Prompts Object will be used as is, otherwise it will be created dependent of the provided String
    A String will be used as Text-to-Voice. A File ending in .wav, .mp3 or .wma will be used to create a recording.
  .PARAMETER Menu
    Optional. Menu Object to be used.
  .PARAMETER Disconnect
    Optional. Creates a default Menu, disconnecting the Call.
  .PARAMETER TransferToCallTarget
    Optional. String. Creates a default Menu, redirecting to the specified Call Target
    UserPrincipalName (User, ApplicationEndpoint), Group Name (Shared Voicemail), Tel Uri (ExternalPstn)
  .EXAMPLE
    New-TeamsAutoAttendantCallFlow [-Name "Default Call Flow"] -Menu $MenuObject [-Greeting $PromptObject]
    Classic behaviour, synonymous with functionality provided by New-CsAutoAttendantCallFlow. Please see parameters there.
    Creates Call Flow with the Menu Object provided and optionally applies the PromptObject as the Greeting.
  .EXAMPLE
    New-TeamsAutoAttendantCallFlow -Menu $MenuObject -Greeting "Welcome to Contoso"
    Creates Call Flow with the Menu Object provided and creates the Greeting with the provided String (Text-to-voice)
  .EXAMPLE
    New-TeamsAutoAttendantCallFlow -TransferToCallTarget "John@domain.com"
    Creates a Menu Object to transfer the Call to a call Target and no Greeting
    UserPrincipalName (User, ApplicationEndpoint), Group Name (Shared Voicemail), Tel Uri (ExternalPstn)
  .EXAMPLE
    New-TeamsAutoAttendantCallFlow -Disconnect
    Default. Creates Call Flow with a default Disconnect and no Greeting
  .NOTES
    Limitations: DialByName
  .INPUTS
    System.String
  .OUTPUTS
    System.Object
  .COMPONENT
    TeamsAutoAttendant
  .LINK
    https://github.com/DEberhardt/TeamsFunctions/tree/master/docs/
    .LINK
    New-TeamsAutoAttendant
    .LINK
    Set-TeamsAutoAttendant
    .LINK
    New-TeamsCallableEntity
    .LINK
    New-TeamsAutoAttendantCallFlow
    .LINK
    New-TeamsAutoAttendantMenu
    .LINK
    New-TeamsAutoAttendantMenuOption
    .LINK
    New-TeamsAutoAttendantPrompt
    .LINK
    New-TeamsAutoAttendantSchedule
    .LINK
    New-TeamsAutoAttendantDialScope
  #>

  [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = "Disconnect", ConfirmImpact = 'Low')]
  [Alias('New-TeamsAAFlow')]
  [OutputType([System.Object])]
  param(
    [Parameter(HelpMessage = "Optional Name of the Call Flow")]
    [ValidateLength(5, 63)]
    [string]$Name,

    [Parameter(HelpMessage = "Prompt Object, Text-To-Voice String or Full path to AudioFile")]
    #Type is determined in BEGIN block
    $Greeting,

    [Parameter(ParameterSetName = "Menu", HelpMessage = "Menu Object to be used")]
    [Object]$Menu,

    [Parameter(ParameterSetName = "Disconnect", HelpMessage = "Creates a menu, using Disconnect")]
    [switch]$Disconnect,

    [Parameter(ParameterSetName = "TransferToCallTarget", HelpMessage = "Creates a menu, redirecting to the Call Target")]
    [string]$TransferToCallTarget
  ) #param

  begin {
    Show-FunctionStatus -Level RC
    Write-Verbose -Message "[BEGIN ] $($MyInvocation.MyCommand)"

    # Asserting AzureAD Connection
    if (-not (Assert-AzureADConnection)) { break }

    # Asserting SkypeOnline Connection
    if (-not (Assert-SkypeOnlineConnection)) { break }

    # Setting Preference Variables according to Upstream settings
    if (-not $PSBoundParameters.ContainsKey('Verbose')) { $VerbosePreference = $PSCmdlet.SessionState.PSVariable.GetValue('VerbosePreference') }
    if (-not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = $PSCmdlet.SessionState.PSVariable.GetValue('ConfirmPreference') }
    if (-not $PSBoundParameters.ContainsKey('WhatIf')) { $WhatIfPreference = $PSCmdlet.SessionState.PSVariable.GetValue('WhatIfPreference') }
    if (-not $PSBoundParameters.ContainsKey('Debug')) { $WhatIfPreference = $PSCmdlet.SessionState.PSVariable.GetValue('DebugPreference') } else { $DebugPreference = 'Continue' }

    # Preparing Splatting Object
    $Parameters = $null
  } #begin

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

    #region Greeting
    if ($Greeting) {
      # Processing Greeting
      $GreetingType = ($Greeting | Get-Member | Select-Object TypeName -First 1).TypeName
      switch ($GreetingType) {
        "Deserialized.Microsoft.Rtc.Management.Hosted.OAA.Models.Prompt" {
          Write-Verbose -Message "Call Flow - Greeting provided is a Prompt Object"
          $Parameters += @{'Greetings' = @($Greeting) }

        }
        "System.String" {
          Write-Verbose -Message "Call Flow - Greeting provided as a String"
          # Process Greeting
          try {
            $GreetingObject = New-TeamsAutoAttendantPrompt -String $Greeting
            if ($GreetingObject) {
              Write-Verbose -Message "Prompts - Adding 1 Prompts created (Greeting)"
              $Parameters += @{'Greetings' = $GreetingObject }
            }
          }
          catch {
            Write-Warning -Message "Call Flow - Menu - Greeting - Error creating prompt. Omitting Greeting. Exception Message: $($_.Exception.Message)"
          }
        }

        default {
          Write-Error -Message "Type not accepted as a Greeting/Prompt, please provide a Prompts Object or a String" -ErrorAction Stop
        }
      }
    }
    #endregion


    #region Options
    # Processing Options
    switch ($PSCmdlet.ParameterSetName) {
      "Menu" {
        if ($Menu) {
          #<#
          $MenuType = ($Menu | Get-Member | Select-Object TypeName -First 1).TypeName
          if ($MenuType -eq "Deserialized.Microsoft.Rtc.Management.Hosted.OAA.Models.Menu") {
            Write-Verbose -Message "Menu - Provided Object is a Menu Object. Adding Menu"
          }
          else {
            Write-Error -Message "Menu - Provided Object not of correct Object Type. Please create a Menu with New-TeamsAutoAttendantMenu or New-CsAutoAttendantMenu" -ErrorAction Stop
          }
          #>
        }
        else {
          Write-Error -Message "Menu - Provided Object is NULL" -ErrorAction Stop
        }
      }

      "Disconnect" {
        $Menu = New-TeamsAutoAttendantMenu -Action Disconnect
      }

      "TransferToCallTarget" {
        $Menu = New-TeamsAutoAttendantMenu -Action TransferToCallTarget -CallTarget $TransferToCallTarget
      }
    }

    $Parameters += @{'Menu' = $Menu }
    #endregion


    #region Other Parameters
    if ( -not $Name) {
      $Name = "Call Flow using '$($PSCmdlet.ParameterSetName)'" + $(if ($Parameters.Greetings) { " and Greeting" })
    }
    $Parameters += @{'Name' = "$Name" }

    #endregion


    # Create Call Flow
    Write-Verbose -Message "[PROCESS] Creating Call Flow"
    if ($PSBoundParameters.ContainsKey('Debug')) {
      "Function: $($MyInvocation.MyCommand.Name): Parameters:", ($Parameters | Format-Table -AutoSize | Out-String).Trim() | Write-Debug
    }

    if ($PSCmdlet.ShouldProcess("$($Parameters.Name)", "New-CsAutoAttendantCallFlow")) {
      New-CsAutoAttendantCallFlow @Parameters
    }
  }

  end {
    Write-Verbose -Message "[END ] $($MyInvocation.MyCommand)"
  } #end
} #New-TeamsAutoAttendantCallFlow