Reference14r2:Concept App Service Connector for Microsoft 365
Applies To
- Connector for Microsoft 365 from Version 14r2
Overview
Connector for Microsoft 365 synchronises Microsoft Teams presences with the innovaphone PBX and back.
Requirements
- innovaphone PBX
- innovaphone Application Platform
- App(Connector for Microsoft 365)
- PBX-App(innovaphone-microsoft365) license per user - order no. 02-00050-009
Concept
Configuration
Please have a look into our Howto guide for basic configuration aid.
Technical Overview
If the Connector for Microsoft 365 app is fully configured, the app connects to Microsoft to obtain a token. With the token, the app gets the teams users (with a Teams license) through the Microsoft Graph API. A presence subscription to Microsoft is started with the licensed users of the PBX to get presence changes in Microsoft Teams for these users. A user subscription is also started to get changes of the users (adding, deleting or update). If a user has changed, the Teams users are retrieved again. If the presence has changed, it is forwarded to the PBX. The presences of Teams are mapped to the presences of the PBX.
- User subscriptions are renewed every 60 minutes.
- Presence subscriptions are renewed every 10 minutes.
- License Check is made periodically.
The app synchronises the PBX presence with Teams through the Graph Api. The on-the-phone presence will be renewed every 5 minutes. The other presences have a lifetime of 1 day but the away has a lifetime of 7 days. The lifetimes are described here
Please be aware: The actual change of presence or line state will be live, the above-mentioned subscriptions are needed to register against the Microsoft API for changes. After successful subscription Microsoft will trigger the Connector for Microsoft 365 App every time a presence or line state for a user has changed. The subscription will then be renewed in the above-mentioned time interval to receive further live updates.
User Matching
You now can choose the fields used for user matching on either side from the following options:
- PBX
- CN (Long Name property from the PBX user object)
- h323 (Name property from the PBX user object)
- Azure Portal
- displayName
- mailNickname
- onPremisesDistinguishedName
- onPremisesSamAccountName
- onPremisesUserPrincipalName
- userPrincipalName
Additionally, you have the possibility to remove a possibly contained domain from the Azure fields content.
Example: 'user@domain.tld' is transformed to 'user', if this option is checked.
Mapping Table
Teams Presence | PBX Presence |
---|---|
Away | away |
BeRightBack | away |
Busy | busy |
DoNotDisturb | dnd |
InACall | on-the-phone |
InAMeeting | meeting |
Inactive | online |
PresenceUnknown | online |
Available | online |
Offline | online |
Offwork | online |
OutOfOffice | away |
UrgentInterruptionsOnly | dnd |
Presenting | on-the-phone |
InAConferenceCall | on-the-phone |
The value "online" unsets the Teams presence in the PBX.
Master/Slave
For Master/Slave combination the "Connector for Microsoft 365" App has to be added to the slave (if no full replication is on). The slave websocket connection is needed to display "on-the-phone" presence.
Related Articles
Known Limitation
Line states set by the PBX does not block calls in Teams
Line states set by a 3rd party application (like the Connector for Microsoft 365) through the graph API are currently only for display purpose and do not block new calls in Teams.
https://techcommunity.microsoft.com/t5/teams-developer/ms-graph-setpresence-problems/m-p/2798805/highlight/true#M3957
As you can see in the above linked discussion, there once existed a feature request on Microsoft Voice, which is no longer available since it was not voted.
Maximum number of supported users
The connector now supports multiple Microsoft Teams communication users which is the prerequisite to subscribe for more than 650 users. There is a new ribbon (Manage Teams Accounts) that allows you to configure as many communication users as you need. Every configured communication user can be used to subscribe 650 users, for example:
- 3 configured communication users x 650 licensed users = 1950 users can be subscribed
Please be aware: Each communication user must have a Teams license applied.
This limitation is caused by Microsoft.
Trying to subscribe more than 650 users (with one communictation user) by using the presence subscription API will be declined by the graph API with an error message, that too many users are requested.
(The following article is also mentioning the limitation in the 3rd paragraph at bullet point 2: https://devblogs.microsoft.com/microsoft365dev/get-notified-of-presence-changes-the-microsoft-graph-presence-subscription-api-is-now-available-in-public-preview/)
Communication User (UserSynctoPbx)
Users with MFA (multi-factor-authentication) are not supported as technical communication user for the Connector.
Subscription Timeout
Situation
Due to a current limitation in the Graph API it is not possible to cancel or delete an active presence subscription.
As you can see in the of the current Graph API (1.0) the “Delete subscription” chapter does not include presence subscriptions.
It is also not possible to have multiple subscription in parallel.
To make sure to only request a new presence subscription when the old one is not valid anymore, the app will store the state of the presence subscription and the time until it is valid in the database.
As mentioned in the chapter “Technical Overview” we are creating presence subscriptions with a validity of 10 minutes.
The presence subscription will be renewed as soon as it is no longer valid which will be 10 minutes after initial subscription.
Impact
If settings are changed or the app instance is restarted it will check the corresponding database entry on startup.
In case the last presence subscription was completed less than 10 minutes ago, there is still an active presence subscription and the app has to wait for it to become invalid.
Some Changes (e.g., to the “Notification-URL”) will only take effect after a new created subscription.
The current Beta Version of the Graph API is already providing a function to delete presence subscriptions, so we hope we can improve this behavior in the future.
Troubleshooting
Creating an app trace
For further analysis and creating a support ticket it will be useful to have a suitable app trace.
Before creating the trace please make sure the following trace flags are activated for the app instance:
- App
- Database
- HTTP client
- TLS
- TCP
- App WebSocket
- Config
- Webserver
After setting the config flags, please make sure to
- stop the instance
- deleting the current instance log
- start the instance
Now please wait at least 5 Minutes before you save the log, otherwise we could not have the whole picture in the trace.
The restart and deletion of the the old log is useful the see the complete initialization process right away.
GUI Feedback
The app itself shows required states with green and red as connections to the Master PBX, Authentication and Presence Subscription to identify if there are problems.
Sometimes it needs a little bit time until the states are changed.
If the states remain, it is mandatory to enable logs on the app platform and check for more information.
(Concept App Service Connector for Microsoft 365: Creating an app trace)
No connection to Master PBX
Check the MasterPBX name.
The field must only contain the name [pbx], not the full domain [pbx.domain.tld]. (Synchronization from Teams to the PBX - Master PBX field)
Presence subscription failed
There are many reasons why the "Presence subscription failed" message could be displayed.
We try to list the most common reasons:
- The permission for the registered app in the Azure portal are not correctly set (Howto: Create an App for syncing Teams to PBX)
- The Notification URL is wrong (Concept App Service Connector for Microsoft 365: Correctness of notification URL )
- The App service is not reachable from the internet (Concept App Service Connector for Microsoft 365: Correctness of notification URL )
- The certificate for the public endpoint (e.g. reverse proxy) is not valid, or not publicly signed (Concept App Service Connector for Microsoft 365: SSL Certificate for notification URL)
- The user from PBX and the Azure Portal cannot be matched (Concept App Service Connector for Microsoft 365: User Matching)
- The App Platforms clock time is wrong (Concept App Service Connector for Microsoft 365: App Platform clock time is wrong)
- No user has a valid Connector for Microsoft 365 App license (Concept App Service Connector for Microsoft 365: Requirements)
Teams License for communication user
If presence subscription does not work, please check if all of the configured communication users have a Microsoft Teams license applied and no multifactor authentication is in use for this particular user.
Also please make sure you can login with the configured credentials. (If you have set a password as an Administration, the user needs to change the password during the first login, therefore the given password will be invalid for API access).
Sometimes, after changing setting or after the instance has restarted it can take up to 12 minutes until the presence subscription is working correctly. (Due to the subscription timeout)
SSL Certificate for notification URL
It also is useful to make sure the notification URL has a valid and public signed certificate.
You can do that, using an SSL-Checker, for example: https://www.sslshopper.com/ssl-checker.html
Without a valid, public signed certificate, Microsoft will decline the connection since it will not be possible to establish a trust relationship for the SSL/TLS secure channel.
Correctness of notification URL
You can try to open the notification URL in your Browser
Most likely you will see a HTTP 404 (Not Found) error message, which is the expected behavior since we are not providing an HTML website, the HTTP GET request from the browser will not be answered with content.
This is perfectly fine since Microsoft will send presence updates with HTTP POST and will not try to request content from our app.
What you can find out by trying to open the URL in your browser are the two following things:
- If you receive a HTTP 404 error message you are most likely connected to an App Platform, if not you need to check your DNS (and maybe also reverse proxy) settings.
- If the URL is modified and the used build number is added, an app has answered your request
- Example:
https://public.dns/your.domain/microsoft365/subscriptions
is modified tohttps://public.dns/your.domain/microsoft365/137786/subscriptions
- If this is not the case, your URL is wrong. (Be aware: The URL depends on the settings of the web server path of your app instance)
- Example:
Be aware: The URL-Recognition in the Application Platform is case sensitive.
Known Issues
Special Characters In Password
If you are using special characters (*, &, (, ), etc.) in you password you could possibly run into a problem with the authentication of the communication user.
The authentication failed status is beeing displayed.
For the moment the only workaround is to eliminate special characters from you password.
App Platform clock time is wrong
If the clock time at the App Platform is not correct, this will lead to an unstable behaviour of the Connector for Microsoft 365.
Since the Connector for Microsoft 365 is using the Microsoft Graph APIs presence subscription function, it needs to provide in its request a precise time until the subscription validity will be expired.
The app service is handling subscription and will automatically recreate a new subscription each time the previous one has expired.
A wrong clock time will lead to false expiration times and thus
- the subscription will be expired earlier than expected (synchronisation is not working because there is no valid subscription)
- the subscription will be valid longer than expected (the app service is trying to create a new subscription because it is expecting the previous one to be expired - will lead to a 409 conflict error, because only one subscription can be valid at a time)
If you are not sure about the current time of the App Platform, you can login via SSH into the App Platform and execute the date
command to check the current time.
You will receive an output like:
Tue Mar 12 13:38:57 UTC 2024
Please be aware: The time is displayed in UTC, so please make sure to convert to your local time zone.
Geoblocking
Since there might be no reliable country assignment for Microsoft addresses, all Microsoft addresses must be enabled on the upstream firewall in the event of geoblocking in order to ensure functionality of the Office365 Connector.
As an alternative you might be able to configure your firewall to bypass the geoblocking for the configured notification URL.