Advanced Configuration

Backend Permissions

Warning

If you add an Azure AD Group, only direct members of the group will receive access.

1. Search for the Unified Contacts Backend App Registration

2. Open the App Registration and click on the link to the linked Enterprise App

3. Under Properties enable the setting "Assignement required?" and click "Save"

4. You can now add users and groups that shall receive access to the Unified Contacts Backend via the "Users and groups" section

Custom Domain

Step 1: Custom Domain Creation and Assignment

If you want to create your own custom domain for your Unified Contacts App Service URL, there are two options depending on your domain provider:

Option 1: Azure App Service Domain

• Navigate to your Unified Contacts App Service
• In the left navigation bar scroll down to the "Settings" section. Click "Custom domains".
• Click "Add custom domain" (in case you have not bought an App Service Domain yet, first create one by clicking "Buy App Service domain").
• Configure the custom domain as follows:
  • Domain provider: App Service Domain
  • TLS/SSL certificate: select App Service Managed Certificate if you want to create and bind the certificate to your custom domain automatically, this certificate is managed by Azure and will be automatically renewed at no cost.
  • TLS/SSL type: SNI SSL Binding is free of cost and supported by most modern browsers.
  • App Service Domain: Choose an existing App Service Domain
  • Domain type: Subdomain
  • Subdomain: Set your preferred subdomain
• Click "Add"

By clicking on add, the custom domain and the SSL Managed Certificate will be created and bound automatically.

Option 2: Non-Azure Domain

• Navigate to your Unified Contacts App Service
• In the left navigation bar scroll down to the "Settings" section. Click "Custom domains".
• Click "Add custom domain"
• Configure the custom domain as follows:
  • Domain provider: All other domain services
  • TLS/SSL certificate: select App Service Managed Certificate if you want to create and bind the certificate to your custom domain automatically, this certificate is managed by Azure and will be automatically renewed at no cost.
  • TLS/SSL type: SNI SSL Binding is free of cost and supported by most modern browsers.
  • Domain: Set your preferred domain
  • Hostname record type: CNAME
• Register the displayed CNAME or TXT record mapping with your DNS provider. Once this is done, click "Validate".
• Click "Add" when the validation is successful.

Note

In both cases it can take a few moments until the SSL binding with the App Service Managed Certificate is complete.

Step 2: Update Permissions

Note

This step is only required if you are adding the custom domain after you have already deployed Unified Contacts.

The App Registrations that were created during the post-deployment step must now be updated to support the new custom domain. Therefore,

• Navigate to Azure AD, "Manage" --> "App registrations"
• Locate the two App registrations that were created during the deployment of Unified Contacts. You assigned the name in the first step of the deployment.\

• First, click on the "admin" App registration and navigate to "Manage" --> "Authentication".
  • Under the "Redirect URLs", add your custom domain and click "Save"\

• Next, go the the "teams" App registration and navigate to "Manage" --> "Authentication".
  • Under the "Redirect URLs", add your custom domain and click "Save"\

• Next, navigate to "Manage" --> "Expose API" and update the "Application ID URI" with your custom domain.\

The configuration of the custom domain is complete.

Warning

In the next step of the deployment guide, remember to update the Api Domain in the Teams Manifest configuration.

SBC Number Lookup

Note

Applicable to version 5.4.0 and above

With Unified Contacts 5.4.0 and later you can perform a reverse number lookup against contacts in the Unified Contacts Database and inject the DisplayName of the caller into the SIP header.

Setup

Unified Contacts Settings

Per default the SBC Lookup Endpoint is disabled. To enable it open the Unified Contacts Admin Portal and click on Settings. All settings will be have to be configured under the category SBC Lookup.

Warning

If you have updated recently and can't see the SBC Lookup Category you might have to clear your browser cache and reload the page.

Enable the SBC Lookup Endpoint

Per default the SBC Lookup Endpoint is disabled. To enable it open the Unified Contacts Admin portal at the root page. Navigate to Settings > SBC Lookup and enable the SBC Lookup Endpoint.

Configure IP Authentication

Caution

We highly recommend having IP Authentication enabled. Without it you expose the lookup endpoint publicly into the internet, secured only by Basic Auth.

To allow access to the Endpoint you can specify an allow-list of IP addresses that are allowed to access the Endpoint. You can add any valid IPv4 or IPv6 address. Add it by entering the address into the input field and click on the + Button.

To delete an IP address from the allow-list click on the trash bin symbol.

Warning

The endpoint validates the last IP address in a forwarding chain. If you have the Unified Contacts AppService set up behind a reverse proxy, load balancer or other proxy service(s) the request will be treated as if it was send from the outbound IP address of the last proxy in the chain. In such cases make sure to implement your own firewall in front of the proxy service and add the IP address(es) of your proxy service(s) to the SBC Lookup endpoint allow-list.

Configure Authentication Credentials

As most SBCs don't support modern Authentication the SBC Lookup endpoint uses Basic Auth for Authenticating requests. To use the Endpoint you have to set a username and password. Those are the credentials you will also have to enter in your SBC.

Note

Usernames have to have at least 3 chars. Only alphanumerical chars are allowed Passwords have to have at least 16 chars and contains at least one special character. Only alphanumerical chars and a list of special characters (!?@#$%^&*()_+-=[]{}) are allowed

Warning

After you leave this page you will not be able to see the credentials you have configured. Make sure to store the credentials securely (e.g. in your Password Manager). If you forget the credentials you have to set new ones.

SBC Setup

AudioCodes SBC Mediant Series

Setup an AudioCodes SBC requires the configuration of Remote Web Services and a Call Setup Rule.

First go to Setup -> IP Network -> Web Services -> Remote Web Services and create a new RWS. Give it s unique name on your SBC as it will be used in the Call Setup Rule later.
Usage Type is General and Path must be /api/v1/sbclookup/phone.
You need to specify a TLS Context as the connection will be secured, we recommend to use the same TLS Context you use for your connection to MS Teams.
Username and password are those you defined earlier in the section above in the Unified Contacts Portal.

Next step is to define the HTTP Remote Host on the same screen, just click the blue link below password.

The value for Address you can copy from your Unified Contacts Portal website. Here we need to enter the App Service URL, the Port should be changed to 443 and Transport Type to HTTPS.
As Interface select the one you want to use and from which you specified the public IP address in Unified Contacts Portal.

To get information of the Web Services you might want to enable logging on the SBC. This can be done in Setup -> IP Network -> Web Services -> Web Services Settings. Just modify the Debug Level to Detailed

Finally, you need a Call Setup Rule which queries the database on an incoming call.
Just go to Setup -> Signaling & Media -> SIP Definitions -> Call Setup Rules and create a new one.
Request Type is HTTP GET and Request Target must be the Remote Web Services Name.
Request Key is the calling number, so enter Param.Call.Src.User.
Next a condition is required to make sure that messages are manipulated only when a match is found. This should be HTTP.Response.Status == '200'.
As an action we're going to modify Param.Call.Src.Name with the body of the 200 OK message received. So Action Value is HTTP.Response.Body

This CSR must be added to any IP Group on which you want to run the Reverse Name Lookup. Likely on every PSTN SIP Trunk IP Group.

Note

You might have already some Call Setup Rules on your SBC and one or more are already assigned to IP Groups on which you want to run this feature.
In this case you create the new Call Setup Rule with the same Rule Set ID. If you have multiple Rule Sets in use, just create multiple rules to meet your environment.

SharePoint Online Lists

Unified Contacts can search for contacts in SharePoint Online lists. You can use a contact list in SharePoint Online in different fashions:

• As bridge technology to export your customer contact data from any third party database and import it to SharePoint Online
• To deploy a centralized, shared contact list in your departments or business units

To optimize the search in SharePoint Online, Unified Contacts searches for a dedicated SharePoint content type - contacts. Therefor your contacts needs to be stored in a SharePoint Online Contacts list or a List where the content type "contacts" is assigned to.

Warning

Users will only be able to search a SharePoint Online list if they have (read-) permissions to access the list and the site under which it is stored.

This article describes how to create a new SharePoint Online list and assign the correct content type.

Create an empty SharePoint Online List

• Open the SharePoint Online site where you would like to store the contacts
• Create a new list by clicking "Settings" -> "Add an app"
• Open the classic view by clicking "classic experience"\

• Select "Custom List"
• Define a name for the list and create it

Assign the Content Type to a new SharePoint Online List

The list you just created must be of the "Contacts" content type to be found with Unified Contacts. One option is to assign a content type to a SharePoint list, and all newly created items in the list inherit the content type of that list.

Therefore, add the Contact content type and remove the default content type from the list.

• Open the SharePoint Online list

• Open list settings by clicking "Settings" --> "List settings"\

  

• Open "Advanced settings"
• Enable "Allow management of content types" and save the changes by clicking "OK" at bottom of the page.
• SharePoint opens the settings page and you will see the section "Content Types"
• Click "Add from existing site content types"\

• Add "Contact" and save the changes by clicking "OK"
• Click on "Default content type" and delete it

UC Database

[!Info] Applicable to version 1.5.0 and above \

With Unified Contacts 1.5.0 and later you can fill the internal database (UC Database) with contacts from anywhere which can be searched by each of your users.

To fill the database you need to insert your contacts in a specific schema as described below. We also provide a RESTful API for CRUD operations on Database contacts.

We provide two detailed examples in our documentation on how to add contacts to the UC Database leveraging

1. Azure Data Factory as data integration service
2. Our API for CRUD operations

UC Database Documentation

The following documentation explains where to find the UC Database and how the Contacts table is structured.

Database Location

The UC Database (DB) can be found in the resource group in which Unified Contacts was deployed.

Warning

If you did not choose a custom name when installing Unified Contacts, the DB-Server is called db-uc- followed by 13 digits and numbers, the DB itself is calledsql-db by default.

To access the DB you will need the user and password you have set when installing Unified Contacts.

Database Contacts Structure

Caution

Only alter tables that have the prefix UnifiedContactsCustom.
Only alter the content, NEVER change the table schema.
Changing data in an unsupported way may degrade or even break Unified Contacts functionality.

Database Contacts are stored in the UnifiedContactsCustom.Contacts Table. You can change the content of this table as you like but DO NOT change the table's schema definition.

Schema Definition

column name	data type	optional?	description	example
id	NVARCHAR(256)	false	Unique identifier of the contact	sap_28648f3b-8a60-4ded-a2df-5f303a74a17a
displayName	NVARCHAR(256)	true	DisplayName of the contact	John Doe
jobTitle	NVARCHAR(256)	true	JobTitle of the contact	Software Developer
department	NVARCHAR(256)	true	Department of the contact	R&D
companyName	NVARCHAR(256)	true	Name of company associated with the contact	Fantastic Company Inc.
mailAddresses	NVARCHAR(4000)	true	Email addresses of the contact. Multiple entries have to be separated with a semicolon (;)	john.doe@example.test;john.doe@example.test
imAddresses	NVARCHAR(4000)	true	Instant messaging addresses of the contact. Used for initiating a chat in Teams. If multiple imAddresses are provided, the first one is used to initiate a chat. If not provided the first email address of the contact is used. Multiple entries have to be separated with a semicolon (;)	john.doe@example.test;john.doe@example.test
mobilePhoneNumbers	NVARCHAR(4000)	true	Mobile phone numbers of the contact. Multiple entries have to be separated with a semicolon (;)	+1234567890;+9876543210
businessPhoneNumbers	NVARCHAR(4000)	true	Business phone numbers of the contact. Multiple entries have to be separated with a semicolon (;)	+1234567890;+9876543210
homePhoneNumbers	NVARCHAR(4000)	true	Home phone numbers of the contact. Multiple entries have to be separated with a semicolon (;)	+1234567890;+9876543210
addressFullString	NVARCHAR(512)	true	Full address of the contact. If this is set it is used for displaying the address in the contact card. If not set the address is built from the other address properties.	Any Street 1, 12345 Any City, Any Country
addressStreetAddress	NVARCHAR(512)	true	Street address of the contact	Any Street 1
addressPostalCode	NVARCHAR(512)	true	Postal code of the contact	12345
addressCity	NVARCHAR(512)	true	City of the contact	Any City
addressCountry	NVARCHAR(512)	true	Country of the contact	Any Country
source	NVARCHAR(64)	true	Sub source of the contact. This is used to identify the source of the contact if you are syncing multiple data sources.	SAP

Sync Data with Azure Data Factory

Note

The Azure Data Factory is a chargeable Microsoft Service. In normal use, these charges are nominal. Please visit https://azure.microsoft.com/en-us/pricing/details/data-factory/data-pipeline/ for more Details.

• To set up a connection between a Data Source and the Azure Data Factory, please log in to Azure Portal, navigate to the Resource group of Unified Contacts and create a new resource by clicking "+ Create" and subsequently searching for Azure Data Factory.
• This will take you through the steps to create a Data Factory

• When the deployment has completed successfully, a confirmation screen will be displayed

• Clicking on "Go to Resource" will bring you to the Azure Data Studio Launch Page

• Click "Launch Studio" to begin the data source configuration
• In the next step, we need to ingest (collect) the data from our external source that we want to use in the Data Factory

Note

The Azure Data Factory supports more than 90 Data Sources natively (e.g. MySQL, Oracle DB, SAP, MongoDB, Microsoft Dynamics, Salesforce, Xero). For Details of the available connectors, please visit https://learn.microsoft.com/en-us/azure/data-factory/connector-overview.

• Click on "Ingest" to begin the configuration\

• Select Built-In copy task and Schedule. Normally, a daily ingestion is sufficient but it can be configured to run more frequently if required.

• In the Source Screen, select the data source that you want to use and then click "New connection"
• In this example, we are ingesting data from a Dynamics Business Central Instance and are going to connect via HTTP to it.

• Under the Source data store, select HTTP

• In the next screen, enter a connection Name, the Base URL and chosen Connection method. Then click "Next".

• In the following screen, all defaults can be accepted

• Next, we need to provide the details of the database where the data collected from our Data Source will be stored. This database is created as part of the Unified Contacts installation (UC Database).
• If you did not choose a custom naming when installing Unified Contacts the DB-Server is called db-uc- followed by 13 digits and numbers and the DB itself sql-db by default.
• By choosing the Account Selection Method "From Azure Subscription" the database details will be retrieved automatically.

• Once you have entered all the data, click "Apply"
• Then confirm the File format settings for your data source

• Configure the Source -> Destination mappings

Caution

Please ensure that your data fits the specified database schema. Any rows not fitting the schema might cause the Copy activity to fail or the faulty rows to be skipped, depending on the configured fault tolerance.

In the case of fields that are too long consider editing the data in your source (query) or adding a Data Flow activity to transform it into a valid form (i. e. shortening the text and adding "..." at the end.)

• Finally, configure the settings for the copy data task
• Under Fault tolerance, choose the required level

• Once you have completed the final step, the Data Factory can be deployed

CRUD operations with REST API

Authentication

To access the API endpoints you need to acquire a Bearer token. The API uses Microsoft as an Identity Provider with Application permissions. Therefore the access can be managed similarily to the the access of the Microsoft Graph API.

Prerequisites

• Unified Contacts setup completed with version 1.5.0 or later
• Cloud Application Administrator, Application Administrator or Global Admin privileges (used for the admin grant)

Caution

If you have used UnifiedContactsPS with version lower than 1.1.0 to install Unified Contacts, you first have to perform the additional steps explained here.

NOTE: If you have initially installed Unified Contacts before version 1.5.0, this is very likely the case.

Permission Setup

1. Select an existing App Registration or create a new one that will be used to authenticate you when accessing the Unified Contacts REST API.
2. Navigate to API permissions > Add a permission > My APIs then select the Unified Contacts Admin AppRegistration. If you have not changed the default naming when deploying Unified Contacts via the ARM template the name will be in the following format:
   admin-app-reg-uc-<13 random alphanumeric characters>\

3. Select Application permissions on the top and activate the checkbox next to Contacts.Database.ReadWrite.All. Finalize the assignment by clicking "Add permissions" on the bottom.\

4. A Cloud Application-, Application-, or Global-Admin now has to Grant admin consent for the tenant. This is done by clicking the Grant admin consent for <Tenant> button and confirming the action by clicking on Yes.\

5. After the Admin consent is granted the AppRegistration is ready for usage.

Acquiring a token

A detailed explanation on acquiring tokens against an AppRegistration can be found here (Microsoft docs).

In the following example we will configure Postman to acquire a valid token with an Application Secret. However we recommend the usage of a Managed Identity (when applicable) or with Certificates when creating a productive/regularly running process or sync.

• More details on certificate authentication can be found here (Microsoft docs).
• More details on Managed Identity authentication can be found here (Microsoft docs).

1. Open the AppRegistration from before. Navigate to Certificates & secrets > Client secrets > New client secret. Set a description and configure the Expiry date (max. 2 years). Finalize the process by clicking "Add".\

2. Copy and store the freshly generated client secret somewhere secure (e.g. a credential manager). NOTE: Once you leave this page you will only be able to see a censored shortened version of the secret. So if you do not store the secret properly and forget it you'll need to create a new one\

3. Navigate to the Overview tab of the AppRegistration. Copy the ClientId for later use. Click on Endpoints and copy the OAuth 2.0 token endpoint (v2) for later use.\

4. Navigate to API permissions select the Contacts.Database.ReadWrite.All permission and Copy the scope for later use.\

5. Create a new Postman Collection and navigate to the Authentication tab. There select OAuth 2.0 as Type\

6. Fill out the Configure new token category\

* **Token Name**: Any custom Name
* **Grant Type**: Client Credentials
* **Access Token URL**: Paste the token URL copied in Step 3
* **Client ID**: Paste the Client Id copied in Step 3
* **Client Secret**: Paste Secret copied in Step 2
* **Scope**: Paste scope copied in step 4. Replace **Contacts.Database.ReadWrite.All** with **.default**
* **Client Authentication**: Send as Basic Auth header

7. Your result should look something like this:

8. If you have configured everything correctly, you can now scroll to the bottom and click on "Get New Access Token" to acquire a new access token. All requests within the Collection can now be authenticated with that token.

API Documentation

This section details the available REST API endpoints for contact operations. A full swagger.json file is available in the repository assets.

Endpoints Overview

GET /api/v1/contacts/{contactId}

Gets a contact with all meta data that is stored in the database.

Parameters:

• contactId (path, required): Id of the contact

Responses:

• 200 OK: Contact successfully found and returned

  {
    "displayName": "John Doe",
    "jobTitle": "Software Developer",
    "department": "Development",
    "companyName": "Fantastic Company Inc.",
    "mailAddresses": ["john.doe@example.test", "john.doe-alt@example.test"],
    "imAddresses": ["john.doe@example.test", "john.doe-alt@example.test"],
    "mobilePhoneNumbers": ["+123456789", "+198765432"],
    "businessPhoneNumbers": ["+123456789", "+198765432"],
    "homePhoneNumbers": ["+123456789", "+198765432"],
    "addressFullString": "Any Street 1, 12345 Any City, Any Country",
    "addressStreetAddress": "Any Street 1",
    "addressPostalCode": "12345",
    "addressCity": "Any City",
    "addressCountry": "Any Country",
    "source": "SAP",
    "id": "sap_28648f3b-8a60-4ded-a2df-5f303a74a17a"
  }

• 404 Not Found: Contact with id not found

POST /api/v1/contacts

Creates a new contact.

Request Body:

{
  "displayName": "John Doe",
  "jobTitle": "Software Developer",
  "department": "Development",
  "companyName": "Fantastic Company Inc.",
  "mailAddresses": ["john.doe@example.test", "john.doe-alt@example.test"],
  "imAddresses": ["john.doe@example.test", "john.doe-alt@example.test"],
  "mobilePhoneNumbers": ["+123456789", "+198765432"],
  "businessPhoneNumbers": ["+123456789", "+198765432"],
  "homePhoneNumbers": ["+123456789", "+198765432"],
  "addressFullString": "Any Street 1, 12345 Any City, Any Country",
  "addressStreetAddress": "Any Street 1",
  "addressPostalCode": "12345",
  "addressCity": "Any City",
  "addressCountry": "Any Country",
  "source": "SAP",
  "id": "sap_28648f3b-8a60-4ded-a2df-5f303a74a17a"
}

Responses:

• 200 OK: Contact created successfully (returns the created contact)
• 201 Created: Contact was successfully created
• 409 Conflict: Contact with id already exists

PUT /api/v1/contacts/{contactId}

Overwrites the meta information of an existing contact.

Parameters:

• contactId (path, required): Id of the contact

Request Body:

{
  "displayName": "John Doe",
  "jobTitle": "Software Developer",
  "department": "Development",
  "companyName": "Fantastic Company Inc.",
  "mailAddresses": ["john.doe@example.test", "john.doe-alt@example.test"],
  "imAddresses": ["john.doe@example.test", "john.doe-alt@example.test"],
  "mobilePhoneNumbers": ["+123456789", "+198765432"],
  "businessPhoneNumbers": ["+123456789", "+198765432"],
  "homePhoneNumbers": ["+123456789", "+198765432"],
  "addressFullString": "Any Street 1, 12345 Any City, Any Country",
  "addressStreetAddress": "Any Street 1",
  "addressPostalCode": "12345",
  "addressCity": "Any City",
  "addressCountry": "Any Country",
  "source": "SAP"
}

Note: The id field is not included in the request body as it's provided in the URL path.

Responses:

• 200 OK: Contact was successfully updated - full contact info is returned
• 404 Not Found: Contact with id not found

PATCH /api/v1/contacts/{contactId}

Updates provided meta information of an existing contact.

Parameters:

• contactId (path, required): Id of the contact

Request Body:

{
  "displayName": "John Doe Updated",
  "jobTitle": "Senior Software Developer",
  "department": "R&D"
  // Only include fields that need to be updated
}

Note: Only include the fields that need to be updated. Other fields will remain unchanged.

Responses:

• 200 OK: Contact was successfully updated - full contact info is returned
• 404 Not Found: Contact with id not found

DELETE /api/v1/contacts/{contactId}

Deletes an existing contact.

Parameters:

• contactId (path, required): Id of the contact

Responses:

• 200 OK: Contact deleted
• 204 No Content: Contact was successfully deleted
• 404 Not Found: Contact with id not found