Using HTTP transport protocol with v4.2.2 ICS

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

Notes:

  1. To send and receive documents between WebSphere Business Integration Connect and a pre-4.2.2 WebSphere InterChange Server over the HTTP transport protocol, see Using HTTP transport protocol with pre-4.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 v4.2.2 InterChange Server and the appropriate ICS-compatible components for use with Business Integration Connect over HTTP:

Components required for documents to v4.2.2 ICS over HTTP transport

For Business Integration Connect to communicate with a v4.2.2 of InterChange Server using the HTTP transport protocol requires that these two components be configured. Table 60 summarizes these configuration steps.

Table 60. 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.2.2 Creating v4.2.2 ICS artifacts for HTTP

In addition, to send or receive a document between Business Integration Connect and a v4.2.2 of InterChange Server using the HTTP transport protocol, you use the ICS-compatible components listed in Table 61.

Table 61. Components required to transfer documents with v4.2.2 InterChange Server through HTTP

Component Description Notes and restrictions

WebSphere Business Integration Adapter for HTTP

(Adapter for HTTP)

This adapter allows InterChange Server to exchange business objects with applications that send or receive data in the form of HTTP streams.

This adapter cannot be used with WebSphere InterChange Server before version 4.2.2.

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.

The following sections describe how the components in Table 61 work together to send and receive documents between Business Integration Connect and v4.2.2 InterChange Server over the HTTP transport protocol.

Sending documents to v4.2.2 ICS through HTTP

For Business Integration Connect to send a document to v4.2.2 InterChange Server using the HTTP transport protocol, you use the Adapter for HTTP to retrieve the document that Business Integration Connect has sent as an HTTP stream. The adapter then routes the document to InterChange Server. Figure 16 provides an overview of how Business Integration Connect sends documents to v4.2.2 InterChange Server over the HTTP transport protocol.

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


Receiving documents from v4.2.2 ICS through HTTP

For Business Integration Connect to receive a document from v4.2.2 InterChange Server using the HTTP transport protocol, you use the Adapter for HTTP, which sends the message it receives from InterChange Server as an HTTP stream for Business Integration Connect to retrieve. Figure 17 provides an overview of how Business Integration Connect receives documents from v4.2.2 InterChange Server over the HTTP transport protocol.

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


Setting up the environment for HTTP transport with v4.2.2 ICS

Because the sending and receiving of documents to and from InterChange Server involves ICS-compatible components, you must perform the setup and configuration tasks on the Adapter for HTTP. For information on how to configure Business Integration Connect for use with InterChange Server over HTTP, see Configuring Business Integration Connect for InterChange Server.

The Adapter for HTTP is the ICS-compatible component that allows Business Integration Connect to exchange documents with v4.2.2 InterChange Server in the form of HTTP messages. It supports the following interactions with InterChange Server:

Important:
WebSphere Business Integration Connect does not include the WebSphere Business Integration Adapter for HTTP. You must obtain this product separately and install it according to the instructions in its Adapter for HTTP 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 HTTP to communicate with InterChange Server, follow the steps in these sections to configure this adapter for listen for HTTP messages from Business Integration Connect:

Specifying the payload data handler

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

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 HTTP to use this payload data handler. You can set the payload data handler in either of the following ways:

Configuring the protocol-handler package name

The Adapter for HTTP uses the JavaProtocolHandlerPackages connector configuration property to identify the name of the Java Protocol Handler packages. For integration with Business Integration Connect, make sure that the JavaProtocolHandlerPackage property is set to its default value:

com.ibm.net.ssl.internal.www.protocol

Configuring the HTTP protocol listener

The Adapter for HTTP supports hierarchical configuration properties to obtain the information it needs to configure its protocol listeners. The top-level configuration property is called ProtocolListenerFramework. Within this top-level property are several levels of subproperties. To configure the protocol handlers for use with the Adapter for HTTP, make sure that the properties are configured in the ProtocolListener property, as described in the following steps:

  1. Configure a protocol listener with subproperties under the following configuration property:
    ProtocolListenerFramework
       ProtocolListeners
          HttpListener1
    

    To configure your protocol listener, set the subproperties listed in Table 62.

    Table 62. Configuring the protocol listener

    Property Description Value
    Protocol

    Type of protocol listener:

    • HTTP
    • HTTPS

    http or https

    Host IP address on which the protocol listener listens IP address of the local machine on which WebSphere Business Integration Connect is running
    Port Port on which the protocol listener listens for requests 8080
  2. Configure the URL configurations that the protocol listener supports with subproperties under the following configuration property:
    ProtocolListenerFramework
       ProtocolListeners
          HttpListener1
             URLsConfiguration
                URL1
    

    Set the ContextPath property to the URI for the HTTP requests that the protocol listener receives.

    Note:
    This directory must be the same one that the Business Integration Connect gateway specifies as its Target URI. For more information, see Configuring for outgoing documents over HTTP transport protocol.
  3. If your document contains attachments, you must configure a transformation for the protocol listener by setting subproperties of the following configuration property:
    ProtocolListenerFramework
       ProtocolListeners
          HttpListener1
             URLsConfiguration
                URL1
                   TransformationRules
                      TransformationRule1
    

    To configure the attachment transformation for your protocol listener, set the subproperties listed in Table 63. You need one transformation rule for each instance of the Attachment data handler you are using. For more information on the Attachment data handler, see Handling documents with attachments.

    Table 63. Configuring the attachment transformation for the protocol listener

    Property Description Value
    ContentType Content type of the data to be transformed with a data handler Content type associated with the attachment data
    MimeType MIME type to use to identify the data handler to call MIME type associated with the instance of the Attachment data handler
    Charset Character set to use when transforming data of the specified content type Character set for the attachment data

For more information on these properties, see the Adapter for HTTP User Guide.

Creating business object definitions for v4.2.2 ICS over HTTP

The Adapter for HTTP sends and receives your document to InterChange Server in the form of a payload business object. The Adapter for HTTP invokes 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 64 to represent the payload business-object structure that the Adapter for HTTP expects.

Table 64. Business object definitions for the Adapter for HTTP

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

Payload business object:

  • Top-level business object
  • Request business object
  • Response business object (optional)
  • Fault business object (optional)

Creating the payload business-object structure for v4.2.2 ICS over HTTP
If you are using Backend Integration packaging for your message

Add to the payload business object the business objects to hold the message header information:

  • Dynamic meta-object
  • HTTP-properties business object

Creating HTTP transport-level header information for v4.2.2 ICS.
If the document includes attachments You must also create additional business objects to represent the attachments. Creating attachment-related business object definitions

Creating the payload business-object structure for v4.2.2 ICS over HTTP

The Adapter for HTTP expects a payload business-object structure that consists of the following business objects:

Figure 18 shows a sample business-object structure for a payload business object definition for use with a v4.2.2 InterChange Server over the HTTP transport protocol.

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

Figure 18. Business-object structure for the HTTP payload business object for v4.2.2 ICS


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 the top-level business object definition.


Table 65. Attributes of top-level business object

Attribute Attribute type Description
MimeType String

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

Charset String

Used to determine which data handler to call.

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.
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.
Note:
When using the Adapter for HTTP with Business Integration Connect, do not need to include fault business objects in your top-level business object.

Table 66 summarizes the application-specific information that the top-level business object definition can have.

Table 66. Application-specific information for the top-level business object definition

Application-specific information Tag Description
Business-object level ws_mode Defines whether the interaction is synchronous or asynchronous
Attribute level ws_botype Defines which attribute contains the request or response business object

For a complete description of the structure of the top-level business object and its application-specific information, see the Adapter for HTTP User Guide.

Request business object

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

Note:
The top-level business object identifies its 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 HTTP 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 67. Tags in application-specific information of request business object

Application-specific-information tag Description Required?
ws_tloname Gives the name of the top-level business object Only required if business object definition participates in event notification
cw_mo_http Specifies the HTTP protocol-configuration meta-object, which contains the HTTP transport-level header fields. For more information, see Creating HTTP transport-level header information for v4.2.2 ICS. Only required if you are using Backend Integration packaging

Note:
If you are using the Attachment data handler to process documents wrapped in an XML transport envelope, you must modify your request business object to hold the attachments, as described in Creating attachment-related business object definitions.

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 and a business response is expected in response to your request.

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

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 HTTP transport-level header information for v4.2.2 ICS

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. The Adapter for HTTP expects this custom header information to be in a dynamic meta-object.

Figure 19 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 19. Relationship of the request business object to the HTTP protocol-configuration meta-object


Make sure your business-object structure includes an HTTP protocol-configuration 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 HTTP protocol-configuration meta-object.
  3. Modify the business object definition for your request business object to include an attribute for the HTTP protocol-configuration meta-object.

Each of these steps is described in the sections below.

Creating the user-defined-properties business object

The Adapter for HTTP supports a user-defined-properties business object to hold custom properties in the HTTP protocol-configuration meta-object. Business Integration Connect uses this business object to hold 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 a user-defined-properties business object definition for the HTTP header fields, 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).

  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:

    ws_prop_name=HTTPproperty
    

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

In Figure 19, 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:

ws_prop_name=x-aux-sender-id

Creating the HTTP protocol-configuration meta-object

For event notification, the request, response, or fault business object can contain a dynamic meta-object called the HTTP protocol configuration meta-object to hold configuration information (such as header information).

For the basic description of the HTTP protocol-configuration business object's structure, refer to the Adapter for HTTP User Guide. For use with Business Integration Connect, you must make the following customizations to the structure of the HTTP protocol-configuration business object definition:

  1. Create an attribute within the business object definition for any of the fields you require.

    All attributes should have an attribute type of String.

    Note:
    For a complete list of attributes in the HTTP protocol-configuration meta-object, see the Adapter for HTTP User Guide.
  2. Add the UserDefinedProperties attribute to this business object definition.

    The attribute type of this attribute is the business object definition for the user-defined-properties business object (see Creating the user-defined-properties business object).

For example, in Figure 19, the HttpConfigMO_BusObj business object definition contains attributes the UserDefinedProperties attribute, whose attribute type is HttpProps_BusObj.

Modify the request business object definition

The request business object definition represents the information 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 the HTTP protocol-configuration meta-object.

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

  2. Add the cw_mo_http tag to the business-object-level application-specific information of your request business object definition to identify the attribute that contains the HTTP protocol-configuration meta-object.

    The cw_mo_http tag has the following format:

    cw_mo_http=HttpConfigMetaObjAttr
    

    where HttpConfigMetaObjAttr is the name of the attribute in the request business object that holds the HTTP protocol-configuration meta-object.

For example, in Figure 19, an attribute named HttpConfigMO 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 HttpConfigMO_BusObj. In addition, the application-specific information of the request business object has been modified to include the following cw_mo_http tag to identify this dynamic meta-object:

cw_mo_http=HttpConfigMO

Creating v4.2.2 ICS artifacts for HTTP

To configure a v4.2.2 InterChange Server for communication with Business Integration Connect over the HTTP transport protocol, you must create the InterChange Server artifacts shown in Table 68.

Table 68. Artifacts for communicating with v4.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 v4.2.2 ICS over HTTP
Connector object Represents the Adapter for HTTP at run-time Creating the HTTP 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 HTTP

Creating the HTTP connector object

To obtain an instance of the Adapter for HTTP at run-time, you must 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 HTTP connector object for use with Business Integration Connect, see Setting up the environment for HTTP transport with v4.2.2 ICS.

Binding collaborations to communicate with Adapter for HTTP

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 uses the Adapter for HTTP to send information to and receive it from Business Integration Connect, you bind the collaboration ports, as follows:

Copyright IBM Corp. 2003, 2004