Set up and configuration of the Workbooks Exchange Server Sync (WESS)
Purchasing the WESS
In order to use the WESS it must be purchased as an add-on module on a per user basis. More information can be found here or you can call our sales team.
Activating the WESS Module
Now that you have purchased the WESS add-on, and it has been applied to your Account, the module needs to be activated. Go to Start > Configuration > Users & Security> Licences and Modules and navigate to the Modules tab. In the list of Modules on this tab ensure that the Exchange Sync Module is activated as in the screenshot below;
Allocating WESS licences
Once you have activated the WESS module, you must allocate the licences you have purchased to the users that need them. This can be achieved by going to Start > Configuration > Users & Security > Users. Select a user that you would like to allocate a licence to.
Ensure that under the ‘Licence’ section, the ‘Allocated Extension’ for ‘Exchange Sync’ is checked. This will enable the WESS for the specific user and reduce the number of licences you have left to allocate to other users.
Once you've allocated a user this extension, click Save and a new reveal section will appear named ‘Exchange Sync’. If the Exchange Synchronisation has not been enabled for this User yet, either by them or you, then you will be presented with the following message.
This can be changed by the User themselves by enabling their synchronisation.
Go to Start > Preferences > Integration > Exchange Sync and tick the ‘Synchronisation Enabled?’ checkbox.
This can also be done by a System Administrator.
Go to Configuration > Email & Integration > Exchange Sync, select the user you would like to enable and tick the checkbox.
This message will now change and you will be presented with the following information.
As a System Administrator you can select the database that the user will synchronise with and change their username and email address. This should not need to be changed often, if at all, as the ‘Exchange Email’ must be the Outlook email address they use.
Summarised Checklist for IT
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
You must obtain your Exchange Email Address, Exchange Mailbox, and Exchange Password. These will be used to autodiscover your Exchange server details. If the autodiscover does not work, you will need to 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 or Direct Authentication
You must decide if you will go via the Impersonation or Direct Authentication Route. We strongly recommend the use of Impersonation, as this simplifies set up of each User, and will prevent Users from having to re-authenticate with your Exchange Server if they change their Exchange Password.
- 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.
-
If using Impersonation, you will need the Impersonation User Email and Password, otherwise, you will need the individual Users emails and passwords of each User that will be using the WESS (or you need to prepare each User to enter these themselves).
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 not currently support multi factor authentication. If you have this configured, then anywhere where ‘Password’ is mentioned above, use a Microsoft generated ‘App Password’ instead.
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)
- 20.67.154.92/30 (Primary, North Europe location - Ireland)
- 20.73.199.196/30 (Fallback, West Europe location - Netherlands)
Supported Exchange auth methods:
1. Direct: username and password are required
2. Impersonation: username, impersonation-admin-mailbox and impersonation-admin-password are required
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
Method 1: Automatic detection
Workbooks has the capability of running an automatic detection of the EWS URL built in and is the default method of entering the EWSURL. When intially setting up the WESS simply add your main Users login credentials and Workbooks using an automated version of the video above to locate the EWSURL;
Go to Start > Configuration > Email & Integration > Exchange Sync and enter the Main Users Login details;
If successful the following window will open with the EWSURL following values entered by Workbooks are valid;
- Email - The Email used for autodiscovery.
- Password - The Exchange password for the User Mailbox, used to perform authentication on Exchange server.
- UserName - The User name used to perform authentication on the Exchange server. This is usually the same as the Mailbox email address, e.g. user@company.com, but for some Exchange servers it may be the domain\user format.
If the Automatic detection was successful then this means that the Exchange credentials entered were valid for Exchange validation. If not, the possible errors you will receive will be one of the following;
- AutoDiscoverFailed - The autodiscover service did not manage to obtain Exchange Web Service URL. If this occurs Workbooks suggests utilising Method 2 of this Knowledge base article, please contact support@Workbooks.com if this problem persists.
- Unauthorized - Either the Username or Password is invalid.
- ErrorNonExistentMailbox - The email address provided is invalid
NOTE: The Autodetect can take some time but this check will run in the background allowing you to continue with other work as the checks take place.
As a System Administrator you are now presented with two options. If you have an Impersonation User set up on your Microsoft Exchange server then you will only need to enter this Username and password, leaving minimal configuration for your Users to complete themselves. This is our recommendation.
Method 2: Manual Configuration
Workbooks needs information about your Exchange server in order for the two to be able to communicate. This information needs to be input into the ‘Exchange Sync’ section of Configuration and thus requires System Administration capabilities.
Go to Start > Configuration > Email & Integration > Exchange Sync.
The first piece of information to obtain and input is 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;
NOTE: If this is changed, please let Workbooks Support know, because in some cases the change to the URL will not take effect.
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
A video guide of how to do this is shown below.
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, shown below. This will now work for all users who enable their synchronisation.
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.
The email ‘Exchange Email’ and ‘Exchange Password’ are the credentials they use to log in to Outlook or any other Exchange service.
This information can also be viewed and changed by a System Administrator, however, the password will be encrypted to protect your Users.
NOTE: Workbooks runs a automatic check on save when entering these details. If it finds that it cannot make the connection it will inform you that the credentials entered have been rejected.
From this Preference pane, a user can "force a Sync" by clicking the "Sync Now" button.
Go to Start > Configuration > Email & Integration > Exchange Sync.
Then select the user that you would like to modify and you will be presented with the same information.
User Preferences
To ensure the WESS is running correctly, the individual User and the System Administrator can both access the same information via different paths.
A User should go to Start > Preferences > Integration > Exchange Sync.
The information here will provide the User with data about recent synchronisations (including any errors), the ability to change any configuration settings (although these should not need to be modified) and the capability to enable or disable their own synchronisation.
The ‘Connection’ section allows a user to synchronise with a different Exchange server from the company’s, using a different ‘Exchange Web Service URL’, this is not a common situation.
If a User has any reason to believe that their Exchange Synchronisation is not working then they should look here first, and search for any errors such as the ones highlighted above. They should then contact their internal Workbooks Authorised Support Contact who will contact the Workbooks Support team if they're unable to resolve the issue themselves.
It is also recommended that users check this section once in a while to ensure their synchronisations are running correctly and as often as they would expect.
System Administrator Configuration
Go to Start > Configuration > Email & Integration > Exchange Sync.
Select the User for whom you'd like to view synchronisation data and you will be presented with the same information that they see in Preferences. If a User is having issues with their WESS then ensure that synchronisation is enabled and the correct database is selected. Double check that the user is entering the correct Exchange email and password by asking them to log in to Outlook web access with the same credentials.
NOTE: The WESS will not synchronise for any User that has not been activated, is awaiting a login email address change and/or has been disabled.