In this article we cover how the XQi Engine can be used to collect call records (CDRs) from your MS Teams tenant and send/insert them (in)to any solution where you might need them.
This example illustrates only one particular use case. In a similar way, many other notifications (also called webhooks or subscriptions) from other applications, can be handled by the XQi Engine!
The advantage of notifications is that you only start a process when there is an actual change in the data. This is in general a much better way to work than when you have to poll for changes, as described in our previous article: https://xqting.wordpress.com/2020/07/06/synchronizing-azure-ad-users-using-the-xqi-engine-and-ms-graph/.
However, when an API generates notifications, another problem quickly arises: your application becomes the target and it must have a web server that can handle these notifications (HTTP requests). This is fundamentally different than calling API functions yourself; you act as client, make the requests and process the response. Running as a web server and handling HTTP requests, is in general a lot more complex.
Luckily, the XQi Engine does not only have a HTTP client module; it also has a HTTP server module onboard. This allows you to easily use it as a web server handling all kinds of notifications, without the burden of having to implement a server application from scratch.
Configuring the XQi Engine as web server
When an application generates notifications, you have to configure the URL that must be called in that application.
See the next chapter in this blog article on how to create a notification in MS Graph to receive information about call records. Each application will have it’s own way of configuring. For some this will be done using the administration web interface of that particular solution, for others, this will be done using other API functions… it depends on the application.
The XQi Engine is a web server and handles requests for its own administration web interface. All requests made to the “httpserver” path will be redirected to the http server script module, and, can be handled in the process script any way you like.
For example, suppose your XQi Engine web interface is reachable via https://xqiengine.company.com. Any request that starts with https://xqiengine.company.com/httpserver will be routed to the HTTP server module and can launch a new process. For our example, we will configure the URL https://xqiengine.company.com/httpserver/callrecord as the notification URL. In the engine configuration script, this is simple and only a few lines of code to define a new route:
Multiple routes can be defined. If needed, the same or different process scripts can be used to handle these requests. There is also a possibility to define different routes for different HTTP verbs that might be used.
Handling an incoming request is done by implementing the the httpServer.onRequestReceived function in the process script:
Processing in this case means you can write it to file, push it to the database of an ERP or CRM application, call another REST API with the data, etc. This is up to your specific situation. See other articles on the XQi Engine on how to use the different modules, or, see the documentation and examples that come with the engine.
Configuring subscriptions in MS Graph
To get notifications (and in MS Graph, they are actually called subscriptions) from MS Graph API, you must register your URL using the MS Graph API. The Microsoft 365 administration web interface does not have any means to configure this. See the information on https://docs.microsoft.com/en-us/graph/webhooks. You can for example do this using a tool like Postman and call the create subscription API and provide the URL to your XQi Engine implementation.
However, when you do this, you will notice that during the creation process, your URL will already be called one time for validation. Even more, if you do not reply this request correctly, the creation of the subscription will fail! From the documentation, you can find that the validation will be done by calling the URL with a specific validation Token query parameter in the URL, and, that the value of this token must be returned as content of the request. As such, you have to support the validation handling in the XQi Engine process script for when this happens. As always, this is pretty easy to add in the XQi Engine:
If you do not have a tool like Postman available to call the “create subscription” function of the MS Graph API, it is possible to use the XQi Engine to create it, using the msGraph module and a little workaround: you can define a route for an URL, let’s call it “CREATE_SUBSCRIPTION” and define a path for it, e.g. “create”. When you call this URL (something like https://xqiengine.company.com/httpserver/create) in your browser, you will trigger the process script. In your process script, you can then execute following code to create a new subscription in the MS Graph API:
For the configuration of the MS Graph module, we refer to these articles:
Make sure to read the limitations about registering subscription in the MS Graph API. There are important limitations to take into account. One of them is the expiration date which cannot be far in the future (only a couple of days). It requires you to renew the subscription on a regular base. This can be done with the timer module of the XQi Engine if needed.
Public access to the XQi Engine
One of the basic requirements to receive notifications from a cloud application or platform such as Microsoft 365, is that your XQi Engine installation is publicly available. This means there must be some DNS name and/or IP address that is pointing to your engine. This must be planned upfront, and this must most likely be configured by your IT administrator (if you run the XQi Engine on-premise). If you use a cloud instance of the XQi Engine provided by us, we will take care of that. Furthermore, if you need/want to use HTTPS, you will also need a valid certificate installed.
In development, or even in production, a possible solution to overcome this, is to use a tool called ngrok: https://ngrok.com/. Ngrok has proven to be usefull in this type of development and services many times, and we can strongly advise it.