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:
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:
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.
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
Figure 9 provides an overview of how Business Integration Connect sends documents to a pre-4.2.2 ICS over 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:
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:
Business Integration Connect sends the document to the URL specified as the target gateway.
The HTTP request message contains two parts:
Each URL corresponds to a collaboration to be invoked. (See Configuring the Connect Servlet for information.)
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.
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.
Set the HTTP headers in the HTTP-properties business object, which is a child of the dynamic meta-object of this payload 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.
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.
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.
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.
Configuration of the Connect Servlet involves the following steps:
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
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:
These files can be found in the lib subdirectory of the InterChange Server product directory.
Notes:
These files can be found on the Business Integration Connect installation medium in the following directory:
integration/wbi/wics/http/lib/thirdparty
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:
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:
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.
| 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 |
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:
It specifies an integer number of URLs configured in this file:
The associated collaboration properties have property names of the form WBIC_URL_count_propertyName. Table 50 defines these a sample of these WBIC_URL_count_propertyName properties. In the Example column, this table provides sample values of the WBIC_URL_count_propertyName properties for the first collaboration URL (count is 1).
Table 50. Collaboration properties of the servlet properties file
Property name | Description | Example |
---|---|---|
WBIC_SERVLET_COUNT |
The number of URLs configured in this file:
| 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 |
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:
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
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.
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
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.
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:
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:
You must initialize a child meta-object with the Wrapper data handler's configuration information.
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.
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.
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.
|
wbic_response_mime |
MIME type of the data handler that the Wrapper data handler will invoke to process the payload of the response message.
|
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.
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:
The attribute type of this attribute is the business object definition for the Wrapper data handler's child meta-object (see Creating the Wrapper child meta-object).
The attribute type of these attributes would be the child meta-object of the associated data handler.
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.
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
For more information on how to create this business-object structure, see Creating business object definitions for pre-4.2.2 ICS over 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.
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.
|
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.
The following steps describe how Business Integration Connect participates in request processing by receiving a document initiated by a collaboration within InterChange Server:
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.
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.
The HTTP protocol handler calls the data handler to convert the business object to an HTTP stream.
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.
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.
Business Integration Connect listens on this URL, which is configured as its target.
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.
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 |
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:
connectors/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:
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.
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.
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.
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
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.
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.
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
For more information on how to create this business-object structure, see 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:
| 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:
| 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 |
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.
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.
|
MimeType | String |
Defines the content type and format of the data that is being passed to the URL.
|
BOPrefix | String |
Used to determine which data handler to call.
|
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. |
For a complete description of the structure of the top-level business object, see the Adapter for XML User Guide.
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:
For more information, see Creating business object definitions for sending documents.
For more information, see Creating business object definitions for receiving documents.
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:
This attribute provides configuration information for the headers of the message. For more information, see Creating HTTP transport-level header information for pre-4.2.2 InterChange Server.
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) |
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:
This tag has the following syntax:
wbic_type=reply
If this tag is not specified, the Wrapper data handler uses the child meta-object indicated by the wbic_response_mime attribute (in the top-level business object) to determine the data handler to use for the response.
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.
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.
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:
Each of these steps is described in the sections below.
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:
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).
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
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.
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:
The attribute type for this attribute is the business object definition for the dynamic meta-object (see Creating the HTTP 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
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 |
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:
For information on how to configure your Adapter for XML for use with Business Integration Connect, see Configuring the 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.