The Verastream Interface for BizTalk Server

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. The procedures in this document are based on 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.

Sample Projects

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:

  1. Start the Verastream Design Tool and choose Open from the File menu.
  2. Open the appropriate model file. (For PTContestWinner, the model is <Verastream Interface install folder>/Examples/PTContestWinner/Model/PTContestWinner/PTContestWinner.model.)
  3. Choose Deploy to Local Server from the File menu.
  4. After you see the confirmation dialog you can exit the Design Tool.

How does the Verastream Interface for BizTalk Server work?

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:

Using the Verastream Interface

There are two methods available to the BizTalk Orchestration Designer to access host data through the Verastream adapter:

 


Software Requirements, Installation, and Configuration of the Verastream Interface for BizTalk Server

Requirements

The requirements for the computer on which you install Verastream Interface for BizTalk Server are:

Installing

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:

  1. Add the adapter to the Registry using <VHI installation directory>/BizTalk/Adapter/VerastreamAdapter.reg
  2. Add the Adapter in the BizTalk Server Administration Console.
  3. Optionally, you can add the Schema Builder to Visual Studio as an external tool.

Note: If you have installed an earlier version of Verastream Interface for BizTalk Server, you must uninstall it before you install the new version.

Configuring the Properties for the Verastream Interface for BizTalk Server

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:

  1. Open BizTalk Administration Console and expand the BizTalk group, Platform Settings, Adapters, Verastream node.
  2. Double-click the Adapter Handler, typically named BizTalkServerApplication.
  3. In the Adapter Handler Properties dialog box, click Properties.

You must provide a compatible set of Verastream Server Connection parameters—that 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).

 

Properties for the Verastream Interface for BizTalk Server

Property Description
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:
  • Exceptions—An adapter call is written to the log file only if an exception occurs.
  • Full—Every adapter call is written to the log file.
  • None—No adapter calls are written to the log file.
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 myproj.log as your log file name, the message ID is inserted into this name so that it becomes myproj.<message ID>.log.
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:


What is the Schema Builder?

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.


Using the Verastream Interface

  1. To create a BizTalk project that connects to a Verastream server, use the Verastream Schema Builder to create input and output schemas, based on an existing Verastream Host Integrator model. The model must include procedures. Save the schemas in a BizTalk project folder.

    Notes on Using Generated Schemas:

  2. Create a BizTalk project (including an Orchestration) that contains a message (matching the Verastream input schema) as input to the Verastream adapter.

    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.

  3. Build and deploy your BizTalk project.
  4. In the project settings, supply a BizTalk Application name. Otherwise, your work will be accessible under the default application, typically named "BizTalk Application 1."

  5. Configure Send and Receive Ports for your BizTalk application.

  6. Bind, enlist, and start the application.

  7. Test and run your project.

  8. Export your application as an MSI file and deploy it in your production environment.

The Example Project: PTContestWinner illustrates how these steps are implemented in the context of a sample project.

Example Project: PTContestWinner

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 <install directory>/BizTalk/Examples/PTContestWinner.

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.

  1. Open Windows Explorer
  2. In the directory where Verastream is installed, open BizTalk/Examples/PTContestWinner and double-click PTContestWinner.sln. This opens Visual Studio 2005 and the PTContestWinner BizTalk project.

  3. Deploy the model.
  4. Build and deploy the project (using the Solution Explorer panel in Visual Studio 2005.)

    This will create the BizTalk application PTContestWinner. The orchestration contains three ports, which will be configured in the following steps.


  5. Open the BizTalk Server 2006 Administration Console. You have two options for configuring the application:
    To make the bindings yourself:
    1. Refresh the Applications Node and select the PTContestWinner application. Select Receive Ports, then New>One-way Receive Port. Add a Receive port named PTContestWinnerReceivePort with 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.

    2. 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.


    3. 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 PTContestWinnerSendPort in 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.

    4. 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.

  6. Right-click the BizTalk application and select Start.

    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.


Troubleshooting

Review the following troubleshooting topics if you're having problems.

BindingException: Specified cast is not valid
XML Process String and earlier versions

BindingException: Specified cast is not valid

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

XML Process String and Earlier Versions of Verastream Interface for BizTalk Server

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.


Resource Information

Technical Support

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.