Exchange Server Sync - IT Setup Guide
NOTE: Workamajig is deprecating the Exchange Server Sync. The preferred connection is using a subscription to your Outlook calendar. The tool may be hidden in the UI. If you do not see Sync Settings, please contact your Account Manager at support@workamajig.com for further assistance.
NOTE: The guide below is for your IT Team to set up and test the connection between Workamajig and Outlook/Exchange. Individual Users should use the User Calendar Setup Guide
Workamajig has the ability to synchronize your Workamajig Calendar information with Microsoft Exchange Server to reflect the same information. The sync is designed to connect the individual user's personal calendar in Outlook/Exchange with their personal calendar in Workamajig. For example, when entering an appointment into your Microsoft Outlook, this appointment will automatically be entered in your Workamajig Calendar. The sync direction can be in both directions. However, you may consider that if Outlook is your main calendar, the sync may be set up in a unidirectional manner so Outlook meetings are synced into Workamajig only to ensure meetings are included in the user's daily workload considerations.
For this synchronization to take place, you will need to install the Workamajig Exchange Windows Service onto a single Windows-based server or workstation. This single installation will be used by the entire organization and is typically installed on the same server running Exchange.
NOTES
- DO NOT install the sync tool on each workstation in your organization.
- Exchange is a Microsoft product, as such the sync tool we created requires it to be installed on a machine running Windows OS.
- If you are using 2-Step Authentication: Make sure each person is able to create an App Password for use when creating their individual calendar sync connection.
If you encounter any difficulties, please email support@workamajig.com.
Additional Information for Network Administrators
Upgrading to a New Exchange Server
Overview
The synchronization between Exchange and Workamajig is accomplished by a small program installed onto a single Windows-based OS machine that acts as a conduit for the information. It talks to both sides and handles updating the information. In order to synchronize information from Exchange to Workamajig, you must map folders on each side to each other. When the sync program runs for the first time, it retrieves a list of folders that are available to it based on the login information provided in Workamajig. These folders must be brought into Workamajig the first time in order to allow you to then map the exchange folders to the Workamajig folders. The reason that Workamajig does not directly go for the folders in Exchange is that we may not have direct access to the Exchange server. If you use our hosted service, your exchange server is likely not available on the web. In this case, the synchronization service on the Windows-based machine would be installed behind your firewall (it does not have to be on the exchange server). The service then sends Workamajig a list of folders and you can then set up the mapping from that point. If a folder is not mapped to an exchange folder, then it will not synchronize any information.
The synchronization process looks for the most recent record and updates each side accordingly. This process is invisible to you but will require an initial setup to identify folders and settings to use for this information exchange. This guide will walk you through this setup process. The following is an example as to how conflicts are handled:
- If the last sync was on 10/1 and the last time the exchange record was modified was 9/30 and the last time the Workamajig record was updated was 10/15. When the sync is run on 10/20, the Workamajig record will replace the exchange record completely because it was last updated. The same holds true if the direction was reversed.
- If the last sync was on 10/1 and the last time the exchange record was modified was 10/5 and the last time the Workamajig record was updated was 10/15. When the sync is run on 10/20 then the system uses a method of least lost data.
- If a field in exchange does not have data, and the field in Workamajig does, it will add the information to exchange.
- If both fields have data, then the side that was updated last wins. In this case, the Workamajig information would update the exchange server in that field.
Public Folders
Public folders are accessed by the main exchange login ID you provide to Workamajig. NOTE: Public Folders do not sync if using Office/Exchange 365. Public Exchange folders can be mapped to public folders in Workamajig. Same for private folders.
Additional Information For Network Administrators
How Does it Work?
The Windows Service runs on a selected 60sec to 60min interval and communicates with both Exchange and Workamajig (WMJ). It will obtain the Exchange credentials from WMJ. For each user, it will log into the Exchange Box using WebDAV and first pull back all their Calendar folders and send that to WMJ. If folder mapping exists in WMJ, it will request all Calendar information from the Exchange server and send it to the WMJ sync engine. The sync engine will determine the most recent information and will update each system accordingly.
The Windows Service has no logic and only serves as a communication bridge between WMJ and Exchange. Because the service is stand-alone, there are a few different configurations for this process to function. For example, the service could reside on the Exchange Server, the WMJ Web Server, or any Microsoft Windows Box that meets the requirements listed below.
Workamajig Exchange Service Requirements
The sync tool only needs to be installed on a single Windows-based machine to be used by the entire organization. Do NOT install on multiple machines.
- .NET 2.0 Installed
- Hosted customers: The service must have access to the internet on port 443 (SSL).
- Service should be installed on a Windows Server, Exchange Server, or Windows Workstation.
NOTE: A Windows Workstation installation must be a stand-alone machine. It should also be set to not go into Sleep/Hibernate mode and only be tasked with performing the sync function. There may be other needs regarding the actual service installation, see below.
Microsoft Exchange Server Requirements
- Workamajig currently supports Microsoft Exchange 2013, 2016, and 365.
- The server can be hosted on your server or via an outside hosting service.
- OWA (Outlook Web Access) must be enabled.
NOTES:
- Exchange 2003, 2007, and 2010 are no longer supported by Workamajig, but should still work with the Exchange Sync Tool.
- Exchange 2013, 2016, and Exchange 365: Workamajig does not support syncing of Exchange Public Calendar Folders.
- If updating/migrating your Exchange server, please contact install@workamajig.com prior to making changes for the latest steps to follow.
Configuration
Creating a thin service allows for a number of different configurations:
- Install the service on the same box running Microsoft Exchange Server.
- Install the service onto the Workamajig Web Server. (Local Installed Only-if you are on a Workamajig app server, this is not available).
- Install the service onto any Windows Server.
- Install the service onto any Window 7 and above the workstation. This workstation must always be on and set to not sleep/hibernate.
Process Flow
Workamajig Exchange Service
A windows service that communicates with Microsoft Exchange using WebDAV and with the Workamajig Exchange Connector using a web service.
Workamajig Exchange Connector
This component listens.
Central Sync Processor
This component is responsible for comparing data from Microsoft Exchange against Workamajig.
Installed Customers
Hosted Customers
Setup Exchange Sync Tool
EXCHANGE SERVICE SETUP
Download the Workamajig Exchange Windows Service.
Unpack the zip file to the location you wish to run the tool from. NOTE: All files must remain within this folder for the tool to work correctly
Right-click WSSExchangeSettings.exe and select Run as Administrator. You will get the following screen:
Click Install: This will install the Workamajig Exchange services
Click Start: When clicked the Workamajig Exchange service will start.
Click Modify Settings to begin configuring the tool
NOTE: For Window Workstation installations the WSSExchange Service may not install, which would be indicated by the Start button not appearing, you will need to unblock the WSSService.exe.
- Right-click on the WSSService.exe and select Properties.
- Click the Unblock button, and then click OK
- You can now go back to WSSExchangeSettings.exe and perform the install again.
NOTE: If you are not using a Windows Server machine, you may need to go to the Computer Management Console > Applications & Services > Services > find WSSExchange: right-click > Properties > set Startup Type = Automatic. Also, confirm the service is in the Status= Running
You will also want to make sure the workstation sleep settings have been turned off or adjusted to fit your office work hours.
Configuration Tab
.png)
Web Site Settings
WMJ URL: This is the website where you log into Workamajig. You do not need to add the HTTP:// or HTTPS:// in front of the URL
NOTE: If you are using a Workamajig server, DO NOT add /platinum to the URL. Ex.: USE>>app.workamajig.com NOT app.workamajig.com/platinum
WMJ User ID: The User ID you use to log into Workamajig.
NOTE: The User ID is used for testing purposes only. It is used to confirm that the website is correct. If you receive an error, confirm that the URL and UserID are correct. The credentials that are set up by the individual users in Workamajig will be used for the actual sync process.
SSL: Check this box if your site uses SSL. (This must be checked if using a Workamajig App server. This will auto set the port 443)
WMJ Port: Enter the port for the Workamajig website. (If using a Workamajig App server, this should be set to 443)
Test Web Site: Will test the credentials entered.
Exchange Server Settings
Exchange Server Name: The name of your exchange server
NOTE: The Exchange Server Name field if you have been using Exchange 365 must be left blank. The system needs to hit the auto-discover URL on Microsoft's servers which tells the system which server your mailbox is on. Everything else remains the same.
Mailbox (Optional): The mailbox of the user. Only use this field if the mailbox is different from the user name.
User Name: The user name you use to log into Exchange email.
Password: The password you use to log into your Exchange email.
NOTE: The User ID and Password are used to confirm the connection to the Exchange/365 site and must be left in place. The individual logins credentials set up by the users on their calendar will be used to sync their individual calendars. If you receive an error, confirm that the URL, UserID, and Password are correct. The credentials that are set up by the individual users in Workamajig will be used for the actual sync process. For Exchange/Office 365 see below.
PUBLIC FOLDERS NOTE: If using a stand-alone version of Exchange and wishing to sync public calendars, the login credentials are mandatory and must provide access and edit rights to the Exchange Public Calendars.
Port: The port is used to connect to the OWA interface.
SSL: Check this box if your OWA site uses SSL.
Use GMT (turned off by default): unchecked by default: this must be checked if you are using GMT for your Exchange server.
Version: select the version of Exchange you are using.
Start Month: select how far back you would like the sync to look. (Initial sync time to completion will be greatly affected by the selection. Most will set to -6) NOTE: Recurring Meetings must be set up with the Parent meeting being created within the Start Month range. If it is outside this range, the meeting will not be synced into Workamajig. We also recommend that the number of recurrences does not exceed this number. Ex. if set to -12, then you should only setup 11 recurrences,
Delete Timeframe: select how far back you would the sync to look for deleting past events ( Most will set to -1)
Test Exchange: It will test the Exchange server settings.
NOTE: If you are using Test Exchange and using 365, please refer to the following information for testing your connection.
Service Timer
Service Timer: The interval the service will run. Our recommendation is 30 minutes.
NOTE: If you are a large organization and are using Exchange 365, please set this to 60 for the initial sync. Otherwise, the service may not be complete prior to making another "sync request" to 365. You may also consider rolling it out in waves to prevent Microsoft from shutting down your access. Once all users have completed the initial sync, you can return this to 30 min.
Maintenance Window: REQUIRED: The time interval when the process will stop syncing. The times MUST be selected or the tool will not run correctly. If left blank, it is considered a 24hr window of no syncing.
Save Settings: Will save your settings
NOTE: Prior to testing connections and using the tool, all fields must be filled in except those designated as Optional. If a field is left blank an error will occur.
LOGGING TAB
Logging - most will only use the logging features for initial setup and troubleshooting. But you can keep logging turned on. But be aware that some logging levels will quickly produce a very large log file.
Turn on Logging File: When checked, the exchange process will write out logs to the server.
Test Write Permissions: This button will write out a test file to verify security settings.
Logging Level:
- Extreme: will log all communications with the webserver.
NOTE: This is not to be used for daily logging as the files can get large since it logs every piece of communication. - Detail: will log most communications with the webserver.
NOTE: This is not to be used for daily logging as the files can get large since it logs every piece of communication. - Abbreviated: will log steps during the sync process. Typically used for first step troubleshooting
- Errors Only: will only log errors. This is the typical setting if you want to keep logging turned on.
Mail - This is used to send out error messages regarding the sync.
Server: Your SMTP server.
User ID: The user ID used for sending emails using the SMTP server.
Password: The password used for sending emails using the SMTP Server.
Authentication Method: The authentication method. Most times left blank.
Email Test To: Enter an email address if you want to test the email credentials.
Send Test Button: Click the button to send a test email.
Support Only - This section will only be used for troubleshooting when requested by Workamajig.
REAL-TIME WATCH
This tab is used for initial setup and sync troubleshooting.
Start Manual Sync: This forces a sync session to begin. During the initial setup, it will be used to confirm the setup of the first individual to be set up. After this, it can be used for troubleshooting any sync issue that may occur.
MISC AND GET TABS
These are used for troubleshooting purposes only, so they can be ignored for the setup process.
Workamajig Interface Exchange Setup
The following steps are for the initial setup of the sync connection. The assumption is that you have followed the instructions above to confirm the connection between Workamajig and your Exchange server.
We recommend that you set up and test with one individual. Once all settings are confirmed you can set up another group of users. We recommend you do the setup in waves. This is because the initial sync can take up to 6 hours, depending on the number of events and the months backward you are asking for the system to look at.
We also recommend that any recurring calendar events should be ended in the current period. You can then recreate the event and recur it into the future. This will allow the system to see the "Parent" event.
Initial Setup Steps
There are 4 steps to complete your initial setup. You will toggle between the Workamajig interface and the Exchange Sync Tool. You will only need to perform these steps for the initial setup. Once you have confirmed the connection between Workamajig and Exchange is working, any additional users can follow the User Setup instructions to connect their Workamajig calendars to Exchange.
There are two options for setting up Exchange credentials in Workamajig. One is as an administrator and one is as a user. The administrator option allows you to handle the configuration from the employee setup screens, and the user option allows the user to handle the configuration from their individual calendar screen. Both options update the same information in Workamajig. If you are using Office365, it is a good bet that you are using 2-step authentication. Because this requires an App Password, it is recommended that you set up using the User Option, instead of the Administrator option.
NOTE: In order to complete setup, you must have access to the WSSExchange.exe>>WMJ Sync Exchange Settings: Real-time watch tab.
ADMINISTRATOR SETUP
NOTE: Users can enter this information from their Calendar> ...more > Sync Settings.
1) From Workamajig
From the main menu select Admin/Manager > Employees > and search for the user(s) you want to update.
Click on the specific employee you want to add Exchange credentials for
From the Employee edit screen select Sync.
.png)
Select the Exchange Sync tab and enter the necessary information:
Mailbox: (optional) The mailbox on the Exchange server if different from the User ID. Most users will leave this field blank.
User ID: The user id used to log into the selected user's Exchange email.
Set a New Password: The password used to log into the selected user's Exchange email. Enter the password in the New Password and Confirm Password fields.
NOTE: If you are using Office365, you may need to obtain an App Password to use for the login credentials. For details from Microsoft go HERE.
Click Save.
2) From Exchange Sync Tool Location.
Go to the machine that has the sync tool installed> right-clickWSSExchange.exe>select Run as Administrator> click Modify Settings>.
click on WMJ Sync Exchange Settings: Logging. Set logging to Detail>SAVE Settings.
Click on the Real-Time Watch tab.
Click the "Start Manual Sync" button. You should see information regarding the sync process.
3) Back to Workamajig.
Refresh the browser tab for Workamajig. This should bring you back to the employee record.
Click Sync.
You should now see Sync Settings: Exchange > Sync Setup.
Make the following selections:
Personal Calendar: this is the Workamajig calendar the users want to sync to Exchange: typically "default Calendar".
Exchange Folder: this is the Exchange folder the user wants to sync to Workamajig: typically "calendar" or "default calendar".
Sync Direction: There are 4 choices for the sync>.
Do Not Sync: default setting following setup. No calendar events are synced.
Both: calendar events created in Outlook will sync to Workamajig and events created in Workamajig will sync to Outlook.
To Workamajig: calendar events created in Outlook will sync to Workamajig and events created in Workamajig will NOT sync to Outlook.
From Workamajig: calendar events created in Outlook will NOT sync to Workamajig and events created in Workamajig will sync to Outlook.
NOTE: Though the system is able to sync in both directions, we recommend that you decide on a "Master" calendar for the user and sync from that calendar. So if Outlook is the "master" use "To Workamajig". This will help prevent duplication of events, etc. that may occur because the Master calendar is being used to sync to multiple devices/locations.
Depending on the sync direction settings, in this example the setting is BOTH, create an event in Workamajig and an event in Outlook. We suggest using Saturday or Sunday for the events and the subject: "From Workamajig" and "From Outlook" and select different times.
4) Back to Exchange Sync Tool.
Click on the Real-Time Watch tab > click Start Manual Sync.
You should notice that the text filling up the Real-Time Watch screen is looking at calendar events. This may take some time for this process to complete. But you should see a noticeable difference in the amount of data being pushed into the screen.
Once the manual sync has been completed, ask the user to open their Outlook and Workamajig calendar to confirm the events have synced correctly.
This completes the initial setup and testing for one user. You may repeat the above steps for another small group of employees, but it is not necessary as you have confirmed the connection has been made and is working correctly.
USER SETUP
For detailed step-by-step instructions, please refer to the User Setup for Workamajig/Exchange Calendar Sync guide.
The initial setup steps are the same:
- Have the user set up their Exchange credentials.
- Start manual sync from the Sync Tool.
- Have users set up their calendar sync options.
- Start manual sync from the Sync Tool.
- Confirm events are flowing correctly.
NOTES:
- Administrators can enter this information from the Employees record.
- One Exchange folder/calendar will map to one Workamajig folder/calendar. The Workamajig Windows Exchange Service must be running to populate the list of available folders. This process will take approximately 15 minutes (or longer based on the setup) to begin syncing once the correct Exchange User ID and Password have been entered.
Additional / New Staff Setup
After the initial setup of a few employees, any new employees can follow the User Setup for Workamajig/Exchange Calendar Sync guide.
In order to see the Sync Setup, the user must first set up their Exchange credentials in Workamajig. We recommend that this be done first thing in the morning.
Once the Exchange Sync Tool sync process has been triggered, it will recognize that new calendar sync has been added to the system. Following this, the user will then be able to go to the Sync Setup screen and complete the setup procedures. The time difference between entering credentials and completing the setup will depend on the timing you set up on the Sync Tool: Configuration>Service Timer.
A typical workflow would be to have the employee set up the credentials sometime in the morning or afternoon. Prior to leaving for the day, they should be able to set the sync options. When they return in the morning, their calendars should be finished syncing.
There should be no need for you to click the Manual Sync on the Sync Tool unless you want to trigger the sync earlier.
How Does The Sync Work
There is a reason why the above setup steps are required. This is due to how the sync tool identifies the user login and makes the Exchange calendar folder available for syncing.
When the service is triggered to run:
It makes a call to Workamajig to find any Exchange login credentials that have been entered.
If it finds credentials, then it makes a call for the folder settings > If it finds folder settings it uses the login credentials to access the User's Exchange folder and begins the sync.
If it finds credentials but does not find folder settings, the sync process is stopped for that user.
If it does not find credentials, the sync process is stopped.
This is why it takes 4-steps for the initial setup and 2-steps to complete additional user setup. The Exchange folder selection in Workamajig is not made available until the sync tool has identified that your login credentials are valid. So when the user enters their Exchange Login credentials, the next time the sync tool runs it will pick up the user's credentials and recognize the user wants to sync their calendar and will make the folders available for selection. Without this connection, there is no way for the system to know what folders to get. Now that the user is recognized, the user can now set up the folder and sync direction. The next time the sync tool runs it picks up the folder settings and the sync will begin.
In the initial setup step, you overrode the timing of the sync tool using Manual Sync, so that you could quickly confirm the user credentials and set up the folders.
Upgrading Or Replacing Your Current Exchange Server
WARNING! Please contact Workamajig Support prior to upgrading or migrating to a new Exchange Server.
When you migrate to a different Exchange Server the event ids are different. This will cause duplicates on any recurring events. Workamajig Support will be able to provide you with a script to run against your database prior to the move, to eliminate duplication.
Also, make sure that the settings in your WSSExchangeSettings.exe have been updated with the new server version information following the upgrade/migration.
Troubleshooting
Meetings are no longer syncing
Take the following steps:
- Confirm WSSExchange service is in Status=Running. You may want to stop and restart the service.
- Confirm UserID and reenter the password/app password for the user.
If you have confirmed the above, please contact Workamajig at support@workamajig.com. We will provide you with a User Key to continue with the following troubleshooting steps:
- Open WSSExchangeSettings.exe.
- Click on the Logging tab.
- check Turn On Logging to File > click Test Write Permissions.
- select Logging: Detailed.
- Under Support Only: enter the User Key provided by Workamajig Support.
- Click Save Settings.
- click Real-Time Watch.
- Click Start Manual Sync: This is starting the sync process for just one user.
Once completed, review the contents of the watch screen. If you do not see an immediate answer, please send the log files found in the Exchange Tool folder (exchangeLogErrors.wjlog and exhangeLogMain.wjlog), along with the user name of the person having the issue.
Office 365
There are a few things to consider when syncing with Office 365.
- The server/workstation must be able to successfully connect to Office 365. To verify connectivity to your Exchange 354 use the following steps:
- Go to https://testconnectivity.microsoft.com
- Select the Office 365 tab at the top.
- Under the Microsoft Exchange Web Services Connectivity Test select Synchronization, Notification, Availability, and Automatic Replies.
- Enter a valid Email Address, Microsoft Account (should be the same as Email Address), and Password. Make sure the Use Autodiscover to detect server settings is selected, and the Ignore Trust for SSL is not selected. Select the other “I understand that…” checkbox and enter the Verification string and Verify.
- Select Perform Test.
- Analyze the results and make sure there are not any problems. Some tests might fail a couple of steps but ultimately succeed by trying some alternate tests. These failed steps could still indicate a problem.
- If there are problems with the tests from item #1, the problem could have to do with ports being blocked on the server/workstation. The following link has a list of ports necessary for accessing Office 365, Ports Information. The primary ports that need to be open are TCP 80 and 443.
- If using Office 365 and having auto-discovery issues, look to see if an SCP object is causing the problem. Directions found at this link: https://technet.microsoft.com/en-us/library/mt473796
Exchange Throttling Restrictions
Throttling restrictions apply to both Office 365 and installed versions of Exchange. The primary policy items to be concerned with are maxSubscriptions and findCountLimit. If those items are simply blanked out then a default policy will most likely take effect, so it is better to raise them to a very high level. The following links describes throttling policies for Exchange, http://technet.microsoft.com/en-us/library/dd297964(v=exchg.141).aspx
http://msdn.microsoft.com/en-us/library/office/jj945066(v=exchg.150).aspx
For Office 365 you do not have an option to manage the throttling policies since it is a hosted solution. This can possibly cause some problems if users have a large number of meetings that are being synced. The following link describes throttling for Office 365,
Things to contact Workamajig before doing…
- Exchange migration
Migrating from one installation of Exchange to another will most likely create new IDs in Exchange and has the potential to create duplicate meetings in Exchange and/or Workamajig. This includes, but not limited to, moving from a local installed Exchange to a hosted solution (not necessarily Office 365), creating a new Exchange server and migrating the old instance, and upgrading an existing instance of Exchange.
- Email change
Same as with an Exchange migration, updating the email address or moving to a new email address and exporting/importing the calendar will most likely create new IDs in Exchange and has the potential to create duplicate meetings in Exchange and/or Workamajig.
Problems are seen before
- The time zone in Workamajig was not set for the user and caused the sync to crash for that user. All dates for the calendar are stored in UTC, and the time zone is needed to convert from UTC. If the time zone is set at the company level it should cascade down to the user, but it’s something to make sure is selected at the user level if syncing.
Error Notifications
You may receive notifications from Workamajig that the system was unable to connect to your exchange box. Each time the sync tool is triggered, it is sending a request to exchange to get information. Sometimes, due to things not being controlled by Workamajig, Exchange will ignore or not respond to the request. At this time, Workamajig will send out a notification to the user, stating that it could not connect. If you get more than 3 of these emails in a row, based upon the Service Timer set on the Sync Tool, please notify your IT person.
Oftentimes, these emails can be ignored as the next time the request is sent, Exchange responds and the sync will proceed without issue.