New-UcmCsFixedNumberDiversion

Creates an AutoAttendant to forward a PSTN number to an external number permanently, which can be used as a batch to produce large quantities of forwards.

Description

Diverts a number associated with Microsoft Teams Via Microsoft Calling plans or Telstra Calling to an external PSTN number by performing the following actions

• Creates a Resource Account with named "PSTN_FWD_(inboundNumber)@domain.onmicrosoft.com" by default (Configurable using -AccountPrefix)

• Licences the account with a Virtual Phone System Licence

• Licences the account with an appropriate calling licence (Will attempt to locate a calling licence using Locate-CsCallingLicence)

• Creates an AutoAttendant with a 24-hour schedule

• Configures a forward rule in the AutoAttendant

Note: All accounts will be "Cloud born" and use your tenant's onmicrosoft domain to remove any requirements for on-prem accounts

Warning: The script presently only supports Cloud Numbers, attempting to use Direct Routing numbers will fail.

Known Issue: There is currently a delay with Office365 replication where the object may not be licenced in time before attempting to assign a line uri. I'm working on a fix for this. Rerunning the cmdlet after a few minutes will fix this; it will check for any existing objects and update them before creating new ones.

Examples

PS> New-CsFixedNumberDiversion -OriginalNumber [phone] -TargetNumber [phone]

Creates an AutoAttendant associated with the number [phone] to forward calls to [phone]

The target number does not need to be internal to the Teams Tenant, but the resource account will require licences/policies for PSTN calling as per your tenant.

Parameters

-OriginalNumber: The number of the new AutoAttendant. IE: The number you wish to forward from

-TargetNumber: The number the AutoAttendant will forward calls to. IE: the number you wish to forward to

-Domain: This domain name will be used to create the resource accounts for the diversion. This should be an "onmicrosoft" domain or fully AzureAD-hosted domain to minimise any directory sync issues For example, "Contoso.onmicrosoft.com"

-LicenceType: This specifies how the cmdlet will licence the AutoAttendant to make PSTN calls. Valid options are, MCOPSTN1, MCOPSTN2, MCOPSTNEAU2

Note this cmdlet presently doesn't support Direct Routing or Operator Connect. This is a planned feature.

-Country: As we set licences for the virtual users, we need to know what country to licence them in. Make sure to use upper case!

-AccountPrefix: (optional) This is the name that will be placed before the inbound phone number in the account name, used if you have a special naming convention for service accounts "PSTN_FWD_" by default

-AADisplayName: (optional) The display name to assign to the AutoAttendant "<original number> Forward" by default

Inputs

This cmdlet also supports pipeline input, so you can pass a whole bunch of numbers using multiple objects on the pipeline!

Pipeline Example

$Data = Import-CSV "C:\UcMadScientist\New-UcmCsFixedNumberDiversion-Example.csv" -ErrorAction Stop
$data | New-UcmCsFixedNumberDiversion -Domain contoso.onmicrosoft.com -LicenceType MCOPSTNEAU2 -Country AU -Verbose

This will create a forward for each number in the New-UcmCsFixedNumberDiversion-Example.csv file using their OriginalNumber and TargetNumber properties and licence them for Telstra Calling for Office 365 in Australia.

Example CSV file (Download)

OriginalNumber	TargetNumber
61370105550	61755501230
61370105551	61755501231
61370105552	61755501232
61370105553	61755501233
61370105554	61755501234

Outputs

This Cmdet returns a PSCustomObject with multiple keys to indicate the cmdlet results.

$Return.Status

$Return.Status returns one of four values "OK" : The operation was successful, nothing of concern "Warn" : The operation was successful, but there is something you should be mindful of (For example trying to create a forward that already exists, or running low on licences to assign) More information will be found in $Return.Message "Error" : The operation was unsuccessful, Something happened when attempting to perform the operation that the function couldn't handle automatically, check $Return.Message for more information "Unknown" : Cmdlet reached the end of the function without returning anything, this shouldn't happen, if it does please log an issue on GitHub with your relevant log files.

$Return.Message

$Return.Message returns descriptive text relevant to the status, mainly for logging, reporting or diagnosis.