This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Tech Community.
Office 365 Outlook adapters are introduced in BizTalk Server 2020 and qualified customers got access to many of its capabilities in BizTalk Server 2016 Feature Pack 3 to provide support for a variety of Office 365 integration scenarios based on email, calendar or contacts.
With these adapters, users can:
- Sync with any Office 365 Outlook email account or calendar.
- Send emails, meeting requests or contacts from an Office 365 account.
In this article we focus on the built-in filtering functionality provided in the transport properties configuration of Office 365 Email and Calendar receive locations.
Filtering Outlook items by their location on the Office 365 server
By default, a receive location with transport type Office 365 Outlook Email will listen to the Inbox folder. However, any other folder available on the Office 365 mail server can be selected. A typical scenario would be when emails are sorted into specific folders via server-side rules.
Similarly, in the Office365 Outlook Calendar adapter, the default calendar is "Calendar", but any other calendar can be selected. This would be applicable for instance when an organization has several shared calendars, or several calendars as part of its business workflow. Another scenario could be when multiple calendars need to be merged into a unified view, which can be achieved by creating one receive location per calendar and subscribing to these locations.
The UI for configuring folders and calendars is shown below. The tree views are always up to date and reflect the hierarchy of these destinations in the Office 365 account on the server side.
Transport properties for Email receive location |
Transport properties for Calendar receive location |
 |
 |
The Office 365 Outlook Calendar adapter also provides calendar selection on the send side. So, back to the above-mentioned calendar consolidation, one could have a send port pointing to a user-created calendar and listening to several calendars on the receive side.
Filtering Outlook items by date
In the configuration of a location with Email transport type, the "Start from:" field is used to filter emails by timestamp, i.e. time received on the Office 365 server. A field value set in the past will limit how far back emails should be fetched. Setting the date far enough in the past can be used to backup all emails contained in the folder server-side. Conversely, setting a date in the future can be used to start fetching emails after a certain date.
In the case of emails, filtering by mail timestamp is pretty straightforward. Less so in the case of calendar events. In the Calendar adapter, the date filtering is based on the start datetime of an event, which must fall within a pre-set "time horizon" (screenshot below).
It is easier to understand by looking under the hood: The Calendar adapter constantly polls the Office 365 server every minute to retrieve the most recent set of events starting between when the polling happens, and that time plus the time horizon. So for instance, if the adapter polls at 3pm and the time horizon is set to 2 hours, a new BizTalk message will be created for each new calendar event found that starts between 3pm and 5pm. Note that the adapter polls every minute, but calendar events found in consecutive polling intervals are only considered once; no duplicate BizTalk message gets created for the same events.
The Calendar adapter configuration has built-in time horizon values corresponding to different time scales (minutes/hours/days/weeks) that we think are most relevant to business processes in general. The choice of a value really depends on how one views the Calendar adapter. Short time horizon corresponds to a "get the events that are about to start" scenario, a notification service where there are a lot of events. A longer time horizon can be better suited for a planning type of business process, or could correspond to a Lead time within which events are scheduled and where event starting "a while from now" need to be published as soon as they're created on the Office 365 server. Custom values are not currently supported, but could be in the future if there is enough demand for the feature. The minimum of 15 minutes was chosen as a reasonable BizTalk publication delay under heavy load, i.e., between the time content is received from the external server to the time the content is processed and through the Message Box database.
Preventing duplication
The Office 365 Outlook Email and Calendar adapters keep track of the Outlook items that have already fetched and published. This applies even after a receive location has been restarted.
Filtering emails by read status
An Office 365 Outlook Email receive location can be configured to only receive unread mails (checkbox shown below). These could be new emails not read on any other email client, as well as mails that are changed from read to unread.
Note that the option to mark emails as read is available in the transport options as a Post Action.
Filtering email payload
Starting with BizTalk Server 2020, the Office 365 Outlook Email adapter provides the option to choose the email content format, as well as whether attachments should be fetched.
On the send side, the configuration of an send port also gives the choice of including attachments, which correspond to the parts of a multipart BizTalk message.
