Planning the back-end integration

This section provides the following information about how to plan your back-end integration with WebSphere Business Integration Connect:

What business protocol are you using?

The business protocol of your message determines the format of the document format. The business protocol affects many of the decisions you must make as you plan for integration to a back-end system. The choice of business protocol determines the packaging method you must use, which in turn, affect which message-transport protocols you can use.

For a complete description of business protocols, see the Administrator Guide. This section describes integration information that is specific to the following business protocols:

Web Services (SOAP)

Business Integration Connect can make the following Web Services available to members of the hub:

Refer to the Hub Configuration Guide for more information, including how to set up your document flow definitions for Web Services.

cXML

You can send or receive cXML documents to or from your community participants. When Business Integration Connect receives a cXML document from a community participant, it validates the document and translates it (if specified) before sending it to the back-end system at the Community Manager. Note that translation should not be used for synchronous cXML messages. In a synchronous exchange, the back-end system generates a response, which Business Integration Connect returns to the community participant (if appropriate for the message).

A back-end system at the Community Manager that needs to send a cXML document can do one of two things:

Note:
If XML document translation is used, for synchronous request/response transactions with the community participant, the response is returned asynchronously to the back-end system.

Refer to the Administrator Guide for more information, including how to set up your document flow definitions for cXML.

RosettaNet

Business Integration Connect provides support for RosettaNet 1.1 and 2.0, assuming the RosettaNet messages have Backend Integration packaging (that is, they must have transport-level headers.) These messages must use the HTTP or JMS transport protocol. The transport-level header retains meta-information that is not part of the PIP and enables Business Integration Connect to route the message appropriately.

For example, suppose an application wants to send a message to a community participant using RosettaNet sent on HTTP. The application provides the RosettaNet service content and adds the transport-level header. The header identifies which community participant will handle the request, what PIP will be sent, and the version of the PIP along with other information. This information enables Business Integration Connect to send the correct PIP to the community participant.

You can find information about setting up RosettaNet support and configuring PIPS in the Hub Configuration Guide.

Event notification

Because Business Integration Connect separates the application from the community participant that is the RosettaNet service provider, Business Integration Connect provides event notification. Event notification enables Business Integration Connect to, for example, notify the application if Business Integration Connect is unable to send a PIP to the participant. The application can then handle the failure.

An event notification message is an XML document that carries information about events that occurred within Business Integration Connect or an application. These messages have the same structure as any other message that enters or leaves Business Integration Connect; that is, they have transport-level header and payload. Business Integration Connect can be configured to send or not send event notification messages as they are optional.

Table 1 summarizes the event notification messages that Business Integration Connect can send to back-end systems.

Table 1. Event notification messages sent to back-end system

Event condition Event notification message

Business Integration Connect delivers a RosettaNet document to a community participant and receives a Receipt Acknowledgment.

Event 100

Business Integration Connect cancels a PIP by generating an 0A1 message and delivering it to the community participant.

Event 800

Business Integration Connect receives a Receipt Acknowledgment exception or a general exception from a community participant.

Event 900

Business Integration Connect can send 0A1 message to the destination application as it would do with any other PIP, if it has been configured to send these messages using Exclusion List Management. See "Managing Exclusion Lists" in the Administrator Guide.

An application can send a event notification message to Business Integration Connect to cancel a RosettaNet PIP.

Event message structure

An event notification message has the standard transport-level header with the x-aux-process-type field set to XMLEvent. However, the payload of the message has a specific structure, as shown in the sample XML schema in Figure 2.

Figure 2. Sample XML schema for an event notification message

<?xml version="1.0" encoding="UTF-8"?> 
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   targetNamespace=
 "http://www.ibm.com/websphere/bcg/2003/v1.0/xmleventnotification"
   xmlns:evntf=
 "http://www.ibm.com/websphere/bcg/2003/v1.0/xmleventnotification"
   elementFormDefault="qualified">
 <!-- EventNotification version 1.0 document element -->
    <xsd:element name="EventNotification">
       <xsd:complexType>
         <xsd:all>
             <xsd:element ref="evntf:StatusCode"/>
             <xsd:element ref="evntf:StatusMessage"/>
             <xsd:element ref="evntf:EventMessageID"/>
             <xsd:element ref="evntf:BusinessObjectID"/>
             <xsd:element ref="evntf:GlobalMessageID"/>
             <xsd:element ref="evntf:Timestamp"/>
          </xsd:all>
       </xsd:complexType>
    </xsd:element>
<!-- StatusCode element -->
    <xsd:element name="StatusCode">
       <xsd:simpleType>
          <xsd:restriction base="xsd:string">
             <xsd:enumeration value="100"/>
             <xsd:enumeration value="800"/>
             <xsd:enumeration value="900"/>
             <xsd:enumeration value="901"/>
             <xsd:enumeration value="902"/>
             <xsd:enumeration value="903"/>
             <xsd:enumeration value="904"/>
          </xsd:restriction>
       </xsd:simpleType>
    </xsd:element>
<!-- StatusMessage element -->
    <xsd:element name="StatusMessage">
       <xsd:simpleType>
          <xsd:restriction base="xsd:string"/>
       </xsd:simpleType>
    </xsd:element>
<!-- EventMessageID element -->
    <xsd:element name="EventMessageID">
       <xsd:simpleType>
          <xsd:restriction base="xsd:string"/>
       </xsd:simpleType>
    </xsd:element>
<!-- BusinessObjectID element -->
    <xsd:element name="BusinessObjectID">
       <xsd:simpleType>
          <xsd:restriction base="xsd:string"/>
       </xsd:simpleType>
    </xsd:element>
 <!-- GlobalMessageID element -->
    <xsd:element name="GlobalMessageID">
       <xsd:simpleType>
          <xsd:restriction base="xsd:string"/>
       </xsd:simpleType>
    </xsd:element>
  <!-- Timestamp element -->
    <xsd:element name="Timestamp">
       <xsd:simpleType>
          <xsd:restriction base="xsd:dateTime"/>
       </xsd:simpleType>
    </xsd:element>
 </xsd:schema> 

Table 2 describes each field within the event payload.

Table 2. Event notification XML fields

Field Description
StatusCode Type of message. The valid values are:
  • 100 - Business Integration Connect has delivered the document and received a receipt acknowledgment.
  • 800 - The application cancelled the PIP.
  • 900 - Business Integration Connect received a Receipt Acknowledgment exception, a general exception, or a 0A1Failure PIP from the community participant.
StatusMessage Alpha-numeric description of this event notification message
EventMessageID Alpha-numeric identifier of this particular event notification message
BusinessObjectID The x-aux-msg-id in the transport-level header of the message affected by this message notification event. This links the payload of the original message to this event.
GlobalMessageID The x-aux-system-msg-id in the transport-level header of the message that caused this message notification event
Timestamp

When the event occurred using the UTC time stamp format:

CCYY-MM-DDThh:mm:ssZ

including fractional precision of seconds (...ss.ssssZ). The date stamp must conform to the XML schema data type for dateTime (w3.org/TR/2001/REC-xmlschema-2-20010502#dateTime)

Event notification message example

Figure 3 shows an example of an event notification message sent using the HTTP protocol.

Figure 3. Example of an event notification message using HTTP

POST /builderURL HTTP/1.1
Content-Type: application/xml
Content-length: 250
x-aux-sender-id: 000000001
x-aux-receiver-id: 000000002
x-aux-third-party-bus-id: 000000003
x-aux-create-datetime: 2002-10-28T23:05:02Z
x-aux-protocol: XMLEvent
x-aux-protocol-version: 1.0
x-aux-process-type: XMLEvent
x-aux-process-version: 1.0
x-aux-payload-root-tag: evntf:EventNotification
x-aux-msg-id: 98732
x-aux-system-msg-id: 12345
x-aux-production: Production
x-aux-process-instance-id: 3456
x-aux-event-status-code: 100
x-aux-transport-retry-count: 0

<?xml version="1.0" encoding="UTF-8"?>
<evntf:EventNotification xmlns:evntf=
   "http://www.ibm.com/websphere/bcg/2003/v1.0/xmleventnotification">
   <evntf:StatusCode>100</evntf:StatusCode>
   <evntf:StatusMessage>The message was delivered</evntf:StatusMessage>
   <evntf:EventMessageID>12345</evntf:EventMessageID>
   <evntf:BusinessObjectID>34234</evntf:BusinessObjectID>
   <evntf:GlobalMessageID>98732</evntf:GlobalMessageID>
   <evntf:Timestamp>2001-01-31T13:20:00Z</evntf:Timestamp>
</evntf:EventNotification>

Which packaging will you use?

The packaging type determines the format in which Business Integration Connect sends the message to the back-end system.

You use the Community Console to establish the connection with your community participants and to specify the packaging that is used between Business Integration Connect and the back-end system. To determine which packaging to use, you must understand the following issues:

For more information on how to set up partner connections, see the Hub Configuration Guide.

Valid packaging types for integration

Not all packaging types are valid when you use Business Integration Connect for integration. Table 3 lists the packaging types that are relevant when Business Integration Connect is acting as a Community Manager.

Table 3. Packaging types relevant for back-end integration

Packaging type Description
None packaging

Causes Business Integration Connect to send the message to the back-end system without any header data

Backend Integration packaging

Adds additional attributes to the message header and, optionally, wraps the message contents in an XML transport envelope

Note:
Other packaging types (such as AS) are available with Business Integration Connect. However, for integration with back-end systems, only the None and Backend Integration packaging types are recommended.

None packaging

When packaging is set to None, Business Integration Connect neither adds a transport-level header when it sends a message to a back-end system nor expects one when it receives a message from a back-end system. Instead, Business Integration Connect sends only the message to the back-end system. Information in the document controls routing.

Backend Integration packaging

When packaging is set to Backend Integration, messages sent to or received from a back-end system must have the following components:

The header and payload are mandatory while attachments are optional. The following sections describe each of the components of a document that uses Backend Integration packaging.

Transport-level header content

The transport-level header contains information that Business Integration Connect uses to process and route the message to the correct destination. The transport-level header is bi-directional so that all messages entering and leaving Business Integration Connect have the mandatory fields and any of the optional fields that apply.

Table 4 lists the fields of the transport-level header.

Table 4. Transport-level header fields

Header field Description Required?
x-aux-sender-id Identifier of the message sender, such as a DUNS number. Yes
x-aux-receiver-id Identifier of the message receiver, such as a DUNS number. Yes
x-aux-protocol Protocol of the message content. Valid values include RNSC for RosettaNet service content, XMLEvent, and Binary. For Business Integration Connect, the value in this field has priority over any protocol field in the payload. Yes
x-aux-protocol-version Version of the message content protocol. Yes
x-aux-process-type Process to be performed or what type of message is being sent. For RosettaNet messages, this is the PIP code such as 3A4. For event messages, it is XMLEvent and for Binary messages, it is Binary. For Business Integration Connect, the value in this field has priority over any process field in the payload. Yes
x-aux-process-version Version of the process. For RosettaNet messages, this is the version number of the PIP. Yes
x-aux-create-datetime When the message was successfully posted using the UTC time stamp format (CCYY-MM-DDThh:mm:ssZ)
x-aux-msg-id Identifier of the payload content. For example, it could be the identifier of the RNPIPServiceContent instance for a RosettaNet message or it could be a proprietary document identifier. This links the message payload with something in the message sender's system for tracing purposes.
x-aux-production Routing of the message. Valid values are: Production Test This value is populated for requests in both directions. Note that when the message is a response to a two-way PIP initiated by a community participant, Business Integration Connect uses the GlobalUsageCode in the request and ignores the value in the transport level header.
x-aux-system-msg-id Global Unique Identifier (GUID) for the message, which is used for duplicate checking. Yes
x-aux-payload-root-tag Root tag element of the payload. For example, for 3A4 RosettaNet service content, the value of this field would be Pip3A4PurchaseOrderRequest. For event notification messages, the value for this field would be EventNotification.
x-aux-process-instance-id Identifier that links documents in a multiple message business process to a unique process instance. For RosettaNet, it must be unique for RosettaNet processes within the last 30 days. All messages exchanged as part of a RosettaNet process instance, including retries, use the same process instance ID.
x-aux-event-status-code Status code for the event notification. See the StatusCode field in Event message structure.
x-aux-third-party-bus-id Identifier such as a DUNS number of the party that delivered the message. This can be different from both the x-aux-sender-id and the x-aux-receiver-id if a third party is hosting Business Integration Connect on behalf of the community owner.
x-aux-transport-retry-count Number of unsuccessful attempts at posting this message prior to this attempt. If a message posts successfully on the first attempt, the value of this field will be 0.
content-type The content type of the message.
content-length The length of the message (in bytes).
Note:
For compatibility with IBM WebSphere MQ (A JMS provider), the fields of a JMS protocol message use underscores instead of hyphens. For example, in a JMS message, there is an x_aux_sender_id field instead of an x-aux-sender-id field.

Table 4 provides an overview of the transport-level header information. The following sections provide transport-level header information specific to certain business protocols:

Transport-level header and a RosettaNet message 

Table 5 describes where Business Integration Connect obtains values for the fields of the transport-level header from a RosettaNet message.

Table 5. Transport-level header fields and RosettaNet content

Header field Source of value: RosettaNet 2.0 Source of value: RosettaNet 1.1
x-aux-sender-id
<(DeliveryHeader)>
  <messageSenderIdentification>
    <PartnerIdentification>
      <GlobalBusinessIdentifier>
<ServiceHeader>
  <ProcessControl>
    <TransactionControl>
      <ActionControl> or <SignalControl>
        <PartnerRouter>
          <fromPartner>
            <PartnerDescription>
              <BusinessDescription>
                <GlobalBusinessIdentifier>
x-aux-receiver-id
<(DeliveryHeader)>
  <messageReceiverIdentification>
    <PartnerIdentification>
      <GlobalBusinessIdentifier>
<ServiceHeader>
  <ProcessControl>
    <TransactionControl>
      <ActionControl> or <SignalControl>
        <PartnerRouter>
          <toPartner>
            <PartnerDescription>
              <BusinessDescription>
                <GlobalBusinessIdentifier>
x-aux-protocol Set value for RosettaNet: RNSC Same as for RosettaNet 2.0
x-aux-protocol-version Set value: 1.0 Same as for RosettaNet 2.0
x-aux-process-type

The source XPath is:

/ServiceHeader/ProcessControl/
pipCode/GlobalProcessIndicatorCode 

The source XPath is:

/ServiceHeader/ProcessControl/
ProcessIdentity/GlobalProcessIndicatorCode
x-aux-process-version

The source XPath is:

/ServiceHeader/ProcessControl/
pipVersion/VersionIdentifier 

The value of the version identifier of each PIP is in its PIP specification.

The source XPath is:

/ServiceHeader/ProcessControl/
ProcessIdentity/VersionIdentifier

The value of the version identifier of each PIP is in its PIP specification.

x-aux-payload- root-tag Name of the PIP such as Pip3A4PurchaseOrderRequest Same as for RosettaNet 2.0
x-aux-process-instance-id

For processes initiated by the application, the value is the ID of the process instance. For processes initiated by a community participant that are not pass-through workflow, the value is the process ID in the initial RosettaNet request:

<ServiceHeader>
  <ProcessControl>
    <pipInstanceId>
      <InstanceIdentifier>
<ServiceHeader>
  <ProcessControl>
    <ProcessIdentity>
      <InstanceIdentifier> 
x-aux-msg-id
<(RNPipServiceContent)>
  <thisDocumentIdentifier>
    <ProprietaryDocumentIdentifier> 
Same as for RosettaNet 2.0
x-aux-production
<ServiceHeader>
  <ProcessIndicator>
    <GlobalUsageCode>
<Preamble>
  <GlobalUsageCode>

Transport-level header and an AS2 message 

Table 6 describes where Business Integration Connect obtains values for the fields of the transport-level header from an AS2 message.

Note:
The values are case-sensitive.

Table 6. Transport-level header fields from AS2 content

Header field Source of value
x-aux-sender-id When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, the AS2-From header field of the AS2 message is set in the x-aux-sender-id field of the back-end integration message that is sent to the Community Manager. When an AS2 message goes out to a community participant, the x-aux-sender-id field of the incoming back-end integration message is used as the AS2-From header value of the AS2 message.
x-aux-receiver-id When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, the AS2-To header field of the AS2 message is set in the x-aux-receiver-id field of the back-end integration message that is sent to the Community Manager. When an AS2 message goes out to a community participant, the x-aux-receiver-id field of the incoming back-end integration message is used as the AS2-To header value of the AS2 message.
x-aux-protocol When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, the ToProtocol of the participant connection is set in the x-aux-protocol field of the back-end integration message that is sent to the Community Manager. When an AS2 message goes out to a community participant, the x-aux-protocol field of the incoming back-end integration message is used to determine the FromProtocol of the participant connection.
x-aux-protocol-version When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, the ToProtocolVersion of the participant connection is set in the x-aux-protocol-version field of the back-end integration message that is sent to the Community Manager. When an AS2 message goes out to a community participant, the x-aux-protocol-version field of the incoming back-end integration message is used as the FromProtocolVersion of the participant connection.
x-aux-process-type When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, the ToProcessCode of the participant connection is used to set in the x-aux-process-type field of the back-end integration message that is sent to the Community Manager. When an AS2 message goes out to a community participant, the x-aux-process-type field of the incoming back-end integration message is used as the FromProcessCode of the participant connection.
x-aux-process-version When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, the ToProcessVersion of the participant connection is set in the x-aux-process-version field of the back-end integration message that is sent to the Community Manager. When an AS2 message goes out to a community participant, the x-aux-process-version field of the incoming back-end integration message is used as the FromProcessVersion of the participant connection.
x-aux-payload- root-tag When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, for custom XML protocol only, the Root tag specified in the XPATH is parsed out of the message and used in the x-aux-payload-root-tag field. When an AS2 message goes out to a community participant, this field doesn't need to be set in the incoming back-end integration message.
x-aux-process-instance-id This field is not used for AS2.
x-aux-msg-id When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, for custom XML protocol only, the Doc ID specified in the XPATH is parsed out of the message and used in the x-aux-payload-root-tag field. When an AS2 message goes out to a community participant, this field doesn't need to be set in the incoming back-end integration message.
x-aux-system-msg-id When a community participant sends an AS2 message to Business Integration Connect Enterprise or Advanced edition, this field is set to the internally generated unique ID for this message. When an AS2 message goes out to a community participant, this field doesn't need to be set in the incoming back-end integration message.
x-aux-production This field is not used for AS2.

Transport-level header and an AS1 message 

Table 7 describes where Business Integration Connect obtains values for fields in the transport-level header from an AS1 message.

Note:
The values are case-sensitive.

Table 7. Transport-level header fields from AS1 content

Header field Source of the value
x-aux-sender-id When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, the FromID in the "Subject: ToID;FromID" header field of the AS1 message is set in the x-aux-sender-id field of the back-end integration message that is sent to the Community Manager. When an AS1 message goes out to a community participant, the x-aux-sender-id field of the incoming back-end integration message is used as FromID in the "Subject: ToID;FromID" header value of the AS1 message.
x-aux-receiver-id When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, ToID in the "Subject: ToID;FromID" header field of the AS1 message is set in the x-aux-receiver-id field of the back-end integration message that is sent to the Community Manager. When an AS1 message goes out to a community participant, the x-aux-receiver-id field of the incoming back-end integration message is used as ToID in the "Subject: ToID;FromID" header value of the AS1 message.
x-aux-protocol When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, the ToProtocol of the participant connection is set in the x-aux-protocol field of the back-end integration message that is sent to the Community Manager. When an AS1 message goes out to a community participant, the x-aux-protocol field of the incoming back-end integration message is used as the FromProtocol of the participant connection.
x-aux-protocol-version When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, the ToProtocolVersion of the participant connection is set in the x-aux-protocol-version field of the back-end integration message that is sent to the Community Manager. When an AS1 message goes out to a community participant, the x-aux-protocol-version field of the incoming back-end integration message is used as the FromProtocolVersion of the participant connection.
x-aux-process-type When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, the ToProcessCode of the participant connection is set in the x-aux-process-type field of the back-end integration message that is sent to the Community Manager. When an AS1 message goes out to a community participant, the x-aux-process-type field of the incoming back-end integration message is used as the FromProcessCode of the participant connection.
x-aux-process-version When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, the ToProcessVersion of the participant connection is set in the x-aux-process-version field of the back-end integration message that is sent to the Community Manager. When an AS1 message goes out to a community participant, the x-aux-process-version field of the incoming back-end integration message is used as the FromProcessVersion of the participant connection.
x-aux-payload- root-tag When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, for custom XML protocol only, the Root tag specified in the XPATH is parsed out of the message and set in the x-aux-payload-root-tag field. When an AS1 message goes out to a community participant, this field doesn't need to be set in the incoming back-end integration message.
x-aux-process-instance-id This field is not used for AS1.
x-aux-msg-id When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, for custom XML protocol only, the Doc ID specified in the XPATH is parsed out of the message and used in the x-aux-payload-root-tag field. When an AS1 message goes out to a community participant, this field doesn't need to be set in the incoming back-end integration message.
x-aux-system-msg-id When a community participant sends an AS1 message to Business Integration Connect Enterprise or Advanced edition, this field is set to the internally generated unique ID for this message. When an AS1 message goes out to a community participant, this field doesn't need to be set in the incoming back-end integration message.
x-aux-production This field is not used for AS1.

Payload

The payload of the message contains the actual content of the message. The location of the payload depends on the transport protocol that is sending the message, as Table 8 shows.

Table 8. Location of payload

Transport protocol Location of payload
HTTP protocol messages In the body of the HTTP post
JMS protocol messages In the body of the JMS message
RosettaNet messages The service content from the PIP
Sending EDI over AS2

The EDI message

The payload is not wrapped with an XML envelope unless the message also carries one or more attachments. For information on the XML envelope and tags used to wrap the attachments, see Attachments.

The payload can be Base64-encoded and in an XML transport envelope in either of the following cases:

This XML transport envelope wraps the document in the <transport-envelope> root tag. Inside this root tag there is a <payload> tag that contains the document payload. If any attachments exist, each is contained in an <attachment> tag. For more information on the structure of these tags, see Attachments.

Business Integration Connect includes the following W3C XML schema file that describes the Backend Integration XML transport envelope structure:

wbipackaging_v1.0_ns.xsd

This schema file is located in the following directory on the installation medium:

B2BIntegrate\packagingSchemas

You can use any XML editing tool to validate your Backend Integration XML against this schema file to ensure the document is valid before it is sent to the Document Manager.

Attachments

If the business message protocol permits them, each document can have one or more attachments. If the document has attachments, it must be wrapped in an XML transport envelope, as described in Payload. Table 9 describes the XML attributes in the payload and attachment tags.

Table 9. XML attributes of the payload and attachment tags

XML attribute Description Required?
Content-Type Identifies the MIME type/subtype, such as text/xml or image/gif. Yes
Encoding Identifies the encoding. Because the attachment and payload must be Base64-encoded, the only valid value for this attribute is "Base64". No

Figure 4 shows an example of a document in an XML transport envelope that contains the payload and one attachment.

Note:
The namespace in this example is required:
xmlns="http://www.ibm.com/websphere/bcg/2003/v1.0/wbipackaging"

Figure 4. Sample XML transport envelope for payload and one attachment

<?xml version="1.0" encoding="utf-8"?>
<transport-envelope
    xmlns="http://www.ibm.com/websphere/bcg/2003/v1.0/wbipackaging">
  <payload encoding="base64" contentType="application/xml">
    ...base64 encoded XML message...
  </payload>
  <attachment encoding="base64" Content-Type="text/xml">
    ...base64 encoded XML attachment...
  </attachment>
</transport-envelope>
Note:
To process documents wrapped in the XML transport envelope with the WebSphere InterChange Server, Business Integration Connect provides the Attachment data handler. For more information, see Handling documents with attachments.

Which packaging type works with your documents?

Documents in certain business protocols can use only certain types of packaging. For example, a RosettaNet document can be processed only when a packaging of Backend Integration has been specified. See Table 15 and Table 20 for a complete list of which document types can be associated with which types of packaging.

Example of Backend Integration packaging over HTTP

Figure 5 shows an example of a message from Business Integration Connect to an application using the HTTP transport protocol. Note that the message does not contain an attachment.

Figure 5. Sample message using HTTP transport protocol

POST /sample/receive HTTP/1.1
Host: sample. COM
Content-Type: application/xml
Content-Length: nnn 
x-aux-sender-id: 000000001
x-aux-receiver-id: 000000002
x-aux-third-party-bus-id: 000000003 
x-aux-create-datetime: 2002-10-28T23:05:02Z
x-aux-protocol: RNSC
x-aux-protocol-version: 1.0
x-aux-process-type: 3A4
x-aux-process-version: V02.00
x-aux-payload-root-tag: Pip3A4PurchaseOrderRequest
x-aux-msg-id: 1021358129419
x-aux-system-msg-id: 2
x-aux-production: Production
x-aux-process-instance-id: 123456
x-aux-transport-retry-count: 0

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Pip3A4PurchaseOrderRequest SYSTEM
     "3A4PurchaseOrderRequestMessageGuideline_v1_2.dtd">
<Pip3A4PurchaseOrderRequest>

   <PurchaseOrder>
      ...
   </PurchaseOrder>
      ... 

   <thisDocumentIdentifier>
      <ProprietaryDocumentIdentifier>1021358129419
      </ProprietaryDocumentIdentifier>
   </thisDocumentIdentifier>
   <GlobalDocumentFunctionCode>Request</GlobalDocumentFunctionCode>

</Pip3A4PurchaseOrderRequest>

Which message transport will you use?

When the back-end system and WebSphere Business Integration Connect send messages to one another, each must use the same message-transport protocol. The message-transport protocol defines the communication protocol in which the messages are sent.

Business Integration Connect communicates with a back-end system through its Backend Integration interface. Table 10. lists the transport protocols that this Backend Integration interface supports.

Table 10. Transport protocols supported by Business Integration Connect

Transport protocol For more information
HTTP or HTTPS HTTP transport protocol
File-system files File-system protocol for Enterprise and Advanced editions
JMS JMS protocol

See Table 15 and Table 20 for information on which transport protocols are valid for a particular combination of message content and Backend Integration packaging.

HTTP transport protocol

To send messages using an HTTP protocol, Business Integration Connect uses HTTP/S 1.1. To receive messages from back-end systems, Business Integration Connect supports both HTTP/S version 1.0 and 1.1.

The HTTP message can include the integration packaging attributes. Whether these attributes are included depends on the packaging type associated with the participant connection, as follows:

Process

When HTTP or HTTPS messages are sent between Business Integration Connect and an application for asynchronous exchanges, the following steps occur:

  1. The source system (Business Integration Connect or the back-end system) posts an HTTP message to the target system using a specific URL.
  2. The target system receives the message and sends the protocol-level acknowledgment, HTTP 200 or 202, to signify the change in ownership. The source system ignores the body of this acknowledgment message. If an error occurs during this processing, the target system sends an HTTP 500 message back to the source system.
  3. If Business Integration Connect is the target system (that is, when Business Integration Connect receives a message), it then persists the message and releases the connection to the source system.
  4. The target system can then process the message asynchronously.

When the exchange is synchronous (for example, for a SOAP or cXML document), a response is returned along with the HTTP 200 message in the same HTTP connection.

Sending and receiving messages using the HTTP protocol

To send a message to Business Integration Connect using the HTTP protocol, a back-end system takes the following steps:

  1. Create the message.

    The Content-Type attribute in the transport-level header gives the encoding used for the message.

  2. Package the message according to the packaging type set for the connection.

    For Backend Integration packaging, the back-end system adds the protocol header attributes that Business Integration Connect requires.

  3. Post the message to the URL that Business Integration Connect uses to receive these messages.
  4. If the exchange is synchronous, the back-end system waits to receive a response in the same connection that was used for the request.

To enable HTTP message exchange in this direction, use the Target Details screen of the Community Console to set up a target for inbound documents. For more information, see Receiving documents from the back-end system.

To receive a message from Business Integration Connect using the HTTP protocol, a back-end system takes the following steps:

  1. Listen for a message at a particular URL.
  2. When a message is received, process the message:
  3. If the exchange is synchronous, the back-end system returns a response in the same connection used for the request.

To enable HTTP message exchange in this direction, use the Gateway screen of the Community Console to set up a gateway for outbound documents. For more information, see Sending documents to the back-end system.

JMS protocol

The JMS protocol is based on the Java Message Service (JMS) and transfers messages through transactional, persistent JMS queues provided by, for example, IBM WebSphere MQ. The JMS Protocol supports the following JMS message types:

In JMS protocol, the sending system sends a JMS message to the receiving system using the Enqueue operation. The receiving system gets the message from the queue, persists the message, and then performs the Dequeue operation to remove the message from the queue. From this point forward, the receiving system can process the message asynchronously.

The JMS message can include integration packaging attributes. Whether these attributes are included depends on the packaging type associated with the participant connection, as follows:

With the exception of binary messages, Business Integration Connect supports sending and receiving JMS messages with either type of packaging. Binary messages received from an application must have the Backend Integration packaging. The reverse is not true because Business Integration Connect supports sending binary messages to the application using either type of packaging.

Sending messages using the JMS protocol

To send a message to Business Integration Connect using the JMS protocol, a back-end system takes the following steps:

  1. Create the message.

    The content_type header attribute sets the content type for the message and the content_length header attribute specifies the length of the message (in bytes).

  2. Package the message according to the packaging type set for the connection.

    For Backend Integration packaging, the application adds the required JMS header attributes.

  3. Send the message to the JMS queue that the back-end system uses to send messages to Business Integration Connect.

To enable JMS message exchange in this direction, use the Target Details screen of the Community Console to set up a target for inbound documents. For more information, see Receiving documents from the back-end system.

Receiving messages using the JMS protocol

To receive a message from Business Integration Connect using the JMS protocol, a back-end system takes the following steps:

  1. Listen for a message on the JMS queue.
  2. When a message is received, process the message:

To enable JMS message exchange in this direction, use the Gateway screen of the Community Console to set up a gateway for outbound documents. For more information, see Sending documents to the back-end system.

File-system protocol for Enterprise and Advanced editions

The File System protocol enables Business Integration Connect to send messages by placing them in a defined directory structure. Business Integration Connect receives messages by reading them from the directory structure. The file-system protocol supports the following:

Sending messages using the file-system protocol

To send a message to Business Integration Connect using the file-system protocol, an application should take the following steps:

  1. Create the message file in a temporary directory.
  2. Once the file is ready, move the file to the directory that Business Integration Connect polls.

To enable file-system message exchange in this direction, use the Target Details screen of the Community Console to set up a target for inbound documents. The target of the message determines the directory that Business Integration Connect polls. When you create a target, Business Integration Connect creates a Documents directory and its subdirectories for the target, as follows:

<doc_root>
    Documents
        Production
        Test
      <other destination types>

Business Integration Connect polls the Documents directories and their subdirectories regularly to detect message files. If it finds a message, Business Integration Connect persists the message and then deletes the message from the directory. Business Integration Connect then processes the message normally. See the Hub Configuration Guide for information on how to create a target.

Receiving messages using the file-system protocol

To receive messages using the file system protocol, an application should do the following:

  1. Poll the appropriate directory for message files.
    Note:
    Temporary files (those with extensions .tmp or .tmp1) should be ignored. The application must not pick up or delete these temporary files.
  2. When there is a message, persist it.
  3. Delete the message from the directory.
  4. Process the message.

To enable file-system message exchange in this direction, use the Gateway screen of the Community Console to set up a gateway for outbound documents. Business Integration Connect places the message file in the Documents directory, which the gateway defines. By defining the destination directory according to the gateway, each participant connection can have a different directory. For information on gateways, see the Hub Configuration Guide.

How do you access your back-end application?

Business Integration Connect provides the ability to integrate with many different back-end applications. Usually, a back-end application is accessed through a back-end system, such as an integration broker. Integration to the back-end systems listed in Table 11 are covered in this guide.

Table 11. Supported back-end systems for Business Integration Connect

Back-end system For more information
WebSphere InterChange Server Introduction to InterChange Server Integration
WebSphere Business Integration Message Broker Integrating with WebSphere Business Integration Message Broker
WebSphere Data Interchange Integrating with WebSphere Data Interchange

Copyright IBM Corp. 2003, 2004