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:
- Which packaging types are valid for use with a back-end system?
- Which packaging types are valid with a message in a particular
business protocol?
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:
- A transport-level
header, which contains meta-information about the message (required)
- A payload,
which contains the content of the message (required)
- An attachment
(optional)
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.
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:
- 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.
-
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:
- If the document contains an attachment
A document with attachments must be wrapped
in an XML transport envelope. For more information on how attachments
are formatted, see Attachments.
- If you set the envelope flag for Backend
Integration packaging to Yes
To wrap a document in the XML transport envelope regardless of
whether it contains attachments, set the Backend Integration envelope
flag to Yes from the profile's B2B Capabilities screen.
For example, to set this flag in the Community Manager's profile,
perform the following tasks:
- Click Account Admin > Profiles.
- Enter the name of the Community Manager (or perform a search
on all participants).
- Click the View details icon next to the
name of the Community Manager.
- Click B2B Capabilities.
- Click the Edit icon next to Backend Integration.
- Set the Envelop Flag to Yes.
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>
