The Verastream Interface for BizTalk® Server links Microsoft BizTalk 2004 and 2006 to data and logic residing in IBM Mainframe, AS/400, HP, and VT hosts. These procedures use BizTalk 2006. With the Verastream Interface for BizTalk, you can design and execute BizTalk Orchestrations that access host applications without leaving the BizTalk environment.
Note: The Verastream Interface for BizTalk Server is installed as part of typical Host Integrator Development and Server Kit setup if BizTalk is detected on the installation machine. If you add BizTalk Server after Host Integrator is installed, you can add Host Integrator BizTalk support manually by running Setup again. Choose the Custom / Modify option and add Interface for BizTalk Server.
Verastream Interface for BizTalk Server contains four sample projects. These samples are located in
<installdir>\BizTalk\Examples, along with readme.txt files containing detailed instructions. The samples are:
Notes on the Sample Projects:
Before running any of these sample projects, you must run the Verastream Host Integrator Design Tool and deploy the appropriate model to the local server:
The Verastream Interface for BizTalk® Server links Microsoft BizTalk projects to data and logic residing in IBM Mainframe, AS/400, HP, and VT hosts.
In a typical scenario, a Web Service or other application:
There are two methods available to the BizTalk Orchestration Designer to access host data through the Verastream adapter:
The requirements for the computer on which you install Verastream Interface for BizTalk Server are:
When you install a Verastream Host Integrator Developer's or Server Kit using the Typical option on a machine that has BizTalk Server installed, the Verastream BizTalk Interface is automatically installed.
If you want to install Verastream Interface for BizTalk on a machine that does not have BizTalk Server already installed, additional configuration is necessary:
<VHI installation directory>/BizTalk/Adapter/VerastreamAdapter.reg
Note: If you have installed an earlier version of Verastream Interface for BizTalk Server, you must uninstall it before you install the new version.
The default properties for the Verastream Interface (adapter) are inherited by any project that includes the adapter. They can be overridden for any individual Verastream Send port in an Orchestration. It is not necessary to set defaults for these properties, if you correctly configure all Send ports that use the Verastream adapter in your Orchestration.
To set the default properties, follow these steps:
You must provide a compatible set of Verastream Server Connection parametersthat is, a set that does not contradict itself. If you specify a Server Name, do not specify a Domain or a Directory Server; if you specify a Domain and a Directory Server, do not specify a Server Name.
Note: Some of the properties do not accept an empty string as a value. If you have entered something and wish to remove it, you must nullify it: right-click the name of the property and select Nullify (property name).
|Connection Timeout||Default value is 30 seconds. Range of values is 0 to 86400 seconds. Specifies how many seconds Host Integrator should wait for a successful connection to the host. If Host Integrator is unable to connect to the host is the allotted time, an error results. If the timeout is set to zero, a single host connection attempt is made. If it is unsuccessful, no additional attempts are made.|
|Secure Connection||When set to True, all communication between the BizTalk adapter and Verastream Host Integrator server is encrypted, regardless of the authentication setting on the server. Secure connections are considerably slower.|
|Process String Preserve XML Tag||The default is True. When set to True, a document's XML tags are retained when using the Process String access method. If you are upgrading from an earlier version of the Verastream BizTalk Interface and want to retain your current implementation, set this to False.|
|Trace Level||Determines what information is written to the log file. Select one of three possible settings:
|Log File||Specifies the location of the log file for the Verastream adapter. To ensure
that different BizTalk Orchestration instances are not attempting to write to the same log file at the same time, the message ID of the XML document returning to the Orchestration is used as part of the log file name. For example, if you specify
|Server Name||The default is localhost. Specifies the name of a Verastream Host Integrator Server.|
|Session Pool||Specifies the name of a Verastream Host Integrator session pool.|
|Domain||Specifies the name of a Host Integrator domain.|
|Directory Server||Specifies a Host Integrator authentication and authorization directory server (AADS).|
|User ID||If you have security configured on your Host Integrator Server or domain, you must specify a UserID.|
|Password||If you have security configured on your Host Integrator Server or domain, you must specify a Password.|
There are two properties that are only available when you are configuring a specific project:
Your business process determines which of these methods best fit your needs. Handling the error in the business process requires more coding in the orchestration, but keeps the message from being suspended. If you do not have a natural way to handle the error, then suspending the message is your best option.
Specifies how long the adapter should wait for a response from the Verastream server. The default value is 30000 (milliseconds).
Schema Builder is a stand-alone wizard, available as part of the Verastream Interface for BizTalk Server, that guides a BizTalk Orchestration Designer through the process of creating a schema file (XSD) that can connect to and interact with a Verastream server. The Designer then incorporates the created schema into a BizTalk project, to manage communication between the Orchestration and the host application through a Host Integrator Server.
To run the Schema Builder, from the Windows Start menu, click:
Programs >Attachmate Verastream >Host Integrator> Schema Builder
You can also run Schema Builder from the Tools menu in Visual Studio.
Notes on Using Generated Schemas:
When the project is running, the Verastream adapter will return XML text conforming to the Verastream output schema to the Orchestration for each message that is input to the adapter.
In the project settings, supply a BizTalk Application name. Otherwise, your work will be accessible under the default application, typically named "BizTalk Application 1."
The Example Project: PTContestWinner illustrates how these steps are implemented in the context of a sample project.
PTContestWinner is a sample BizTalk project that uses sample data provided with the Verastream Interface for BizTalk Server. When the project is fully implemented, placing an XML document in the designated input folder causes a query to be run against data in a (simulated) host application. The results are placed in an XML file in a separate output folder. The input and output folders simulate message queues in an actual project. Follow the steps below to see how this project can be implemented in Visual Studio.
Note: To see the finished project, open the readme.txt file in the Verastream
This example communicates with the Verastream model using a table procedure.
All necessary schemas, XML files, and project files are supplied. All that remains is to incorporate host data into the Orchestration.
BizTalk/Examples/PTContestWinnerand double-click PTContestWinner.sln. This opens Visual Studio 2005 and the PTContestWinner BizTalk project.
This will create the BizTalk application PTContestWinner. The orchestration contains three ports, which will be configured in the following steps.
To make the bindings yourself:
- Refresh the Applications Node and select the PTContestWinner application. Select Receive Ports, then New>One-way Receive Port. Add a Receive port named
PTContestWinnerReceivePortwith one Receive location named
PTContestWinnerReceiveLocation. Set FILE as the Transport Type. Set the URL to the folder that is to serve as the receive port for the scenario:
<Verastream install folder>/BizTalk/Examples/PTContestWinner/In.
Use the XMLReceive pipeline.
- In the BizTalk Administrative console, right-click Send Ports and select New Static Solicit-Response Send Port.
In the Static Solicit-Response Send Port Properties dialog box, enter PTContestWinnerVerastreamSendPort in the Name field.
Select Verastream as the Transport Type, then press Configure to open the Verastream Transport Properties dialog box. These are the same properties used to configure default properties for the Verastream adapter:
Default properties you have already configured are shown and will be used unless you supersede them here. Properties for which you didn't supply defaults are also shown and can be configured here, specific to this port.
Note: If you change any of the properties in the Verastream Server Connection section (Server Name and below), then the default values you have configured for these properties are disregarded. So, for example, if you specify a session pool, then you must also remember to add a server name, even if you have one configured in the Default Send Port Properties, because the default Verastream Server Connection properties are disregarded for this particular port after any of them are modified.
You do not have to configure any values in the Verastream Transport Properties dialog box for this example scenario. Click OK to return to the Static Solicit-Response Send Port Properties dialog box. Use XML Transmit as the Send Pipeline and XML Receive as the Receive Pipeline. Click OK to dismiss the Static Solicit-Response Send Port Properties dialog box.
- Configure a Static Send Port that exports an XML document in the Out folder. The final port to configure is the Send Port that exports an XML document to the Out folder, described below.
- In the BizTalk Administrative console, right-click Send Ports and select New>Static One-Way Send Port.
- In the Static One-way Send Port Properties dialog box, enter
PTContestWinnerSendPortin the Name field.
- Select FILE as the Transport Type and then click Configure.
- Enter the path and filename for the folder where BizTalk is to place the results of the query against the host application:
<VHI install dir>/<BizTalk directory&/Examples/PTContestWinner/Out. Use XML Transmit as the Send Pipeline.
- With the ports now configured, you can now bind, enlist, and start the project: Right-click the BizTalk application and select Configure. Select the orchestration PTContestWinnerOrchestration on the left and configure the following values:
- Set PTContestWinnerReceivePort to PTContestWinnerReceivePort.
- Set PTContestWinnerToVerastreamPort to PTContestWinnerVerastreamSendPort.
- Set PTContestWinnerWriteWinnerPort to PTContestWinnerSendPort.
Select Host in the Explorer pane and select BizTalkServerApplication as the value for the Host field. Click OK to dismiss the Configure Application dialog box.
To test the Orchestration, copy
GetWinner.xml from the Documents directory under
<Verastream install folder>/BizTalk/Examples/PTContestWinner and paste it into the
In directory. Momentarily the file will disappear from the
In directory, and a new file will appear in the
Out directory. The filename is unique, so you can run the scenario multiple times and get a unique output file each time.
Review the following troubleshooting topics if you're having problems.
BindingException: Specified cast is not valid
XML Process String and earlier versions
Symptom: Deploying an Orchestration that uses the Verastream Adapter causes this or a similar error:
[Microsoft.BizTalk.Deployment.DeploymentException] Unable to deploy early bindings. [Microsoft.BizTalk.Deployment.Binding.BindingException] Failed updating binding information. BindingException: Specified cast is not valid. [System.InvalidCastException] Specified cast is not valid.
Cause: BizTalk Server 2004 requires installation of the Com+ Roll-up QXP6 for Microsoft Windows XP, or the Com+ Roll-up 29 for Microsoft Windows 2000.
Resolution: Install the Com+ Rollup package from the Microsoft Download Center: http://support.microsoft.com/?id=837119
A new property, Process String Preserve XML Tags, changes the behavior of Process string. If you are upgrading from an earlier version of the Verastream BizTalk Interface and want to retain your current implementation, set this to False.
If you have questions or are experiencing problems with the Verastream Interface for BizTalk Server, click:
Technical Support Web site
From this Web site you can browse technical notes, download support software, or contact a support technician.