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

• How does the Verastream Interface for BizTalk Server work?



• What are the software requirments for the Verastream Interface for BizTalk Server? How do I install and configure it?



• What is the Schema Builder?



• How do you use the Verastream interface?



• Encountering problems?



• Where can I go for additional support?

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:

• PTContestWinner is a sample project that implements a Table Procedure. Follow the instructions in the readme.txt file in the PTContest folder to see the completed project, or follow detailed instructions to see exactly how such a project can be implemented.



• PTContestWinnerMore also implements a Table Procedure but tests the Verastream Adapter result document for success or failure status. Upon a successful result, the Orchestration maps the result document; upon a failure, the Orchestration instead writes a description to a file. This sample is intended to show a more complete usage of the Verastream Adapter in a BizTalk Orchestration. Follow the instructions in the readme.txt file in the PTContestWinnerMore folder to see the completed project.



• StockTransactions is a sample project that implements a Process String Event Handler. This project demonstrates how you can retain XML tags when using the Process String access method. Follow the instructions in the readme.txt file in the StockTransactions folder to see the completed project.



• WSContestWinner is a sample project that accesses a Host Integrator model through a BizTalk SOAP adapter. Follow the instructions in the readme.txt file in the WSContestWinner folder to see the completed project.

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:

• Passes an XML message to a BizTalk Orchestration by placing it in a message queue. The BizTalk Orchestration processes the XML message and invokes the Verastream adapter. (Verastream functionality is defined as an adapter in BizTalk Server.)
• The adapter parses the XML document, connects to the Verastream Host Integrator Server, makes the appropriate API calls, and retrieves the requested data.
• Next, the adapter converts the retrieved data to XML and returns it to the BizTalk Orchestration
• The BizTalk Orchestration then places the XML message in the message queue where it is picked up by the requesting Web Service or application.

Using the Verastream Interface

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

• Using a Verastream Table Procedure
  With this method, the Orchestration Designer uses the BizTalk Schema Builder to browse the models and procedures deployed to one or more Host Integrator Servers, or exported to XML model files. The resulting schema (XSD file) is then incorporated into a BizTalk project.
  
  A table procedure is a structure that the model developer creates in the Verastream Host Integrator Design Tool.
  
  
• Using a "Process String" Event Handler
  In Verastream Host Integrator, an event handler is custom procedural code that is associated with a model. If the ProcessString event is implemented in the Host Integrator model and you select Process String as your document type in the Schema Builder, any XML document that BizTalk passes to the Verastream adapter will be parsed and processed by the ProcessString event handler within the Host Integrator model.

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:

• BizTalk Server 2004 and Visual Studio .NET 2003
  
  • SQL Server 2000 must be updated for BizTalk Server 2004. See http://support.microsoft.com/default.aspx?scid=kb;en-us;838166 for details.
  • The BizTalk Server 2004 Roll-up Package 1.
• BizTalk Server 2006 and Visual Studio .NET 2005

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

There are two properties that are only available when you are configuring a specific project:

• Retry on Failure—Use this property to determine which method to use when an error occurs:
  • If the property is False, errors that occur are returned in the reply document. You can handle the error in your business process. The PTContestWinnerMore example shows how this is implemented. The error is not reported to BizTalk and your message is not suspended.
  • If the property is True, errors are reported to BizTalk and the message will be retried, dependant on the retry count and -interval you configured in the adapter settings. If the operation keeps failing until the retry count is exceeded, BizTalk suspends your message and orchestration. You must use the Administration Console to resume or terminate the instances. In this case, you will never receive an error in the reply document from the adapter.

  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.

• Method Timeout

  Specifies how long the adapter should wait for a response from the Verastream server. The default value is 30000 (milliseconds).

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:

   • If you map an element from the input document schema to an element in the input schema generated by Schema Builder, the default value provided in Schema Builder for this element will be ignored.
     
   • If the schemas produced by the Schema Builder are to be used in more than one BizTalk Orchestration, they should be placed in a separate DLL which can then be referenced from each BizTalk Orchestration project that uses them. This will prevent a BizTalk Server runtime error that would otherwise occur when a single schema is deployed multiple times.
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.

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

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


5. Bind, enlist, and start the application.


6. Test and run your project.


7. 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:
   • Import the bindings shipped with the example. This is the easiest way to configure the application. Right-click the example and select Import>Bindings. Browse to the Example directory and select the file named PTContestWinnerBinding.xml.
     -or-
   • Make the bindings yourself. See the procedure below.

   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.