Microsoft Exchange

This address provider allows to access contacts in Microsoft Exchange via the EWS interface. For this a "Service Account" from your Active Directory is required.

Configuration

Online

To access Exchange Online, authentication via OAuth is required. For this, an "App Registration" in Azure Active Directory is required. Follow these steps:

• Log in via the Azure Portal.
• Select your Azure Active Directory & copy the TenantId.
• In "App registrations" create a new one with any name you want.
• In the "App" under "Authentication" enable the "Treat application as a public client" option.
• Also in "Authentication" add urn:ietf:wg:oauth:2.0:oob as a "Redirect URI"
• Under "Manifest" insert the following entry under requiredResourceAccess within the square brackets:

{
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
        {
            "id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5",
            "type": "Scope"
        }
    ]
}

• In "Overview" copy the ClientId.

You can also read this configuration in the Microsoft Documentation.

After completing the registration, store the ClientId as AppClientId and the TenantId as TenantId.

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Microsoft Exchange address provider -->
  <AddressProvider id="24425bd4-d6f1-4e2c-a323-3cc63fb5f07b">
    <Debug>false</Debug>
    <Title>Exchange Online</Title>
    <EWSUrl>https://outlook.office365.com/EWS/Exchange.asmx</EWSUrl>
    <AppClientId>{AppClientId}</AppClientId>
    <TenantId>{TenantId}</TenantId>
    <UserName>{username}</UserName>
    <Password>{password}</Password>
    <!-- Optional Mapping -->
    <Mapping>
    </Mapping>
  </AddressProvider>
</AddressProvider>

OnPrem

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Microsoft Exchange address provider -->
  <AddressProvider id="24425bd4-d6f1-4e2c-a323-3cc63fb5f07b">
    <Debug>false</Debug>
    <Title>Exchange OnPrem</Title>
    <EWSUrl>{HOST}/EWS/Exchange.asmx</EWSUrl>
    <UserName>{username}</UserName>
    <Password>{password}</Password>
    <IgnoreSslErrors>false</IgnoreSslErrors>
    <!-- Optional Mapping -->
    <Mapping>
    </Mapping>
  </AddressProvider>
</AddressProvider>

Recommended mapping

The following mapping is recommended, but can be customized as desired.

<!-- AddressService -->
<AddressProvider id="E10A8313-A92D-4CB2-A12B-9AEB58F39207" order="1" active="true">
  <!-- serverside Microsoft Exchange address provider -->
  <AddressProvider id="24425bd4-d6f1-4e2c-a323-3cc63fb5f07b">
    <!-- other settings for OnPrem or Cloud -->
    <Mapping>
      <Map Source="GivenName" Target="Person_FirstName" />
      <Map Source="Surname" Target="Person_LastName" />
      <Map Source="JobTitle" Target="Person_Position" />
      <Map Source="Profession" Target="Person_Profession" />
      <Map Source="MiddleName" Target="Person_SecondName" />
      
      <Map Source="CompanyName" Target="Company_Name" />
      <Map Source="Department" Target="Company_Department" />
      <Map Source="Contact.Address.Street" Target="Company_Street" />
      <Map Source="Contact.Address.City" Target="Company_City" />
      <Map Source="Contact.Address.PostalCode" Target="Company_ZipCode" />

      <Map Source="Contact.Phone.Business" Target="Company_PhoneDirect" />
      <Map Source="Contact.Phone.CompanyMainPhone" Target="Company_PhoneCentral" />
      <Map Source="Contact.Fax.Business" Target="Company_FaxDirect" />
      <Map Source="Contact.Phone.Mobile" Target="Company_Mobile" />
      
      <Map Source="Mailbox.Address" Target="Company_EmailDirect" />
              
      <Map Target="Company_CountryShortCode">
        <Map.SourceExpression>
          function main() {
          switch(source('Contact.Address.CountryOrRegion')) {
            case 'Albania': return 'AL';
            case 'Andorra': return 'AD';
            case 'Azerbaijan': return 'AZ';
            case 'Azerbaidzhan': return 'AZ';
            case 'Belgium': return 'BE';
            case 'Bosnia and Herzegovina': return 'BA';
            case 'Bulgaria': return 'BG';
            case 'Denmark': return 'DK';
            case 'Germany': return 'DE';
            case 'Estland': return 'EE';
            case 'Finland': return 'FI';
            case 'France': return 'FR';
            case 'Georgia': return 'GE';
            case 'Greece': return 'GR';
            case 'Ireland': return 'IE';
            case 'Iceland': return 'IS';
            case 'Italy': return 'IT';
            case 'Kazakhstan': return 'KZ';
            case 'Kazakstan': return 'KZ';
            case 'Kosovo': return 'XK';
            case 'Croatia': return 'HR';
            case 'Latvia': return 'LV';
            case 'Liechtenstein': return 'LI';
            case 'Lithuania': return 'LT';
            case 'Luxembuorg': return 'LU';
            case 'Malta': return 'MT';
            case 'Macedonia': return 'MK';
            case 'Moldova': return 'MD';
            case 'Monaco': return 'MC';
            case 'Montenegro': return 'ME';
            case 'Netherlands': return 'NL';
            case 'Norway': return 'NO';
            case 'Austria': return 'AT';
            case 'Polen': return 'PL';
            case 'Portugal': return 'PT';
            case 'Romania': return 'RO';
            case 'Russia': return 'RU';
            case 'San Marino': return 'SM';
            case 'Sweden': return 'SE';
            case 'Switzerland': return 'CH';
            case 'Serbia': return 'RS';
            case 'Slowakia': return 'SK';
            case 'Slowenia': return 'SV';
            case 'Spain': return 'ES';
            case 'Czech Republic': return 'CZ';
            case 'Türkey': return 'TR';
            case 'Ukraine': return 'UA';
            case 'Hungary': return 'HU';
            case 'Vatican City': return 'VA';
            case 'United Kingdom': return 'GB';
            case 'Belarus': return 'BY';
            case 'India': return 'IN';
            case 'United States': return 'US';
            case 'Indonesia': return 'ID';
            case 'Thailand': return 'TH';
            
            default: return 'DE';
          }
            
          return '';
          }  
        </Map.SourceExpression>
       </Map>
    </Mapping>
  </AddressProvider>
</AddressProvider>

Parameters

• id 24425bd4-d6f1-4e2c-a323-3cc63fb5f07b.
• Title Title of the address provider. Default: "Exchange"
• EWSUrl Uri of the Exchange service endpoint. For Exchange Online this is always "https://outlook.office365.com/EWS/Exchange.asmx"
• UserName The user with which the provider logs on to Exchange.
• Password The password with which the provider logs on to Exchange (can be encrypted).
• AppClientId The AppClient id of the EWS app configured in AAD (Exchange Online only)
• TenantId The TenantId of the AAD (Exchange Online only)
• Debug true whether additional information should be logged. Logged are the existing values which can be used for mapping.
• IgnoreSslErrors Ignore invalid SSL certificates or not. Default: false. Only partially necessary for OnPrem option.
• Mapping Optional mapping to customize the filled information.
  The following data can be accessed via the default contact mapping:
  • DisplayName
  • GivenName
  • Initials
  • CompanyName
  • EmailAddresses
    • Dictionary of type EmailAddressDictionary and Enum EmailAddressKey as Key
  • PhysicalAddresses
    • Dictionary of type PhysicalAddressDictionary and Enum PhysicalAddressKey as Key
  • PhoneNumbers
    • Dictionary of type PhoneNumberDictionary and Enum PhoneNumberKey as Key
  • ContactSource
  • Department
  • JobTitle
  • Manager
  • Surname
  • AliasCertain values from the dictionaries are already extracted for the mapping and offered as simple values:
  • PhysicalAddressDictionary[PhysicalAddressKey.Business]
    • City → Contact.Address.City
    • Street → Contact.Address.Street
    • PostalCode → Contact.Address.PostalCode
    • State → Contact.Addess.State
    • CountryOrRegion → Contact.Address.CountryOrRegion
  • PhoneNumberDictionary
    • PhoneNumberKey.BusinessPhone → Contact.Phone.Business
    • PhoneNumberKey.CompanyMainPhone → Contact.Phone.CompanyMainPhone
    • PhoneNumberKey.Mobile → Contact.Phone.Mobile
    • PhoneNumberKey.BusinessFax → Contact.Fax.Business
  • MailBox
    • MailBox.Address → MailBox.Address
    • MailBox.Name → MailBox.Name
• Default Mapping The default mapping which takes effect if no mapping is defined includes the following properties (field names from Exchange):
  • GivenName
  • Surname
  • JobTitle
  • Profession
  • MiddleName
  • CompanyName
  • Department
  • BusinessPhone
  • CompanyMainPhone
  • BusinessFax
  • MobilePhone
  • PhysicalAddress.Business
    • City
    • PostalCode
    • Street
  • Mailbox.Address (Primary Email)

note

NOTE
EWS provides only the country name for an address, but not the ISO code of the country. In the OneOffixx recipient dialog, however, the two-letter ISO code must be set. For the default mapping this means that the country is not mapped via the address provider, but using the DefaultCountryCode from the general recipient configuration.
If it is necessary to set the country specifically, because addresses from different countries exist within the (A)AD, then this must be done the same way as for the Generic SQL address provider.