CloudStorage Adapter for Microsoft BizTalk

Requirements: /n software Adapters for Microsoft BizTalk

Introduction

The CloudStorage BizTalk adapter provides an easy way to upload and download files from various cloud storage service providers such as Amazon S3, Azure Blob, Box.com, Dropbox, OneDrive, Google Drive, SharePoint Online, and Wasabi.

Contents

  1. Overview
  2. Authorization
  3. Downloading Files
  4. Uploading Files

Overview

The CloudStorage BizTalk adapter provides an easy way to upload and download files from major cloud storage service providers. The adapter properties and operation are very similar to our FTP adapter which allows for a common experience.

Support Providers

The CloudStorage BizTalk adapter supports the following cloud storage service providers:

  • Amazon S3
  • Azure Blob
  • Box
  • Dropbox
  • Google Drive
  • OneDrive
  • SharePoint Online
  • Wasabi
To specify the provider set the ServiceProvider property in the adapter.

In all cases the interaction with the remote file system is the same. The only difference is how the authentication is performed which is covered in more detail in the Authorization section.

Functionality Overview

The CloudStorage 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. The following encryption algorithms are supported:

  • AES-256
  • Blowfish
  • CAST
  • DES
  • IDEA
  • RC2
  • RC4
  • TEA
  • 3DES
  • TwoFish

Authorization

Depending on the service in use different authentication mechanisms are used.

For OAuth based providers 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.

For Amazon S3 and Share Point Online authentication credentials are specified at design time without any additional required steps.

Box, Dropbox, Google Drive, and OneDrive (OAuth Based Services)

The following providers require OAuth Authorization:

  • Box
  • Dropbox
  • Google Drive
  • OneDrive

Before authenticating a ClientId and ClientSecret are required. These must be obtained from your account with the service provider by registering an application. Consult the provider website for details on the OAuth process and obtaining these values. In addition a callback or redirect URI may be registered with the provider. This is a whitelist of URLs to which a user can be redirected when using your application. If required choose a value like "http://localhost:7777".

Once your application is registered with the provider you should have the following pieces of information:

  • ClientId
  • ClientSecret
  • CallbackURL

These three pieces of information are required in order to perform OAuth authentication. The Callback URL may have been referred to as the callback URI, or redirect URI when registering your application.

After the application has been registered within the adapter properties open the Oauth Authorization dialog from the adapter setting by clicking the ellipses (...) button of the OAuth Authorization property. A dialog will be displayed:

OAuth Authorization Dialog

Within this dialog specify the ClientId, ClientSecret, and CallbackURL with the appropriate values. Click the Authorize button to initiate the OAuth authorization. A browser will be displayed and access will be requested. Grant access to the application and return to the adapter properties.

After authorization succeeds additional properties will be populated. The following table provides some basic details on the populated properties.

Property NameDescription
AuthorizationString The current authorization string. This may be refreshed from time to time by the adapter at runtime.
RefreshToken The refresh token may be used at runtime to obtain a new authorization string.
ExpiresIn The time (in seconds) until the current authorization string becomes invalid. This is used when determining whether the token should be refreshed.
TimeStamp The time at which the authorization string was obtained. This is used when determining whether the token should be refreshed.

The above values do not ever need to be set manually. They 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.

Amazon S3

To authenticate to Amazon S3 set the following properties:

  • AmazonS3AccessKey
  • AmazonS3SecretKey

No other settings are required.

Azure Blob

To authenticate to the Azure Blob service set the following properties:

  • AzureBlobAccount
  • AzureBlobAccessKey

No other settings are required.

SharePoint Online

When connecting to SharePoint Online the following properties are applicable:

  • SharePointUser
  • SharePointPassword
  • SharePointURL
The SharePointUser is in the format "admin@mycrm.onmicrosoft.com". The SharePointURL is in the format "https://mycrm.sharepoint.com/".

Wasabi

To authenticate to Wasabi set the following properties:

  • WasabiAccessKey
  • WasabiSecretKey

No other settings are required.

Downloading Files

The CloudStorage Receive Adapter can be configured to download files in as few as two properties after authorization settings are provided. The RemotePath specifies the directory on the server from which files are downloaded and FileMask specifies a filemask to indicate which files should be downloaded.

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

Property Description
DeleteMode Controls if and when files are deleted from the remote server after download.
EncryptionAlgorithm The algorithm to use when decrypting downloaded files.
EncryptionPassword Specifies the decryption password. If unspecified decryption is not attempted.
FileMask Files matching this mask will be downloaded. For instance "*.txt".
RemotePath The path to the directory on the server from which files are downloaded. For instance "My Folder/subfolder". If left unspecified files are downloaded from the root directory.
ServiceProvider The cloud storage provider to use.
TempPath If specified files will be download to disk at this path before submitting to BizTalk. If extremely large files are downloaded the use of this property will reduce memory consumption.
TransportLog Offers additional logging capabilities. Expand this property in the designer for more options.

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

An example configuration in the BizTalk Administration console may look like:

Cloud Storage Receive Adapter Properties

Cloud Storage Receive Adapter Properties

Uploading Files

Uploading files with the CloudStorage Send Adapter can be accomplished with a minimum of settings. The RemoteFile property specifies the name of the file to be written on the server and defaults to "%SourceFileName%". In many cases this does not need to be changed. The RemotePath property specifies the directory on the server in which the file will be uploaded.

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

Property Description
EncryptionAlgorithm The algorithm to use when encrypting files before uploading.
EncryptionPassword Specifies the encryption password. If unspecified encryption is not performed.
Overwrite Whether to Overwrite the remote file if it exists. The default is True.
RemoteFile The name of the uploaded file. Macros are supported and the default is "%SourceFileName%".
RemotePath The path to the directory on the server to which files are uploaded. For instance "My Folder/subfolder". If left unspecified files are uploaded to the root directory.
ServiceProvider The cloud storage provider to use.
TransportLog Offers additional logging capabilities. Expand this property in the designer for more options.

An example configuration in the BizTalk Administration console may look like:

Cloud Storage Send Adapter Properties

Cloud Storage Send Adapter Properties

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.