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.

Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand Platform Settings node.
Select the Adapters node to bring up the list of installed adapters.
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.
In the Add Adapter dialog box, select the adapter you wish to add from the drop-down menu.
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.
Enter any comment you wish to describe the adapter's transport type.
Click OK.

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

Configuring a Send Port

Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
Expand the node for the appropriate application.
Right-click Send Ports and select New.
Select Static One-way Send Port.
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.
Press the Configure button. This will bring up the property page for the adapter.
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.
Click "OK". The URI should now contain a value.
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.

Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
Expand the node for the appropriate application.
Right-click Receive Ports and select New.
Select Static One-way Receive Port.
Enter a name for the port at the top of the port configuration window. Click "OK" to close the window.
Right-click Receive Locations and click "New".
Select Static One-way Receive Location.
Select the appropriate Receive Port of which the new Receive Location will be a member.
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.
Press the Configure button. This will bring up the property page for the adapter.
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.
Click "OK". A value will be generated and used to fill out the URI field.
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.
Select a pipeline to use in processing the data, and click "OK". Your port is now configured.
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.

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.
In Visual Studio, click File, select New, and finally Project.
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.
In the Solution Explorer pane, right click on the project, and select Add and then click New Item.
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.
Scroll over the Toolbox, and when it appears, right click inside of it and click on Choose Items.
Select the BizTalk Pipeline Components tab. Check the desired Assembler/Disassembler to add to the toolbox. Click OK.
Drag the desired Assembler/Disassembler into the Pipeline and drop in the appropriate Assemble/Disassemble box.
Set any properties in the Properties pane.
When all pipeline components in the project are configured correctly, right click on the project from the Solution Explorer and click Build.
Right click on the project from the Solution Explorer and click Deploy.
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

Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
Expand the node for the appropriate application.
Right-click Send Ports and select New.
Select Static One-way Send Port.
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.
Press the Configure button. This will bring up the property page for the adapter.
Properly configure the adapter as needed.
Click on the drop-down list of pipelines. Select the name you gave to the pipeline when you created it.
Click the ellipsis ("...") on the side of the pipeline selection box.
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.
Click "OK". Your port is now configured.

Configuring a Receive Location

Click the Start menu, select Programs, Microsoft BizTalk Server, and then BizTalk Server Administration.
In the BizTalk Administration Console, expand the appropriate BizTalk Group node and expand the Applications node.
Expand the node for the appropriate application.
Right-click Receive Ports and select New.
Select Static One-way Receive Port.
Enter a name for the port at the top of the port configuration window. Click "OK" to close the window.
Right-click Receive Locations and click "New".
Select Static One-way Receive Location.
Select the appropriate Receive Port of which the new Receive Location will be a member.
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.
Press the Configure button. This will bring up the property page for the adapter.
Properly configure the adapter as needed.
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.
Click the ellipsis ("...") on the side of the pipeline selection box.
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.
Click "OK". Your port is now configured.

Enabling Support for Read-Only BizTalk Users

The release of BizTalk Server 2020 introduced a new group, 'BizTalk Server Read Only Users'. Users in this group have read-only access to adapter properties. However, they do not have permission to read adapter properties from the BizTalk database containing this information. As a result, Microsoft Adapters will cache their adapter configurations elsewhere, specifically for read-only users to view later.

/n software BizTalk adapters cannot cache their adapter properties for read-only users by default. As a result, read-only users will initially be unable to view /n software adapter configurations. To support read-only users, a specific configuration must be enabled in the BizTalk Management Database for each /n software adapter, which must be done manually.

To enable this configuration for each adapter, please run the SQL commands located in the CachingAdapterConfig.sql file, which can be found in the /lib folder of the installation directory. For example, these commands can be run like so in PowerShell:

Invoke-SqlCmd -InputFile "%USERPROFILE%\Documents\BizTalk Adapters 2024\lib\CachingAdapterConfig.sql"

Afterward, all /n software adapters can generate the cached configuration for read-only users. Please note that this will have no immediate effect on existing adapters, as the cached configuration does not exist. For existing adapters, a non-read-only user must manually open any existing adapter properties in the BizTalk Server Administration Console, click OK, then OK again. In this case, BizTalk Server will generate the cached configuration and properties may now be read by 'BizTalk Server Read Only Users'.

For new adapters, BizTalk Server will generate the cache config upon creation and no extra steps are required.

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:

Open MMC either by right-clicking "My Computer" and selecting Manage, or by opening the console and typing "mmc".
Expand the Services and Applications node. Expand the Internet and Information Services (IIS) Manager node.
Right click the Application Pools node and select New -> Application Pool. Give the new application pool a name and click "OK".
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."
Expand the Web Sites node. Expand the Default Web Site node (or the site under which your application is hosted).
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.

The 2024 version of the adapters will run side-by-side with any earlier versions that are currently deployed. 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:

Open an instance of Microsoft Visual Studio .NET.
Open the BizTalk Explorer (this can be done by pressing ctrl-alt-z).
Expand the BizTalk Configuration Databases node and navigate to the <server>.BizTalkMgmtDb.dbo node.
Expand the Orchestrations node.
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).
Right-click the orchestration again and select Bind.
Select the orchestration port you wish to rebind and click the down-arrow to drop down a list of available BizTalk adapter ports.
Select your new port, and click "OK" to close the binding window.
Right-click the orchestration again and select Start.
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.