6
Connectivity and networking
In the last chapter we learned about tuning and optimizing our BizTalk 2010
Environment. In this chapter we will learn about connectivity and networking.
Since connectivity and networking is such a broad subject, we will only discuss a few
essential topics.
The following topics will be discussed:
IIS Configuration
o
Application Pool advanced settings
o
Securing BizTalk WCF Services
Windows Azure AppFabric Connectivity
Adapters
o
Windows SharePoint Services
o
Microsoft BizTalk Adapter Pack
o
Line of Business
o
Third-Party
IIS Configuration
Application Pool Advanced Settings Configuration
An application pool defines a group of one or more worker processes, configured with
common settings that serve requests to one or more applications that are assigned to that
application pool. Because application pools allow a set of Web applications to share one
or more similarly configured worker processes, they provide a convenient way to isolate
a set of Web applications from other Web applications on the server computer. Process
boundaries separate each worker process; therefore, application problems in one
application pool do not affect Web sites or applications in other application pools.
2
Application pools significantly increase both the reliability and manageability of your
Web infrastructure.
You can choose to use the default application pool provided by IIS on install, or you can
create your own application pool. You can run as many application pools on your IIS 7
server as you need, though this can affect server performance. Application pools can
contain one or more worker processes. Each worker process represents work being done
for a Web site, Web application, or Web service
Application Pool Identities
Application Pool Identities allow you to run Application Pools under a unique account
without having to create and manage domain or local accounts. The name of the
Application Pool account corresponds to the name of the Application Pool. The image
below shows an IIS worker process (W3wp.exe) running as the DefaultAppPool identity.
Application Pool Identity Accounts
Worker processes in IIS 6.0 and IIS 7 run as NETWORKSERVICE by default.
NETWORKSERVICE is a built-in Windows identity. It doesn't require a password and
has only user privileges; that is, it is relatively privileged. Running as a
low-privileged account is a good security practice because then a software bug can't be used
by a malicious user to take over the whole system.
However, a problem arose over time as more and more Windows system services started
to run as NETWORKSERVICE. This is because services running as
Because IIS worker processes run third-party code by default (Classic ASP, ASP.NET,
PHP code), it was time to isolate IIS worker processes from other Windows system
services and run IIS worker processes under unique identities. The Windows operating
system provides a feature called "Virtual Accounts" that allows IIS to create unique
identities for each of its Application Pools. Click
here
for more information about Virtual
Accounts.
Configuring IIS Application Pool Identities
If you are running IIS 7.5 on Windows Server 2008 R2, you don't have to do anything to
use the new identity. For every Application Pool you create, the IIS Admin Process
(WAS) will create a virtual account with the name of the new Application Pool and run
the Application Pool's worker processes under this account.
Securing Resources
Whenever a new Application Pool is created, the IIS management process creates a
security identifier (SID) that represents the name of the Application Pool itself. For
example, if you create an Application Pool with the name "MyNewAppPool," a security
identifier with the name "MyNewAppPool" is created in the Windows Security system.
From this point on, resources can be secured by using this identity. However, the identity
is not a real user account; it will not show up as a user in the Windows User Management
Console.
You can try this by selecting a file in Windows Explorer and adding the
"DefaultAppPool" identity to the file's Access Control List (ACL).
1.
Open Windows Explorer
2.
Select a file or directory.
3.
Right click the file and select "Properties"
4.
Select the "Security" tab
5.
Click the "Edit" and then "Add" button
6.
Click the "Locations" button and make sure you select your machine.
7.
Enter "IIS AppPool\DefaultAppPool" in the "Enter the object names to
select:" text box.
8.
Click the "Check Names" button and click "OK".
By doing this, the file or directory you selected will now also allow the
“DefaultAppPool" identity access.
4
You can do this via the command-line by using the ICACLS tool. The following example
gives full access to the DefaultAppPool identity.
ICACLS test.txt /grant "IIS AppPool\DefaultAppPool":F
On Windows Server 2008 R2, the default is to run Application Pools as the Application
Pool Identity. To make this happen, a new identity type with the name "AppPoolIdentity"
was introduced. If the "AppPoolIdentity" identity type is selected (the default on
Windows 7 and Windows Server 2008 R2), IIS will run worker processes as the
Application Pool identity. With every other identity type, the security identifier will only
be injected into the access token of the process. If the identifier is injected, content can
still be ACLed for the AppPool identity, but the owner of the token is probably not
unique.
Accessing the Network
Using the NETWORKSERVICE account in a domain environment has a great benefit.
Worker process running as NETWORKSERVICE access the network as the machine
account. Machine accounts are generated when a machine is joined to a domain. They
look like this:
<domainname>\<machinename>$,
The nice thing about this is that network resources like file shares or SQL Server
databases can be ACLed to allow this machine account access.
Windows Azure AppFabric Connectivity
AppFabric Connect
BizTalk Server 2010 AppFabric Connect for Services
One of the key requirements in development of cloud based applications is to be able to
leverage existing on-premise assets by exposing them as web services. However, since
most of the organizations are firewall protected, the on-premise web services are
typically not accessible to external clients running outside the organization’s firewall,
unless these web services are explicitly hosted in DMZ. More often than not, hosting
services in the DMZ is a cumbersome process. Azure AppFabric Service Bus provides
the capability to extend the reach of on-premise web services to external clients (without
having to host them in the DMZ) in a secure way.
Feature Overview
The new ‘
BizTalk Server 2010 AppFabric Connect for Services
’ feature brings
together the capabilities of BizTalk Server and Windows Azure AppFabric thereby
enabling enterprises to extend the reach of their on-premise Line of Business (LOB)
systems and BizTalk applications to cloud.
6
Business scenario
With the advent of cloud platforms and people building cloud based applications, it is
still true that a lot of data for these applications resides in on-premise LOB systems. More
often than not, these applications would also want to leverage existing on-premise
applications. To build such hybrid applications with components residing on-premise as
well as on cloud, a secure mechanism to connect an enterprise’s on-premise assets with
those on cloud is the need of the hour. While this is true for any applications, it is even
truer for integration applications. The following fictional scenario illustrates this better:
Woodgrove bank wants to build an online banking portal where its customers can view
their bank or stock related information, and trade their stocks. The data needed for this
portal resides in on-premise LOB systems. The stock trading functionality is
implemented using a BizTalk Server Orchestration. The bank has also designed an
ASP.Net based web portal and hosted it in Windows Azure. To enable communication
between the cloud based web portal and the on-premise assets, the bank exposes the on-
premise LOB data and the BizTalk solution as WCF services with endpoints in Azure
AppFabric Service Bus.
Security considerations when exposing on-premise assets on
cloud:
Security is an important requirement when exposing on-premise assets on cloud. Azure
AppFabric Service Bus endpoints can be secured using Azure AppFabric ACS. A more
detailed description of how to secure Service Bus endpoints is
here
. On top of this, the
regular WCF security features such as transport level and message level security can be
used to secure end-to-end communication between the client and the service.
BizTalk WCF Adapter for Windows Azure Storage Services
The BizTalk WCF Adapter for Windows Azure Storage Services enables communication
between .Net framework applications and Windows Azure Storage Queues and Blobs.
The current version includes support for PutMessage, ClearMessages outbound
operations and GetMessage inbound operation on Azure Queues as well as for AddBlob,
DeleteBlob outbound operations and GetBlob inbound operation on Azure Blobs.
Also implemented is a basic polling strategy with PollingIntervalInSeconds value.
The adapter was created by Jérémie Devillard and Maxime Labelle and is available on
CodePlex
http://azurestorageadapter.codeplex.com/Adapters
Windows SharePoint Services Adapter
The BizTalk 2010 SharePoint Adapter can be configured using the BizTalk 2010
Configuration Tool. Before we can install and configure the adapter we must first install
the prerequisite.
8
Depending on the functionality we require, we can install either SharePoint Services 3.0
SP 2 or SharePoint Foundation 2010. More information can be found on
http://msdn.microsoft.com/en-us/library/bb743377.aspx
.
In addition, a new Domain group, typically called “SharePoint Enabled Hosts”
needs to be created. Both the Domain BizTalk Service and SharePoint Service
Accounts are added to this group.
Both SharePoint Services 3.0 SP 2 or SharePoint Foundation 2010 create a new
SharePoint Site using Port 80. We will need to use the SharePoint Central
Administration to remove this site. We then add new site using a different Port
number.
Once this has been completed we can Install and Configure the Windows SharePoint
Services Adapter as shown in the figure below.
Microsoft BizTalk Adapter Pack
WCF LOB Adapter for mySAP Business Suite
Like all the WCF LOB Adapters, they can be configured both at design-time and
run-time. In this section we will discuss run-time configuration.
10
Since the setup and install includes the .NET Framework Data Provider for
mySAP Business Suite, we do not have to worry about it’s installation.
In order to perform any operation on a SAP System, the clients that use the adapter must
have access to the relevant Remote Function Calls (RFC), Business Application
Programming Interfaces (BAPIs), and IDOCs (or intermediate documents). The included
.NET Framework Data Provider for mySAP Business Suite provides an ADO Interface to
the SAP System.
SAP Binding Properties
To configure the adapter at run-time we need to set the proper properties that appear the
Send Port and Receive Location Dialog Boxes.
The following tables show the Node Properties that appears in the dialog boxes.
General Node Properties
Binding Property Description
CloseTimeout Specifies the WCF connection close timeout. The default
is 1 minute.
DataTypesBehavior The SAP system does not enforce correct values to be
specified for DATS, TIMS, and NUMC fields. So, if invalid values are present in the SAP data store for DATS, TIMS, and NUMC fields and a client program tries to read the values using the SAP adapter, the adapter throws an exception.
Also, the SAP system has special values for representing minimum and maximum values for the DATS, TIMS, and NUMC fields for which there is no equivalent .NET type. For example, the minimum and maximum values for a DATS field are 00000000 and 99999999 respectively, for which there is no equivalent .NET type DateTime. Moreover, converting the minimum and maximum values for DATS fields to
DateTime.MinValue and DateTime.Max value is not feasible because the minimum or maximum value for DATS field and minimum or maximum value for a .NET DateTime type are not the same.
To enable adapter clients to control the adapter behavior when special values are encountered in the SAP system, you can set the DataTypesBehavior binding property. This is a complex binding property that has the following sub-properties.
DateTimeMaxToDats Specifies the behavior the adapter should follow to send a DATS value when the adapter client sends the value DateTime.MAX, which is
“9999-12-31T23:59:59.9999999”. You could set this to the following values. ERROR. When set to this, the adapter throws an error if the client program sends the DateTime.MAX value. <VALUE>. When set to this, the adapter sends the specified value to SAP if the client program sends the DateTime.MAX value. Default is 99991231.
DateTimeMaxToTims Specifies the behavior
the adapter should follow to send a TIMS value when the adapter client sends the value DateTime.MAX, which is
“9999-12-31T23:59:59.9999999”. You could set this to the following values. ERROR. When set to this, the adapter throws an error if the client program sends the DateTime.MAX value. <VALUE>. When set to this, the adapter sends the specified value to SAP if the client program sends the DateTime.MAX value.
12
Default is 235959.
DateTimeMinToDats Specifies the behavior
the adapter should follow to send a DATS value when the adapter client sends the value DateTime.MIN, which is “0001-01-01T00:00:00”. You could set this to the following values. ERROR. When set to this, the adapter throws an error if the client program sends the DateTime.MIN value. <VALUE>. When set to this, the adapter sends the specified value to SAP if the client program sends the DateTime.MIN value. Default is 00010101.
DateTimeMinToTims Specifies the behavior
the adapter should follow to send a TIMS value when the adapter client sends the value DateTime.MIN, which is “0001-01-01T00:00:00”. You could set this to the following values. ERROR. When set to this, the adapter throws an error if the client program sends the DateTime.MIN value. <VALUE>. When set to this, the adapter sends the specified value to SAP if the client program sends the DateTime.MIN value. Default is 000000.
DateTimeNullToDats Specifies the behavior the adapter should follow to send a DATS value when the adapter client sends a NULL DateTime value. You could set this to the following values. ERROR. When set to this, the adapter throws an error if the client program sends a NULL DateTime value. SKIP. When set to this, the adapter skips the field and does not send any value to SAP if the client program sends a NULL DateTime value. <VALUE>. When set to this, the adapter sends the specified value to SAP if the client program sends a NULL DateTime value. Default is SKIP.
DateTimeNullToTims Specifies the behavior
the adapter should follow to send a TIMS value when the adapter client sends a NULL DateTime value. You could set this to the following values. ERROR. When set to this, the adapter throws an error if the client program sends a NULL DateTime value. SKIP. When set to this, the adapter skips the field and does not send any value to SAP if the client program sends a
14
NULL DateTime value. <VALUE>. When set to this, the adapter sends the specified value to SAP if the client program sends a NULL DateTime value. Default is SKIP.
DatsMaxToDateTime Specifies the behavior
the adapter should follow to retrieve a DateTime value when the adapter receives a DATS.MAX value, which is 99999999, from SAP. You could set this to the following values.
ERROR. When set to this, the adapter throws an error if it receives a DATS.MAX value from SAP.
NULL. When set to this, the adapter returns NULL if it receives a DATS.MAX value from SAP.
<VALUE>. When set to this, the adapter parses the specified value in the XSD:DateTime format and returns it to the client program. Default is ERROR.
DatsMinToDateTime Specifies the behavior
the adapter should follow to retrieve a DateTime value when the adapter receives a DATS.MIN value, which is 00000000, from SAP. You could set this to
the following values. ERROR. When set to this, the adapter throws an error if it receives a DATS.MIN value from SAP.
NULL. When set to this, the adapter returns NULL if it receives a DATS.MIN value from SAP.
<VALUE>. When set to this, the adapter parses the specified value in the XSD:DateTime format and returns it to the client program. Default is ERROR.
EmptyDatsToDateTime Specifies the behavior
the adapter should follow to retrieve a DateTime value when the adapter receives an empty DATS value from SAP. You could set this to the following values. ERROR. When set to this, the adapter throws an error if it receives an empty DATS value from SAP.
NULL. When set to this, the adapter returns NULL if it receives an empty DATS value from SAP.
<VALUE>. When set to this, the adapter parses the specified value in the XSD:DateTime format and returns it to the client program. Default is
0001-01-16
01T00:00:00.
EmptyNumcToInt Specifies the behavior
the adapter should follow to retrieve an integer value when the adapter receives an empty NUMC value (all spaces) from SAP. You could set this to the following values. ERROR. When set to this, the adapter throws an error if it receives an empty NUMC value from SAP.
NULL. When set to this, the adapter returns NULL if it receives an empty NUMC value from SAP.
<VALUE>. When set to this, the adapter assumes that the specified value is a valid Int32 or Int64 value and returns it to the client program. Default is 0.
EmptyTimsToDateTime Specifies the behavior
the adapter should follow to retrieve a DateTime value when the adapter receives an empty TIMS value from SAP. You could set this to the following values. ERROR. When set to this, the adapter throws an error if it receives an empty TIMS value from SAP.
NULL. When set to this, the adapter returns
NULL if it receives an empty TIMS value from SAP.
<VALUE>. When set to this, the adapter parses the specified value in the XSD:DateTime format and returns it to the client program. Default is 0001-01-01T00:00:00.
InvalidDatsToDateTime Specifies the behavior
the adapter should follow to retrieve a DateTime value when the adapter receives an invalid DATS value from SAP. You could set this to the following values.
ERROR. When set to this, the adapter throws an error if it receives an invalid DATS value from SAP.
NULL. When set to this, the adapter returns NULL if it receives an invalid DATS value from SAP.
<VALUE>. When set to this, the adapter parses the specified value in the XSD:DateTime format and returns it to the client program. Default is ERROR.
InvalidNumcToInt Specifies the behavior
the adapter should follow to retrieve an integer value when the adapter receives an invalid NUMC value
18
from SAP. You could set this to the following values.
ERROR. When set to this, the adapter throws an error if it receives an invalid NUMC value from SAP.
NULL. When set to this, the adapter returns NULL if it receives an invalid NUMC value from SAP.
<VALUE>. When set to this, the adapter assumes that the specified value is a valid Int32 or Int64 value and returns it to the client program. Default is 0.
TimsMaxToDateTime Specifies the behavior
the adapter should follow to retrieve a DateTime value when the adapter receives a TIMS.MAX value from SAP. You could set this to the following values. ERROR. When set to this, the adapter throws an error if it receives a TIMS.MAX value from SAP.
NULL. When set to this, the adapter returns NULL if it receives a TIMS.MAX value from SAP.
<VALUE>. When set to this, the adapter parses the specified value in the XSD:DateTime format and returns it to
the client program. Default is ERROR.
Name Not supported.
OpenTimeout Specifies the WCF connection open timeout. The default
is 1 minute.
ReceiveTimeout Specifies the WCF message receive timeout.
Essentially, this means the maximum amount of time the adapter waits for an inbound message. The default is 10 minutes.
SendTimeout Specifies the WCF message send timeout. The default is
1 minute. EnableBizTalkCompatiblityMo
de
Specifies whether the BizTalk Layered Channel Binding Element should be loaded. The BizTalk Layered Channel Binding Element is loaded to enable BizTalk transactions to flow through the SAP adapter to the SAP system.
Set this to true to load the binding element. Otherwise, set this to false.
When using the adapters from BizTalk Server, you must always set the property to true. When using the adapters from Visual Studio, you must always set the property to false.
EnablePerformanceCounters Specifies whether to enable the WCF LOB Adapter SDK performance counters and the SAP adapter LOB Latency performance counter. The default is false; performance counters are disabled. The LOB Latency performance counter measures the total time spent by the SAP adapter in making calls to the SAP system.
Note
EnablePerformanceCounters is a static property within an application domain (app domain) for the WCF LOB Adapter SDK performance counters, but it is an instance property for the adapter's LOB Latency performance counter. This means that changing EnablePerformanceCounters for a binding instance in an app domain will:
enable or disable the WCF LOB Adapter SDK performance counters for all objects created from all binding instances within the same app domain. enable or disable the adapter's LOB Latency
20
performance counter only for objects created from that binding instance after the change is made.
BizTalk Node Properties
Binding Property Description
EnableBizTalkCompatiblityMode Specifies whether the BizTalk Layered
Channel Binding Element should be loaded. The BizTalk Layered Channel Binding Element is loaded to enable BizTalk transactions to flow through the SAP adapter to the SAP system.
Set this to true to load the binding element. Otherwise, set this to false.
When using the adapters from BizTalk Server, you must always set the property to true. When using the adapters from Visual Studio, you must always set the property to false.
Bapi Node Properties
Binding Property Description
EnableBusinessObjects This property is deprecated. The adapter
always displays the BAPI node when
browsing the metadata using the Add Adapter Service Reference Plug-in or the Consume Adapter Service Add-in. The behavior is the same as setting EnableBusinessObjects to true in BizTalk Adapter Pack version 1.0. For more information about the
EnableBusinessObjects binding property in BizTalk Adapter Pack version 1.0, see
http://go.microsoft.com/fwlink/?LinkId=135612.
Connection Node Properties
Binding Property Description
EnableConnectionPooling Specifies whether the SAP adapter
connection pool is enabled. The default is true, which specifies that the connection
pool is enabled.
IdleConnectionTimeout Specifies the SAP adapter idle connection
timeout. When a connection in the pool is idle (unused) for a period that exceeds this timeout, the connection will be disposed. The default is 15 minutes. The idle connection timeout only applies to connections in the pool that are not being used. It does not affect active (open) connections which may be waiting for data.
MaxConnectionsPerSystem Specifies the maximum number of
connections in the SAP adapter connection pool. The default is 50.
MaxConnectionsPerSystem is a static property within an application domain. This means that when you change
MaxConnectionsPerSystem for one binding instance in an application domain, the new value applies to all objects created from all binding instances within that application domain.
Important
By default, the SAP client library
(librfc32u.dll) supports a maximum of 100 connections to the SAP system. If you exceed this number of connections, an exception will be thrown by the SAP adapter. For this reason, you should not set MaxConnectionsPerSystem to a value greater than the number of connections supported by the SAP client library. You can increase the number of connections that the SAP client library supports by setting the environment variable,
CPIC_MAX_CONV. You must reboot your computer after setting this variable for the change to take effect.
RfcAllowStartProgram Specifies the external programs that the
RFC client library can start, if required by an RFC partner. For example, if you are invoking an RFC that internally invokes a program on the computer running the adapter client, you must specify the name of that program for this binding property.
22
If you are specifying multiple programs for this binding property, they must be
separated by a semi-colon. For example, if you want to specify the sapftp and saphttp programs, you must specify them as sapftp;saphttp.
Also, make sure the following conditions are met:
The external program required by the RFC is available on the computer running the adapter client.
The location of the external program is present in the PATH variable on the computer running the adapter client.
For example,
BAPI_DOCUMENT_CHECKOUTVIEW2 internally executes a program, sapftp. So, while invoking this RFC, you must set the RfcAllowStartProgram binding property to sapftp. You must also ensure that the sapftp program is available locally, and the location of the sapftp program is added to the PATH variable on the computer running the adapter client.
Diagnostics Node Properties
Binding Property Description
EnablePerformanceCounters Specifies whether to enable the WCF LOB
Adapter SDK performance counters and the SAP adapter LOB Latency
performance counter. The default is false; performance counters are disabled. The LOB Latency performance counter measures the total time spent by the SAP
adapter in making calls to the SAP system.
Idoc Node Properties
Binding Property Description
AutoConfirmSentIdocs Specifies whether the SAP adapter
auto-commits tRFC client calls used for sending IDocs. The default is false; auto-commit is disabled. If auto-commit is disabled, the client application must explicitly commit the tRFC call by invoking the
RfcConfirmTransID operation. The RfcConfirmTransID operation is a special operation surfaced by the SAP adapter. It appears under the TRFC node when you use the Add Adapter Service Reference Visual Studio Plug-in or the Consume Adapter Service BizTalk Project Add-in.
PadReceivedIdocWithSpaces Specifies whether each line returned by the
ReceiveIdoc operation is padded with spaces to the correct length. The default is false; lines are not padded.
Metadata Node Properties
Binding Property Description
EnableSafeTyping Enables or disables safe typing. The
default is false; safe typing is disabled. This feature controls how the adapter surfaces certain SAP data types
FlatFileSegmentIndicator Specifies whether the <appinfo> tag should
contain segment types or segment definitions for parsing flat file IDocs. Note that the XML schema elements, however, should always contain segment definition names only. There are two possible values for the FlatFileSegmentIndicator property:
SegmentDefinition indicates that the flat files should contain the Segment Definition for each
24
Segment in the IDoc.
SegmentType indicates that the flat files should contain the Segment Type for each Segment in the IDoc.
The default is SegmentDefinition. GenerateFlatfileCompatibleIdocSchema Specifies whether flat file <appinfo> tags
should be added to the IDoc message schema. This is required by the BizTalk flat file parser. The default is true, which specifies that <appinfo> tags will be added to the schema.
ReceiveIDocFormat Specifies the XML format of the messages
dispatched by the SAP adapter to the client application on the inbound side (SAP to adapter). There are three possible values for the ReceiveIDocFormat property:
String specifies that the IDoc message should be
represented as a single, string field in the WCF message.
Typed specifies that the IDoc message should be parsed and represented as a strongly-typed WCF message.
Rfc specifies that the SAP adapter should pass the incoming RFC call as a WCF message with RFC parameters.
The default is Typed.
SNC Node Properties
Binding Property Description
SncLibrary Specifies the location of the SNC library on
your computer. If the PATH environment variable contains the directory in which the library resides, you only have to supply the filename of the library; otherwise you must supply the full path. The SncLibrary binding property surfaces an SAP connection
property.
You must set the UseSnc parameter in the connection URI to enable Secure Network Communications (SNC).
SncPartnerName Specifies the SNC partner name. The
SncPartnerName binding property surfaces an SAP connection property
You must set the UseSnc parameter in the connection URI to enable Secure Network Communication (SNC).
TrfcServer Node Properties
Binding Property Description
TidDatabaseConnectionString Specifies the database connection string for
the SQL Server database that the SAP adapter uses to store Transaction Ids (TIDs). The BizTalk Adapter Pack setup wizard installs some SQL scripts that must be run by the SQL Server administrator against an existing database to create the SQL Server objects that are used by the adapter to store TIDs to enable inbound transactional RFC (tRFC) server calls. For more information about the SQL scripts, refer to the BizTalk Adapter Pack installation guide available at <installation drive>:\Program Files\Microsoft BizTalk Adapter Pack\Documents.
You must set this property to enable inbound tRFC server calls for receiving IDocs or RFCs from SAP. The default is null; tRFC server calls are not enabled.
You can specify the connection string in the following format:
Data Source=<myServerAddress>;Initial Catalog=<myDataBase>;User
Id=<myUsername>;Password=<myPassword>; To specify the connection string, click the ellipsis button (…) against the binding property and enter the values for the required
26
Additional information is available in the Microsoft BizTalk Adapter 2010
Documentation
.http://www.microsoft.com/en-us/download/details.aspx?id=1325
Line of Business Adapters
Beside the WCF LOB SDK Adapters, BizTalk 2010 includes serveral Line of Business
Adapters. These adapters provide connectivity with several Enterprise Resource Planning
(ERP) systems.
The following are the adapters included:
JD Edwards OneWorld XE
JD Edwards EnterpriseOne
Tibco Rendezvous
Tibco Enterprise Message Service
PeopleSoft Enterprise
Configuration
The configuration of the Line of Business Adapters hasn’t changed much in BizTalk
2010. The configuration settings are set using the adapters Transport Properties dialog
box. The settings for the adapter is as follows.
JD Edwards OneWorld XE
We use the
JD Edwards OneWorld Transport Properties dialog box
when setting the
required properties. Additional information is available at
http://msdn.microsoft.com/en-us/library/aa559542
The following table describes how to set the properties.
Property Step
Adapter Required Properties
Host Provide the name or IP address.
JAVA_HOME Provide the complete path to your JDK
installation.
JDEdwards Environment Provide the name of an environment in JD
Edwards OneWorld.
for each of the JAR files.
Password Provide the user password.
Port Provide the Port Number.
User name Provide the user name.
Max Concurrent Calls The default value is 5.
Refresh Agent Select Yes if you want the process to
restart automatically if it loses coonection with the server.
Affiliate Application If you are using SSO, select the affiliate
application
Use SSO Select Yes if you are using SSO.
JD Edwards EnterpriseOne
We use the
JD Edwards EnterpriseOne Transport Properties
dialog box when setting
the required properties. . Additional information is available at
http://msdn.microsoft.com/en-us/library/aa560631
The following table describes how to set the properties.
Property Step
Adapter Required Properties
Host Provide the name or IP address.
JAVA_HOME Provide the complete path to your JDK
installation.
JDEdwards Environment Provide the name of an environment in JD
Edwards OneWorld.
JDEdwards JAR files Provide the complete path and file name
for each of the JAR files.
Password Provide the user password.
Port Provide the Port Number.
User name Provide the user name.
Bootstrap Data Source Required Properties
Data Source Name Provide the name of the data source.
Database Owner Provide the name of the database owner.
28
Database Server Port Provide the database server port number.
Database Type Provide a single character for the database
type.
Physical Database Name Provide the name of the physical database.
Concurrency Control
Max Concurrent Calls The default value is 5
Refresh Agent
Refresh Agent Select Yes if you want the process to
restart automatically if it loses coonection with the server.
Security Server
Security Server Name Provide the name of the security server.
Service Name Connect Provide the port number used by the
security server. Default is the JD Edwards server port.
Single Sing-On
Affiliate Application If you are using SSO, select the affiliate
application
Use SSO Select Yes if you are using SSO.
Tibco Rendezvous
We use the
Tibco Rendezvous
Send Transport Properties
dialog box when setting the
required properties for sending messages. . Additional information is available at
http://technet.microsoft.com/en-us/library/aa578274
The following table describes how to set these properties.
Property Step
Certified Sender Properties
Ledger file name Defaults to blank
Reusable name Defaults to blank. This is only used for
certified message delivery. Credentials
Password Defaults to blank.
General Settings
Code page number Defaults to 65001
Default subject name Defaults to blank
Enable Time Batch Defaults to False
Map unsupported types to string Defaults to True
Path to Binaries Provide if not already in PATH
environmental variable.
Preserve order Defaults to True
Send port identifier Appears in log messages associated with
this port.
We use the
Tibco Rendezvous Receive Transport Properties dialog box
when setting
the required properties for
receiving
messages. . Additional information is available at
http://technet.microsoft.com/en-us/library/aa560286
The following table describes how to set these properties
.
Property Step
Adapter required properties
Rendezvous subject name
Provide the subject name that the adapter
listens for.
Certified Listener Properties
Ledger file name Defaults to blank
Reuable name Defaults to blank. Only required to survive
a process being restarted. Distributed Queue Settings
Activation Interval Defaults to 20 seconds. Time interval
without a heart beat message from the scheduler.
Heart Beat Interval Defaults to 10
Scheduler Weight Policy Defaults to blank
Worker Capacity Policy Defaults to 1
Worker Weight Policy Defaults to 1
30
Appendix wildcard substitute Specify a wildcard text substitute.
Code Page Number Default is 65001
Element wildcard substitute Specify a different wildcard text substitute.
Event Queue Name Specify a name to use when you are
creating the Rendezvous Queue object. Default to blank.
Filter Default to blank.
Map unsupported types to string Defaults to True
Member of BizTalk group Defaults to False
Receive Location Identifier Provide the name of receive location
Reserved For special use.
Tibco Enterprise Message Service
We use the
Enterprise Message Service Transport Receive Properties dialog bo
x
when setting the required properties for the
Receive Port
. . Additional information is
available at
http://technet.microsoft.com/en-us/library/aa548036The following table describes how to set the properties.
Property Step
System Definition - Required
URL
Provide the URL.
Target namespace
Provide the Target Namespac e.
Message Handling
Message Selector
Messages are received only if this string
evaluates to True with the message in the
destination.
Retry Count
Defaults to
0.
Retry Interval
Defaults to
5 minutes
Server Connection Definition
Destination - Required
Provide the name and type of the
destination.
port number.
Server Name - Required
Provide the name of the system hosting the
TIBCO EMS Server.
Use Single Sign-On
Select Yes if you are using SSO.
Affiliate application
If you are using SSO, select the affiliate
application
User CredentialsPassword
Provide if not using SSO
User Name
Provide if not using SSO
We use the
Enterprise Message Service Transport Send Properties dialog bo
x when
setting the required properties for the
Send Port
. . Additional information is available at
http://technet.microsoft.com/en-us/library/aa558716
The following table describes how to set the properties.
Property
Step
System Definition - Required
Destination Defines the name and type of the
destination
Port Number Port on which the TIBCO EMS server
listens
Server Name Mandatory setting. Name of the system
hosting the TIBCO EMS server.
Message Handling
Message Expiration Time
An integer that describes the length of time
the message stays on the queue or topic;
after the time expires, the message is
deleted by the TIBCO EMS server.
Defaults to
0
milliseconds.
Message is Persistant
Defaults to
True.
Message Priority
Defaults to
4
Server Connection Definition
32
destination.
Port Number
Provide the TIBCO EMS Server listener
port number.
Server Name - Required
Provide the name of the system hosting the
TIBCO EMS Server.
Use Single Sign-On
Select Yes if you are using SSO.
Affiliate application
If you are using SSO, select the affiliate
application
User Credentials
Password
Provide if not using SSO
User Name
Provide if not using SSO
PeopleSoft Enterprise Adapter
We use the PeopleSoft Transport Properies dialog box when setting the adapter-required
properties. Additional information is available at
http://technet.microsoft.com/en-us/library/aa578107The following table describes how to set the properties.
Property Step
Adapter Required Properties
Application server path Provide the path of the PeopleSoft Server.
JAVA_HOME Type the name for the JAVA_HOME
location.
Password Provide the user password.
PeopleSoft 8.x JAR files Provide the path for the location of the
PeopleSoft JAR files.
User name Provide the user name.
Additional Parameters
Database Date Format Provide the format you want dates to
appear. Concurrency Control
Connection
Maximum number of sessions Provide the maximum number of sessions.
Defaults to 40. Refresh Agent
Refresh Agent Select Yes if you want the process to
restart automatically if it loses coonection with the server.
Single Sign-On
Affiliate Application If you are using SSO, select the affiliate
application
Use SSO Select Yes if you are using SSO.
Third-Party Adapters
/n Software
The /n software Adapters for Microsoft BizTalk include fully-managed .NET Adapters
that seamlessly integrate with the BizTalk Messaging Pipeline. The /n software Adapters
extend the features of BizTalk with advanced Internet communications and secure
messaging capabilities.
Community Edition
The /n software Community Edition includes plain-text versions of same fully-managed
.NET Adapters and Pipeline Components found in our Enterprise Adapter suite. The
Community Edition includes binaries for all of the Adapters found in both, and features
are enabled based on the type of license installed.
The Community Edition includes the following Adapters:
FTP Adapter
- Plain-text FTP Adapter with advanced firewall and proxy
capabilities.
Email Adapters
- Email (SMTP/POP/IMAP) Adapter
RSS Adapter
- RSS Client integration Adapter.
SNPP Adapter
- Alphanumeric paging Adapter.
XMPP Adapter
- Jabber / XMPP Instant Messaging Adapter.
Amazon S3 Adapter
- Integration with Amazon Simple Storage Service (S3).
More information on the use and configuration of these adapters can be found at
34
ODBC Adapter from Two-Connect
BizTalk 2010 does not have an adapter for every Data Resource. We have a choice of
either purchasing an Adapter, creating our own by using the WCF LOB SDK, or using
the Community ODBC Adapter provided by TWOCONNECT
http://www.twoconnect.com/BizTalk-Products/ODBC-Adapter.aspx
TWOCONNECT has updated the open source ODBC Adapter made on GotDotNet
several years ago, to work with BizTalk 2010. It has been updated to support the Net 4.0
Target and the Install Folder Path has been fixed for 64 Bit Systems
According to TWOCONNECT:
It has support for creating two way operations
Can no longer be configured on a Request/Response Port
Poll While Data Found option on Receive Location is supported.
Performance Counters and Event Source created at install time.
No longer requires Administrator rights at Runtime
The adapter does have limitations and issues:
When using Insert, Update, or Delete Table Operations, there is no return value.
It only supports a one-way operation.
You cannot use Output parameters in Stored Procedures
To demonstrate the use of the Adapter, we have three scenarios.
1.
Request\Response operation using a Select from a table.
2.
Request operation using an Update on a table.
3.
Request\Response operation using a stored procedure
Before we can use the Adapter we need to install it.
1.
We will have to manually add the Adapter to our BizTalk Environment as shown
below:
36
3.
We then assign our ODBC Host Instance to the ODBC Adapter’s Send and
Receive Handlers as shown below.
Assign our ODBCHost to Send Handler
Setting our ODBC Data Source
1.
Assuming that our BizTalk 2010 Environment is 64 bit, we will need to use the
odbccad32.exe, which is located in C:\Windows\SysWOW32, to create your
ODBC Data Source.
38
3.
Clicking “Add” starts the Configuration Wizard.
4.
Enter a name for our Data Source.
6.
Click “Next” until you get to the page show below.
7.
Check the “Change the default database to:” and select our PurchaseOrders
Database.
8.
Click “Next” again
40
10.
If we configured everything correctly, we will see the results as show above.
Scenarios
Request\Response operation using a Select from a table
Open Visual Studio 2010 and create a new BizTalk Application. Name it
“ODBC_Sample”.
1.
Next we will use the “Add Adapter Metadata Wizard” to generate our schemas
and orchestration as shown below.
42
2.
Select the ODBC Adapter as shown below:
3.
Click “Next”.
4.
Then enter our Target Namespace, Request and Response element root names as
shown below.
5.
Click “Next”.
6.
We will be doing a simple Select Statement. Select “SQL Script” and click
“Next” as shown below
44
8.
Next we will enter our Select Statement as shown below.
9.
Next Click “Generate”.
After a few seconds you will see two schemas and an orchestration in our project
folder.
Since we did a Select without a where clause, our generated schema is generic as
shown below.
The Response Schema contains all the fields from our table.
Looking at the Multipart Message Types, we can see that there is a problem with
the Multi-part Message Types. (
This is one of the issues in the Adapter
)
46
Another issue is that there are two ports created instead of one as shown
below.(
This is also an issue with the adapter
).
The solution to this issue is to
delete the ODBCRequest
and ODBCResponse
Port Types and
create a new Request-Response Port
as shown below.
10. Next we need to add our Inbound Message. We are using the Request Message
generated by the Adapter Wizard.
48
The following diagram shows our Port Binding.
Request operation using an Update on a table.
We will need to repeat Steps 1 – 5 above .
6.
In order to do an Update, we need to manually enter our Update Query into
the Query Editor as shown below.
7.
Before we click on “Generate”, we need to check the “Override default query
processing” If we omit this step, all of our Input Parameters will default to an
NVarChar Data Type with a field size of 1.
50
8.
We have to select each Parameter and set its Type and Field Size. Setting the
Sample Data value is optional.
10.
This brings us back to the Schema Generation page.
11.
We can now click on “Generate”.
12.
This time we have one Schema and an Orchestration generated
We also have the same issue with Multi-part Message Types.
52
2.
Our generated schema is shown below
4.
Our Orchestration is similar to our first demo, the only exception being a
Send Port instead of a Send\Receive
Request\Response operation using a stored procedure
54
2.
Next we must follow Steps 1 - 5 as in the previous demos.
3.
On the Statement Type page , we will select Stored Procedure.
5.
Click “Generate
56
8.
Our Response Schema
We still have the same issue with the Multipart Message Types.
58
Two Port Types are created. We need to delete these and create a new Request/Response
Port
2.
We are sending a Request and Receiving a response
3.
Our new Request\Response Port as show below.
60
Because we are using a Stored Procedure that returns a value, we can add
Exception Handling. In this case we are validating the result and throwing a
System.Exception if the Stored Procedure returns an Error Code.
Deployment
We will need to create two Send Ports, a Static Request-Response for our Select Table
Operation and Stored Procedure Demos, and a Static Request Port for our Update Table
Operation.
Creating Ports for the ODBC Adapter
1.
Open the BizTalk 2010 Administration Console and add a new Application
called “ODBC Test” as shown below.
2.
After deploying our demos, we need to configure a Static Solicit-Response Send
Port as shown below.
3.
Since we are using Windows Authentication for our ODBC Data Sources, we
uncheck “Include UserID and Password” as shown below.
62
5.
Our ODBC Transport Properties are set as shown below.
64
7.
We configure the Send Port by setting our Connection String
8.
We then click on the Connection String button.
66
If our ODBC Data Source supports Transactions, you can select from the
“Transaction type to be applied” list as shown below.
68
