SharePoint Adapter for Microsoft BizTalk

Requirements: /n software Adapters for Microsoft BizTalk

Introduction

The SharePoint BizTalk adapter provides an easy way to upload and download files from SharePoint Online.

Overview

The SharePoint adapter provides upload and download functionality through the Send and Receive adapters respectively. When uploading, the RemotePath specifies the directory on the server where files are uploaded and RemoteFile specifies the remote file name. This includes support for macros like %SourceFileName%.

When downloading, the RemotePath again specifies the directory from which files are downloaded and FileMask specifies a filemask. Any files found in the directory matching the filemask will be downloaded.

Encryption is also supported through the EncryptionAlgorithm and EncryptionPassword properties. This allows client side encryption where you are in complete control of the keys used for encryption and decryption. Files are encrypted when uploading, and decrypted when downloading.

Authorization

OAuth information is specified at design time and is cached locally to allow the adapter to authenticate at runtime without the need for any human interaction.

Before authenticating, you will need to register an application with Microsoft to obtain a ClientId and ClientSecret. When registering the application, "http://localhost" should be provided as a Redirect URI.

After the application has been registered, go to the receive location or send port properties and open the OAuth Authorization dialog from the adapter setting by clicking the ellipses (...) button next to the OAuth Authorization property. A dialog will be displayed:

Within this dialog specify the ClientId and ClientSecret with the appropriate values. The CallbackURL field can generally be left blank, but can also be set to a value like "http://localhost:7777" to use a specific port. The Authorization Scopes value can be left as the default, and the URL values can be adjusted as needed.

Once the upper part of the dialog window has been filled in, click the Authorize button to open the browser and initiate the OAuth process. The lower part of the dialog window will be populated after a successful authorization:

The values above will be saved along with other OAuth information within the cache file specified in CacheLocation. At runtime the adapter will read the values from the cached file and automatically refresh the authorization string if necessary.

Downloading Files

At minimum, you will need to set the RemotePath and FileMask properties to download files. The RemotePath specifies the path on the server from which files will be downloaded and FileMask indicates which files should be downloaded.

The remote path for a folder in SharePoint starts with the site name, followed by the subsite (if any), then the name of the document library, then the path within the document library. Note that the "Shared Documents" library is a special case: while it is shown as "Shared%20Documents" in the URL, its name in in the path is simply "Documents". For example, the remote path of a folder in Shared Documents might be "MySite/MySubSite/Documents/MyFolder".

If a file was uploaded with encryption, you can set the EncryptionAlgorithm and EncryptionPassword properties to decrypt it after downloading. The values must match the values used during uploading for the decryption to succeed. If EncryptionPassword is left blank, decryption will not be performed.

The following is a list of common properties used when downloading files. For complete details see the online help documentation.

Each downloaded file is submitted as an individual message to BizTalk. The following context properties are present on the message to provide additional details about the downloaded file:

• ReceivedFileDate
• ReceivedFileName
• ReceivedFileSize

Uploading Files

To upload files to SharePoint, you will need to set at least the RemotePathand RemoteFile properties. The RemotePath property specifies the directory on the server in which the file will be uploaded.The RemoteFile property specifies the name of the file to be written on the server and defaults to "%SourceFileName%", which uses the file name as it was received by the send port.

The remote path for a folder in SharePoint starts with the site name, followed by the subsite (if any), then the name of the document library, then the path within the document library. Note that the "Shared Documents" library is a special case: while it is shown as "Shared%20Documents" in the URL, its name in in the path is simply "Documents". For example, the remote path of a folder in Shared Documents might be "MySite/MySubSite/Documents/MyFolder".

Files can optionally be encrypted with a password before uploading for additional security. To do that, select an algorithm with the EncryptionAlgorithm property and set the EncryptionPassword property to the desired password. Be sure to record the values used, as the exact same values will be needed to decrypt the file when it is downloaded later. If EncryptionPassword is left blank, encryption will not be performed.

The following is a list of common properties used when uploading files. For complete details see the online help documentation.