Exchange Connector
The Dime.Scheduler Exchange connector - unsurprisingly - provides a link between Dime.Scheduler and Exchange. There are two flavors of the connector available:
- On-premise Exchange connector
- Office 365 Exchange connector
The on-premise Exchange connector is powered by a third-party vendor whereas the Office 365 connector is managed by Dime.
On-premise Exchange connector
The on-premise connector uses Microsoft SQL server (Dime.Scheduler database) and Exchange Web Services (EWS) to make a connection between the two systems. There is not that much to tell as it is mostly technical mumbo-jumbo to establish the connection. All you need to know about this connector is documented here.
Office 365 Exchange connector
In contrast, the Office 365 Exchange connector is a plugin like any other plugin in the Dime.Scheduler ecosystem. It comes with its own service and management website.
It also relies on different technologies: Office 365 and Azure Active Directory. Using the Microsoft Graph development platform, the connector can access the data that is stored in Office 365. Specifically, the resources' calendars are accessed and manipulated to reflect the planning in Dime.Scheduler.
Before any of this can be done, the administrator needs to grant Dime.Scheduler access to the organization's data on Office 365. In Azure Active Directory, this is done with so-called "application registrations". With such registrations, administrators can define what an application is allowed to do. For example, Dime.Scheduler only needs Read and Write permissions for the calendars. It makes sense for an administrator to only allow this permission set and nothing else to prevent potential security leaks.
This guide walks you through the process of creating such an application on Azure. However, this particular tutorial demonstrates the setup of Azure AD authentication, so make sure to select the following permissions:
- Calendars.Read/Write
- MailBoxSettings.Read/Write
Don't forget to grant consent for these permissions too. It should look something like this:
Once this setup is done, the connector is good to go. When an appointment is published from Dime.Scheduler, Exchange connector contacts the resource's calendar on Office 365 and it adds, updates or deletes the event from the calendar.
Exchange plugin website
The Dime.Scheduler Exchange plugin website allows you to monitor all the traffic from Dime.Scheduler to Exchange.
The Dime.Scheduler Exchange plugin website is usually installed on the same web server as the Dime.Scheduler planning application but with a different port number. Check with your system administrator for the correct URL.
Between Exchange itself and Dime.Scheduler is a façade - or a management application if you will - that shows the status of the connection between the two. It gives the administrator an overview of the appointments that have been sent to Exchange and can intervene if an error has occurred.
To learn more about Exchange, click here. In this document we'll stick to the management application.
Authentication
Plugins such as this one have a simple authentication and authorization mechanism. Local forms accounts are used to secure the system.
Views
The Dime.Scheduler Exchange plugin website supports administrators in monitoring the status of the connection between Dime.Scheduler and you guessed it, Exchange. It is therefore a management and reporting tool that helps administrators in diagnosing issues and provides tools for resolving them.
Appointments
The appointments view shows the list of appointments that have been processed by the Exchange plugin. In this view, you can consult some of its properties, along with the status of the transactions.
By default the records are sorted in descending order by the date of the last transaction. To change the sorting order, click on any of the column headers. To search for a specific value (e.g. all transactions belonging to a specific job), click on the filter icon and enter a filter criteria. Use the filter icon again to clear any filter criteria.
Click on the magnify button in the first column to enter the details section.
The details section shows change tracking information and identification values for the Exchange application. Below this information on the 'last activity' tab you see the list of transactions and their status. On the MBOC Settings tab you see the connection details towards the Exchange application that were used.
Transactions
The transactions view is similar to the appointments view, except that it's a flat list rather than a table grouped per appointment.
Error Tracking
The error tracking view shows transactions that were not successfully sent to Exchange. You can change sorting of the records and set filters as in the History list. In the details section you can inspect the reason for the error and change the MBOC Settings - if necessary - to resend the transaction to Exchange.
All transactions can be archived or resent to Exchange at once by using the "Archive All" and "Retry All" buttons after selecting the records.
Logs
The logging view shows all the messages logged by the Dime.Scheduler Exchange application and allows you to detect any issues.
Events
This page links appointments from Dime.Scheduler to events in Exchange. These connections are crucial to update the calendars in Exchange.
Status
The status screen, accessible via the link at the bottom-right of any page gives you an indication of the connection with the Dime.Scheduler Exchange plugin Windows Service.
Automatic retry
If, for any reason, a transaction fails, it will appear automatically in the error list. In this view you may choose to attempt to retry the transaction and if needed, change the MBOC settings. Since Dime.Scheduler 2020.1.0, a timer job will do this automatically. Any transaction with the 'Failed' status will be queried and executed.
This is an opt-in feature. By default, the CRON expression is empty. This is configurable though. Head to the appsettings.json file of Exchange website and look for the RetryJobCronExpression configuration item. The accepted value looks like gibberish but in fact it is a CRON expression. For instance, the value "*/15 * * * *" means "At every 15th minute". As long as you adhere to the CRON syntax, any value can be used here.
Renew subscriptions
The bi-directional synchronization mechanism relies on subscriptions. If an event in the calendar is updated, all subscribers to this event will be notified. However, such a subscription is limited in time, so it needs to be refreshed at regular intervals. This is the scope if this job: to renew the subscriptions to keep the two-way synchronization alive.
This too is an opt-in feature. By default, the CRON expression is empty. This is configurable though. Head to the appsettings.json file of Exchange website and look for the RenewSubscriptionCronExpression configuration item. The accepted value looks like gibberish but in fact it is a CRON expression. For instance, the value "*/15 * * * *" means "At every 15th minute". As long as you adhere to the CRON syntax, any value can be used here.
The Exchange website is optional
The Exchange plugin consists of two elements:
- The component that takes care of sending messages from Dime.Scheduler to Exchange.
- The reporting dashboard
The latter is also known as Exchange website whereas the former is referred to as Exchange service. It is implemented as a Windows Service and continuously keeps an eye open for new transactions occurred in Dime.Scheduler's client application.
To integrate Dime.Scheduler with Exchange, only the Windows Service is required. The website is an optional feature free of charge at the disposal of Dime.Scheduler's administrators.
Exchange plugin service
The service does the heavy lifting: it listens for events in both Exchange and Dime.Scheduler and makes sure they are handled appropriately. Because this is a two-way street, there are also two configuration sets that are crucial:
- Dime.Scheduler configuration
- Exchange configuration
Dime.Scheduler configuration
To notify Dime.Scheduler of changes in Exchange, we need three pieces of information:
- The URI where Dime.Scheduler is hosted
- The Forms account user
- The Forms account password
Exchange configuration
To notify Exchange of changes in Dime.Scheduler, we need the following information:
- The client id of the Azure AD application
- The client secret of the Azure AD application
- The tenant id
- The URI of the service endpoint
The three first items are boilerplate and are necessary for most Azure AD applications. The last item is crucial for the bi-directional synchronization.
To be notified of changes in Exchange, a subscription to the Graph API is needed: you need to tell which event to subscribe to, which resource, which URI to call and for how long to keep this connection open. When a resource changes an appointment, Office 365 calls these webhooks, allowing these applications to do whatever they have to do. For Dime.Scheduler, that is to link these changes back to the planning application and the back office systems. It is therefore important that this endpoint is accessible by Office 365.