What is this article about?
This is a guide for the things you should be aware of and do in Emply when changing Microsoft Entra ID tenant.
First of all, it is important to understand what data are used for mapping data between the two systems:
Mapping condition
We map the Microsoft Entra ID user to the Emply user by the condition:
MicrosoftEntraID.User.Email is equal to Emply.User.Email
OR
MicrosoftEntraID.User.Userprincipalname is equal to Emply.User.UserName.
Once that is clear, we can move on to the specifics about changing tenant in Microsoft Entra ID.
Steps to change tenant
1. In Emply: Turn off Microsoft Entra ID integration
During the procedure, we will clean up all related to Microsoft Entra ID sync data in the database.
Note: during this step, we do not remove Users or Event, but we remove related mapping information between Emply and Microsoft Entra ID (Users, Calendars)
2. In Microsoft Entra ID: Prepare AAD group and users.
You need to prepare your new Microsoft Entra ID environment with correct groups and users, and migrate data to the new Microsoft Entra ID tenant.
We cannot provide specifics for this step, as it is done within Microsoft Entra ID.
3. In Emply (if needed): Update User\Employee User Name and Email
If you migrate Users with the same Email and Userprincipalname you can skip this step.
HOWEVER, if you are changing the main mapping as well, you will need to proceed with the following.
Go to Emply and update username and email to match the ones in the new tenant, so the system will be able to sync the user when turning on Microsoft Entra ID integration.
Example:
OldTenant:
Email: user@customer.com
Userprincipalname: user@customer.com
NewTenat
Email: user@newcustomer.com - Need to update the Email in Emply User
Userprincipalname: user@newcustomer.com - Need to update UserName in Emply User
4. In Emply: Turn on Microsoft Entra ID integration
Now you should be able to setup the integration in Emply and establish a connection to the new Tenant by giving proper credentials and Configure new Microsoft Entra ID group binding to Emply Role and clicking 'Save'.
At this point, all users with the same UserName or Email from Microsoft Entra ID will be linked with existing users in Emply, otherwise, new users will be created in Emply. Calendars should be enabled and start working again.
Caution: Even though Emply.User is linked with Microsoft Entra ID.User no properties such as department will be copied from Microsoft Entra ID to Emply if User is linked with Employee, as Employee is master in such case, therefore only the status AccountEnabled (i.e. user being active) will be mapped.