---
title: "Microsoft Exchange ESA"
canonical: "https://help.agiloft.com/space/HELP/597164062/Microsoft+Exchange+ESA"
format: markdown
---
This topic will help you understand the capabilities of the Exchange synchronization (Exchange ESA) and how to set up and manage synchronization between the systems.

> ℹ️ **Prerequisites**
> ℹ️ 
> ℹ️ The Exchange ESA integration of <span style="color: #000000">Agiloft</span> works with MS Exchange 2013 and above for the Windows domain using Exchange Web Services (EWS). You need to grant an [impersonation role](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/58918622) to the Exchange user for this domain.

# Adding an Exchange ESA Sync in Agiloft

The steps in this section require you to alternate between your <span style="color: #000000">Agiloft</span> instance and MS Exchange, so open each one in a separate browser window or tab.

## In MS Exchange

1. Obtain the details of the Exchange user with the [impersonation role](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/58918622), who can access and perform actions over other mailboxes in the server. Some public Exchange servers require a full email (user@domain.com) as the user name here.
2. Check the Exchange host by navigating to `https://[Exchange Host]/EWS/exchange.asmx`.

## In <span style="color: #000000">Agiloft</span>

1. In <span style="color: #000000">Agiloft</span>, click the **Setup** gear in the top-right corner, go to Sync, and then select **New > External Sync** to open the External Sync wizard. Choose these settings, and configure the others as you like:
  1. In the General tab, enter a name, and select Microsoft Exchange as the External System Type.
  2. In Conflicts, select External System should take precedence.
2. Click Next to navigate to the ESA Settings tab.
  1. Enter the address of the Exchange Host, the full name of the impersonation user, the account password, and the user domain name. Refer to [Exchange ESA Impersonation](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/58918622) for guidance if you don't have this information already.
  2. Select Yes for Collect all user's contacts.
  3. Select the entities to sync. Exchange can sync Exchange users (with mailboxes), those users' contacts, and their calendar events.
3. Click Next. The system automatically tests the connection. If it passes, it opens the Mapping tab. If it fails, the error message provides some guidance on remedying the problem.

## Add Mappings

1. In the Mapping tab, select the external structure mappings for the defined Exchange attributes such as users, contacts, and calendar events.
  1. Calendar will match to events.
  2. Either Person or Employee will match to users.
    1. Note: If you want to use the Calendar synchronization, it is better to use the People table than the Employees sub-table because the <span style="color: #000000">Agiloft</span> calendar is linked to the People table.
  3. External User will match to contacts.
2. For each entity, click Edit Mapping to set up the field matching. Note that due to EWS restrictions, you can only perform People operations on <span style="color: #000000">Agiloft</span> and not the other way around.
3. We can use the following field mappings for the Person details:
  1. Alias to Login
  2. CompanyName to Company
  3. GivenName to First Name
  4. MailBoxAddress to Email (identifying)
  5. Manager to Manager Name
  6. Surname to Last Name
4. We can use the following field mappings for the Contacts/External Users details:
  1. Alias to Login
  2. CompanyName to Company
  3. DisplayName to Full Name (identifying, but not changeable at both ends)
  4. EmailAddress1 to Email (identifying)
  5. GivenName to First Name
  6. Manager to Manager Name
  7. Surname to Last Name  
Note: It is advisable to deselect the flag "Use strict match for identification". Setting it for strict match would prevent the sync of contacts that have no email address.
5. The calendar synchronization works in both directions, apart from deletions that work only from <span style="color: #000000">Agiloft</span> to Exchange due to Exchange restrictions.

## Sync Events

We can use the following field mappings for the Calendar/Events:

1. Duration to Duration
2. Start to Start Time
3. Subject to Description
4. ReminderMinutesBeforeStart to Notification Time

It is important to note that calendar events will sync to the Owner calendar. This mapping is set as the event owner in the Relation Mapping tab. This mapping is generally done automatically if the event Owner is the <span style="color: #000000">Agiloft</span> event creator. However, if you as an admin create an event to someone else, the mapping field must be changed accordingly, otherwise the events will not be synced. 

![Relation Mapping with ContactAttendees, UserAttendees, and event owner mapped](media://06c985d6-d926-4bc2-bf66-506b207914c9)

### Event Recurrence

The following fields can also be mapped to specify event recurrence:

1. IsRecurring to Recurrent - a choice field with No/Yes options.
2. Recurrence Pattern to Recurrence Pattern - a choice field with Daily/Monthly/Weekly/Yearly options.
3. RepeatAfter to Repeat After
4. Weekdays to Weekdays - a multi-choice field with the available weekdays listed.
5. EndEventType to End Event Type - a choice field with After Certain Date/After Number Of Events/No End Date options.
6. EndDate to End Date - the end of the event occurrence, used if End Event Type = After Certain Date. Note that End is not the same as End Date - see below for more details.
7. NoOfOccurrences to No of Occurrences

Note: The fields Start, Duration and End fields are used to set a formula where Start + Duration = End. Do not confuse End with End Date, or the formula will not have a result. 

- For a Yearly occurrence, the Start is defined as Month/Day, with an interval of 1.
- For a Monthly occurrence, the Start is defined as DayOfMonth.
- For a Weekly occurrence, the Start is defined as DayOfWeek, if Weekdays does not have a value.

## Add Relations

1. Click Next to open the Relation Mapping tab.
2. Set up the linked field relations with Exchange.
3. You can use the standard Calendar to Person table relations
  - Person (Creator Name, Creator Login, Creator Team) for Event Owner relation. This relationship is required, since an Exchange Event cannot exist without an owner. Any calendar events from <span style="color: #000000">Agiloft</span> must include the Event Owner person to be synchronized.
  - Person (personalinv) for UserAttendees
  - For the ContactAttendees relation, create a linked field similar to the Person (personalinv) from External Users to Calendar.

## Finish and Save

Define the Run Mode, and then click Finish to save the sync. 

# Test the Exchange Synchronization

The following examples will perform some tests of the Exchange synchronization:

## Sync Employees

1. Navigate to the Employees table, and select **Actions > Sync > Run <sync name>**.
2. This will create the Administrator and superimp users in the <span style="color: #000000">Agiloft</span> People table.
3. In Exchange, change the superimp user's name and re-run the sync.
4. The user should be visible in the People table.

## Sync Contacts

1. Navigate to the External Users table and select **Actions > Sync > Run <sync name>**.
2. This will result in contacts with matching emails being updated and some new contacts created.

## Synchronization restrictions with users

It is not possible to retrieve the Last modified date and time of users through EWS, so <span style="color: #000000">Agiloft</span> will sync all users whenever it's run.

Additionally, the functions Create / Update / Delete users are not supported using EWS.

## Sync contacts not in the Contacts folder of the impersonation user

1. In Exchange, log in as a user other than the impersonation role user, and create a new contact with an email address.
2. Verify that the user doesn't exist in the impersonation user's Contacts folder.
3. Run sync from the External Users table.
4. The user will be created in <span style="color: #000000">Agiloft</span> and they will be added to the Contacts folder of the user with the impersonation role.

## Delete contacts

1. In <span style="color: #000000">Agiloft</span>, delete a contact from the External Users table.
2. Run sync.
3. The user will also be deleted in the Contacts folder of the user with the impersonation role.   
Note: Agiloft will sync the delete operation with the Contacts folders of the impersonation user and not any other contact. So if another contact with the same email address exists in another user's contact folder, they will remain untouched.

## Create and Update Calendar Events

1. On the Calendar table Actions, run the sync.
2. Check that the new events were added to the <span style="color: #000000">Agiloft</span> calendar.
3. In <span style="color: #000000">Agiloft</span>, add an event that includes the admin user, and some other contacts. Sync the calendar.
4. Check that the event was added to Exchange.   
Note: if a contact does not exist in the user's contacts folder, they will be displayed as emails in the event attendees list.

### Event synchronization restrictions

Please note that only the first 1000 events will be synchronized starting from a week ago to two months in the future.

> Macro (hide-if)
> 
> #### Related articles
> 
> > Macro (contentbylabel)