WebSphere Partner Gateway can send and receive documents with WebSphere InterChange Server (ICS) over the HTTP transport protocol
This section provides the following information on how to configure InterChange Server and the appropriate adapters for use with WebSphere Partner Gateway over HTTP:
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.
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.
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.
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.
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.
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:
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:
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.
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:
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
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:
ProtocolListenerFramework ProtocolListeners HttpListener1
To configure your protocol listener, set the subproperties listed in Table 43.
Property | Description | Value |
---|---|---|
Protocol |
Type of protocol listener:
|
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 |
ProtocolListenerFramework ProtocolListeners HttpListener1 URLsConfiguration URL1
Set the ContextPath property to the URI for the HTTP requests that the protocol listener receives.
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.
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.
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.
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:
|
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:
|
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 |
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.
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.
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. |
Table 47 summarizes the application-specific information that the top-level business object definition can have.
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 objectThe 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:
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:
This attribute provides configuration information for the transport-level headers of the message. For more information, see Creating HTTP transport-level header information for ICS.
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 |
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:
This attribute provides configuration information for the transport-level headers of the message. For more information, see Creating HTTP transport-level header information for ICS.
This tag has the following syntax:
ws_botype=response
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.
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.
Make sure your business-object structure includes an HTTP protocol-configuration meta-object by taking the following steps:
Each of these steps is described in the sections below.
Creating the user-defined-properties business objectThe 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:
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).
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-idCreating 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:
All attributes should have an attribute type of String.
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 definitionThe 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:
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).
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
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.
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 |
To obtain an instance of the Adapter for HTTP at run-time, you must take the following steps within System Manager:
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.
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: