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:
WebSphere Partner Gateway can make the following Web services available to members of the hub community:
You will have to provide your community participant with the public WSDL that WebSphere Partner Gateway generates. It is important to note that the URL on which the community participant invokes the Web service is the Web service public URL specified while uploading the Web service. WebSphere Partner Gateway acts as a proxy. It receives a SOAP message from the participant and figures out the corresponding private Web service. It then invokes the private Web service (provided by the Community Manager) using the same SOAP message. The response returned by the Community Manager is then returned to the participant.
It is important to note that the same Web Service Interface can be provided by multiple partners. WebSphere Partner Gateway makes the Web service available to the Community Manager at the Web service URL specified in the console while uploading the Web service. Additionally the Community Manager will have to provide the URL parameter to identify "To Partner". Refer to the Hub Configuration Guide for more details. WebSphere Partner Gateway acts as a proxy. It receives a SOAP message from the Community Manager and figures out the corresponding Web service and the "To Partner". It then invokes the Web service provided by the partner using the same SOAP message. The response message returned by the partner is then returned to the Community Manager.
Refer to the Hub Configuration Guide for more information, including how to set up your document flow definitions for Web services.
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:
Refer to the Hub Configuration Guide for more information, including how to set up your document flow definitions for cXML.
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.
A back-end application can send the following types of documents:
WebSphere Partner Gateway de-envelopes the individual EDI transactions and translates these individual transactions. If the transactions are translated into EDI, they are enveloped and then routed to the participant. The back-end application can use None or Backend packaging and send the interchange over a variety of transports, as defined in Table 13.
Figure 6 shows an X12 interchange consisting of three transactions being de-enveloped. The transactions are transformed into EDIFACT format and are then enveloped and sent to the participant.
Each of the transactions has a transformation map associated with it, which specifies how the transaction is transformed. The transaction can be transformed into a single transaction or, if map chaining was used to create the map, multiple transactions.
If the transaction is translated into an XML or ROD document, it is routed as configured in the participant connection for that transaction.
Figure 7 shows an EDI X12 interchange being de-enveloped and transformed into XML documents, which are then sent to the participant.
The transaction can be transformed into a single document or, if map chaining was used to create the map, multiple documents.
WebSphere Partner Gateway translates the document into an EDI transaction, envelopes the transaction, and sends it to the participant. The back-end application can use None or Backend Integration packaging and can send the document over a variety of transports, as defined in Table 13.
Figure 8 shows an XML document that is transformed into X12 transactions and then enveloped.
One document can be transformed into multiple transactions (if map chaining was used to create the map), and the transactions can be enveloped into different interchanges.
Figure 9 shows an XML document that is transformed into three X12 transactions. Two of the transactions are enveloped together. One is put in a separate envelope.
If the document is translated into another XML document or another ROD document, it is routed as configured in the participant connection for the document.
WebSphere Partner Gateway splits the documents and translates them. If the documents are translated into EDI transactions, WebSphere Partner Gateway envelopes the transactions and sends the envelope to the participant. If batch IDs were assigned to the XML or ROD documents, WebSphere Partner Gateway attempts to send the EDI transactions in one envelope (as a batch). The back-end application can use None or Backend Integration packaging and can send the document over a variety of transports, as defined in Table 13.
Figure 10 shows a set of XML documents being split, resulting in individual XML documents. The XML documents are transformed into X12 transactions, and the transactions are enveloped.
Figure 10 shows how the documents are split and the transformed transactions are enveloped together. To allow documents to be split, you must configure a splitter handler (in this case, the XML Splitter Handler) for the target you are using to send the documents. The XML Splitter Handler must have the BCG_BATCHDOCS option set to on (the default value) for this scenario to occur. BCG_BATCHDOCS assigns a batch ID to the XML documents so that the resulting transactions will be put into the same envelope. See the Hub Configuration Guide for information on the XML Splitter Handler and the BCG_BATCHDOCS attribute.
If the documents are translated into other XML documents or other ROD documents, they are routed as configured in the participant connection for the documents.
WebSphere Partner Gateway splits the file into individual interchanges. It then de-envelopes the interchanges into individual transactions and translates them. If the documents are translated into EDI transactions, WebSphere Partner Gateway envelopes the transactions and sends the envelope to the participant. The back-end application can use None or Backend Integration packaging and can send the document over a variety of transports, as defined in Table 13.
If the documents are translated into XML or ROD documents, they are routed as configured in the participant connection for the documents.
A participant can send the following types of documents:
WebSphere Partner Gateway de-envelopes the individual EDI transactions and translates these transactions. If the transactions are translated into EDI, they are enveloped and routed to the back-end application. The back-end application can use None or Backend Integration packaging, and the transactions can be sent over a variety of transports, as defined in Table 14.
If the transactions are translated into XML or ROD documents, they are routed as configured in the participant connection for the transactions.
WebSphere Partner Gateway translates the document into an EDI transaction, envelopes the transaction, and routes the envelope to the back-end application. Either None or Backend Integration packaging can be used.
If the document is translated into another XML document or another ROD document, it is routed as configured in the participant connection for the document.
WebSphere Partner Gateway splits the documents and translates them. If the documents are translated into EDI transactions, WebSphere Partner Gateway envelopes the transactions and sends the envelope to the back-end application. If batch IDs were assigned to the XML or ROD documents, WebSphere Partner Gateway attempts to send the EDI transactions in one envelope (as a batch). Either None or Backend Integration packaging can be used.
If the documents are translated into other XML documents or other ROD documents, they are routed as configured in the participant connection for the documents.
WebSphere Partner Gateway splits the file into individual interchanges. It then de-envelopes the interchanges into individual transactions and translates them. If the documents are translated into EDI transactions, WebSphere Partner Gateway envelopes the transactions and sends the envelope to the back-end application. Either None or Backend Integration packaging can be used.
If the documents are translated into XML or ROD documents, they are routed as configured in the participant connection for the documents.
A functional acknowledgment specifies that an EDI interchange was received. A functional acknowledgment is always enveloped before being delivered.
For interchanges received by WebSphere Partner Gateway
For interchanges generated by WebSphere Partner Gateway:
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.
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.
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.
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.
<?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.
Figure 12 shows an example of an event notification message sent using the HTTP protocol.
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>