Using HTTP transport protocol with pre-4.2.2 ICS

WebSphere Business Integration Connect can send and receive documents with a pre-4.2.2 version of WebSphere InterChange Server (ICS) over the HTTP transport protocol.

Notes:

  1. To send and receive documents between WebSphere Business Integration Connect and a version 4.2.2 InterChange Server over the HTTP transport protocol, see Using HTTP transport protocol with v4.2.2 ICS.

  2. If you are exchanging SOAP documents over the HTTP transport protocol, see Sending SOAP documents over HTTP/S.

This section provides the following information on how to configure a pre-4.2.2 InterChange Server and the appropriate ICS-compatible components for use with Business Integration Connect over HTTP:

Sending documents to pre-4.2.2 ICS through HTTP

This section provides the following information to describe how to send documents from Business Integration Connect to a pre-4.2.2 ICS over the HTTP transport protocol:

The document that Business Integration Connect sends to InterChange Server initiates event notification within InterChange Server.

Components required for sending

Business Integration Connect can send documents to the following pre-4.2.2 versions of InterChange Server over the HTTP transport protocol:

For Business Integration Connect to send a document to a pre-4.2.2 ICS using the HTTP transport protocol requires that these two components be configured. Table 45 summarizes these configuration steps.

Table 45. Configuring Business Integration Connect and InterChange Server

Component Version For more information
WebSphere Business Integration Connect 4.2.2

Configuring for outgoing documents over HTTP transport protocol

Configuring for incoming documents over HTTP transport protocol

WebSphere InterChange Server 4.1.1, 4.2.0, 4.2.1 Creating pre-4.2.2 ICS artifacts for HTTP

In addition, to send a document to ICS over the HTTP transport, you use the ICS-compatible components listed in Table 46. Most of these components are provided as part of the Business Integration Connect release.

Table 46. Components required to send documents to pre-4.2.2 ICS through HTTP

Component Description Notes and restrictions
WebSphere Business Integration Connect Servlet (Connect Servlet)

This servlet is a WebSphere InterChange Server access client. An access client is a process that is external to InterChange Server (ICS) and can request execution of a collaboration within ICS.

The servlet can be used with the pre-4.2.2 versions of WebSphere InterChange Server.

Note:
The servlet cannot be used with version 4.2.2 WebSphere InterChange Server.
Wrapper data handler

This data handler is called by the Connect Servlet to convert the HTTP message into the appropriate data business object. It invokes the data handler that is appropriate for your message. For example, if the payload is formatted in XML, the Wrapper data handler can be configured to call the Data Handler for XML.

None
A payload data handler This data handler converts the document payload between its document format (usually XML) and its business-object representation. This data handler is required and must support the MIME type of your payload document.
Attachment data handler

This data handler handles attachment documents for your document message.

This data handler is required only if your documents include attachments.

Note:
All components listed in Table 46 are included on the Business Integration Connect installation medium. For information on the location of these components, see Deploying the Connect Servlet.

Figure 9 provides an overview of how Business Integration Connect sends documents to a pre-4.2.2 ICS over the HTTP transport protocol.

Note:
The Wrapper data handler, the Attachment data handler, and the payload data handler all execute within InterChange Server.

Figure 9. Message flow from Business Integration Connect to a collaboration through the HTTP transport protocol


As Figure 9 shows, the WebSphere Business Integration Connect Servlet is the ICS-compatible component with which Business Integration Connect interacts directly. This Connect Servlet is an access client, which is a process external to InterChange Server that can request execution of an ICS collaboration. The access client issues calls from an application programming interface (API) called the Server Access Interface to interact with ICS. These calls are received and interpreted by WebSphere InterChange Server Access, which is the component within ICS that handles interactions with access clients. The Server Access Interface invokes the collaborations synchronously.

Notes:

  1. Even though some interactions between Business Integration Connect and back-end systems are asynchronous, Server Access still invokes the collaboration synchronously and waits until the collaboration execution has completed.

  2. For more detailed information on access clients and Server Access, see the Access Development Guide in the WebSphere InterChange Server documentation set.

The following steps describe how Business Integration Connect participates in event notification by sending a document to a collaboration within ICS over the HTTP transport protocol:

  1. Business Integration Connect invokes the WebSphere Business Integration Connect Servlet to send the document to InterChange Server.

    Business Integration Connect sends the document to the URL specified as the target gateway.

    Note:
    The Connect Servlet can be used to invoke multiple collaborations.
  2. The Connect Servlet creates a Java string from the HTTP request message that Business Integration Connect sends.

    The HTTP request message contains two parts:

  3. The Connect Servlet checks its servlet properties file to determine the collaboration to invoke, along with the verb and MIME type to use.

    Each URL corresponds to a collaboration to be invoked. (See Configuring the Connect Servlet for information.)

  4. The Connect Servlet sends the Java string, along with the information from the servlet properties file, to WebSphere InterChange Server Access using calls in the Server Access Interface.

    Because the Connect Servlet can only send a document to InterChange Server (it cannot receive a document), it can only participant in event notification with InterChange Server.

    Note:
    To support request processing with InterChange Server, Business Integration Connect must interact with the WebSphere Business Integration Adapter for XML. For more information, see Receiving documents from pre-4.2.2 ICS through HTTP.
  5. WebSphere InterChange Server Access, within InterChange Server, receives the Java string and invokes the Wrapper data handler.

    The job of the Wrapper data handler is to convert the Java string into the corresponding business-object structure. It is business objects that InterChange Server expects as input.

  6. The Wrapper data handler takes the following step to convert the Java string to its business-object structure:
    1. Extract the headers and payload from the Java string.
      Note:
      If the document that Business Integration Connect sent includes attachments, the Wrapper data handler can be configured to call the Attachment data handler. The actions of the Attachment data handler are described in Handling documents with attachments.
    2. Check the MIME type of the payload and call the data handler that has been configured for that MIME type to convert the payload into a payload business object.
    3. Create the HTTP-properties business object and the dynamic business object.

      Set the HTTP headers in the HTTP-properties business object, which is a child of the dynamic meta-object of this payload business object.

    4. Create the top-level business object and set the event business object as its request business object.

      The Wrapper data handler expects the payload business object to have a hierarchical structure. For information on the structure of this payload business object, see Creating business object definitions for sending documents.

    5. Return the top-level business object to the Server Access within InterChange Server.
  7. Server Access invokes the collaboration, passing it the top-level business object.

    Make sure the collaboration port for the collaboration object you will be invoking is configured as the external port. Refer to the WebSphere InterChange Server documentation for details on how to configure ports.

  8. The collaboration executes and returns the top-level business object to the Wrapper data handler.

    Whether the response business object (within the top-level business object) is populated depends on the type of interaction between InterChange Server and Business Integration Connect, as follows:

    For more information, see Response business object.

  9. If the interaction is successful, the Connect Servlet returns an HTTP 200 OK acknowledgment to Business Integration Connect.

Configuring the Connect Servlet

The WebSphere Business Integration Connect Servlet is an access client, which is a process that is external to InterChange Server and can request execution of a collaboration within InterChange Server. The access client uses calls from an application programming interface (API) called the Server Access Interface to interact with ICS. These calls are received and interpreted by WebSphere InterChange Server Access, which is the component of InterChange Server that handles interactions with access clients.

Note:
For more detailed information on access clients and Server Access, see the Access Development Guide in the WebSphere InterChange Server documentation set.

Configuration of the Connect Servlet involves the following steps:

Deploying the Connect Servlet

The Connect Servlet, Wrapper data handler, and the repository file for the Wrapper data handler are available on the Business Integration Connect installation medium, in the locations listed in Table 47.

Table 47. Location of the Connect Servlet components

Component Location
Connect Servlet Integration/WBI/WICS/WBICServlet/ bcgwbiservlet.war
Wrapper data handler Integration/WBI/WICS/WBICServlet/ bcgwbiwrapperdh.jar
Repository file for Wrapper data handler Integration/WBI/WICS/WBICServlet MO_DataHandler_WBIWrapper.in
Note:
If you are expecting to send documents that include attachments, you can also deploy the Attachment data handler and its associated repository file, as described in Deploying the Attachment data handler.

This servlet can connect to WebSphere InterChange Server versions 4.1.1, 4.2.0, and 4.2.1. It can be deployed on the platforms on which any of these versions of InterChange Server is supported. Additionally you need to make sure that the Server Access Interface is supported on that platform. Refer to the WebSphere InterChange Server documentation for a list of the platforms on which the ICS version you are using is supported.

To deploy the components in Table 47, follow these steps:

  1. Deploy the Connect Servlet and associated files into the Web server according to the documentation for the Web server.
  2. Make sure the following files are in the CLASSPATH of the Connect Servlet:

    These files can be found in the lib subdirectory of the InterChange Server product directory.

    Notes:

    1. These files must be from the same version of the InterChange Server that you will be invoking.

    2. These files must be available to the web container of the Connect Servlet in your web server. For more information on how to make files available to a web container, consult your web server documentation.
  3. Make sure the following files are in the CLASSPATH of the Connect Servlet:

    These files can be found on the Business Integration Connect installation medium in the following directory:

    integration/wbi/wics/http/lib/thirdparty
    

    Note:
    These files must be available to the web container of the Connect Servlet in your web server. For more information on how to make files available to a web container, consult your web server documentation.
  4. Make the InterChange Server Interoperable Object Reference (.ior) file available on the machine on which the Connect Servlet is deployed.

    If the Connect Servlet is on a different machine from InterChange Server, you can take either of the following actions to make the .ior file available:

    Note:
    You will also need to update the ICS_IORFILE property in the Connect Servlet's properties file with the location of this .ior file. For more information, see Identifying the InterChange Server instance.

Setting the Connect Servlet properties

As mentioned in Sending documents to pre-4.2.2 ICS through HTTP, the servlet properties file contains information, such as port name and verb, that the WebSphere Business Integration Connect Servlet needs to invoke a collaboration. You must create this servlet properties file, specifying general information about WebSphere InterChange Server. Then, for any collaboration you want the servlet to invoke, you provide information about that collaboration.

This section provides the following information about how to set the properties for the Connect Servlet:

Creating the servlet property file

A servlet properties file contains the sections listed in Table 48.

Table 48. Sections of the servlet properties file

Section of servlet properties file Description For more information
General information Properties to identify the InterChange Server instance Identifying the InterChange Server instance
Collaboration information Properties to identify each collaboration to invoke Identifying the collaborations to invoke
Logging information Properties to configure the servlet's logging Specifying the location of the servlet log file

Identifying the InterChange Server instance  The first section of the Connect Servlet's properties file contains general information to identify the InterChange Server instance with which Business Integration Connect communicates. This ICS instance contains the collaboration (or collaborations) that Business Integration Connect needs to invoke. Table 49 shows the general properties of the servlet properties file.

Table 49. General properties of the servlet properties file

Property name Description Example
ICS_SERVERNAME The host machine on which WebSphere InterChange Server is running. Server1
ICS_VERSION The version number of WebSphere InterChange Server. Possible values are 4.1.1, 4.2.0, and 4.2.1. 4.2.0
ICS_IORFILE

The file name of the Interoperable Object Reference (.ior) file, which is used to access WebSphere InterChange Server Access. The example shows how you would specify the path on a Windows system.

Note:
This path should be entered on one line.
c:/myiorlocation/
Server1ICS.ior
ICS_USERNAME The User ID for connecting to WebSphere InterChange Server. admin
ICS_PASSWORD The password for connecting to WebSphere InterChange Server. null
ICS_ENCRYPTED_PASSWORD An indication of whether the ICS_PASSWORD is encrypted. The servlet sets this field to true if the password is encrypted. false
ICS_DISABLEENCRYPTION An indication of whether password encryption is disabled (true) or enabled (false). Set this field to false if you want to allow passwords to be encrypted. true
Note:
For a sample servlet properties files that defines the values listed in the Example column of Table 49, see Sample servlet properties file.

Identifying the collaborations to invoke 

The second section of the Connect Servlet's properties file contains collaboration information, which associates the collaboration URL with associated collaboration properties. This section identifies collaboration URLs in two parts, as follows:


Table 50. Collaboration properties of the servlet properties file

Property name Description Example
WBIC_SERVLET_COUNT

The number of URLs configured in this file:

  • If it is set to 1, the servlet will process the URL and properties for WBIC_URL_1.
  • If it is set for 2, the servlet will process the URL and properties for WBIC_URL_1 and WBIC_URL_2.

1
WBIC_URL_1 The name of the relative URL PurchaseOrder
WBIC_URL_1_COLLAB The name of the collaboration PurchaseOrderCollab
WBIC_URL_1_PORT The port name of the collaboration From
WBIC_URL_1_VERB The verb subscribed to by the collaboration Create
WBIC_URL_1_WRAPPER_MIME The MIME type that the Wrapper data handler supports. Note that the example is in lowercase. wbic/wrapper
WBIC_URL_1_CHARENCODE The character encoding to use for the HTTP requests. Specify valid Java character encoding. UTF-8
Note:
For a sample servlet properties files that defines the values listed in the Example column of Table 50, see Sample servlet properties file.

The collaboration section of the servlet properties file provides a relative URL to identify the collaboration to execute. To look up the collaboration at run-time, the Connect Servlet combines the following pieces of information:

For example, if you used the sample values shown in Table 50, the Connect Servlet would need to obtain the URL of the PurchaseOrderCollab collaboration. To look up this URL, the servlet takes the following steps:

  1. Obtain the servlet URL, which identifies the location of the Connect Servlet.

    The servlet obtains the servlet URL from your web server. For example, suppose you deployed the Connect Servlet at the following location:

    http://www.yourcompany.com/tasks
    
  2. Append to the servlet URL the path in the WBIC_URL_count property.

    In Table 50, the WBIC_URL_1 property contains the value "PurchaseOrder". Therefore, the Connect Servlet would append this string to the servlet URL to obtain the following URL for the collaboration:

    http://www.yourcompany.com/tasks/PurchaseOrder
    

In the collaboration properties, the WBIC_URL_1_WRAPPER_MIME property specifies the MIME type for the Wrapper data handler. If you specify more than one MIME type, you need multiple meta-objects. See Creating the Wrapper child meta-object for information.

Specifying the location of the servlet log file  You specify logging properties in the third section of the Connect Servlet's properties file. You specify the location of the servlet log file in the properties file by adding the following statement:

log4jappender.RollingFile.File=logFileLocation

As shown in Figure 10, the log4jappender.RollingFile.File property is in the section of the servlet properties file that configures the Log4J. To configure the Connect Servlet, you only need to specify the location of the log file, by setting the log4jappender.RollingFile.File property. If you are familiar with Log4J, you can set other of its properties as well.

Sample servlet properties file  Figure 10 shows an example of the servlet properties file, which configures the values from the Example columns of Table 49 and Table 50.

Figure 10. Sample servlet properties file

# Example properties file for WebSphere Business Integration
# Connect Servlet
 ICS_SERVERNAME=Server1
 ICS_VERSION=4.2
 ICS_IORFILE=C:/myiorlocation/Server1InterChangeServer.ior
 ICS_USERNAME=admin
 ICS_PASSWORD=null
 ICS_ENCRYPTED_PASSWORD=false
 ICS_DISABLEENCRYPTION=true
# Collaboration properties for single collaboration
 WBIC_SERVLET_COUNT=1
 WBIC_URL_1=PurchaseOrder
 WBIC_URL_1_COLLAB=PurchaseOrderCollab
 WBIC_URL_1_CHARENCODE=UTF-8
 WBIC_URL_1_PORT=From
 WBIC_URL_1_VERB=Create
 WBIC_URL_1_WRAPPER_MIME=wbic/wrapper
#Log4J Debug Properties
#Possible Categories - debug/info/warn/error/fatal
#Default Category "error". Output to: stdout and RollingFile
log4j.rootCategory=debug,RollingFile
log4j.appender.RollingFile=org.apache.log4j.RollingFileAppender
#Log File Name
log4j.appender.RollingFile.File=D:\\_DEV\\servlet.log
log4j.appender.RollingFile.MaxFileSize=1000KB
#Number of backup files to keep
log4j.appender.RollingFile.MaxBackupIndex=10
log4j.appender.RollingFile.layout=org.apache.log4j.PatternLayout
log4j.appender.RollingFile.layout.ConversionPattern=
   %d{yyyy-MM-ddHH:mm:SS} %-5p [%c{1}] - %m%n

You can also find a sample servlet properties file in the SAMPLES directory on the Business Integration Connect installation medium.

Identifying the location of the servlet properties file

The deployment descriptor of Connect Servlet, web.xml, provides initialization parameters for the servlet. To identify the location of the servlet properties file, you set the WBIC_FILENAME parameter in this deployment descriptor. This parameter specifies the absolute pathname of the Connect servlet properties file.

For example, if the sample servlet properties file shown in Figure 10 was called connectServlet.cfg and it was located in the deployment directory of the Connect Servlet (for example, C:\WBIC\integration), you would need to set the WBIC_FILENAME parameter as follows:

C:\WBIC\integration\connectServlet.cfg

Configuring the Wrapper data handler

The Wrapper data handler converts a document from its serialized format (which the Connect Servlet has created from the HTTP message) into its corresponding business object. When the Connect Servlet invokes a collaboration, it sends to InterChange Server the serialized format of the document that Business Integration Connect has sent it. This collaboration request is received by WebSphere Server Access, which resides within InterChange Server. As Figure 9 shows, Server Access calls the Wrapper data handler, passing it the Business Integration Connect document. The data handler returns the corresponding payload business object.

To configure the Wrapper data handler, take the following steps:

The steps to configure the Wrapper data handler are summarized in the following sections. For general information about data handlers, see the Data Handler Guide in the WebSphere InterChange Server documentation set.

Specifying the location of the Wrapper data handler

InterChange Server needs to know the location of the Wrapper data handler, so that it can load it at run-time. To specify the location, take the following steps:

  1. Edit the ICS startup script, start_server.bat, which is located in the bin subdirectory of the InterChange Server product directory (on the machine where InterChange Server resides).
  2. To this file, add the jar file for the Wrapper data handler, bcgwbiwrapperdh.jar, to the list of jar files included at ICS startup. Usually, data-handler jar files are added to the DATAHANDLER variable in the ICS startup script.
    Note:
    If you have installed the optional Attachment data handler, you must also add its jar file to the ICS startup script. For more information, see Specifying the location of the Attachment data handler.

Creating the configuration business objects for the Wrapper data handler

To identify the data handler to invoke, Server Access (within InterChange Server) checks the top-level data-handler meta-object, MO_Server_DataHandler. This file is located in the following subdirectory of the InterChange Server product directory:

repository\edk

This top-level meta-object associates a MIME type with a child meta-object, which contains the configuration information for the data handler. Therefore, creating configuration business involves the following steps:

  1. Creating the Wrapper child meta-object

    You must initialize a child meta-object with the Wrapper data handler's configuration information.

  2. Editing the MO_Server_DataHandler meta-object

    You must create an entry in this meta-object that associates a MIME type with the name of the Wrapper data handler's child meta-object.

Creating the Wrapper child meta-object

To configure the Wrapper data handler, you must create its child meta-object and initialize it with configuration information. The data handler uses the attributes of this meta-object to obtain its configuration information, including the name of the data-handler class to instantiate. To create this meta-object, you create a business object definition that contains the attributes listed in Table 51.

Note:
Use Business Object Designer to create this business object definition.

Table 51. Configuration properties in the Wrapper child meta-object

Attribute Description
ClassName

Class name (required), which points to the following data handler class:

com.ibm.bcg.integration.wbi.datahandlers.
WBICWrapperDataHandler
TopBOPrefix Prefix is used to determine the name of the top-level business object. If the request business object returned by the data handler configured for the request does not have the wbic_mainboname tag in its business-object-level application-specific information, the name of the top-level object is obtained by adding the TopBOPrefix to the name of the request business object.
wbic_request_mime

MIME type supported by the data handler that the Wrapper data handler invokes to process the payload of the request message. Make sure that this data handler has been configured so that it can be invoked by the WebSphere InterChange Server Access. For more information, see Editing the MO_Server_DataHandler meta-object.

Note:
If your documents contain attachments, the MIME type for this configuration property should be the MIME type that invokes the Attachment data handler. For more information, see Handling documents with attachments.
wbic_response_mime

MIME type of the data handler that the Wrapper data handler will invoke to process the payload of the response message.

Note:
You do not have to set the wbic_response_mime if Business Integration Connect is not expecting a response.
Important:
To assign a value to the attributes in Table 51., set the default value of the attribute. For example, if the Wrapper data handler is to use the Delimited data handler for its request message, set the Default Value of the wbic_request_mime attribute to text/delimited.

You can define a child meta-object for each instance of the Wrapper data handler that you need to use. For example, if you need to support only one request MIME type or one combination of request and response MIME types, you can create a single child meta-object and set the default values of the wbic_request_mime and wbic_response_mime attributes accordingly. If, however, you need to support different combinations of request and response MIME types, you can create one child meta-object for each of the supported combinations.

Business Integration Connect provides the following InterChange Server repository file, which contains a sample child meta-object for the Wrapper data handler:

ProductDir/Integration/WBI/WICS/WBICServlet/MO_DataHandler_WBICWrapper.in

where ProductDir is the directory of your installed Business Integration Connect product. This repository file defines a single instance of the Wrapper data handler, which is configured to call the Delimited data handler for both request and response business objects. Figure 11 shows the sample child meta-object called MO_DataHandler_WBICWrapper.

Figure 11. Sample child meta-object for a Wrapper data handler


If you also needed to support a document whose request message was in XML, you would create a second child meta-object to represent a second instance of the Wrapper data handler. In this child meta-object, the default value of the wbic_request_mime attribute would have the MIME type of text/xml.

Editing the MO_Server_DataHandler meta-object

WebSphere InterChange Server Access uses a top-level meta-object, called MO_Server_DataHandler, to associate MIME types that access clients can handle with the data handlers that provide the support for these MIME types. Specifically, this top-level meta-object associates MIME types with data-handler child meta-objects.

The MO_Server_DataHandler meta-object is a business object definition. Therefore, to edit this meta-object, bring up the MO_Server_DataHandler in Business Object Designer and add to it a new attribute for each supported instance of the Wrapper data handler. Each instance of this data handler is a unique combination of request and response MIME types.

To the MO_Server_DataHandler meta-object, you make the following modifications:

For example, suppose you have the Wrapper data handler as configured in Figure 11.. Figure 12 shows the MO_Server_DataHandler meta-object with an attribute that associates the wbic_wrapper MIME type with the instance of the Wrapper data handler that is configured by the MO_DataHandler_WBICWrapper child meta-object. This MO_Server_DataHandler meta-object also associates the request and response MIME types (text/delimited) with the Delimited data handler's child meta-object.

Figure 12. Associating the wbic_wrapper MIME type with the Wrapper data handler


For each unique combination of request and response MIME type that you need to support, repeat this process by adding an attribute in the MO_Server_DataHandler top-level meta-object whose attribute name is the MIME type associated with the Wrapper data handler instance and whose type is the name of the associated child meta-object. Also ensure that the configured request and response MIME types (and their child meta-objects) exist in MO_Server_DataHandler.

Note:
If you are using the Attachment data handler to process attachments in your Business Integration Connect documents, you must also modify the MO_Server_DataHandler to support the Attachment data handler, as described in Configuring the Attachment data handler.

Creating business object definitions for sending documents

The WebSphere Business Integration Connect Servlet sends your document to InterChange Server in the form of a payload business object. For the Connect Servlet, the payload business object is represented as a hierarchy of business objects. The Wrapper data handler creates this business-object hierarchy when it receives a Business Integration Connect document. Therefore, you must create business object definitions to represent this hierarchy.

Because the Connect Servlet participants only in event notification with InterChange Server, the request and response attributes of the top-level business object are interpreted as shown in Table 52.

Table 52. Request and response business objects in event notification

Attribute Use
Request business object Contains the request message from Business Integration Connect; this message is the event that triggers the collaboration.
Response business object Contains the response message, if the interaction is synchronous.

For more information on how to create this business-object structure, see Creating business object definitions for pre-4.2.2 ICS over HTTP.

Receiving documents from pre-4.2.2 ICS through HTTP

This section provides the following information to describe how to receive documents from Business Integration Connect from a pre-4.2.2 InterChange Server over the HTTP transport protocol:

The document that Business Integration Connect receives from InterChange Server as been initiated by request processing within InterChange Server.

Components required for receiving

Business Integration Connect can receive documents from the following pre-4.2.2 versions of InterChange Server over the HTTP transport protocol:

For Business Integration Connect to receive a document from pre-4.2.2 InterChange Server using the HTTP transport protocol requires that these two components be configured. Table 45 summarizes these configuration steps. In addition, to receive a document from InterChange Server over the HTTP protocol, you use the ICS-compatible components listed in Table 53..

Table 53. Components required to receive documents to pre-4.2.2 InterChange Server through HTTP

Component Description Notes and restrictions

WebSphere Business Integration Adapter for XML

(Adapter for XML)

This adapter his adapter allows InterChange Server to exchange business objects with applications that receive data in the form of HTTP messages. The Adapter for XML and Business Integration Connect communicate through a URL address.

The Adapter for XML is not shipped with Business Integration Connect. You must use version 3.1.x or higher of this adapter.

Note:
The adapter can only be used with version 4.2.2 WebSphere InterChange Server.
The HTTP or HTTPS protocol handler

This protocol handler works with the Adapter for XML to send information stream to and receive them from the URL.

This protocol handler is provided with Business Integration Connect. For more information, see Deploying the HTTP protocol handler.
A payload data handler This data handler converts the document payload between its document format (usually XML) and its business-object representation. This data handler is required and must support the MIME type of your payload document.
Attachment data handler This data handler converts documents that contain attachments between their document format and their business-object representation. This data handler is required only if your documents include attachments. For more information, see Handling documents with attachments.

Figure 13 provides an overview of how Business Integration Connect receives documents from a pre-4.2.2 InterChange Server over the HTTP transport protocol.

Note:
All references to the HTTP protocol handler apply to the HTTPS protocol handler as well.

Figure 13. Message flow from a collaboration to Business Integration Connect through the HTTP transport protocol


The following steps describe how Business Integration Connect participates in request processing by receiving a document initiated by a collaboration within InterChange Server:

  1. The collaboration within InterChange Server makes a service call to the Adapter for XML, sending it a top-level business object that includes request and response child objects.

    The request child object contains application-specific information pointing to a dynamic meta-object that contains the custom HTTP headers, which Business Integration Connect expects.

  2. The Adapter for XML invokes the HTTP protocol handler.
  3. The HTTP protocol handler uses a data handler to convert the business object that the collaboration has sent into an HTTP stream.

    The protocol handler reads the MIME type and URL from the top-level business object to determine the data handler to use and the address of the recipient.

  4. From the top-level business object, the HTTP protocol handler obtains the first populated business object. This is the request business object.

    The HTTP protocol handler calls the data handler to convert the business object to an HTTP stream.

    Note:
    If your documents have attachments, install the Attachment data handler and then configure the Adapter for XML to call it to convert the require business object to a document with attachments. For more information, see Handling documents with attachments.
  5. The HTTP protocol handler determines, from the request business object, the name of the dynamic meta-object.

    The HTTP protocol handler searches the application-specific information of the request business object for the cw_mo_conn tag, which identifies the attribute that corresponds to the dynamic meta-object. If you are using Backend Integration packaging for your documents, you can specify the custom HTTP header information in this dynamic meta-object.

  6. The HTTP protocol handler searches the dynamic meta-object for the HTTPProperties attribute.

    If this attribute is populated, the protocol handler sets the transport-level headers in the request message. Within the HTTPProperties attribute, you can also specify the content-type standard HTTP header. For more information, see Creating HTTP transport-level header information for v4.2.2 ICS.

  7. The HTTP protocol handler creates an HTTP stream, using the string returned by the data handler. It also sets any custom header information, as defined in the dynamic meta-object.
  8. The HTTP protocol handler sends the resulting request message as a stream to the specified URL.

    Business Integration Connect listens on this URL, which is configured as its target.

  9. Business Integration Connect responds with an HTTP 200 OK.

    If the ReturnBusObjResponse connector property (of the Adapter for XML) is true, the invocation is synchronous. The protocol handler converts the response message into a response business object and returns it to the Adapter for XML. The adapter sets the business object in the top-level business object. The top-level business object is then returned to the collaboration within InterChange Server.

Setting up the environment for HTTP with pre-4.2.2 ICS

Because the receiving of documents from InterChange Server involves the use of ICS-compatible components, you must perform the setup and configuration tasks described in Table 54.. For information on how to configure Business Integration Connect for communication with a pre-4.2.2 InterChange Server over HTTP, see Providing support for outgoing documents.

Table 54. Setting up the environment for sending documents

Step For more information

1. Deploy the HTTP protocol handler.

Deploying the HTTP protocol handler

2. Configure the WebSphere Business Integration Adapter for XML.

Configuring the Adapter for XML

Note:
If your documents contain attachments, you must also install and configure the Attachment data handler, as described in Handling documents with attachments.

Deploying the HTTP protocol handler

Business Integration Connect provides a custom HTTP protocol handler to send and receive messages to Business Integration Connect. This HTTP protocol handler is available on the Business Integration Connect installation medium in the following file:

Integration/WBI/WICS/WBICServlet/bcgwbiprotocol.jar

This custom protocol handler can be plugged into the Adapter for XML version 3.1.x or higher. For a list of supported InterChange Server versions and platforms, refer to the Adapter for XML User Guide for the version of the adapter you are using.

To deploy the HTTP protocol handler to the Adapter for XML, you must let the Adapter for XML know the location of the HTTP protocol handler, so that it can load it at run-time. To specify the location of the HTTP protocol handler, follow these steps:

  1. Edit the startup script for the Adapter for XML, start_xml.bat, which is located in the following subdirectory of the product directory in which your WebSphere Business Integration Adapters are installed:
    connectors/xml
    
  2. In this startup script, add the jar file for the custom HTTP protocol handler, bcgwbiprotocol.jar, to the list of jar files in the CLASSPATH of the Adapter for XML.

Configuring the Adapter for XML

The Adapter for XML is the ICS-compatible component that allows Business Integration Connect to exchange documents with InterChange Server in the form of HTTP messages. It supports the request processing interaction with InterChange Server as follows:

Note:
The event notification feature of this adapter is not used. To send HTTP messages from Business Integration Connect to InterChange Server, use the WebSphere Business Integration Connect Servlet, as described in Sending documents to pre-4.2.2 ICS through HTTP
Important:
WebSphere Business Integration Connect does not include the WebSphere Business Integration Adapter for XML. You must obtain this product separately and install it according to the instructions in its Adapter for XML User Guide. Refer to the adapter documentation to ensure that the version of the adapter is compatible with the version of InterChange Server you are using.

When you have configured the Adapter for XML to communicate with InterChange Server, follow the steps in these sections to configure this adapter to accept HTTP messages from Business Integration Connect.

Specifying the payload data handler

As Figure 13 shows, the Adapter for XML's protocol handler uses a data handler to convert into the appropriate HTTP streams the business objects it receives from InterChange Server.

Note:
The data handler that the Adapter for HTTP calls converts the payload of the document. If your document is wrapped in an XML transport envelope (it contains attachments or the Envelope Flag is Yes), configure the Attachment data handler as the payload data handler. For more information, see Handling documents with attachments.

To indicate which data handler to use to convert the payload, you must take the steps listed in Business object conversion. In addition, you must configure the Adapter for XML to use this payload data handler. In Connector Configurator, set the DataHandlerConfigMO connector configuration property to specify the top-level data-handler meta-object that the Adapter for XML uses to identify data handlers. Make sure you include the name of the top-level data-handler meta-object in the list of supported business objects for the adapter.

Configuring the protocol-handler package name

The Adapter for XML uses the JavaProtocolHandlerPkgs connector configuration property to identify the name of the Java Protocol Handler packages. For integration with Business Integration Connect, make sure that the JavaProtocolHandlerPkgs property is set to the package name for the Business Integration Connect-provided HTTP protocol handler:

com.ibm.bcg.integration.wbi.utils.protocolhandlers

Specifying support for a response business object

The Adapter for XML uses the ReturnBusObjResponse connector configuration property to indicate whether to return a response business object. A response business object is returns only if the interaction is synchronous. By default, the ReturnBusObjResponse connector configuration property is set to false. To configure the Adapter for XML to return a response business object, set the ReturnBusObjResponse connector configuration property to true.

Note:
If Business Integration Connect supports synchronous interactions for the packaging and business protocol that the Community Manager is using, set the ReturnBusObjResponse connector configuration property to true and provide the response business object in your top-level business object.

To set connector configuration properties, use the Connector Configurator tool, which is included as part of the release for your WebSphere Business Integration Adapter for XML. Within Connector Configurator, the ReturnBusObjResponse property should appear in the Connector-specific tab of the connector properties.

Creating business object definitions for receiving documents

The WebSphere Business Integration Adapter for XML receives information from InterChange Server in the form of a payload business object. For the Adapter for XML, the payload business object is represented as a hierarchy of business objects. The Adapter for XML creates this business-object hierarchy when it receives a Business Integration Connect document. Therefore, you must create business object definitions to represent this hierarchy.

Because the Adapter for XML participants only in request processing with InterChange Server, the request and response attributes of the top-level business object are interpreted as shown in Table 55.

Table 55. Request and response business objects in request processing

Attribute Use
Request business object Contains the request information from InterChange Server; the protocol handler and the data handler convert and send this information to the URL on which Business Integration Connect listens.
Response business object Contains the response information from Business Integration Connect, if the interaction is synchronous.

For more information on how to create this business-object structure, see Creating business object definitions for pre-4.2.2 ICS over HTTP.

Creating business object definitions for pre-4.2.2 ICS over HTTP

The Connect Servlet sends your document to InterChange Server in the form of a payload business object. The Adapter for XML receives your message from InterChange Server in this same form. Both these components invoke the payload data handler to handle this business object when it receives or sends a Business Integration Connect document, as follows:

Therefore, you must create the business object definitions shown in Table 56. to represent the payload business-object structure that the Adapter for XML and Connect Servlet expect.

Table 56. Business object definitions for HTTP transport protocol

Condition Business object definition For more information
If you are using either None or Backend Integration packaging for your document and your documents do not have attachments

Hierarchy of business objects for the payload business object:

  • Top-level business object
  • Request business object
  • Response business object (only if a response is expected)

Creating the payload business-object structure for pre-4.2.2 ICS over HTTP
If you are using Backend Integration packaging for your document

Add to the payload business object the business objects to hold the transport-level header information:

  • Dynamic meta-object
  • HTTP-properties business object

Creating HTTP transport-level header information for pre-4.2.2 InterChange Server
If the document includes attachments (Backend Integration packaging is required) You must also create additional business objects to represent the attachments. Creating attachment-related business object definitions

Note:
If you are defining business objects for cXML documents, see Creating business objects for cXML.

Creating the payload business-object structure for pre-4.2.2 ICS over HTTP

Both the Wrapper data handler (for sending documents), as well as the Adapter for XML and the HTTP protocol handler (for receiving documents) expect the same business-object structure for the payload business object. This business-object structure consists of the following business objects:

Figure 14 shows a sample business-object structure for the payload business object definition for use with a pre-4.2.2 InterChange Server over the HTTP transport protocol.

Note:
For a detailed description of this business-object structure, refer to the Adapter for XML User Guide.

Figure 14. Business-object structure for the HTTP payload business object for pre-4.2.2 InterChange Server


Top-level business object

The top-level business object is a wrapper for the request and response business objects. You must create a business object definition for this business object. Table 57 summarizes the attributes of this top-level business object definition.

Table 57. Attributes of the top-level business object

Attribute Attribute type Description
URL String

Destination of the data in the business object.

Important:
This attribute is not used by the Wrapper data handler. However, it is used by the Adapter for XML.
MimeType String

Defines the content type and format of the data that is being passed to the URL.

Important:
This attribute is not used by the Wrapper data handler. However, it is used by the Adapter for XML
BOPrefix String

Used to determine which data handler to call.

Important:
This attribute is not used by the Wrapper data handler.
Response Business object Child business object that represents the response message (if you are expecting a response). The purpose of this business object depends on whether it participates in request processing or event notification. For more information on the structure of this business object, see Response business object.
Request Business object Child business object that represents the request message. The purpose of this business object depends on whether it participates in request processing or event notification. For more information on the structure of this business object, see Request business object.
Note:
If you are using the Attachment data handler to process attachments, you must modify your request business object to hold the attachments, as described in Creating attachment-related business object definitions.

For a complete description of the structure of the top-level business object, see the Adapter for XML User Guide.

Request business object

The request business object contains the data to be passed to the URL. It contains attributes for the various XML tags in the request message. The purpose of this request business object depends on which InterChange Server task it is participating in, as follows:

Note:
This business-object structure identifies its two child business objects as its request and response business objects. However, this structure is used in both request processing and event notification,

For the basic description of the request business object's structure, refer to the Adapter for XML User Guide. For use with Business Integration Connect, there are two customizations you must make to the structure of the request business object definition:


Table 58. Tags in application-specific information of request business object

Application-specific-information tag Description Required?
wbic_mainboname Gives the name of the top-level business object Yes
cw_mo_conn Specifies the dynamic meta-object, which contains the HTTP transport-level header fields. For more information, see Creating HTTP transport-level header information for pre-4.2.2 InterChange Server. No (only required if you are using Backend Integration packaging)

Response business object

The response business object contains the data to be received from the URL. It contains attributes for the various XML tags in the response message. The purpose of this response business object depends on which InterChange Server task it is participating in, as follows:

Regardless of whether the response is part of event notification or request processing, a response business object is sent only if the exchange between Business Integration Connect and InterChange Server is synchronous nd a business response is expected in response to your request. If this is the case, you must take the following additional steps:

Note:
The response business object does not include an attribute for the dynamic meta-object.

If the exchange between Business Integration Connect and InterChange Server is asynchronous, Business Integration Connect does not expect a response, so you do not need to create a response business object.

Creating business objects for cXML

For cXML documents, you can use the XML Object Discovery Agent (ODA) to create the business objects. The XML ODA can consume the cXML DTD. Note, however, that the XML ODA does not support ENTITY. Therefore, before running the cXML DTD with the XML ODA, you need to remove ENTITY from the DTD.

When generating business objects using the XML ODA, you can select the cXML tag as your root element. This might result in a large business object, capturing the entire cXML DTD, however. If you want to create a smaller business object, you can select a different tag as your root element, which will require that you write a custom name handler for the Data Handler for XML. The data handler will invoke this name handler for the top-level business object name resolution. Refer to the Data Handler for XML documentation for information on writing custom name handlers.

Creating HTTP transport-level header information for pre-4.2.2 InterChange Server

If you are sending documents with Backend Integration packaging over the HTTP transport protocol, your request business object needs to contain custom transport-level header information. Both the Wrapper data handler and the Adapter for XML expect this custom header information to be in a dynamic meta-object.

Figure 15 shows the business-object structure for a request business object that represents a Business Integration Connect document with Backend Integration packaging over the HTTP transport protocol.

Figure 15. Relationship of the request business object to the HTTP dynamic meta-object


Make sure your business-object structure includes a dynamic meta-object by taking the following steps:

  1. Create a business object definition to hold the HTTP properties required by the Backend Integration packaging.
  2. Create a business object definition for the dynamic meta-object.
  3. Modify the business object definition for your request business object to include an attribute for the dynamic meta-object.

Each of these steps is described in the sections below.

Creating the HTTP-properties business object

An HTTP-properties business object contains HTTP properties required by the Backend Integration packaging. It can also contain the Content-Type attribute, which specifies the content-type header to set in the request message, and the content-length attribute, which specifies the length of the message, in bytes. Table 4 describes each of the valid transport-header fields.

To create an HTTP-properties business object definition, take the following steps:

  1. Create an attribute within the business object definition for each of the transport-header fields.

    All attributes should have an attribute type of String. You can name the attribute with the exact name of the HTTP property (as listed in the Header field column of Table 4).

    Note:
    The only exception to the HTTP property names is that the content-type field should have an attribute named Content_Type.
  2. For each of the attributes in the HTTP-properties business object, add application-specific information to identify the purpose of the associated attribute.

    This attribute-level application-specific information has the following format:

    name=HTTPproperty
    

    where HTTPproperty is one of the values in the Header field column of Table 4.

In Figure 15, the HttpProps_BusObj business object definition contains attributes for the various transport-header fields. These attributes all have attribute-level application-specific information to specify the name of the related protocol header. For example, the x-aux-sender-id attribute has the application-specific information set as follows:

name=x-aux-sender-id

Creating the HTTP dynamic meta-object

The dynamic meta-object contains a child business object with configuration information for the HTTP header information. You must make sure that your business-object structure includes a dynamic meta-object. The business object definition for the dynamic meta-object must include an attribute named HttpProperties, whose attribute type is the business object definition for the HTTP-properties business object (see Creating the HTTP-properties business object).

For example, in Figure 15, the HttpDynMO_BusObj business object definition contains attributes the HttpProperties attribute, whose attribute type is HttpProps_BusObj.

Modifying the request business object definition

The request business object definition represents the information being requested from Business Integration Connect. For information on how to create the request business object, see Request business object. To incorporate the dynamic meta-object into your payload business-object structure, you must make the following modifications to your request business object definition:

  1. Add an attribute to your request business object definition to hold your dynamic child meta-object.

    The attribute type for this attribute is the business object definition for the dynamic meta-object (see Creating the HTTP dynamic meta-object).

  2. Add the cw_mo_conn tag to the business-object-level application-specific information of your request business object definition to identify the attribute that contains the dynamic meta-object.

    The cw_mo_conn tag has the following format:

    cw_mo_conn=dynamicMetaObjAttr
    

    where dynamicMetaObjAttr is the name of the attribute in the request business object that holds the dynamic meta-object.

For example, in Figure 15, an attribute named HttpDynMO has been added to the request business object definition, WBIC_HttpRequest_BusObj. This attribute contains the dynamic meta-object, which is a child business object of type HttpDynMO_BusObj. In addition, the application-specific information of the request business object has been modified to include the following cw_mo_conn tag to identify this dynamic meta-object:

cw_mo_conn=HttpDynMO

Creating pre-4.2.2 ICS artifacts for HTTP

To configure a pre-4.2.2 InterChange Server for communication withBusiness Integration Connect over the HTTP transport protocol, you must create the InterChange Server artifacts shown in Table 59.

Table 59. Artifacts for communicating with pre-4.2.2 ICS over the HTTP transport protocol

ICS artifact Purpose For more information
Business object definitions Represent the document Creating business object definitions for pre-4.2.2 ICS over HTTP
Connector object (needed for request processing only) Represent the Adapter for XML at run-time Creating the XML connector object
Collaboration template and collaboration object Represents the business process that InterChange Server uses to process the document Binding collaborations to communicate with Adapter for XML

Creating the XML connector object

To support request processing with pre-4.2.2 InterChange Server over HTTP transport protocol, you use the Adapter for XML to send a document to InterChange Server. To obtain an instance of the Adapter for XML at run-time, take the following steps within System Manager:

  1. Create the connector objects:
  2. Configure the connector objects.

    For information on how to configure your Adapter for XML for use with Business Integration Connect, see Configuring the Adapter for XML.

Binding collaborations to communicate with Adapter for XML

As described in Creating the collaborations, a collaboration object must exist at run-time for InterChange Server to know where to receive and send business objects. When you create the collaboration object for the collaboration that sends information to Business Integration Connect, you bind its ports. For request processing, set the "to" collaboration port, which uses the Adapter for XML to send requests to Business Integration Connect, to the connector object you created for the Adapter for XMP; that is, the Adapter for XMP is the destination adapter.

Copyright IBM Corp. 2003, 2004