Which business protocol are you using?

The business protocol of your message determines the format of the document. 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, affects which message-transport protocols you can use.

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

Web services (SOAP)

WebSphere Partner Gateway can make the following Web services available to members of the hub community:

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 WebSphere Partner Gateway 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 WebSphere Partner Gateway 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 Hub Configuration Guide for more information, including how to set up your document flow definitions for cXML.

EDI

WebSphere Partner Gateway accepts EDI documents from participants from value added networks (VANs) as well as from the Internet. EDI documents sent to or received from a VAN use the FTP Scripting transport. The FTP Scripting transport can also be used to send documents to or receive documents from the Internet. See the Hub Configuration Guide for information on the FTP Scripting transport.

An EDI document enters the hub and leaves the hub in an EDI envelope, known as an interchange. The interchange contains individual EDI transactions or groups of transactions.

If the EDI interchange will be passed through the hub (without being de-enveloped), you create one connection between the hub and Community Manager.

However, if the EDI interchange will be de-enveloped, the process for creating interactions and connections is different from other business protocols. The interchange must be de-enveloped, and the individual transactions processed. The transactions are typically translated to another form, according to a transformation map that is imported from the Data Interchange Services client. If the EDI transactions are translated to XML or record-oriented-data (ROD) documents, those documents are sent to the Community Manager or participant. If the transactions are translated to other EDI formats, the transactions are first enveloped before being sent to the Community Manager or participant.

Back-end application to participant flows

A back-end application can send the following types of documents:

Participant to backend-application flows

A participant can send the following types of documents:

Functional acknowledgments

A functional acknowledgment specifies that an EDI interchange was received. A functional acknowledgment is always enveloped before being delivered.

Note: Functional acknowledgments apply only to those interchanges that are de-enveloped by WebSphere Partner Gateway or generated by WebSphere Partner Gateway. They do not apply to interchanges that are passed through WebSphere Partner Gateway.

For interchanges received by WebSphere Partner Gateway

For interchanges generated by WebSphere Partner Gateway:

RosettaNet

WebSphere Partner Gateway provides support to let you send and receive documents that adhere to the RosettaNet 1.1 and 2.0 standards.When a participant sends a RosettaNet message to the hub, the target side of the participant connection must have Backend Integration specified. The hub converts the payload of the message to RNSC format and sends the message to the back-end system. Because Backend Integration packaging is used, the hub adds transport-level headers to the message. The message is sent through the HTTP or JMS transport protocol. The transport-level header retains meta-information that is not part of the PIP and enables WebSphere Partner Gateway to route the message appropriately.

Similarly, when the Community Manager back-end system sends an RNSC message to the hub, the source side of the participant connection must have Backend Integration packaging specified, and the back-end system must supply the transport-level headers.

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, which PIP will be sent, and the version of the PIP along with other information. This information enables WebSphere Partner Gateway 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

WebSphere Partner Gateway executes RNIF PIP processes with community participants on behalf of the Community Manager back-end applications. Therefore, WebSphere Partner Gateway provides event notification as the mechanism to notify the back-end application about various aspects of the RNIF PIP process execution. Event notification enables WebSphere Partner Gateway to, for example, notify the application if WebSphere Partner Gateway 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 WebSphere Partner Gateway or an application. These messages have the same structure as any other message that enters or leaves WebSphere Partner Gateway; that is, they have a transport-level header and payload. WebSphere Partner Gateway can be configured to send or not send event notification messages, because they are optional.

Table 2 summarizes the event notification messages that WebSphere Partner Gateway can send to back-end systems.

Table 2. Event notification messages sent to back-end system
Event condition Event notification message

WebSphere Partner Gateway delivers a RosettaNet document to a community participant and receives a Receipt Acknowledgment.

Event 100

WebSphere Partner Gateway cancels a PIP by generating an 0A1 message and delivering it to the community participant.

Event 800

WebSphere Partner Gateway receives a Receipt Acknowledgment exception or a general exception from a community participant.

Event 900

WebSphere Partner Gateway can send 0A1 messages 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 an event notification message to WebSphere Partner Gateway 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 XML schema in Figure 11.

Figure 11. 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 3 describes each field within the event payload.

Table 3. Event notification XML fields
Field Description
StatusCode Type of message. The valid values are:
  • 100 - WebSphere Partner Gateway has delivered the document and received a receipt acknowledgment.
  • 800 - The application canceled the PIP.
  • 900 - WebSphere Partner Gateway received a Receipt Acknowledgment exception, a general exception, or a 0A1Failure PIP from the community participant.
StatusMessage Alphanumeric description of this event notification message.
EventMessageID Alphanumeric 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 example

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

Figure 12. 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>

Copyright IBM Corp. 2003, 2005