aurenz Presence Hub Administration Guide (EN)

Version 1.22 - 26.01.2024

Introduction

Are you annoyed by parallel phone calls when using Microsoft Teams together with another communication platform like RingCentral, Unify, Avaya or Cisco? Do you miss a reliable user presence status over all systems?

With Presence Hub SaaS, users' presence status is synchronized bidirectionally between all your communication platforms. This ensures that during a call, meeting or presentation, the "do not disturb" status applies in all platforms and a second call is suppressed.

Key benefits

  • Suppression of a second call in the Teams client if the user is already in a call via the PBX. The presence status in Teams is set to "Do Not Disturb" (DND) if the user is in a PBX phone call.

  • Set presence status in the PBX to "Do Not Disturb" (DND) if the user is in a Teams call, Teams conference or Teams meeting.

  • The Presence Hub receives change notification from Microsoft Teams and the PBXs. There is no polling of the actual presence status and therefore the status is updated in near real time.

  • Multi-tenant cloud service that seamlessly connects to your Microsoft Teams tenant.

  • Use the Microsoft Teams client and the phone client like usual. The relevant presence status is synchronized automatically.

  • No additional user interface to control the presence status needed

  • RingCentral: Set the RingCentral user to “do not disturb” also for a call in RingCentral. That prevents the user’s RingCentral clients to ring over an existing call.

  • RingCentral: Do you have several RingCentral instances in your organisation but one Microsoft tenant for all users? That’s no problem. Presence Hub can handle status synchronization of users out of multiple RingCentral instances and one Microsoft Teams tenant.

Read this document to learn about how to enable the service, how to configure the service for your tenant and how to work with it.

Table of Contents

How it works

The Presence Hub is a cloud service which receives presence information from MS Team users, on one hand and users in one or several other communication platforms, on the other hand. These can be classic on premise telecommunication systems but also cloud communication services. If a presence status changes in one of the systems, this change is transmitted from the Presence Hub to the other systems. However, through corresponding rules for status mapping between the systems, there is some logic to this subject -the main goal is to avoid parallel calls! That means calls must not be forwarded to the user if she already is in a call or meeting in one of the platforms.

 

Supported Platforms

  • RingCentral

  • Unify Office

  • Avaya Cloud Office

  • Alcatel Rainbow Office

  • Genesys Cloud CX

  • Avaya IP Office

  • innovaphone cloud PBX

Getting started - Onboarding Process

The aurenz Presence Hub is a cloud service which connects smoothly to your Microsoft Teams tenant. To enable the Presence Hub SaaS for your tenant, please follow the onboarding link that you got from aurenz. Alternatively, you can start the onboarding process via the Microsoft AppSource Marketplace by ordering the Presence Hub Saas there. In both cases you need to log in with an admin account during the onboarding process which starts right after the AppSource purchase process was finished. This is the page that will appear after the purchase was completed. Please start the onboarding process with “Start now!”. The onboarding will enable the SaaS for your tenant.

The account you use for the onboarding has to have the user rights to grant the necessary permissions for the app registration in your tenant. Please login with an appropriate account. The Presence Hub app requires the following application permissions:

If you’re not sure if your account has the required permissions, you can try to login. If you don’t have the required permissions, your login will be denied and you can login again with a different account.

After successfully logged in with an admin account of your organisation the onboarding process is completed and the service is ready to use. Just follow the instructions on the welcome page that is shown.

Login with this URL: https://presencehub.aurenzcloud.de

If after logging in, the Presence Hub shows a message that the onboarding was not completed please see the solution in the section Troubleshooting.

Configuration

Step 1 - Service User/ Service Principle

In order for the Presence Hub to get the change notifications from the users presence statuses, the app must log in to your Microsoft tenant with a service user account. Please go to Configuration menu and click on "Add Service User". A Microsoft authentication pop-up will appear, were you log in with the service users account. Please note that the service user must have the necessary permissions. If this is not the case, authentication will be denied and an error message will appear. These are the required permissions:

  • View users basic profile

  • Maintain access to data you have given it access to

  • Sign in and read user profile

  • Read all users full profiles

  • Read all groups

  • Sign users in

  • Read presence information of all users in your organization

  • View users email address

The Presence Hub does not store the service user password or any other credentials. After logging in with the service user account, the session continues to be used via access tokens which are regularly extended.

At the moment for the delegate permission a user account is necessary. In the next release we will provide the option to use a service

Step 2 - Enable synchronization for certain Users

The presence status synchronization is only carried out for certain users. You must explicitly specify these users in the user list. Select add user and enter the users email address in the search field or select a user from the list. The Presence Hub displays all users of your tenant. Confirm the selection with add selected user. The selected user then appears in the list of synchronized users. You have to activate synchronization for individual users. Therefore select the action “Enable Sync for selected users” and click the button Apply action for selected users..

You can add as many users in the table as you want, but you can use only as many users for synchronization as you have licenses.

If you delete a user, all data for this user will be deleted as well.

To protect the Presence Hub service from misuse there is a limit of status change requests per user per day. When a limit of 135 events per 30 minutes for a user is reached, syncing for that user will be paused for the next 30 minutes. If this is the case, the user gets marked as “blocked” in the user table.

Please consider to define one or more additional administrators to maintain the Presence Hub configuration. You do so by clicking Edit on the user list entry and assigning the Administrator role to it. The user’s role is displayed in the UserRole column in the user list. Please note: only administrator users can login into the Presence Hub configuration.

As an alternative to creating the user list manually, the user list can also be created by an import from the Azure AD. To open the import configuration settings please click on the link Setup Azure AD User Import which you will find above the user list. Define the filter criteria (AND condition) for selecting the relevant users from the Azure AD and define how to handle new users or users who no longer match the filter criteria. Before you run the import please store the settings and press the “Test” button to check the result. If everything is fine you can then execute the import. You also have the possibility to enable an automatic import on a daily base.

Users of the Presence Hub role “Administrator” will never be automatically removed from the user list by the import.

Additionally to the user import you can manage individual users in the user list manually. For these users set the option “manage user manually” in the users list.

Step 3 - Setup a PBX Connector

In order for the presence status to be synchronized with another communication platform, a PBX Connector to these systems must be defined in the Presence Hub configuration.

Depending on which system is to be connected, it might be needed to install a local component in your network that takes over the API communication with your local communication system. This is not needed if your communication platform provides a direct API access through the internet.

Here is a list of supported communication systems that can be connected directly in the Presence Hub without any local installations.

  • RingCentral: Direct API access through the internet, no local PBX Connector installation is required.

  • Unify Office: Direct API access through the internet, no local PBX Connector installation is required.

  • Avaya Cloud Office: Direct API access through the internet, no local PBX Connector installation is required.

  • Alcatel Rainbow Office: Direct API access through the internet, no local PBX Connector installation is required.

  • Genesys Cloud CX: Direct API access though the internet, no local PBX Connector installation is required.

  • Avaya IP Office: Direct API access through the Avaya MT-CTI3 interface

  • Innovaphone Cloud PBX

Connectors in work but not released yet for which a local but centralized PBX connector installation is needed (If you’re interested in using the Presence Hub for one of these PBX, please contact us):

  • Unify OSBiz

  • Swyx

Step 3.1 - Setup a PBX Connector for RingCentral or Genesys Cloud CX

Please configure a new connector under Configuration in the table of PBX Connectors with Add Pbx. A dialog appears: As type, select one of the entries that starts with “RingCentral” respectively “GenesysCloudCX”. If you have selected an item, a description of how the connector handles the status mapping appears below the combo box. Please check the description if the mapping rules fits to your requirements. If not pick another type and check again. Finally assign a meaningful name and description and commit the changes with update. The settings can be changed any time by selecting edit in the corresponding line in the list.

 

The rules for the mapping of the presence status between teams and the PBX will be displayed if you press the Info button of the PBX Connector in the list.

If the RingCentral’s built in presence sync is enabled the user presence status in Teams remains always in status “busy” after a call in RingCentral. Please disable this feature in the RingCentral admin portal! For details please check the Troubleshooting section.

You must also ensure that the RingCentral connection to the Microsoft calendar is disabled. Otherwise, the presence status in Teams will be switched to DND for every calendar event, regardless of whether the user is in a conversation or not.

For details please check the Troubleshooting section.

Now, after you created a PBX Connector instance, you have to configure the connection settings. This differs for each type and will be explained next: Select the new added connector in the list PBX Connectors and click the Configure button. Configuration details will be displayed in a pop up window.

Configuration for RingCentral

Please add a new RingCentral API access point. A RingCentral login window appears that asks for a RingCentral username and password. This user is a RingCentral user that will be used for accessing the RingCentral API for your tenant. The user has to authorize the Presence Hub SaaS to access to following RingCentral resources:

The RingCentral user you want to use needs to have the user role “User Admin” or “Super Admin”.

Single Sign On is not supported as login method here. Please disable the SSO option in the RingeCentral user settings for this user.

After successfully authorization you can close the login window. The API access point with its service user and the access token to refresh this login session are stored and presence change events will be received for the endpoints you will define in the next step. Also API calls to change the presence status in RingCentral will be done through this access point.

Due to RingCentral's API rate limits, one API access point has to be added for every 100 users that are enabled for presence synchronization. You can use the same RingCentral user account (extension) for all instances! Status change events will only be sent to the first access point (this is why the column “Last Subscription Id” is empty for all other access points).

Do you want to connect multiple RingCentral instances? You have to add one PBX Connector for each instance. Please contact us and we will enable this feature for you without any extra costs: support@aurenz.de.

Configuration Option Reflect DND back to RingCentral

With this option the Presence Hub sets the user in RingCentral to DND (do not disturb) during a call in RingCentral itself, Independent of the presence status in Microsoft Teams. This suppresses second calls in RingCentral. The "DND reflect" option is a global setting for all the users in the tenant.

 

Configuration Option Force ‘Accept queue calls’ option to be always enabled

This option forces the user to have the option “Accept queue calls” (AQC) active (what might be a company policy). When the user disables “Accept queue calls” in the RingCentral client the Presence Hub receives an event and actively enables “Accept queue calls” again. This setting affects all users but Individual users can be explicitly excluded from this setting in the user list.

 

Configuration for Genesys Cloud CX:

Before you can setup the connection to your Genesys Cloud CX instance you have to enable a “Client Credentials Grant” with the permissions “analytics:conversationDetail:view” and “analytics:agentConversationDetail:viewin” in your Genesys tenant.

Enter these credentials in the PBX Connector configuration window. Presence Hub uses this credentials to sign up to the API of your Genesys Cloud CX instance. You can test the connection with the Test button. Finish the configuration with Save.

Step 3.2 - Setup a PBX Connector for Avaya IPO

How to setup a PBX Connector for the Avaya IPO is described here.

Step 3.3 - Setup a PBX Connector for innovaphone cloud PBX

How to setup a PBX Connector for the innovaphone cloud PBX is described here.

How to interpret the connector status information

Immediately after creating and configuring the connector, the status is displayed as “Offline” (possibly with additional information), which is normal for the initial setup. However, by pressing Refresh (possibly after a short time), the status should change to “Connected”. Since no users/endpoints have been set up yet, this is the expected status to appear. If users and endpoints are already set up and have 'Sync enabled,' the status should be displayed as “Online”.

Here is a description of the various statuses and how they can be interpreted.

  • Online: The connector is online and has received events from both the presence hub and the PBX in the last 5 minutes.

  • Connected: The connector is linked, but no events have been received from the Presence Hub or the PBX in the last 5 minutes. If there are no ongoing presence changes, this is considered 'normal' (e.g., during a lunch break, etc.). Otherwise, it may indicate a problem.

  • Offline: The connector is not connected! Please review additional information in the status and configuration of the connector. More details are available in the Info (button on the connector).

Step 4 - Setup PBX Endpoints

Endpoint means an entity in the connected communication system to which a call can be addressed. This can be an extension, URI or an email address. After creating a PBX Connector, the endpoints to the associated Teams users can be assigned in the user list. To do this, select a user in the list and click the Endpoints Button. Depending on the communication platform, the users endpoint is defined as the extension, internal name or email address. The description is optional.

Endpoints for RingCentral

The RingCentral to Teams user mapping is done automatically after the RingCentral service user was configured or if the user list changes. The user mapping is done based on the users email address in both systems. If the email address of a user in RingCentral match a email address in Teams the endpoint of this user is assigned automatically to the Teams user. Use the extension number of the RingCentral user as the endpoint.

Endpoints for Genesys Cloud CX

The Genesys to Teams user mapping is done automatically after the Genesys PBX connection was established or if the user list changes. The user mapping is done based on the users email address in both systems. If the email address of a user in Genesys match a email address in Teams the endpoint of this user is assigned automatically to the Teams user. Use the Genesys user’s email address as the endpoint if you want to setup the endpoint manually.

Endpoints for Avaya IPO

If a user in the user list was created (manually or automatically) and ‘Sync enabled' is set for that user, the user’s email address is automatically used as an endpoint to identify the corresponding user in the Avaya IPO. If email addresses are also maintained in the Avaya IP Office for the users, an automatic mapping takes place without the need for additional interventions.

Should the email addresses not be maintained in the Avaya IP Office, an endpoint can be manually modified. Please use the users extension as endpoint (enter it in the Endpoint field).

Endpoints for innovaphone cloud PBX

If a user in the user list was created (manually or automatically) and ‘Sync enabled' is set for that user, the user’s email address is automatically used as an endpoint to identify the corresponding user in the innovaphone. If email addresses are also maintained in the innovaphone for the users, an automatic mapping takes place without the need for additional interventions.

Should the email addresses not be maintained in the innovaphone, an endpoint can be manually modified. Please use the users extension as endpoint (enter it in the Endpoint field).

 

The user list view will not be updated immediately if an endpoint was assigned to a user automatically. Please press the refresh button on top of the user list to update the view.

How to work with the Presence Hub

Normally, you won't even notice the Presence Hub in your daily work. You simply use your telephone clients and MS Teams as usual. It doesn't matter in which client you’re currently in a conversation, the Presence Hub ensures that all clients are synchronized and you wont get parallel calls. However, there are a few things you should be aware of.

Consider that with the Presence Hub, the presence status will play a more important role in your corporate communication. From now on the status is no longer just a displayed information, but also affects the telephone availability. Please consider the following rules:

"Busy" does not necessarily mean "DND"

MS Teams distinguishes between status "busy" and others that stands for "in a conversation". The latter is when you are in a call or in a meeting in the Teams client. “Busy”, on the other hand, is only set if you are in an appointment (event) in the calendar (without other participants) or when the user manually switches to "busy" in Teams. Since the "busy" status in MS Teams does not block any calls, it should not cause the PBX to block calls either. Whereas all other statuses in Teams that stand for "in a conversation" will cause that the status in the PBX is set to "do not disturb” (DND).

Briefly: Only if you are in a conversation in Teams the status will be changed in the PBX to “do not disturb”! Busy in Teams will have no affect on the status of the PBX.

Optionally you can use a status mapping that sets PBX status to DND also for scheduled meetings in the outlook calendar. Please consider, that the DND status is set for the whole scheduled meeting time, even if the actual meeting (conversation) ended earlier. As a result, calls are still suppressed even when the meeting has actually already ended. Please check the status mapping when you setup your PBX Connector in Presence Hub.

If you want to change the presence state manually, you have to do this in MS Teams

Since MS Teams combines presence status from Calendar, User, and Presence Hub, MS Teams is the leading system if you want to change presence status manually through the clients. Manually changing the status in the PBX (through your phone client) has no effect on Teams or is switched back again by the Presence Hub.

Licensing

The Presence Hub service is licensed per Microsoft Teams user, independent of the total number of users in the tenant or in the communication system you can choose for how many users you want to enable the service. Only for these users you need to order a license. The licences can be extended or reduced in your Office 365 Admin portal. Contact your system vendor if you did not obtain your license through the Microsoft marketplace. The amount of users available for presence synchronization (see users) is limited to the total amount of licenses. If the number of licences is reduced and become less than active users, the last users in the list will automatically be "deactivated".

Troubleshooting

Problem: After logging in, the Presence Hub shows a message that onboarding was not completed.

Solution: Please repeat the onboarding process but check this before: If you are already signed in with a Microsoft accounts, it is important that you sign out and close all browser windows so that there is no cached login session (copy the onboarding link into the clipboard before). Open a new browser window and paste the onboarding URL from the clipboard into the address bar. Login with the admin account to proceed with the onboarding.

 

Problem: You get calls in Teams while you are already in a Teams meeting or a Teams call?

Solution: You have to set the “busy on busy” option in Teams Admin Center. Read more here: https://learn.microsoft.com/en-us/MicrosoftTeams/teams-calling-policy

 

Problem: The presence status in Teams does not change at all if you are in a phone call with your PBX.

Solution: Please check the configuration in the Presence Hub Admin portal:

  • The presence synchronization for this Teams user has to be enabled in the user list.

  • An PBX endpoint according to this Teams user has to be assigned to the Teams user in the user list.

  • A service user or service principle that is used for receiving status change notifications from Teams users has to be defined in the Presence Hub Admin portal. Please check this settings in the Admin portal under Configuration

  • You can check the Event Logs in the Presence Hub Admin portal. You should see the events coming from the PBX and Teams and what status change they trigger.

  • Sometimes Teams does not show the latest presence status of the user. An update of the GUI can be triggert if you select another page in the Teams client. E.g. select the Calls page. Check if the user status display in Teams has changed.

 

Problem: The presence status in the PBX client does not change at all if you are in a phone call or meeting in Teams.

Solution: Please check the configuration in the Presence Hub Admin portal:

  • The presence synchronization for this Teams user has to be enabled in the user list.

  • An PBX endpoint according to this Teams user has to be assigned to the Teams user in the user list.

  • A service user or service principle that is used for receiving status change notifications from Teams users has to be defined in the Presence Hub Admin portal. Please check this settings in the Admin portal under Configuration

  • You can check the Event Logs in the Presence Hub Admin portal. You should see the events coming from the PBX and Teams and what status change they trigger.

 

Problem: Presence status in Teams changes but only after a long delay.

Solution: Usually the new presence status in Teams is shown within a second after the change. In some circumstances it could take several minutes until the status in Teams was updated. Please check the following

  • Check for new updates of the MS Teams client. Open the Teams client and click the 3 dots on the upper right corner of the client. Then check for updates and run the update if available.

  • A user whose mailbox is hosted on an on-premises Exchange server can cause these kind of problems. Please check the Microsoft documentation: https://learn.microsoft.com/en-us/microsoftteams/troubleshoot/exchange-integration/teams-exchange-interaction-issue

  • Sometimes Teams does not show the latest presence status of the user. An update of the GUI can be triggert if you select another page in the Teams client. E.g. select the Calls page. Check if the user status display in Teams has changed.

 

Problem: After a call in RingCentral the user presence status in Teams is not set to “available” but remains in status “busy”.

Solution: Probably the RingCentral’s built in presence sync is enabled. RingCentral sets the user status in Teams to “busy” on a CallConnect event right before the Presence Hub sets the status to DND. When the call ends the Presence Hub then resets the DND status and the status falls back to “busy” (status before DND).

Please “undo sync” in the RingCentral admin portal:

Problem: The user is set to DND in Teams even though there is no conversation in RingCentral. The presence status remains stuck in DND.

Solution: This could happen if the RingCentral Outlook calendar synchronization is enabled. Please ensure that the users has not activated the calendar synchronization in the Windows 365 or Windows Exchange connection. Check the setting in the RingCentral client: > Settings > Calendar and Contacts > M365 account connection > Manage > DISABLE Calendar checkbox:

 

Problem: The PBX phone client gets still calls even if my status in Teams is “busy”?

Solution: This is by design. A simple “busy” in Teams does not set the PBX status to DND (do not disturb) to suppress calls in the PBX. Reason: If a user has marked an event with "busy" in his calendar without having added another participant, Microsoft sets this user’s availability and activity to "busy" during the time. This does not mean that the user is in a conversation with someone else. Therefore the status in the PBX is not set to DND. Typical use case: A user is expecting a call at an agreed time. To schedule the call, the user sets a reminder in his calendar. If we would set the status to DND in the PBX during this calendar event, the call would not reach the user! Please Note: if the activity status is not “InACall”, “InAMeeting” or “InAConference” the status in the PBX will not set to DND.

 

 

 

© aurenz GmbH 2022