Which packaging will you use?

The packaging type determines the format in which WebSphere Partner Gateway sends the message to the back-end system and the format in which the back-end system sends the message to WebSphere Partner Gateway.

You use the Community Console to establish the connection with your community participants and to specify the packaging that is used between WebSphere Partner Gateway 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.

Not all packaging types are valid when you use WebSphere Partner Gateway for integration. Table 4 lists the packaging types that are relevant when WebSphere Partner Gateway is exchanging documents or messages with a back-end application of the Community Manager.

Table 4. Packaging types relevant for back-end integration
Packaging type Description
None packaging

Causes the message to be sent to the back-end system or to the hub 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 WebSphere Partner Gateway. 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, WebSphere Partner Gateway 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, WebSphere Partner Gateway 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 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 WebSphere Partner Gateway 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 WebSphere Partner Gateway have the mandatory fields and any of the optional fields that apply.

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

Table 5. 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 WebSphere Partner Gateway, 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 (for example, 3A4). For event messages, it is XMLEvent, and for Binary messages, it is Binary. For WebSphere Partner Gateway, 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 and 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, WebSphere Partner Gateway 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 WebSphere Partner Gateway 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.
x-out-file-name The original file name for messages being sent over JMS with Backend Integration packaging. (See note 2.)
content-type The content type of the message.
content-length The length of the message (in bytes).
Notes:
  1. 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.
  2. If the target is specified as HTTP and the package is specified as None, the original file name is set in the HTTP headers as "Content-Disposition: attachment;po.xml".

    If the target is specified as JMS and the package is specified as Backend Integration, the original file name is written into x-out-file-name along with other x-aux-* headers.

Table 5 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 6 describes where WebSphere Partner Gateway obtains values for the fields of the transport-level header from a RosettaNet message.

Table 6. 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 7 describes where WebSphere Partner Gateway obtains values for the fields of the transport-level header from an AS2 message.

Note: The values are case-sensitive.
Table 7. Transport-level header fields from AS2 content
Header field Source of value when a community participant sends an AS/2 message to the hub Source of value when an AS2 message is sent to a community participant
x-aux-sender-id 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. 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 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. 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 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. 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 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. 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 The ToProcessCode of the participant connection is used to set the x-aux-process-type field of the back-end integration message that is sent to the Community Manager. 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 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. 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 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. This field does not need to be set in the incoming back-end integration message.
x-aux-process-instance-id This field is not used for AS2. This field is not used for AS2.
x-aux-msg-id For custom XML protocol only, the Doc ID specified in the XPATH is parsed out of the message and used in the x-aux-msg-id field. This field does not need to be set in the incoming back-end integration message
x-aux-system-msg-id This field is set to the internally generated unique ID for this message. This field does not need to be set in the incoming back-end integration message
x-aux-production This field is not used for AS2. This field is not used for AS2.
Transport-level header and an AS1 message

Table 8 describes where WebSphere Partner Gateway obtains values for fields in the transport-level header from an AS1 message.

Note: The values are case-sensitive.

Table 8. Transport-level header fields from AS1 content
Header field Source of value when a community participant sends an AS/1 message to the hub Source of value when an AS/1 message is sent to a community participant
x-aux-sender-id 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. 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 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. 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 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. 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 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. 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 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. 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 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. 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 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. This field does not need to be set in the incoming back-end integration message.
x-aux-process-instance-id This field is not used for AS1. This field is not used for AS1.
x-aux-msg-id For custom XML protocol only, the Doc ID specified in the XPATH is parsed out of the message and used in the x-aux-msg-id field. This field does not need to be set in the incoming back-end integration message.
x-aux-system-msg-id This field is set to the internally generated unique ID for this message. This field does not need to be set in the incoming back-end integration message.
x-aux-production This field is not used for AS1. 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 9 shows.

Table 9. 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
EDI The EDI envelope
ROD or XML document The ROD or XML document

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.

WebSphere Partner Gateway 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 10 describes the XML attributes in the payload and attachment tags.

Table 10. 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 13 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 13. 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, WebSphere Partner Gateway 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 12, Table 13, and Table 14 for a complete list of which document types can be associated with which types of packaging.

Example of Backend Integration packaging over HTTP

Figure 14 shows an example of a message from WebSphere Partner Gateway to an application using the HTTP transport protocol. Note that the message does not contain an attachment.

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

Copyright IBM Corp. 2003, 2005