Office365Mail Adapter for Microsoft BizTalk

Requirements: /n software Adapters for BizTalk

Introduction

The /n software Adapters for BizTalk include fully-managed .NET Adapters that seamlessly integrate with the BizTalk Messaging Pipeline. The /n software adapters extend the features of BizTalk with advanced Internet communications and secure messaging capabilities.

This guide will focus specifically on the Office365Mail adapter, which is used to send and download emails from Microsoft Outlook 365.

Contents

• Adapter Installation
• Authorization
• Receive Location Configuration
• Send Port Configuration

Adapter Installation

Before installing you should stop the BizTalk host instance and close the BizTalk Administration Console. After you run the setup application, all of the necessary files will be installed on your system. The adapters will automatically be added to the BizTalk Administration Console, so we can begin using them in send ports and receive locations. If you open the BizTalk Administration Console and create a new receive location or send port, you'll see that the /n software Office365Mail adapter is now available as a transport type.

Authorization

The Office365Mail adapter uses OAuth 2.0 for authorization. To authorize the adapter, first open the OAuth Authorization dialog by clicking the ellipses (...) button of the OAuth Authorization property at design time. This will open a dialog. Within the dialog specify the Client Id, Client Secret, and Callback URL values for the registered application.

After specifying the necessary values press the Authorize button. This will launch a browser and prompt the user to grant access. After access is granted the dialog window will populate the following values:

• Authorization
• Refresh Token
• Expires In
• Time Stamp

All necessary values will be saved in the Cache Location for use in subsequent requests by the adapter. The adapter will use the cached values and will automatically refresh the token if needed. In this way any user interaction is only required at design time, not at runtime.

 

Receive Location Configuration

The Office365Mail receive location can be used to download emails from Microsoft Outlook 365. To begin, create a new receive location named "testOffice365Mail.Receiver" with a transport type of "nsoftware.Office365Mail".

After configuring the OAuth Authorization, you will need to set the MailFolder property to tell the receive location which folder to search. If you enable the adapter after only setting the MailFolder, it will connect to the server and download all emails from the selected folder.

If you want to be more selective about which emails you download, you can set the Filter property. The Filter property uses the OData protocol format. Any Outlook 365 message properties that would be set on a received message can be used to search. For example, to list unread messages from a specific address, you can use the following value for Filter:

isRead eq false and address eq 'specific@address.com'

To download the attachments from messages, set the AttachmentDirectory property to the folder where you want attachments to be saved. Whenever a message with attachments is downloaded, the receive location will also request any attachments and save them to the folder specified in AttachmentDirectory. If an attachment with the same name is already present in the attachment directory, the receive location will automatically rename the attachment before saving it. If you want to override that behavior so that duplicates will overwrite the existing files, you can set the DuplicateAttachmentAction configuration setting to 0 by adding the following line in the Other property:

DuplicateAttachmentAction=0

You can also change the message fields returned in the results by setting the Select property. If Select is an empty string all message properties except for MessageHeaders will be returned. To select all message properties supported by the adapter (including message headers), set Select to "body,ccRecipients,sentDateTime,from,sender,subject,toRecipients,internetMessageHeaders,importance,isDeliveryReceiptRequested,isReadReceiptRequested,hasAttachments".

By default, the receive location will not delete emails after downloading. If the emails are still present in the folder the next time the receive location polls, the receive location will download them again. To avoid repeatedly downloading the same emails, you can set the DeleteMode property to OnSuccess, OnFailure, or Always.

 

Send Port Configuration

The Office365Mail send port can be used to send emails through Microsoft Outlook 365.

After configuring the OAuth Authorization, set SendTo to the address that you want the email to be sent to. To set the contents of the email, set MessageBody to the contents you want to send, and set MessageBodyContentType to indicate whether the message is HTML or text. If you want to add any attachments, set the Attachments property to a pipe ("|") delimited list of file paths.

Other properties can be used to set other fields on the email, such as the subject, addresses to CC on the email, and the address to send from. Note that the account used for OAuth authentication is the one that will be used to send the email. If the From property is not set, the email will be sent from that account's email address. If From is set, the chosen address must be one that the account has been granted permission to send from.

 

Conclusions

This article demonstrates the use of the Office365Mail adapter in particular, but /n software provides a full set of adapters for connecting to various types of internet servers. The adapter properties are kept to a minimum for simplicity, but we make an effort to provide those properties that are necessary for effective control over configurations.

Please contact support@nsoftware.com with any questions.