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

<img alt="Azure Portal with the Unified Contacts AppRegistrations" src="https://github.com/user-attachments/assets/3e448b4e-9061-4f48-b974-7fd32064f28a" />


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


<img alt="" src="https://github.com/user-attachments/assets/7e2de012-8797-45eb-9ec4-c8d246adb5d5"/>

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

![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FvD2SfHMuPp7gNFxscRIf%2Fimage](https://github.com/user-attachments/assets/08d06f43-1c19-4cf0-baea-811d80879714)


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

![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FNdgj0QYBrab3qvAOrOUP%2Fimage](https://github.com/user-attachments/assets/789465cf-0e89-4179-941a-0da2aa3599b2)

![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2Ff9HoDySRvp8eGWdtyRnT%2Fimage](https://github.com/user-attachments/assets/10baa34e-4787-44f3-9b6d-d060b1d302b2)

![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FN4vQ4w5vAeCVCHlpsIAc%2Fimage](https://github.com/user-attachments/assets/cf155826-5995-482e-b0e9-b1be751b1049)

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

![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces2Fuploads2Fimage](https://github.com/user-attachments/assets/220ae845-166f-45d1-9f82-5e3acb08c532)


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.

<img alt="image" src="https://github.com/user-attachments/assets/3c50d742-2fe1-438a-98aa-f5ef077d6ac6" />


> [!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](../deployment/getting-started/unified-contacts-pro.md#step-2-perform-post-deployment-steps-permission-assignments) 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](../deployment/getting-started/unified-contacts-pro.md#step-1-deploy-unified-contacts-pro-base-services).\

<img alt="permissions_01" src="https://github.com/user-attachments/assets/9bd3b1cf-b591-45cd-ad67-c19fb03303ea" />

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

   
![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FNYsJeQ6TLPDmjucP3ySL%2Fimage](https://github.com/user-attachments/assets/997f3005-7652-4fa7-8a80-eb8ac6614c55)

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

![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2Fc4HSKY28kdru5jlQGkdq%2Fimage](https://github.com/user-attachments/assets/03b3e81e-fd3e-4fd8-b0ce-239088092e3f)

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

<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FsM1MQ1eua12dVoCVF6gV%2Fimage" src="https://github.com/user-attachments/assets/739063f1-b7ce-4815-b89b-f3717140b060" />

The configuration of the custom domain is complete.

> [!WARNING]
> In the [next step](../deployment/getting-started/unified-contacts-pro.md#step-4-add-unified-contacts-pro-to-your-app-store) 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**.

![https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FgWiqg8fPhamzB57cJWDL%2Fimage](https://github.com/user-attachments/assets/a6baea52-8966-4685-aedd-eb6b774b14f8)


#### Configure IP Authentication

> [!CAUTION]
> We highly recommend having IP Authentication enabled.&#x20;
> 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.


<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FETgAW3NxigVhifULimj4%2Fimage" src="https://github.com/user-attachments/assets/683bebe4-e84f-4a82-964f-6d883bc27068" />


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


<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FFALsZYEbOhZPJ2vl3LGv%2Fimage" src="https://github.com/user-attachments/assets/71288c2f-61c8-440d-a90f-84a4c98bdc85" />




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

<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FyOXr0lCZPw1yiNRkCgJm%2Fimage" src="https://github.com/user-attachments/assets/5ddad1a3-818b-49a9-a75a-f82dd3cf0ad8" />


> [!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.&#x20;

<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FUKgQbMSi1O4kxjepXV5v%2FRemoteWebServices" src="https://github.com/user-attachments/assets/c99bc426-b294-459b-b19e-9489c41924fa" />


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.

<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2F3WBTn2TGAXnzsJGgUlLU%2FHttpRemoteHosts" src="https://github.com/user-attachments/assets/4a072914-f710-4bc2-a3d0-240d870759ab" />


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


<img alt="image" src="https://github.com/user-attachments/assets/af597c57-61d9-439e-b9a5-b52b5ce03bfb" />


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


<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2FHl4HqKbZaxa0rDiPTcCB%2FCallSetupRule" src="https://github.com/user-attachments/assets/221c445f-d745-46fb-830d-4ff582dfe389" />


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"\



<img alt="image" src="https://github.com/user-attachments/assets/abf525bf-e927-4cdb-8abe-65c9b32dbfdc" />


* 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"\


    <figure><img src="../../.gitbook/assets/image (50).png" alt=""><figcaption></figcaption></figure>
<img alt="image" src="https://github.com/user-attachments/assets/4608c530-7062-4454-9bcb-a6239e56b928" />


* 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"\


<img alt="https___files gitbook com_v0_b_gitbook-x-prod appspot com_o_spaces%2F-MQCiQ0bPFDLQyAa7YAa%2Fuploads%2F1HhVXgRfSWgeuJ4LGvnR%2Fimage" src="https://github.com/user-attachments/assets/48d17dcb-de6d-4dc4-9bff-8e326758e701" />


* 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](sync-data-with-azure-data-factory.md)
2. [Our API for CRUD operations](crud-operations-with-rest-api.md)

## 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.&#x20;

> [!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 called`sql-db` by default.&#x20;


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

<table data-full-width="true"><thead><tr><th width="235">column name</th><th width="173">data type</th><th width="106" data-type="checkbox">optional?</th><th width="310.2">description</th><th width="381">example</th></tr></thead><tbody><tr><td>id</td><td>NVARCHAR(256)</td><td>false</td><td>Unique identifier of the contact</td><td>sap_28648f3b-8a60-4ded-a2df-5f303a74a17a</td></tr><tr><td>displayName</td><td>NVARCHAR(256)</td><td>true</td><td>DisplayName of the contact</td><td>John Doe</td></tr><tr><td>jobTitle</td><td>NVARCHAR(256)</td><td>true</td><td>JobTitle of the contact</td><td>Software Developer</td></tr><tr><td>department</td><td>NVARCHAR(256)</td><td>true</td><td>Department of the contact</td><td>R&#x26;D</td></tr><tr><td>companyName</td><td>NVARCHAR(256)</td><td>true</td><td>Name of company associated with the contact</td><td>Fantastic Company Inc.</td></tr><tr><td>mailAddresses</td><td>NVARCHAR(4000)</td><td>true</td><td>Email addresses of the contact.<br><br><em>Multiple entries have to be separated with a semicolon (;)</em></td><td>john.doe@example.test;john.doe@example.test</td></tr><tr><td>imAddresses</td><td>NVARCHAR(4000)</td><td>true</td><td><p>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.<br></p><p><em>Multiple entries have to be separated with a semicolon (;)</em></p></td><td>john.doe@example.test;john.doe@example.test</td></tr><tr><td>mobilePhoneNumbers</td><td>NVARCHAR(4000)</td><td>true</td><td><p>Mobile phone numbers of the contact.</p><p></p><p><em>Multiple entries have to be separated with a semicolon (;)</em></p></td><td>+1234567890;+9876543210</td></tr><tr><td>businessPhoneNumbers</td><td>NVARCHAR(4000)</td><td>true</td><td><p>Business phone numbers of the contact.</p><p></p><p><em>Multiple entries have to be separated with a semicolon (;)</em></p></td><td>+1234567890;+9876543210</td></tr><tr><td>homePhoneNumbers</td><td>NVARCHAR(4000)</td><td>true</td><td><p>Home phone numbers of the contact.</p><p></p><p><em>Multiple entries have to be separated with a semicolon (;)</em></p></td><td>+1234567890;+9876543210</td></tr><tr><td>addressFullString</td><td>NVARCHAR(512)</td><td>true</td><td>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.</td><td>Any Street 1, 12345 Any City, Any Country</td></tr><tr><td>addressStreetAddress</td><td>NVARCHAR(512)</td><td>true</td><td>Street address of the contact</td><td>Any Street 1</td></tr><tr><td>addressPostalCode</td><td>NVARCHAR(512)</td><td>true</td><td>Postal code of the contact</td><td>12345</td></tr><tr><td>addressCity</td><td>NVARCHAR(512)</td><td>true</td><td>City of the contact</td><td>Any City</td></tr><tr><td>addressCountry</td><td>NVARCHAR(512)</td><td>true</td><td>Country of the contact</td><td>Any Country</td></tr><tr><td>source</td><td>NVARCHAR(64)</td><td>true</td><td>Sub source of the contact. This is used to identify the source of the contact if you are syncing multiple data sources.</td><td>SAP</td></tr></tbody></table>


## 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/](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

<img alt="image" src="https://github.com/user-attachments/assets/ee04c7c7-7d84-492b-a8f1-9e6e64d42d56" />

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

<img alt="image" src="https://github.com/user-attachments/assets/e3f822fb-88cb-44de-9516-05b53e2a1f4f" />

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

<img alt="image" src="https://github.com/user-attachments/assets/00a67943-06b8-4b72-9b32-a5bca5f97c09" />

* 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](https://learn.microsoft.com/en-us/azure/data-factory/connector-overview).


* Click on "Ingest" to begin the configuration\
<img alt="image" src="https://github.com/user-attachments/assets/73623245-ba7c-4d60-b5d1-6a96ac4fd28b" />

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

<img alt="image" src="https://github.com/user-attachments/assets/4ef4a1a2-528c-492b-b249-bec6c6221ec0" />

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

<img alt="image" src="https://github.com/user-attachments/assets/67372a44-2cca-4999-a48a-eb3653449430" />

* Under the **Source data store**, select **HTTP**

<img alt="image" src="https://github.com/user-attachments/assets/19de7d9c-4579-4610-9877-97616e09354f" />

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

<img alt="image" src="https://github.com/user-attachments/assets/0a4216be-1455-4e0c-b034-14fb92577080" />

* In the following screen, all defaults can be accepted

<img alt="image" src="https://github.com/user-attachments/assets/f57b2f12-3bf3-441f-ad35-d70e70631459" />

* 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.&#x20;
* By choosing the **Account Selection Method** "From Azure Subscription" the database details will be retrieved automatically.

<img alt="image" src="https://github.com/user-attachments/assets/fcc2ba13-d34b-4d3e-8fca-6e6ba43af837" />

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

<img alt="image" src="https://github.com/user-attachments/assets/89edadc5-8335-4fa7-b7e0-40c41fd1eac5" />

* Configure the **Source -> Destination** mappings

> [!CAUTION]
> Please ensure that your data fits the specified [database schema](./#schema-definition). 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.)


<img alt="image" src="https://github.com/user-attachments/assets/60302a40-9294-49e2-9e79-a98a9c1ca916" />

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

<img alt="image" src="https://github.com/user-attachments/assets/1dde6f7f-28b9-4b58-825d-ab5b1d7a1c39" />

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

<img alt="image" src="https://github.com/user-attachments/assets/feae6b98-c2c3-4806-817e-da55e6101538" />

## 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](updating-to-unified-contacts-pro-1.5.0.md).
>
> _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](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application) 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>`\


<img alt="image" src="https://github.com/user-attachments/assets/5c555165-523d-4808-9096-a298cde7d67a" />

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


    
<img alt="image" src="https://github.com/user-attachments/assets/970822d3-7951-4392-8ab9-62b50dc64737" />

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


    
<img alt="image" src="https://github.com/user-attachments/assets/520cf325-2d09-43fa-a15a-ea3b278f06fb" />

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)](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow).

\
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)](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#second-case-access-token-request-with-a-certificate).&#x20;
* More details on **Managed Identity** authentication can be found [here (Microsoft docs)](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token).

1.  Open the AppRegistration [from before](crud-operations-with-rest-api.md#permission-setup). 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".\


<img alt="image" src="https://github.com/user-attachments/assets/90e9ba87-8a94-4e31-9e76-a8eb67cb61f0" />

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\


<img alt="image" src="https://github.com/user-attachments/assets/50939eed-42e7-4329-a105-8539e4378cef" />

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

<img alt="image" src="https://github.com/user-attachments/assets/09b9ddd7-4eab-480e-af1b-49de1b94be5b" />

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


<img alt="image" src="https://github.com/user-attachments/assets/87c349b5-a7fd-4775-bffa-101c3b7160ef" />

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

<img alt="image" src="https://github.com/user-attachments/assets/5f7f4585-1be6-48de-a495-03fe341f0837" />

6.  Fill out the **Configure new token** category\


    
<img alt="image" src="https://github.com/user-attachments/assets/2b664aed-0129-44a5-b41e-acfa66d36e9d" />

    * **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:

    
<img alt="image" src="https://github.com/user-attachments/assets/44911dab-17b1-4af6-9120-7878df006da6" />

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.

<img alt="image" src="https://github.com/user-attachments/assets/a69c2e48-e28d-4db3-93dd-5d7f09f097b2" />

#### API Documentation

This section details the available REST API endpoints for contact operations. A full [swagger.json](./.gitbook/assets/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
  ```json
  {
    "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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