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
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
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:
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 Name | Description |
|---|---|
| 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
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:
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:
We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@nsoftware.com.