Microsoft 365 Connector

Field workers require information about the planning to perform their work. Apart from using a mobile application to distribute the planning, OMD can publish the appointments to Microsoft 365, providing the field worker with up-to-date information about the task schedule, the customer's location and other important information.

Synchronization with a corporate calendar has several advantages. The calendar is part of the daily life of a field worker and can be viewed easily from the web or from mobile devices. Colleagues can look into the calendar of their group members. If not using OMD Mobile, viewing the calendar on a smartphone allows field workers to start navigation by clicking on the address or call the customer by clicking on the customer's telephone number.

Updates of the corporate calendar are required whenever

A new task has been planned for a resource
A planned task is moved to another date or time but for the same resource
A planned task is moved to another date or time and resource
A planned task has been un-planned
An unavailability has been added to the calendar of a resource
An unavailability has been updated
An unavailability has been deleted
A new exceptional working day has been assigned to a resource
An exceptional working day has been removed

Requirements

Microsoft 365 Online

Configuring the application on Microsoft 365

In order to use this application, it first needs to be registered.

Sign in to the https://portal.azure.com as an administrator.
If you have access to multiple tenants, use the Directories + subscriptions filter in the top menu to switch to the tenant in which you want to register the application.
Search for and select Azure Active Directory.
Under Manage, select App registrations > New registration.
Enter a Name for your application, for example Daemon-console. Users of your app might see this name, and you can change it later.
Select Register.
Under Manage, select Certificates & secrets.
Under Client secrets, select New client secret, enter a name, and then select Add. Record the secret value in a safe location for use in a later step.
Under Manage, select API Permissions > Add a permission. Select Microsoft Graph.
Select Application permissions.
Under User node, select User.Read.All, then select Add permissions.
Under Calendars node, select Calendars.ReadWrite.
In the permissions overview, click on the 'admin consent' links to activate the permissions.

Note that by default, the application will have access to all users in this tenant. Restricting access to a subset of users is possible by applying an application access policy. See https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access.

Configuring the service in OMD

Preference Name	Default	Description
calendar.msgraph.synchronize	false	Used to turn synchronization with MS Graph calendars on or off.
calendar.msgraph.tenantGuid		The GUID of the tenant in which this application is configured.
calendar.msgraph.clientId		The ID this client app has been assigned in the AD.
calendar.msgraph.clientSecret		The client secret this app uses to authenticate, configured in the AD.
calendar.msgraph.graphEndPoint	https://graph.microsoft.com/v1.0	The endpoint this app will use to call methods of the Graph API.
calendar.msgraph.authEndPoint		The endpoint this app will use to authenticate and obtain an access token.
calendar.msgraph.scopes	https://graph.microsoft.com/.default	The client access scopes this app will request when authenticating.
calendar.msgraph.lookupPrincipleName	false	If false, the user principal is equal to its email address. Otherwise, before each call the user principal will be looked up based on the email address.
calendar.msgraph.timeZone	Europe/Berlin	The time zone to use when creating calendar entries.
calendar.msgraph.daysBack	365	Max number of days in the past to look in the users calendar. Any events older that that will not be queried.

Ignore Resource during Communication

To avoid a resource's visits to be considered for synchronization, set the resource's process flow preference calendar.msgraph.active to false.

One-Way Communication

Note that the connector works only in one direction, from OMD to Microsoft 365. Changes to the Outlook agenda in Microsoft 365 are not communicated back to OMD. This is to avoid conflicts, i.e. OMD controls the workflow of a task.

Performance

Every change to a task being committed by a planner results in a request to the Microsoft 365 connector. Moving a task from one Field Worker to another Field Worker will result in two requests, one for removing the entry from the calendar of the first Field Worker and one for adding the task to the calendar of the second Field Worker. Hence, the total number of requests per day is of an order of magnitude determined by the number of Field Workers multiplied by the average number of tasks per Field Worker per day.

Example

Suppose your environment has to deal with about 200 Field Workers, each of them performing around 7 tasks a day on average. The number of tasks in that case would be roughly 200 x 7 = 1,400 tasks / day. In a normal scenario, each task is re-planned about 5-6 times before being closed. Hence, an average scenario with 200 Field Workers would result in 1,400 x 6 = 8,400 requests / day, which is an average of 15 requests / minute based on a 9 hours working day, or 0.075 requests / resource / minute.

To avoid congestion at peek times, OMD uses an exponential backoff algorithm whenever the service is unable to process the requests. The exponential backoff is stopped when it exceeds 15 minutes.

Templates

When creating Calendar entries, OMD will automatically apply a default layout for each entry description. However, if you want to layout the description differently, the preferences calendarEntryTaskQueries and calendarEntryTaskTemplate will allow you to specify the layout yourself.

The preference calendarEntryTaskQueries must contain an XML document with a list of Download queries. The Download queries determine the content and structure of the XML document that is created for the calendar entry. Once the XML document is created, it will be transformed by the XSL document described below.

calendarEntryTaskQueries
Type	Default Value	Example
String	empty	See below

Example

<?xml version="1.0" encoding="UTF-8" ?>
<omd.domain.s4.Task id="?">
  <omd.domain.s4.Task query="omd.domain.s4.Task.findByTaskGroupOtherTasks"/>
  <omd.domain.s4.Resource query="omd.domain.s4.Resource.findByTaskGroup"/>
</omd.domain.s4.Task>

The preference calendarEntryTaskTemplate must represent an XSL document that transforms the entry XML document.

calendarEntryTaskTemplate
Type	Default Value	Example
String	empty	See below

Example

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output media-type="text/html"/>
  <xsl:template match="/Download/omd.domain.s4.Task">
<html>
 <body>
  <p>
  Task <xsl:value-of select="@externalId"/>
 </p>
  <p>
   <table cellpadding="0" border="0" cellspacing="0">
   <tr><td><b><xsl:value-of select="@name"/></b></td></tr>
   <tr><td><xsl:value-of select="@street"/></td></tr>
   <tr><td><xsl:value-of select="@city"/></td></tr>
   <tr><td><xsl:value-of select="@country"/></td></tr>
  </table>
 </p>
  <p>
  <xsl:value-of select="@remarks"/>
 </p>
 <ul>
  <li>Status: <xsl:value-of select="@status"/></li>
  <li>Estimated Duration: <xsl:value-of select="@estimatedDuration"/> min</li>
  <li>Earliest: <xsl:value-of select="@earliest"/></li>
  <li>Latest: <xsl:value-of select="@latest"/></li>
 </ul>
  <b>Related tasks</b>
  <ul>
  <xsl:for-each select="omd.domain.s4.Task">
  <li>Task <xsl:value-of select="@externalId"/>
  <xsl:if test="string-length(@scheduled) > 0">
  assigned to <xsl:value-of select="//omd.domain.s4.Resource[@id =      ../@scheduledFor]/@fullName"/>
  on <xsl:value-of select="@scheduled"/></xsl:if>
  </li>
  </xsl:for-each>
 </ul>
  </body>
   </html>
  </xsl:template>
  </xsl:stylesheet>