cXML documents

This section contains an overview of cXML support and information about creating document flow definitions for cXML exchanges.

Overview

The WebSphere Partner Gateway Document Manager identifies a cXML document by the root element name of the XML document, which is cXML and the version identified by the cXML DOCTYPE (DTD). For example, the following DOCTYPE is for cXML version 1.2.009:

<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.009/cXML.dtd"> 

The Document Manager performs the DTD validation on cXML documents; however, WebSphere Partner Gateway does not provide cXML DTDs. You can download them from www.cxml.org and then upload them into WebSphere Partner Gateway through the Validation Map module in the Community Console. After you upload the DTD, associate it with the cXML document flow. Refer to Associating maps with document flow definitions for more information about associating the DTD with the cXML document flow.

The Document Manager uses two attributes of the cXML root element for document management: the payloadID and timestamp. The cXML payloadID and timestamp are used as the document ID number and document timestamp. Both are viewable in the Community Console for document management.

The From and To elements within the cXML header contain the Credential element that is used for document routing and authentication. The following example shows the From and To elements as the source and destination of the cXML document.

Note: Here and throughout this book, all DUNS numbers are meant to be examples only.
<Header>
<From>

            <Credential domain="AcmeUserId">
                <Identity>admin@acme.com</Identity>
            </Credential>
            <Credential domain="DUNS">
                <Identity>130313038</Identity>
            </Credential>
</From
<To>
            <Credential domain="DUNS">
                <Identity>987654321</Identity>
            </Credential>
            <Credential domain="IBMUserId">
                <Identity>test@ibm.com</Identity>
            </Credential>
</To>

If more than one credential element is used, the Document Manager uses the DUNS number as the Business Identifier for routing and authentication. In the case where there is no DUNS number given, the first Credential is used.

WebSphere Partner Gateway does not use the information in the Sender element.

In a synchronous transaction, the From and To header is not used in a cXML response document. The response document is sent through the same HTTP connection that is established by the request document.

cXML document types

A cXML document can be one of three types: Request, Response, or Message.

Request

There are many types of cXML requests. The Request element within the cXML document corresponds to the Document Flow in WebSphere Partner Gateway. Typical request elements are:

The following table shows the relationship between the elements in a cXML request document and document flow definitions within WebSphere Partner Gateway:

cXML element
Document flow definition
cXML DOCTYPE
Protocol
DTD version
Protocol version
Request (type)
For example, OrderRequest
Document flow
Response

The target participant sends a cXML response to inform the source participant of the results of the cXML request. Because the results of some requests might not have any data, the Response element can optionally contain nothing but a Status element. A Response element can also contain any application-level data. During PunchOut, for example, the application-level data is contained in a PunchOutSetupResponse element. The typical Response elements are:

The following table shows the relationship between the elements in a cXML response document and document flow definitions within WebSphere Partner Gateway:

cXML element
Document flow definition
cXML DOCTYPE
Protocol
DTD version
Protocol version
Response (type)
For example, ProfileResponse
Document flow
Message

A cXML message contains the WebSphere Partner Gateway document flow information in the cXML Message element. It can contain an optional Status element identical to that found in a Response element. It would be used in messages that are responses to request messages.

The content of the message is custom defined by the business needs of the user. The element directly below the <Message> element corresponds to the document flow created in WebSphere Partner Gateway. In the following example, SubscriptionChangeMessage is the document flow:

<Message>
<SubscriptionChangeMessage type="new">
           <Subscription>
                <InternalID>1234</InternalID>
                <Name xml:lang="en-US">Q2 Prices</Name>
                <Changetime>1999-03-12T18:39:09-08:00</Changetime>
                <SupplierID domain="DUNS">942888711</SupplierID>
                <Format version="2.1">CIF</Format>
            </Subscription>
</SubscriptionChangeMessage>
</Message>

The following table shows the relationship between the elements in a cXML message and the document flow definitions within WebSphere Partner Gateway:

cXML element
Document flow definition
cXML DOCTYPE
Protocol
DTD version
Protocol version
Message
Document flow

The easiest way to tell the difference between a one-way message and a Request-Response document is the presence of a Message element instead of a request or response element.

A message can have the following attributes:

Content-type headers and attached documents

All cXML documents must contain a Content-type header. For cXML documents without attachments, the following Content-type headers are used:

The cXML protocol supports attachment of external files through MIME. For example, buyers often need to clarify purchase orders with supporting memos, drawings, or faxes. One of the Content-type headers shown in the following list must be used in cXML documents that contain attachments:

The boundary element is any unique text that is used to separate the body from the payload portion of the MIME message. Refer to the cXML User Guide at www.cxml.org for more information.

Valid cXML interactions

WebSphere Partner Gateway supports the following cXML document flow definition interactions:

Creating document flow definitions

Use the following process to create a new document flow definition for a cXML document.

Note: You must ensure that the correct version of cXML is defined before you create a cXML document flow definition. The default is version 1.2.009.

  1. Click Hub Admin > Hub Configuration > Document Flow Definition.
  2. Click Create Document Flow Definition. The Create Document Flow Definitions page is displayed.
  3. Select Document Flow for Document flow type.
  4. Perform one of the following tasks, depending on the type of document:
  5. Enter 1.0 for Version.

    The version number is for reference only. The actual protocol version is derived from the DTD version within the cXML document.

  6. Enter an optional Description.
  7. Select Yes for Document level.
  8. Select Enabled for Status.
  9. Select Yes for all Visibility attributes.
  10. Click on the Package: None folder to expand the package selection options.
  11. Select Protocol: cXML (1.2.009): cXML.
  12. Click Save.

Creating interactions

After you create the document flow definition, set up an interaction for the cXML document.

To create interactions, use the following procedure.

  1. Click Hub Admin > Hub Configuration > Document Flow Definition.
  2. Click Manage Interactions.
  3. Click Create Interaction.
  4. If the cXML document is the source, under Source, expand Package: None and Protocol: cXML, and select Document Flow:<document _flow>. If the cXML document is the target, expand Package: None and Protocol: cXML, and select Document Flow: <document_flow> in the Target column.
  5. Expand the source or target column for the other half of the interaction (the document that will be converted to cXML or the document that will be transformed from cXML) and expand its package and protocol and select its document flow.
  6. Select Pass Through from the Action list at the bottom of the page. (Pass Through is the only valid option supported for cXML documents.)

Copyright IBM Corp. 2003, 2005