Using HTTP transport protocol with ICS

WebSphere Partner Gateway can send and receive documents with WebSphere InterChange Server (ICS) over the HTTP transport protocol

Note: 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 InterChange Server and the appropriate adapters for use with WebSphere Partner Gateway over HTTP:

Components required for documents to ICS over HTTP transport

For WebSphere Partner Gateway to communicate with InterChange Server using the HTTP transport protocol requires that these two components be configured. Table 41 summarizes these configuration steps.

Table 41. Configuring WebSphere Partner Gateway and InterChange Server
Component Version For more information
WebSphere Partner Gateway 6.0

Configuration for sending documents to ICS over the HTTP transport protocol

Configuration for receiving documents from ICS over the HTTP transport protocol

WebSphere InterChange Server 4.2.2 or higher Creating ICS artifacts for HTTP

In addition, to send or receive a document between WebSphere Partner Gateway and InterChange Server using the HTTP transport protocol, you use the components listed in Table 42.

Table 42. Components required to transfer documents with 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.

Use version 4.2.1 of the Adapter for HTTP.
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 42 work together to send and receive documents between WebSphere Partner Gateway and InterChange Server over the HTTP transport protocol.

How documents are sent to ICS through HTTP

For WebSphere Partner Gateway to send a document to InterChange Server using the HTTP transport protocol, you use the Adapter for HTTP to retrieve the document that WebSphere Partner Gateway has sent as an HTTP stream. The adapter then routes the document to InterChange Server. Figure 18 provides an overview of how WebSphere Partner Gateway sends documents to InterChange Server over the HTTP transport protocol.

Figure 18. Message flow from WebSphere Partner Gateway to a collaboration through the HTTP transport protocol
This figure shows how a document is sent to WebSphere Partner Gateway, how WebSphere Partner Gateway sends the HTTP request message to the Adapter for HTTP, how the Adapter for HTTP calls the payload data handler, and how the Adapter for HTTP sends the resulting business object to a collaboration.

How documents are received from ICS through HTTP

For WebSphere Partner Gateway to receive a document from 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 WebSphere Partner Gateway to retrieve. Figure 19 provides an overview of how WebSphere Partner Gateway receives documents from InterChange Server over the HTTP transport protocol.

Figure 19. Message flow from a collaboration to WebSphere Partner Gateway through the HTTP transport protocol
This figure shows how a business object is sent from a collaboration to the Adapter for HTTP, how the Adapter for HTTP calls the payload data handler, and how the Adapter for HTTP sends the resulting HTTP stream to WebSphere Partner Gateway.

Setting up the environment for HTTP transport with ICS

Because the sending and receiving of documents to and from InterChange Server involves adapters and data handlers, you must perform the setup and configuration tasks on the Adapter for HTTP. For information on how to configure WebSphere Partner Gateway for use with InterChange Server over HTTP, see Configuring WebSphere Partner Gateway for InterChange Server.

The Adapter for HTTP allows WebSphere Partner Gateway to exchange documents with InterChange Server in the form of HTTP messages. It supports the following interactions with InterChange Server:

Important: WebSphere Partner Gateway 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 to listen for HTTP messages from WebSphere Partner Gateway:

Specifying the payload data handler

As Figure 19 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 WebSphere Partner Gateway, 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 43.

    Table 43. 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 computer on which WebSphere Partner Gateway 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 WebSphere Partner Gateway specifies as its Target URI. For more information, see Configuration for sending documents to ICS over the 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 44. 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 44. 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 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 WebSphere Partner Gateway document, as follows:

Therefore, you must create the business object definitions shown in Table 45 to represent the payload business-object structure that the Adapter for HTTP expects.

Table 45. 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 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 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 ICS over HTTP

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

Figure 20 shows a sample business-object structure for a payload business object definition for use with 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 20. Business-object structure for the HTTP payload business object for ICS
This figure shows a top-level business object pointing to a request business object and a response business object.
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 46 summarizes the attributes of the top-level business object definition.

Table 46. 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 WebSphere Partner Gateway, you do not need to include fault business objects in your top-level business object.

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

Table 47. 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 WebSphere Partner Gateway, there are two customizations you must make to the structure of the request business object definition:

Table 48. 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 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 WebSphere Partner Gateway 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 WebSphere Partner Gateway, there are customizations you must make to the structure of the request business object definition:

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

Creating HTTP transport-level header information for 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 21 shows the business-object structure for a request business object that represents a WebSphere Partner Gateway document with Backend Integration packaging over the HTTP transport protocol.

Figure 21. Relationship of the request business object to the HTTP protocol-configuration meta-object
This figure shows a request business object pointing to a business object of type HttpConfigMO_BusObj, which itself points to a business object of type HttpProps_BusObj, representing the transport-level headers.

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. WebSphere Partner Gateway 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 5 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 5).

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

In Figure 21, 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 WebSphere Partner Gateway, 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 21, the HttpConfigMO_BusObj business object definition contains 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 WebSphere Partner Gateway. 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 21, an attribute named HttpConfigMO has been added to the request business object definition, hub_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 ICS artifacts for HTTP

To configure InterChange Server for communication with WebSphere Partner Gateway over the HTTP transport protocol, you must create the InterChange Server artifacts shown in Table 49.

Table 49. Artifacts for communicating with ICS over the HTTP transport protocol
ICS artifact Purpose For more information
Business object definitions Represent the document Creating business object definitions for 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 WebSphere Partner Gateway, see Setting up the environment for HTTP transport with 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 WebSphere Partner Gateway, you bind the collaboration ports, as follows:

Copyright IBM Corp. 2003, 2005