# New-UcmCsFixedNumberDiversion

## 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

{% hint style="success" %}
Note: All accounts will be "Cloud born" and use your tenant's onmicrosoft domain to remove any requirements for on-prem accounts
{% endhint %}

{% hint style="warning" %}
Warning: The script presently only supports Cloud Numbers, attempting to use Direct Routing numbers will fail.
{% endhint %}

{% hint style="danger" %}
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.
{% endhint %}

## Examples

```powershell
PS> New-CsFixedNumberDiversion -OriginalNumber +61370105550 -TargetNumber +61755501234
```

Creates an AutoAttendant associated with the number +61370105550 to forward calls to +61755501234

{% hint style="info" %}
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.
{% endhint %}

## 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 

{% hint style="warning" %}
Note this cmdlet presently doesn't support Direct Routing or Operator Connect. \
This is a planned feature.
{% endhint %}

**-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 \
\&#xNAN;**"\<original number> Forward" by default**

## Inputs

{% hint style="info" %}
This cmdlet also supports pipeline input, so you can pass a whole bunch of numbers using multiple objects on the pipeline!
{% endhint %}

### Pipeline Example

```powershell
$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](https://www.ucmadscientist.com/docsresource/New-UcmCsFixedNumberDiversion-Example.csv))

| 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.

<details>

<summary>$Return.Status</summary>

`$Return.Status` returns one of four values \
\&#xNAN;**"OK" :** The operation was successful, nothing of concern\
&#x20;**"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`\
\&#xNAN;**"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 \
\&#xNAN;**"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.

</details>

<details>

<summary>$Return.Message</summary>

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

</details>