Blog article
How to synchronise contacts between Active Directory and Innovaphone?
by Matijs
Let's take some time to demo two of our products: the XQTING EasyConnect App & XQTING Integration Engine.
EasyConnect is developed for the Innovaphone App Platform. It allows integrators to interact with the Innovaphone Platform in a RESTfull manner instead of the Innovaphone C++ SDK or WebSocket protocols. This reduces complexity and often steep learning curve that is associated with innovaphone integration. The app is available for download in the Innovaphone App Store.
The XQTING Integration Engine is a "middleware" application server. The tool can be used for fast integration work and connecting several application platforms. There is a wide selection of data sources available to choose from like an HTTP client component, MS Graph client, various database types, …
In this post we will be using an HttpClient for interaction with the EasyConnect App & the MsGraph client. MsGraph will be used to fetch the contacts from all users in our Active Directory. All found contacts will be created (or updated) as contacts in an Innovaphone PBX by means of the EasyConnect App. By doing this, we are creating and maintaining an "address book" in innovaphone based on our Outlook contacts.
EasyConnect setup is not handled here. But the installation procedure is extensively described in the accompanying manual.
MsGraph App Registration
To be able to use the MsGraph Module in the XQTING Integration Engine, we need a clientid & clientsecret. This means we need to create an App Registration for the engine in Azure. How to register an Azure App has been described many times before (for instance here: https://learn.microsoft.com/en-us/azure/active-dir...).
In order to have access to the users in Active Directory & their contacts, the App requires the following permissions:
The Script
Before we start scripting we need to configure the MsGraph Module & HttpClient module. Since this requires no exotic parameters and mostly just a URL and the occasional clientid & clientsecret, this is not handled here.
What's more interesting is the flow of the script:
We kick off by getting all users from Active Directory (using the MsGraph module):
Let's take some time to demo two of our products: the XQTING EasyConnect App & XQTING Integration Engine.
EasyConnect is developed for the Innovaphone App Platform. It allows integrators to interact with the Innovaphone Platform in a RESTfull manner instead of the Innovaphone C++ SDK or WebSocket protocols. This reduces complexity and often steep learning curve that is associated with innovaphone integration. The app is available for download in the Innovaphone App Store.
The XQTING Integration Engine is a "middleware" application server. The tool can be used for fast integration work and connecting several application platforms. There is a wide selection of data sources available to choose from like an HTTP client component, MS Graph client, various database types, …
In this post we will be using an HttpClient for interaction with the EasyConnect App & the MsGraph client. MsGraph will be used to fetch the contacts from all users in our Active Directory. All found contacts will be created (or updated) as contacts in an Innovaphone PBX by means of the EasyConnect App. By doing this, we are creating and maintaining an "address book" in innovaphone based on our Outlook contacts.
EasyConnect setup is not handled here. But the installation procedure is extensively described in the accompanying manual.
MsGraph App Registration
To be able to use the MsGraph Module in the XQTING Integration Engine, we need a clientid & clientsecret. This means we need to create an App Registration for the engine in Azure. How to register an Azure App has been described many times before (for instance here: https://learn.microsoft.com/en-us/azure/active-dir...).
In order to have access to the users in Active Directory & their contacts, the App requires the following permissions:
- Contacts.Read (type Application)
- User.Read.All (type Application)
- User.Read (type Delegated)
The Script
Before we start scripting we need to configure the MsGraph Module & HttpClient module. Since this requires no exotic parameters and mostly just a URL and the occasional clientid & clientsecret, this is not handled here.
What's more interesting is the flow of the script:
We kick off by getting all users from Active Directory (using the MsGraph module):
msGraph.get("msGraph", "/users", onGetUsers);
onGetUsers is a callback method. The result of the query will be directed to this method.
Next, we need to get all contacts of all users (using the user principal):
Next, we need to get all contacts of all users (using the user principal):
msGraph.get("msGraph", "/users/" + userPrincipal + "/contacts", onGetContacts);
Using module methods (in this case the 'get' method of the 'msGraph' module) means the result is delegated to a callback method (in this case: onGetContacts). Since we are requesting contacts for all users, we've made use of a recursive algorithm. Without going too much into detail: there is a method requesting contacts for a single user, in the callback method of the query result, the method requesting contacts is called again, this time for the next user in line. All contacts are put in a single list.
Once all contacts have been received, we can start processing them. Each contact will be processed individually.
First, we check if the contact already exists:
Once all contacts have been received, we can start processing them. Each contact will be processed individually.
First, we check if the contact already exists:
httpClient.get('easyConnect', '/contacts/contact?search=' + displayName + '&apikey=xxxxxx', '', onGetInnoContact);
We're searching for contacts with the same display name as the contact in Active Directory.
The value of the body, is a simple JSON object with mapped values coming from the contact in Active Directory:
The value of the body, is a simple JSON object with mapped values coming from the contact in Active Directory:
var innoContact = {
"cn": contact.displayName,
"givenname": contact.displayName,
"dbsid": "4",
"email": email.address,
"mobile": contact.mobilePhone,
"telephonenumber": telephoneNumber,
"homephone": homePhone
};
When the contact is found (= the response contains exactly one result), we can update the contact using a PUT request:
httpClient.put('easyConnect', '/contacts/contact/' + encodeURI(distinguishedname) + '?apikey=xxxxxx', body, 'application/json', '', onUpdateInnoContact);
When the contact is not found (= the response contains no results), we can add the contact using a POST request:
httpClient.post('easyConnect', '/contacts/contact?apikey=xxxxxx', body, 'application/json', '', onAddInnoContact);
And that is all it takes to synchronize the contact information in your Microsoft 365 environment with your innovaphone PBX. Of course, it is easy to extend this integration or apply a similar synchronization:
- One could not get all contacts, but only specific lists from the directory and filter the data.
- You can also synchronize to other REST APIs; it doesn't have to be an innovaphone setup. Any REST API that allows you to manager your contact information can be used.
- If your contacts are in another database or application that has a REST API, you can replace the MS Graph part and synchronize the data to your innovaphone in a similar way.