Introduction

Welcome to /n software BizTalk Adapters, a suite of fully-managed .NET Adapters and Pipeline Components that seamlessly integrate with the Microsoft BizTalk Messaging Pipeline. The adapters extend the features of BizTalk with advanced Internet communications and secure messaging capabilities.

Included Adapters and Pipeline Components

AES	The AES Pipeline Component can be used to encrypt and decrypt data for regular transport.
AmazonSES	The AmazonSES Component provides a simple interface to Amazon's Simple Email Service (SES).
AMQP	An easy-to-use AMQP 1.0 client implementation.
AMQPClassic	An easy-to-use AMQP 0.9.1 client implementation, with support for RabbitMQ extensions.
AS1	The AS1 Component adds AS1 send and receive capabilities to BizTalk Server.
AS2	The AS2 Component adds AS2 send and receive capabilities to BizTalk Server.
AS3	The AS3 Component adds AS3 send and receive capabilities to BizTalk Server.
AS4	The AS4 Component adds AS4 send and receive capabilities to BizTalk Server.
AS4Web	The AS4Web Component adds AS4 receive functionality to BizTalk Server.
AzureFile	The AzureFile Component allows easy uploading and downloading to and from the Microsoft Azure File service.
Box	The Box Component allows easy uploading and downloading to and from the Box service.
Bzip2	The Bzip2 pipeline component implements a Bzip2-compliant compressor and decompressor.
CloudStorage	The CloudStorage Component allows easy uploading and downloading to major cloud service providers.
CMS	The CMS pipeline component implements the Cryptography Message Syntax standard for encryption and decryption with public key cryptography and X.509 digital certificates.
Dropbox	The Dropbox Component allows easy uploading and downloading to and from the Dropbox service.
Email	The Email Component adds SSL-protected email capability to the BizTalk Server.
EzCrypt	The EzCrypt Pipeline Component can be used to encrypt and decrypt data for regular transport.
FTP	The FTP Component adds SSL-enabled FTP send and receive capabilities to your BizTalk Server.
GISB	The GISB Component adds GISB send and receive capabilities to BizTalk Server.
GoogleDrive	The GoogleDrive Component allows easy uploading and downloading to and from the GoogleDrive service.
Gzip	The GZIP pipeline component implements a gzip compressor and decompressor, compliant to RFC 1952 and compatible with the UNIX gzip and gunzip utilities.
Hash	The Hash Pipeline Component can be used to calculate a hash value.
HTTP	The HTTP component provides a flexible HTTP client to send and receive data to web servers.
LDAP	The LDAP Component enables your BizTalk Server to perform operations against any LDAP directory server.
MQTT	The MQTT Component implements a lightweight, fully-featured MQTT client.
NetCode	The NetCode Pipeline Component can be used to encode or decode data using a variety of web standards.
Office365Mail	The Office365Mail Component adds Outlook 365 send and receive capabilities to your BizTalk Server.
OFTP	The OFTP Component adds OFTP send and receive capabilities to your BizTalk Server.
OneDrive	The OneDrive Component allows easy uploading and downloading to and from the OneDrive service.
OpenPGP	The OpenPGP Pipeline Component provides OpenPGP signing and encryption functionality.
PDF	The PDF pipeline component adds signature and encryption security to PDF processing.
PowerShell	Executes PowerShell scripts and returns the results.
REST	The REST component provides a simple, ligthweight and fast way to communicate with RESTful web server.
RNIF	The RNIF Component provides a way to send and receive RosettaNet messages.
RSS	The RSS Component consumes RSS feeds and translates them into item batches for your BizTalk Server.
S3	The S3 Component provides access to Amazon's Simple Storage Service (S3), as well as other S3-like services.
SCP	The SCP Component adds SSH-secured file transfer capabilities to your BizTalk Server.
SevenZip	The SevenZip pipeline component implements a 7zip-compatible Zip compressor and decompressor.
SExec	The SExec Component enables your BizTalk Server to execute remote commands over SSH.
SFTP	The SFTP Component adds SSH-secured file transfer capabilities to your BizTalk Server.
SMIME	The SMIME pipeline component implements the S/MIME standard for encryption and decryption with public key cryptography and X.509 digital certificates.
SMIMEEmail	The SMIMEEmail Component adds S/MIME-protected email capability to the BizTalk Server.
SMPP	The SMPP Component implements Short Message Peer-to-Peer message transmission functionality.
SNPP	The SNPP Component adds paging send functionality to your BizTalk Server.
SQS	The SQS Component provides access to Amazon's Simple Queue Service (SQS).
SSH	The SSH Component enables your BizTalk Server to execute remote commands over SSH.
Tar	The Tar pipeline component implements a tar archive utility, compatible with the UNIX tar and untar utilities.
TCP	The TCP Component can be used to send data over TCP.
Telnet	The Telnet Component enables remote execution of commands over Telnet.
WebDAV	The WebDAV Component adds SSL-enabled WebDAV send and receive capabilities to your BizTalk Server.
XMPP	The XMPP Component adds instant messaging functionality to your BizTalk Server.
ZCompress	The ZCompress pipeline component implements an LZC compressor and decompressor, compatible with the UNIX compress utility.
Zip	The Zip pipeline component implements a PKZip-compatible Zip compressor and decompressor.

Additional Information

You will always find the latest information about /n software Adapters for BizTalk at our web site: www.nsoftware.com. We offer free, fully-functional 30-day trials for all of our products, and our technical support staff are happy to answer any questions you may have during your evaluation.

Please direct all technical questions to support@nsoftware.com. To help support technicians assist you as quickly as possible, please provide an detailed and accurate description of your problem, the results you expected, and the results that you received while using our product. For questions about licensing and pricing, and all other general inquiries, please contact sales@nsoftware.com.

Thank You!

Thank you for choosing /n software Adapters for BizTalk for your development needs. We realize that you have a choice among development tools, and that by choosing us you are counting on us to be a key component in your business. We work around the clock to provide you with ongoing enhancements, support, and innovative products; and we will always do our best to exceed your expectations!

Adapter Configuration

This section provides step-by-step instructions for creating, configuring and testing a BizTalk Messaging port using an /n software BizTalk Adapter. It is assumed that you are familiar with Microsoft BizTalk Server and the concepts of the transfer protocol used by the /n software BizTalk Adapters.

Adapter Installation

After you run the setup application, all of the necessary files and registry keys will be installed on your system. The setup application will also attempt to register the new adapters within BizTalk, and will also attempt to refresh the registries of any previous installation. However, if an error occurs during this process, it will be necessary to manually complete this step for each adapter that you wish to use.

1. Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
2. In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand Platform Settings node.
3. Select the Adapters node to bring up the list of installed adapters.
4. If the adapter you installed was not successfully added to the list by the setup application, right click the Adapters node, click New, and then click Adapter.
5. In the Add Adapter dialog box, select the adapter you wish to add from the drop-down menu.
6. Enter a name for the adapter's transport type in the top text field. This name is arbitrary and does not affect the behavior of the adapter itself. It will be the name that shows up in the "Transport Type" drop down box when configuring a new port.
7. Enter any comment you wish to describe the adapter's transport type.
8. Click OK.

The adapter will now appear in the list of adapters in the BizTalk Administration console.

Configuring a Send Port

1. Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
2. In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
3. Expand the node for the appropriate application.
4. Right-click Send Ports and select New.
5. Select Static One-way Send Port.
6. Enter a name for the port at the top of the configuration window, and expand the drop-down Transport Type menu. Select the name you gave to the adapter when you installed it.
7. Press the Configure button. This will bring up the property page for the adapter.
8. Fill out the relevant fields on the property page. Please refer to the section on the adapter in this help file for a description of the various properties and their function.
9. Click "OK". The URI should now contain a value.
10. Select a pipeline to use in processing the data, and click "OK". Your port is now configured.

Configuring a Receive Location

Configuring a receive port is very similar to configuring a send port, however a receive can receive data from multiple receive locations. You will first need to add a receive port, and then add and configure a receive location for it.

1. Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
2. In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
3. Expand the node for the appropriate application.
4. Right-click Receive Ports and select New.
5. Select Static One-way Receive Port.
6. Enter a name for the port at the top of the port configuration window. Click "OK" to close the window.
7. Right-click Receive Locations and click "New".
8. Select Static One-way Receive Location.
9. Select the appropriate Receive Port of which the new Receive Location will be a member.
10. Enter a name for the location at the top of the receive location properties window, and expand the drop-down Transport Type menu. Select the name you gave to the adapter when you installed it.
11. Press the Configure button. This will bring up the property page for the adapter.
12. Fill out the relevant fields on the property page. Please refer to the section on the adapter in this help file for a description of the various properties and their function.
13. Click "OK". A value will be generated and used to fill out the URI field.
14. Select a handler to host the adapter. Note: the AS2 receive adapter is hosted out of process, so the handler you choose must be an isolated host, and must be a member of the BizTalk Isolated Host Users group.
15. Select a pipeline to use in processing the data, and click "OK". Your port is now configured.
16. SPECIAL CONFIGURATION FOR THE AS2 ADAPTER: since this adapter must receive requests over HTTP, an HTTP receive application (normally just an ASPX page or module) must be setup under IIS, or any other viable ASP.NET web server, to forward AS2 requests to BizTalk. A sample is included in the aspx subfolder of the installation directory. This sample can be used as is, or be modified to suit your site requirements.

The adapters are now ready for binding to a BizTalk orchestration. You may refer to the sample orchestrations for demonstrations of how to use the ports you have just created.

Pipeline Installation

After you run the setup application, all of the necessary files will be installed on your system. The setup application will also attempt to register the new pipeline components within BizTalk. However, if an error occurs during this process, it will be necessary to manually complete this step for each pipeline component that you wish to use.

1. Click the Start menu, select Programs, Microsoft Visual Studio (which ever version you have installed, 2003 or later), then select the Microsoft Visual Studio icon.
2. In Visual Studio, click File, select New, and finally Project.
3. Click BizTalk Projects in the Project types pane. Select Empty BizTalk Server Project in the Templates pane. Click OK once you have named the project.
4. In the Solution Explorer pane, right click on the project, and select Add and then click New Item.
5. Select Pipeline Files in the Categories pane, and select either the Send or Receive Pipeline. Once you have named this pipeline, click Add. Repeat the last two steps for any other desired pipelines.
6. Scroll over the Toolbox, and when it appears, right click inside of it and click on Choose Items.
7. Select the BizTalk Pipeline Components tab. Check the desired Assembler/Disassembler to add to the toolbox. Click OK.
8. Drag the desired Assembler/Disassembler into the Pipeline and drop in the appropriate Assemble/Disassemble box.
9. Set any properties in the Properties pane.
10. When all pipeline components in the project are configured correctly, right click on the project from the Solution Explorer and click Build.
11. Right click on the project from the Solution Explorer and click Deploy.
12. The host instance of BizTalk Server must be restarted for the Pipelines to properly be installed.

The pipeline will now appear in the list of pipelines in the BizTalk Administration console.

Configuring a Send Port

1. Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
2. In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
3. Expand the node for the appropriate application.
4. Right-click Send Ports and select New.
5. Select Static One-way Send Port.
6. Enter a name for the port at the top of the configuration window, and expand the drop-down Transport Type menu. Select the name you gave to the adapter when you installed it.
7. Press the Configure button. This will bring up the property page for the adapter.
8. Properly configure the adapter as needed.
9. Click on the drop-down list of pipelines. Select the name you gave to the pipeline when you created it.
10. Click the ellipsis ("...") on the side of the pipeline selection box.
11. Fill out the relevant fields on the property page. Please refer to the section on the pipeline in this help file for a description of the various properties and their function.
12. Click "OK". Your port is now configured.

Configuring a Receive Location

Configuring a receive port is very similar to configuring a send port, however a receive can receive data from multiple receive locations. You will first need to add a receive port, and then add and configure a receive location for it.

1. Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
2. In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
3. Expand the node for the appropriate application.
4. Right-click Receive Ports and select New.
5. Select Static One-way Receive Port.
6. Enter a name for the port at the top of the port configuration window. Click "OK" to close the window.
7. Right-click Receive Locations and click "New".
8. Select Static One-way Receive Location.
9. Select the appropriate Receive Port of which the new Receive Location will be a member.
10. Enter a name for the location at the top of the receive location properties window, and expand the drop-down Transport Type menu. Select the name you gave to the adapter when you installed it.
11. Press the Configure button. This will bring up the property page for the adapter.
12. Properly configure the adapter as needed.
13. Select a handler to host the adapter. Click on the drop-down list of pipelines. Select the name you gave to the pipeline when you created it.
14. Click the ellipsis ("...") on the side of the pipeline selection box.
15. Fill out the relevant fields on the property page. Please refer to the section on the pipeline in this help file for a description of the various properties and their function.
16. Click "OK". Your port is now configured.

Adapter Hosting

In BizTalk Server, adapters are divided into two classes based on how they are hosted. These are "Regular" (in-process) and "Isolated" (out-of-process).

Regular

Regular adapters are also referred to as "in-process." A regular adapter is created and hosted within the BizTalk service process, Btsntsvc.exe. This means that BizTalk creates and manages the lifetime of the adapter, initializes it with a transport proxy, services the adapter requests, and terminates the adapter upon service shutdown.

In regular adapters, BizTalk also delivers any configuration to the adapter at run time, including handler, send port, and receive location configuration. In addition, aspects of configuration such as service windows are handled by the Messaging Engine so that the adapter does not need to ensure that a receive location or send port is outside of a service window.

Note that all send adapters are regular adapters.

Isolated

Isolated, or "out-of-process", adapters make up a small subset of adapters. These adapters are created in an isolated host that is not part of the BizTalk runtime. There are scenarios when hosting receive adapters in the BizTalk process is not possible. For example, the Internet Information Services (IIS) process model is such that IIS manages the lifetime of ASP.NET applications and ISAPI extensions. When it is not possible for BizTalk to manage the lifetime of the adapter, the adapter is referred to as an isolated adapter.

The AS2 receive adapter is one such adapter. Because the adapter takes care of fetching its own configuration from the BizTalk server and uses that configuration to process messages, all you need to do is create an instance of the adapter within the isolated host. In the case of the AS2 receive adapter, all you need to do is instantiate it within a webpage. You can find an example of this in the included ASP.NET demo project.

Note that when reinstalling adapters, IIS AND BizTalk must be stopped/restarted in order to force the handles to be released so that the re-install will function as expected.

Permissions

For any adapter to be able to fetch its configuration from the SQL databases used by BizTalk Server, the application under which the adapter runs must have proper security access to the SQL server. Normally, BizTalk Server takes care of this when you create a new host and set the user identities for the various groups like "BizTalk Isolated Host Users". BizTalk Server will make sure that the user identity you supply has the necessary permissions to access SQL Server. However, this does not apply for applications running under Internet and Information Services (IIS) such as ASP.NET. In order to get the necessary permissions to adapters hosted on web sites, use the following process:

1. Open MMC either by right-clicking "My Computer" and selecting Manage, or by opening the console and typing "mmc".
2. Expand the Services and Applications node. Expand the Internet and Information Services (IIS) Manager node.
3. Right click the Application Pools node and select New -> Application Pool. Give the new application pool a name and click "OK".
4. Right click the application pool you just created and select Properties. Go to the "Identity" tab and give the application pool an identity that is a member of the BizTalk Isolated Host Users group. Click "OK."
5. Expand the Web Sites node. Expand the Default Web Site node (or the site under which your application is hosted).
6. Right click the page and select Properties. On the "Virtual Directory" tab, select the application pool you just created from the drop down menu beside "Application Pool". Click "OK." Your web site now has the necessary access rights for the adapter to work.

BizTalk Orchestrations

Orchestrations are the main entities that will house your BizTalk Server e-Business solutions. They are graphically designed flow charts with nodes of various shapes that allow you to listen for, receive, create, edit, and/or send messages.

The simplest orchestrations are those that have one Receive and one Send shape and are bound to one receive port and one send port. You may add multiple shapes to the flow chart between, before, and even after the Receive and Send shapes in order to construct the complicated processes vital to your company's e-Businesses needs.

Orchestrations rely on ports to receive and send information to and from the BizTalk Message Engine.

Adapter Ports

The BizTalk Message Engine works by managing the flow of data to and from the various receive and send ports you have configured. Once you have configured and started the port (or the host instance in the case of an isolated receive port), BizTalk Server will pass the configuration to the appropriate adapter instance during run time. This configuration allows the adapter to determine how it will receive or send its particular data.

In order to have messages forwarded to an orchestration, you must bind the message's receive port to that orchestration. When a message comes in on the receive port, it is forwarded to the orchestration, where the BizTalk Server enacts your business process on it and sends the finalized message out through any send ports also bound to the orchestration.

Each receive port may be made up of multiple receive locations, each one with a different transport type allowing a single receive port to receive data from several locations at once. Send ports are unary: a single transport type sending to a single destination. However, BizTalk Server places no restrictions on the number of ports that may be used by a particular orchestration. If you wish to send an EDI message to several trading partners, all you need to do is bind multiple AS2 send ports to your orchestration.

Unbound Ports

You may wish to have a send port that transmits data received from a single receive location without modifying the data whatsoever. BizTalk Server lets you achieve this simple Receive-Send model without creating an orchestration. To do so, the send port you wish to use must have a correlation or subscription to the message type you wish to send. This is done by adding a filter to the send port.

A filter can be added by opening the edit page for the selected adapter and selecting Filters & Maps and then Filters. Select "BTS.InboundTransportLocation" in the "Property" column and "==" in the "Operator" column. In the "Value" column, add the receive location's Address (URI) value.

Please refer to the Microsoft BizTalk Server documentation for more details on filters.

Upgrade Notes

This release includes major upgrades and enhancements to the entire suite of /n software BizTalk Adapters. All of the BizTalk Adapters now support both static and dynamic modes of operation. In addition, all of the Adapters have improved integration with BizTalk Server offering enhanced error handling, integrated messaging, and advanced testing facilities. Pipeline Components have been added to the suite of BizTalk Adapters as well.

Version 4.0 adapters will run side-by-side with currently deployed /n software version 3.x adapters. The setup will automatically add the new adapters to the BizTalk Server Admin Console and deploy the new Adapters to the BizTalk and global assembly caches.

Upgrading Orchestrations

If you wish to upgrade an existing orchestration to use the latest version of the adapter, you will need to rebind the orchestration's ports. To do this, first follow the steps to configure either a new send port or a new receive location.

Once the new port has been configured, you can use the following steps to rebind the orchestration:

1. Open an instance of Microsoft Visual Studio .NET.
2. Open the BizTalk Explorer (this can be done by pressing ctrl-alt-z).
3. Expand the BizTalk Configuration Databases node and navigate to the <server>.BizTalkMgmtDb.dbo node.
4. Expand the Orchestrations node.
5. Right-click the orchestration you wish to rebind and select Unenlist (note: the orchestrations cannot be changed if it is still in the enlisted state).
6. Right-click the orchestration again and select Bind.
7. Select the orchestration port you wish to rebind and click the down-arrow to drop down a list of available BizTalk adapter ports.
8. Select your new port, and click "OK" to close the binding window.
9. Right-click the orchestration again and select Start.
10. When prompted, make sure to start all of the necessary services.

Prebuilt Pipelines

Prebuilt Pipelines allow the use of pipeline components without having to first create, build, and deploy a pipeline project.

The Prebuilt Pipelines are ideal for use cases where a simple pipeline with only the /n software pipeline component is needed. The Prebuilt Pipelines consist of one pipeline for each pipeline component offered in the toolkit. There is no need to build a pipeline project in Visual Studio and deploy it, simply add the assembly to the BizTalk Administration Console and configure the pipeline options from the Send Port or Receive Location where the pipeline will be used.

Installation Steps

By default the Prebuilt Pipelines are not deployed to BizTalk, however this can be done in a few quick steps. From the BizTalk Administration Console navigate to the BizTalk Application in which you will use the pipelines and right click. Select Add -> BizTalk Assemblies.

In the Add Resources Dialog that opens press "Add..." and navigate to the prebuilt directory of the installation. By default this is C:\Program Files\nsoftware\BizTalk Adapters 2016\prebuilt. Within this directory select the nsoftware.BizTalk.PrebuiltPipelines.dll file.

Check the "Add to the global assembly cache on add resource (gacutil)" option and press OK.

After pressing OK the pipelines should now be present in the Pipelines listed for the BizTalk application. For instance:

Using the Pipelines

After the Prebuilt Pipelines are deployed any Send Port or Receive Location can make use of the pipelines. For instance when configuring a send port the ZipAssembler pipeline should be visible:

After selecting the pipeline pressing the ellipses button (...) will open the pipeline properties where various options can be configured for the pipeline.

The Send Port can now be used to process files. For pipeline specific properties and settings please see the corresponding help file section.

Note: Prebuilt Pipelines are only available in BizTalk 2009 and later.

Note: The PipelineOptions setting seen in the Other properties is applied by default and should not be modified. This is used to indicate that the pipeline is operating in prebuilt mode.