Support

Knowledge Base

Browse our knowledge base articles to quickly solve your issue.

Set up and configuration of the Workbooks Exchange Server Sync (WESS)

NOTE: Basic Authentication for Microsoft Exchange is no longer supported, if you are using Direct Logon method or Microsoft Exchange Impersonation Method of authorisation, you must switch to either Office 365 Oauth or Microsoft 365 Oauth (EWS Api) - Impersonated Logon. Please see here how to switch.

 

Purchasing the Exchange Sync licence

The WESS licence must be purchased as an add-on module per user – more information on the pricing of this can be found on our website here, or you can contact our sales team.

Activating the WESS module

Once the licence has been purchased, the corresponding module must be enabled in Workbooks. Go to Start > Configuration > Account Settings > Licences and Modules and navigate to the Modules tab. Tick the checkbox next to ‘Exchange Sync’ and click Save & Close.

Setting up the Exchange Sync

After enabling the module on your database, access the Exchange Sync admin panel by going to Start > Configuration > Email & Integration > Exchange Sync. Here you will be presented with a screen asking you if you would like to connect your database to the Exchange Sync Service - click 'Yes' to continue:

The next page will confirm that the connection has been successful, click continue to move on. You will then be presented with your Users tab, which will be empty for now.

You will notice three tabs across the top of the page:

  • Users - here you can add, remove, and amend Users' WESS access, and see at a glance what their sync status is.
  • Configuration - this is where you control how your Users log into the WESS, set up an Impersonation User, and view your Users' sync statuses.
  • Databases - this tab details what databases you have that are configured to access the WESS - having more than one database connected to the WESS is not recommended.

Users tab

The Users tab displays a list of all Users with an Exchange Sync License, and details whether or not their sync is enabled or disabled, along with a sync status column allowing you to monitor any errors that may occur.

Your first step will be to add Users by clicking on the 'Add Users' button in the top left, which will open a new window showing all of the Users on your database - you can select multiple Users at once in order to assign Exchange Sync licenses en masse.

Once a User has been selected, they will appear in the list on the Users tab and will be greyed out if their sync is disabled. You can remove Users from the WESS by scrolling across to the right of the Users tab and clicking the X button.

NOTE: When adding users to the WESS it is important to check that the user already exists within Workbooks. If a user is present in the WESS before adding them in Workbooks it causes an error. Please see here to resolve issue.  Always add users in Workbooks before WESS. 

Configuration tab

Upon loading the Configuration tab, you will be prompted to select your Default Organisation; you will then be presented with a number of sections as shown below:

  1. Users - this section contains much more detailed information than the aforementioned Users tab, including details of any errors that may have occurred, and if they are initialised or not. We recommend using this section for information only, and making any changes to Users via the main Users tab as previously detailed.
  2. Statistics - here you can find further information on your WESS Users; how many items were last synced, 
  3. Activity - this contains logs of every change made via the WESS Admin Panel, such as changing how Users access the Exchange Sync.
  4. Email Configuration - this section is where you will determine how your Users will access the Exchange Sync; the WESS supports four authorisation types, Microsoft Exchange Direct Logon (as of October 22 is depracated), Microsoft Exchange Impersonation (as of October 22 is deprecated) , Office365 OAuth, and Microsoft 365 OAuth Impersonation.  More detail on each of these can be found here.

  5. Customisations - this is the home of your WESS Add-in profiles, where you can create and update existing profiles and apply them to the entire business.

Databases tab

This tab lists the databases you have configured to access the WESS, we recommend only having one database - your Main database - set up to communicate with the Exchange Sync; having multiple databases configured to use the WESS is not recommended.

Back to top.

Instructions for IT

Checklist

Here is a summarised checklist of actions/information that are required of your IT Partner/Team in order to setup the WESS. Further details about the contents of this checklist can be found later on within this Knowledge Base page if required:

  1. Exchange Server Details

    If you are using either of the Microsoft Exchange login methods, you must obtain your Exchange server details. When using the 'Microsoft Exchange Impersonation' method, you can use your Impersonation User's login details to autodiscover your Exchange Web Services URL. If the autodiscover does not work, you will need to manually obtain your Exchange Web Services URL. If you are running Office365 this is most likely to be: https://outlook.office365.com/EWS/Exchange.asmx.

  2. Impersonation

    You must decide if you will go via the Impersonation Route. This may be easier for your organisation as it will reduce users' need to authenticate their accounts.  

    If you choose to use Impersonation, the Impersonation user needs to be setup by your IT Team, and Users' mailboxes need to be setup to authenticate via the Impersonation User. You will need the Impersonation User Email and Password.

  3. Configure your Exchange Server

    If you are running on premise Exchange you will also need to whitelist the following IP address range(s) from any intervening firewalls, mentioned in the ‘Configuring your Exchange Server’ section of this guide:

    23.97.212.108 (legacy)

    104.45.14.249 (legacy)

    20.67.154.92/30

    20.73.199.196/30

  4. Multi Factor Authentication

    The WESS does support MFA so long as you are using either of the Office365 OAuth methods of login. If you encounter any problems, then anywhere where ‘Password’ is mentioned, use a Microsoft generated ‘App Password’ instead.

Back to top.

Configuring your Exchange Server

Please configure your Exchange Server and any intervening firewalls to accept connections over HTTPS (TCP port 443) from these IP addresses: 


Legacy

  • 23.97.212.108 (The sync service, wess.cloudapp.net)
  • 104.45.14.249 through 104.45.14.253 (The provisioning system)

New (from January 2021)

Supported Exchange auth methods:

  1. 'Office 365 OAuth' allows users to authenticate themselves directly with Microsoft Office 365 from Workbooks Preferences. This is the simplest method.
  2. 'Microsoft 365 OAuth (EWS API) - Impersonated logon' enables the Administrator to use Office 365 authentication to configure impersonation for all of the users in the Organization. Users do not need to authenticate themselves via Workbooks Preferences. This is the most secure method.

To setup your email configuration for the WESS using the options above:

  1.  Navigate to WESS configuration via Start > Configuration > Email Integrations > Exchange Sync and then select your organisation. If you have multiple options here, then you will need to switch both of them individually.
  2. Once you have selected an organisation you will be taken to that organisation's screen. Navigate to Email Configuration tab and select one of two options: Office 365 OAuth or Microsoft 365 Oauth (EWS API) - Impersonated Logon.
    1.  If you have chosen Office 365 OAuth, the affected users will need to then navigate in Workbooks to, Start > Preferences > Exchange Sync, then the user will need to re-enter their Microsoft 365 credentials to authorise the WESS.
    2.  If you have chosen Microsoft 365 Oauth (EWS API) - Impersonated Logon, bear in mind the impersonated user must already be set up to do this (more information on this can be found on Microsoft's help pages here), you will be prompted to authenticate the impersonation user. Once the impersonation user is authorised, the organisations users can be reenabled and the synchronisation should function as expected. 

NOTE: When using "Domain\Username" format please ensure to use a back-slash, as shown, a forward-slash will not be recognised and will result in a failure to communicate with the Exchange provider.

Finding your Exchange Web Services URL

NOTE: When using either of the OAuth methods, you will not need to locate or enter your EWS URL as this is done automatically through Office365. 

Method 1: Automatic detection
Workbooks has the capability of running an automatic detection of the EWS URL built in when using the 'Microsoft Exchange Impersonation' method of auth:

Go to Start > Configuration > Email & Integration > Exchange Sync, on the Configuration tab, select the Email Configuration section and on the dropdown menu, select 'Microsoft Exchange Impersonation'. Enter your Impersonation User's details, and click the magic wand icon in the EWS URL field.

If the Automatic detection was successful then this means that the Exchange credentials entered were valid for Exchange validation. If not, you may see one of the following errors;

  • AutoDiscoverFailed - The autodiscover service did not manage to obtain Exchange Web Service URL. If this occurs we recommend using Method 2 (Manual Configuration) as opposed to autodiscovery.
  • Unauthorized - Either the Username or Password is invalid.
  • ErrorNonExistentMailbox - The email address provided is invalid.

Back to top.

Method 2: Manual Configuration
Go to Start > Configuration > Email & Integration > Exchange Sync, on the Configuration tab, select the Email Configuration section and on the dropdown menu, select 'Microsoft Exchange Direct Logon'.

You will then be prompted to input your company specific ‘Exchange Web Services URL’. This will only need to be entered once and should only be changed under special circumstances. If the value presented is not the correct format an error will appear.

The IT department at your company should know this information. If this is not the case, and you have auto-discovery set up then you can go to https://testconnectivity.microsoft.com/ and select ‘Outlook Autodiscover’. You should look for the value “EwsUrl” in the results you are provided with.
The URL you need will look similar to https://your.domain.name/EWS/Exchange.asmx.

Configuring usernames, passwords and Impersonation Users

Microsoft have a support article containing detailed information on Impersonation and how to configure this. The basic premise behind it is that an Impersonation user will control all of your User’s emails yet send them as if they have been sent from the mailbox owner. This is ideal for applications that connect to Exchange such as Workbooks as this one Impersonation User handles all emails, with the recipient completely unaware and the need for only one username and password.

If you do have an Impersonation User set up, then you should input your information into the corresponding field on the Email Configuration section. This will now work for all users who enable their synchronisation

User Preferences

If you do not have an Impersonation User for your Microsoft Exchange then each user must enter their own password. This should be done by the individual User themselves.

Go to Start > Preferences > Integration > Exchange Sync. Scroll down until you see the cog icon within the 'Microsoft Exchange Connection Status' section, and click on the cog.

Depending on what method of login you have chosen for your Users, they will then be presented with a screen prompting them to login - if you have selected the 'Any' option, they will be given a choice between the available options:

Users' Exchange Sync login information can also be viewed and changed by a System Administrator, however, the password will be encrypted to protect your Users.

Back to top.