Add post-deployment instructions for managing Direct Routing customers

Author: rcdun

articles/communications-gateway/configure-test-customer-teams-direct-routing.md

@@ -45,42 +45,22 @@ You must be able to configure the tenant with at least two user or resource acco
 - You need two user or resource accounts to activate the Azure Communications Gateway domains that you add to Microsoft 365 by following this article. Lab deployments require one account.
 - You need at least one user account to use for testing later when you carry out [Configure test numbers for Microsoft Teams Direct Routing with Azure Communications Gateway](configure-test-numbers-teams-direct-routing.md). You can reuse one of the accounts that you use to activate the domains, or you can use an account with one of the other domain names for this tenant.
 
-## Choose a DNS subdomain label to use to identify the customer
+## Choose a DNS subdomain label for the test customer tenant
 
 Azure Communications Gateway has _per-region domain names_ for connecting to Microsoft Teams Direct Routing. You need to set up subdomains of these domain names for your test customer. Microsoft Phone System and Azure Communications Gateway use these subdomains to match calls to tenants.
 
-1. Work out the per-region domain names for connecting to Microsoft Teams Direct Routing. These use the form `1-r<region-number>.<base-domain-name>`. The base domain name is the **Domain** on your Azure Communications Gateway resource in the [Azure portal](https://azure.microsoft.com/).
-1. Choose a DNS label to identify the test customer.
-    - The label must be up to **eight** characters in length and can only contain letters, numbers, underscores, and dashes.
-    - You must not use wildcard subdomains or subdomains with multiple labels.
-    - For example, you could allocate the label `test`.
-    > [!IMPORTANT]
-    > The full customer subdomains (including the per-region domain names) must be a maximum of 48 characters. Microsoft Entra ID does not support domain names of more than 48 characters. For example, the customer subdomain `contoso1.1-r1.a1b2c3d4e5f6g7h8.commsgw.azure.com` is 48 characters.
-1. Use this label to create a _customer subdomain_ of each per-region domain name for your Azure Communications Gateway.
-1. Make a note of the label you choose and the corresponding customer subdomains.
-
-For example:
-- Your base domain name might be `<deployment-id>.commsgw.azure.com`, where `<deployment-id>` is autogenerated and unique to the deployment.
-- Your per-region domain names are therefore:
-    - `1-r1.<deployment-id>.commsgw.azure.com`
-    - `1-r2.<deployment-id>.commsgw.azure.com`
-- If you allocate the label `test`, this label combined with the per-region domain names creates the following customer subdomains for your test customer:
-    - `test.1-r1.<deployment-id>.commsgw.azure.com`
-    - `test.1-r2.<deployment-id>.commsgw.azure.com`
-
-> [!IMPORTANT]
-> The per-region domain names for connecting to Microsoft Teams Direct Routing are different to the per-region domain names for connecting to your network.
+[!INCLUDE [communications-gateway-direct-routing-subdomain-calculation](includes/communications-gateway-direct-routing-subdomain-calculation.md)]
 
 > [!TIP]
 > Lab deployments have one per-region domain name. Your test customer therefore also only has one customer subdomain.
 
-## Start registering the subdomains in the customer tenant and get DNS TXT values
+## Start registering the subdomains in the test customer tenant and get DNS TXT values
 
-To route calls to a customer tenant, the customer tenant must be configured with the customer subdomains that you allocated in [Choose a DNS subdomain label to use to identify the customer](#choose-a-dns-subdomain-label-to-use-to-identify-the-customer). Microsoft 365 then requires you (as the carrier) to create DNS records that use a verification code from the customer tenant.
+For Microsoft Phone System to route calls to the test customer tenant correctly, the customer tenant must be configured with the customer subdomains that you allocated in [Choose a DNS subdomain label for the test customer tenant](#choose-a-dns-subdomain-label-for-the-test-customer-tenant). Microsoft 365 then requires you (as the carrier) to create DNS records that use a verification code from the customer tenant.
 
 1. Sign into the Microsoft 365 admin center for the customer tenant as a Global Administrator.
 1. Using [Add a subdomain to the customer tenant and verify it](/microsoftteams/direct-routing-sbc-multiple-tenants#add-a-subdomain-to-the-customer-tenant-and-verify-it):
-    1. Register the first customer subdomain (for example `test.1-r1.<deployment-id>.commsgw.azure.com`).
+    1. Register the first customer subdomain (for example `contoso.1-r1.<deployment-id>.commsgw.azure.com`).
     1. Start the verification process using TXT records.
     1. Note the TXT value that Microsoft 365 provides.
 1. (Production deployments only) Repeat the previous step for the second customer subdomain.
@@ -100,10 +80,10 @@ You can use Azure Communications Gateway's Number Management Portal (preview) or
 1. Select **Accounts**.
 1. Select **Create account**.
 1. Enter an **Account name** and select the **Enable Teams Direct Routing** checkbox.
-1. Set **Teams tenant ID** to the ID of your test customer tenant.
-1. Optionally, select **Enable call screening**. This screening ensures that customers can only place Direct Routing calls from numbers that you have assigned to them.
-1. Set **Subdomain** to the label for the subdomain that you chose in [Choose a DNS subdomain label to use to identify the customer](#choose-a-dns-subdomain-label-to-use-to-identify-the-customer) (for example, `test`).
-1. Set the **Subdomain token region** fields to the TXT values that you obtained in [Start registering the subdomains in the customer tenant and get DNS TXT values](#start-registering-the-subdomains-in-the-customer-tenant-and-get-dns-txt-values).
+1. Set **Teams tenant ID** to the ID of the customer tenant.
+1. Optionally, select **Enable call screening**. This screening ensures that customers can only place Direct Routing calls from numbers that you assign to them.
+1. Set **Subdomain** to the label for the subdomain that you chose in [Choose a DNS subdomain label for the test customer tenant](#choose-a-dns-subdomain-label-for-the-test-customer-tenant) (for example, `contoso`).
+1. Set the **Subdomain token region** fields to the TXT values that you obtained in [Start registering the subdomains in the test customer tenant and get DNS TXT values](#start-registering-the-subdomains-in-the-test-customer-tenant-and-get-dns-txt-values).
 1. Select **Create**.
 1. Confirm that the DNS records have been generated.
     1. On the **Accounts** pane, select the account name in the list.
@@ -113,8 +93,8 @@ You can use Azure Communications Gateway's Number Management Portal (preview) or
 
 1. Use the Provisioning API to configure an account for the customer. The request must:
     - Enable Direct Routing for the account.
-    - Specify the label for the subdomain that you chose in [Choose a DNS subdomain label to use to identify the customer](#choose-a-dns-subdomain-label-to-use-to-identify-the-customer) (for example, `test`).
-    - Specify the DNS TXT values from [Start registering the subdomains in the customer tenant and get DNS TXT values](#start-registering-the-subdomains-in-the-customer-tenant-and-get-dns-txt-values). These values allow Azure Communications Gateway to generate DNS records for the subdomain.
+    - Specify the label for the subdomain that you chose in [Choose a DNS subdomain label for the test customer tenant](#choose-a-dns-subdomain-label-for-the-test-customer-tenant) (for example, `contoso`).
+    - Specify the DNS TXT values from [Start registering the subdomains in the test customer tenant and get DNS TXT values](#start-registering-the-subdomains-in-the-test-customer-tenant-and-get-dns-txt-values). These values allow Azure Communications Gateway to generate DNS records for the subdomain.
 2. Use the Provisioning API to confirm that the DNS records have been generated, by checking the `direct_routing_provisioning_state` for the account.
 
 For example API requests, see [Create an account to represent a customer](/rest/api/voiceservices/#create-an-account-to-represent-a-customer) and [View the details of the account](/rest/api/voiceservices/#view-the-details-of-the-account) in the _API Reference_ for the Provisioning API.
@@ -123,7 +103,7 @@ For example API requests, see [Create an account to represent a customer](/rest/
 
 ## Finish verifying the domains in the customer tenant
 
-When you have used Azure Communications Gateway to generate the DNS records for the customer subdomains, verify the subdomains in the Microsoft 365 admin center for your customer tenant.
+After you use Azure Communications Gateway to generate the DNS records for the customer subdomains, verify the subdomains in the Microsoft 365 admin center for your customer tenant.
 
 1. Sign into the Microsoft 365 admin center for the customer tenant as a Global Administrator.
 1. Select **Settings** > **Domains**.
@@ -134,13 +114,13 @@ When you have used Azure Communications Gateway to generate the DNS records for
 To activate the customer subdomains in Microsoft 365, set up at least one user or resource account licensed for Microsoft Teams for each  domain name. For information on the licenses you can use and instructions, see [Activate the subdomain name](/microsoftteams/direct-routing-sbc-multiple-tenants#activate-the-subdomain-name).
 
 > [!IMPORTANT]
-> Ensure the accounts use the customer subdomains (for example, `test.1-r1.<deployment-id>.commsgw.azure.com`), instead of any existing domain names in the tenant.
+> Ensure the accounts use the customer subdomains (for example, `contoso.1-r1.<deployment-id>.commsgw.azure.com`), instead of any existing domain names in the tenant.
 
 ## Configure the customer tenant's call routing to use Azure Communications Gateway
 
 In the customer tenant, [configure a call routing policy](/microsoftteams/direct-routing-voice-routing) (also called a voice routing policy) with a voice route that routes calls to Azure Communications Gateway.
 
-- Set the PSTN gateway to the customer subdomains for Azure Communications Gateway (for example, `test.1-r1.<deployment-id>.commsgw.azure.com` and `test.1-r2.<deployment-id>.commsgw.azure.com`). This step sets up _derived trunks_ for the customer tenant, as described in the [Microsoft Teams documentation for creating trunks and provisioning users for multiple tenants](/microsoftteams/direct-routing-sbc-multiple-tenants#create-a-trunk-and-provision-users).
+- Set the PSTN gateway to the customer subdomains for Azure Communications Gateway (for example, `contoso.1-r1.<deployment-id>.commsgw.azure.com` and `contoso.1-r2.<deployment-id>.commsgw.azure.com`). This step sets up _derived trunks_ for the customer tenant, as described in the [Microsoft Teams documentation for creating trunks and provisioning users for multiple tenants](/microsoftteams/direct-routing-sbc-multiple-tenants#create-a-trunk-and-provision-users).
 - Don't configure any users to use the call routing policy yet.
 
 > [!IMPORTANT]

articles/communications-gateway/configure-test-numbers-teams-direct-routing.md

@@ -14,9 +14,6 @@ ms.date: 03/31/2024
 
 To test Microsoft Teams Direct Routing with Azure Communications Gateway, you need a test customer tenant with test users and numbers. By following this article, you can set up the required user and number configuration in the customer Microsoft 365 tenant, on Azure Communications Gateway and in your network. You can then start testing.
 
-> [!TIP]
-> When you allocate numbers to a real customer, you'll typically need to ask them to change their tenant's configuration, because your organization won't have permission. You'll still need to make configuration changes on Azure Communications Gateway and to your network.
-
 ## Prerequisites
 
 You must have at least one number that you can allocate to your test tenant.
@@ -38,36 +35,13 @@ You must be able to sign in to the Microsoft 365 admin center for your test cust
 
 ## Configure the test numbers on Azure Communications Gateway
 
-In [Configure a test customer for Microsoft Teams Direct Routing with Azure Communications Gateway](configure-test-customer-teams-direct-routing.md), you configured Azure Communications Gateway with an account for the test customer.
+In [Configure a test customer for Microsoft Teams Direct Routing with Azure Communications Gateway](configure-test-customer-teams-direct-routing.md), you configured Azure Communications Gateway with an account for the test customer. You must add the test numbers to this account.
 
 We recommend using the Number Management Portal (preview) to provision the test numbers. Alternatively, you can use Azure Communications Gateway's Provisioning API (preview).
 
 # [Number Management Portal (preview)](#tab/number-management-portal)
 
-You can configure numbers directly in the Number Management Portal, or by uploading a CSV file containing number configuration.
-
-1. From the overview page for your Communications Gateway resource, find the **Number Management** section in the sidebar. Select **Accounts**.
-1. Select the checkbox next to the enterprise's **Account name** and select **View numbers**.
-1. Select **Create numbers**.
-1. To configure the numbers directly in the Number Management Portal:
-    1. Select **Manual input**.
-    1. Select **Enable Teams Direct Routing**.
-    1. Optionally, enter a value for **Custom SIP header**.
-    1. Add the numbers in **Telephone Numbers**.
-    1. Select **Create**.
-1. To upload a CSV containing multiple numbers:
-    1. Prepare a `.csv` file. It must use the headings shown in the following table, and contain one number per line (up to 10,000 numbers).
-
-        | Heading | Description  | Valid values |
-        |---------|--------------|--------------|
-        | `telephoneNumber`|The number to upload | E.164 numbers, including `+` and the country code |
-        | `accountName` | The account to upload the number to | The name of an existing account |
-        | `serviceDetails_teamsDirectRouting_enabled`| Whether Microsoft Teams Direct Routing is enabled | `true` or `false`|
-        | `configuration_customSipHeader`| Optional: the value for a SIP custom header. | Can only contain letters, numbers, underscores, and dashes. Can be up to 100 characters in length. |
-
-    1. Select **File Upload**.
-    1. Select the `.csv` file that you prepared.
-    1. Select **Upload**.
+[!INCLUDE [instructions for configuring Direct Routing numbers in the portal](includes/communications-gateway-direct-routing-configure-numbers-portal.md)]
 
 # [Provisioning API (preview)](#tab/api)
 

articles/communications-gateway/includes/communications-gateway-custom-header-configuration-portal.md

@@ -0,0 +1,12 @@
+---
+author: rcdun
+ms.author: rdunstan
+ms.service: communications-gateway
+ms.topic: include
+ms.date: 04/04/2024
+---
+
+1. In the sidebar, locate the **Number Management (Preview)** section and select **Numbers**.
+1. Select the **Phone number** checkbox then select **Manage number**.
+1. Specify a **Custom SIP header value**.
+1. Select **Review and upload** then **Upload**.

articles/communications-gateway/includes/communications-gateway-direct-routing-configure-numbers-portal.md

@@ -0,0 +1,32 @@
+---
+author: rcdun
+ms.author: rdunstan
+ms.service: communications-gateway
+ms.topic: include
+ms.date: 04/04/2024
+---
+
+You can configure numbers directly in the Number Management Portal, or by uploading a CSV file containing number configuration.
+
+1. From the overview page for your Communications Gateway resource, find the **Number Management** section in the sidebar. Select **Accounts**.
+1. Select the checkbox next to the enterprise's **Account name** and select **View numbers**.
+1. Select **Create numbers**.
+1. To configure the numbers directly in the Number Management Portal:
+    1. Select **Manual input**.
+    1. Select **Enable Teams Direct Routing**.
+    1. Optionally, enter a value for **Custom SIP header**.
+    1. Add the numbers in **Telephone Numbers**.
+    1. Select **Create**.
+1. To upload a CSV containing multiple numbers:
+    1. Prepare a `.csv` file. It must use the headings shown in the following table, and contain one number per line (up to 10,000 numbers).
+
+        | Heading | Description  | Valid values |
+        |---------|--------------|--------------|
+        | `telephoneNumber`|The number to upload | E.164 numbers, including `+` and the country code |
+        | `accountName` | The account to upload the number to | The name of an existing account |
+        | `serviceDetails_teamsDirectRouting_enabled`| Whether Microsoft Teams Direct Routing is enabled | `true` or `false`|
+        | `configuration_customSipHeader`| Optional: the value for a SIP custom header. | Can only contain letters, numbers, underscores, and dashes. Can be up to 100 characters in length. |
+
+    1. Select **File Upload**.
+    1. Select the `.csv` file that you prepared.
+    1. Select **Upload**.

articles/communications-gateway/includes/communications-gateway-direct-routing-subdomain-calculation.md

@@ -0,0 +1,29 @@
+---
+author: rcdun
+ms.author: rdunstan
+ms.service: communications-gateway
+ms.topic: include
+ms.date: 04/04/2024
+---
+
+1. Work out the per-region domain names for connecting to Microsoft Teams Direct Routing. These domain names use the form `1-r<region-number>.<base-domain-name>`. The base domain name is the **Domain** on your Azure Communications Gateway resource in the [Azure portal](https://azure.microsoft.com/).
+1. Choose a DNS label to identify the test customer.
+    - The label must be up to **eight** characters in length and can only contain letters, numbers, underscores, and dashes.
+    - You must not use wildcard subdomains or subdomains with multiple labels.
+    - For example, you could allocate the label `contoso`.
+    > [!IMPORTANT]
+    > The full customer subdomains (including the per-region domain names) must be a maximum of 48 characters. Microsoft Entra ID does not support domain names of more than 48 characters. For example, the customer subdomain `contoso1.1-r1.a1b2c3d4e5f6g7h8.commsgw.azure.com` is 48 characters.
+1. Use this label to create a _customer subdomain_ of each per-region domain name for your Azure Communications Gateway.
+1. Make a note of the label you choose and the corresponding customer subdomains.
+
+For example:
+- Your base domain name might be `<deployment-id>.commsgw.azure.com`, where `<deployment-id>` is autogenerated and unique to the deployment.
+- Your per-region domain names are therefore:
+    - `1-r1.<deployment-id>.commsgw.azure.com`
+    - `1-r2.<deployment-id>.commsgw.azure.com`
+- If you allocate the label `contoso`, this label combined with the per-region domain names creates the following customer subdomains for your test customer:
+    - `contoso.1-r1.<deployment-id>.commsgw.azure.com`
+    - `contoso.1-r2.<deployment-id>.commsgw.azure.com`
+
+> [!IMPORTANT]
+> The per-region domain names for connecting to Microsoft Teams Direct Routing are different to the per-region domain names for connecting to your network.

articles/communications-gateway/index.yml

@@ -78,7 +78,7 @@ landingContent:
             url: emergency-calls-operator-connect.md
       - linkListType: how-to-guide
         links:
-          - text: Manage enterprises and numbers in the Number Management Portal
+          - text: Manage customers in the Number Management Portal
             url: manage-enterprise-operator-connect.md
 
   # Card
@@ -100,6 +100,10 @@ landingContent:
             url: interoperability-teams-direct-routing.md
           - text: Emergency calling
             url: emergency-calls-teams-direct-routing.md
+      - linkListType: how-to-guide
+        links:
+          - text: Manage Direct Routing customers
+            url: manage-enterprise-teams-direct-routing.md
 
   # Card
   - title: Use Azure Communications Gateway for Zoom Phone Cloud Peering