Configuring Business Protocols

 

The following sections describe how to configure and work with business protocols:

• About Business Protocols

• Configuring a Business Protocol

• Working with the RosettaNet Router

 

---

About Business Protocols

A business protocol defines how the c-hub processes business messages, including how to read the messages and how to route the messages to the recipients. A business protocol also specifies persistence, retries, and quality of service. A business protocol is specified by a decoder, a router, a filter, an encoder, and a conversation coordinator. For information about decoders, routers, filters, and encoders, see Message Processing in Introducing the C-Hub.

WebLogic Collaborate enables you to use the following business protocols:

• XOCP (the default protocol for WebLogic Collaborate)

• RosettaNet

You can use logic plug-ins to customize and extend these protocols beyond their out-of-the-box functionality. For information about logic plug-ins, see Developing Logic Plug-Ins in the BEA WebLogic Collaborate Developer Guide. For information about assigning logic plug-ins to business protocols, see Working with Logic Plug-Ins.

 

---

Configuring a Business Protocol

The following sections describe how to configure each type of business protocol that WebLogic Collaborate supports:

• Configuring XOCP

• Configuring RosettaNet

Configuring XOCP

When you create the c-space, specify the XOCP business protocol.

You can use the C-Hub Administration Console or the Bulk Loader to assign a business protocol to a c-space. For information about using these tools, see the following sections:

• Creating a New C-Space in Working with C-Spaces.

• Importing Data into the Repository in Working with the Bulk Loader.

The following listing is an example of how to assign the XOCP business protocol to a c-space by means of a repository data file which is used by the Bulk Loader.

Listing 6-1 Assigning the XOCP Business Protocol

<c-hub name="MyCHub">
        <c-space name="MyCSpace">
                <business-protocol name="XOCP" \
                        url="http://localhost/protocol3"/>
        </c-space>
</c-hub>

Each c-space/business protocol combination has a unique URL. A trading partner uses this URL to access a particular c-space using a particular business protocol. The url attribute for the business-protocol XML element specifies this URL.

Warning: A URL for a c-space/business protocol combination can be used only by the c-hub and c-enablers. If customer-supplied software uses one of these URLs, messages will not be processed correctly.

Configuring RosettaNet

To configure RosettaNet:

1. When you create the c-space, specify the RosettaNet business protocol.

   You can use the C-Hub Administration Console or the Bulk Loader to assign a business protocol to a c-space. For information about using these tools, see the following sections:

   • Creating a New C-Space in Working with C-Spaces.

   • Importing Data into the Repository in Working with the Bulk Loader.

     The following listing is an example of how to assign the RosettaNet business protocol to a c-space by means of a repository data file which is used by the Bulk Loader.

     Listing 6-2 Assigning the RosettaNet Business Protocol

     <c-hub name="MyCHub">
             <c-space name="MyCSpace">
                     <business-protocol name="RosettaNet" \
                             url="http://localhost/protocol1"/>
             </c-space>
     </c-hub>

     Each c-space/business protocol combination has a unique URL. A trading partner uses this URL to access a particular c-space using a particular business protocol. The url attribute for the business-protocol XML element specifies this URL.

     Warning: A URL for a c-space/business protocol combination can be used only by the c-hub and c-enablers. If customer-supplied software uses one of these URLs, messages will not be processed correctly.

2. Create a trading partner protocol and add it for each trading partner that will use the RosettaNet protocol.

   The new trading partner protocol needs to:

   • Reference a RosettaNet business protocol definition.

   • Identify the RosettaNet DUNS numbers for the trading partner that will use the RosettaNet protocol.

   • Specify the URLs that the trading partner will use to access the c-space.

     You can use the C-Hub Administration Console or the Bulk Loader to add a business protocol to a c-space. For information about using these tools, see the following sections:

   • Assigning a Trading Partner to a TP Protocol in Working with Trading Partners.

   • Importing Data into the Repository in Working with the Bulk Loader.

     The following listing is an example of how to define a trading partner protocol for RosettaNet and assign it to trading partners by means of a repository data file which is used by the Bulk Loader.

     Listing 6-3 Defining and Assigning a Trading Partner Protocol

     <c-hub name="MyCHub">
             <trading-partner name="RosettaNetPartner1">
                     <trading-partner-protocol
                             url="http://localhost:9000/Servlet1"
                             business-id="123456789"
                             business-id-type="DUNS"
                             business-protocol-def-name="RosettaNet"/>
             </trading-partner>
             <trading-partner name="RosettaNetPartner2">
                     <trading-partner-protocol
                             url="http://localhost:9000/Servlet2"
                             business-id="987654321"
                             business-id-type="DUNS"
                             business-protocol-def-name="RosettaNet"/>
             </trading-partner>
     </c-hub>

3. Optionally, you can also set the RosettaNet initialization parameters.

   You must use the Bulk Loader to set the RosettaNet initialization parameters. See Importing Data into the Repository in Working with the Bulk Loader.

   The following listing is an example of how to set the initialization parameters for RosettaNet by means of a repository data file which is used by the Bulk Loader.

   Listing 6-4 Initializing RosettaNet Parameters

   <c-hub name="MyCHub">
           <business-protocol-def name="RosettaNet">
                   <java-class>com.bea.b2b.protocol.rosettanet.RNProtocol</java-class>
                   <decoder>RN-Decoder</decoder>
                   <router>RN-Router</router>
                   <router>RN-Router-Enqueue</router>
                   <filter>RN-Filter</filter>
                   <encoder>RN-Encoder</encoder>
                   <parameter name="preamble.validate">false</parameter>
                   <parameter name="serviceheader.validate">false</parameter>
           </business-protocol-def>
   </c-hub>

The following table describes the initialization parameters for the RosettaNet protocol.

Table 6-1 RosettaNet Initialization Parameters

Parameter	Description
preamble.validate	Specifies whether or not to perform full XML validation on the preamble. By default, the c-hub performs full validation. To disable validation, specify a value of false. Any other value causes the c-hub to use the default value of true. You might want to disable validation in case of performance problems or XML parser problems even though you risk not being able to detect invalid XML content.
serviceheader.validate	Specifies whether or not to perform full XML validation on the service header. By default, the c-hub performs full validation. To disable validation, specify a value of false. Any other value causes the c-hub to use the default value of true. You might want to disable validation in case of performance problems or XML parser problems even though you risk not being able to detect invalid XML content.

 

 

---

Working with the RosettaNet Router

The following sections describe how to work with the RosettaNet Router:

• Processing Messages

• Processing XML

• Defining a Conversation

Processing Messages

The following sections describe message processing for the RosettaNet router:

• Message Structure

• Message Processing

• Message Routing and Conversation Information

• Security

• RosettaNet Sender

Message Structure

The following figure shows the structure of a RosettaNet message, which is a RosettaNet Object (RNO) based on the RosettaNet Implementation Framework (RNIF) version 1.1. For details about the RNO, see the RNIF at http://www.rosettanet.org.

Figure 6-1 RosettaNet Object

 

Some sections of the message are binary. For example, the version, the lengths, and the digital signature are binary. The following message sections contain XML:

• Preamble

• Service header

• Service content

Therefore, the message is not a pure XML document, although it includes XML components.

Message Processing

When the c-hub receives a RosettaNet message and sends it to the decoder section of the business protocol for processing:

• The c-hub does not change the message format. The format that the c-hub receives and sends is the one specified by RosettaNet. The c-hub does not perform any additional wrapping or unwrapping of the object, except for the processing described later in this section.

• The c-hub does not validate the digital signature. The receiving trading partner validates the digital signature.

• The c-hub requires read-only access to the message in order to retrieve the information needed for routing. The RosettaNet routing does not modify the message.

• The c-hub requires all the XML components to be available: the preamble, the service header, and the service content. The c-hub requires the first two XML components for message routing. Only the first two XML components are explicitly processed by the c-hub. For information about these components, see Message Routing and Conversation Information.

Because of the previously described processing, the c-hub requires that the following information be valid in order to route the message:

• Content type and content length for the HTTP header

• RosettaNet Implementation Framework (RNIF) version

• RNO content length

• MIME multipart structure, including:

  • Boundaries

  • Number of parts

• Valid XML for the preamble

• Valid XML for the service header

• Valid minimal subset of contents within these two XML forms

The message sender must make sure that the information is valid. If the c-hub detects invalid information, the c-hub cannot route the message correctly, logs an error message, and returns a RosettaNet-defined error status to the message sender.

Neither the c-hub nor the RosettaNet router validate the following information in the message:

• Existence of, or correct values for, the content-type for each MIME component.

• Valid XML for the service content. Because the RosettaNet API allows information to be retrieved from this component, the user of the API must be prepared to handle Java exceptions if the service content fails the parser. For information about the RosettaNet API, see the BEA WebLogic Collaborate Developer Guide.

• Digital signature.

Message Routing and Conversation Information

The c-hub parses the preamble and service header sections of the RNO to construct routing and conversation information. The following list describes the message fields that must be valid and describes how the c-hub uses these fields. For detailed information about these message fields, see the RNIF at http://www.rosettanet.org.

• Preamble

  • //Preamble/VersionIdentifier: The RNIF version number. The only RNIF version that WebLogic Collaborate supports is 1.1.

• Service Header

  • //ServiceHeader/ProcessControl/ProcessIdentity/GlobalProcessIndicator
    Code: The PIP identifier. This typically has a value such as 3A4 and is used as the conversation name. It must be entered as such in the repository.

  • //ServiceHeader/ProcessControl/ProcessIdentity/VersionIdentifier: The version of the PIP specification used. This typically has a value such as 1.1 and should not to be confused with the RNIF version number. It is used as the version number of the conversation. It must be entered as such in the repository.

  • //ServiceHeader/ProcessControl/TransactionControl/PartnerRoleRoute/
    fromRole/PartnerRoleDescription/GlobalPartnerRoleClassificationCode: The role of the message sender. This typically has a value such as Buyer and is used as the role of the message sender in the conversation. It must be entered as such in the repository.

  • //ServiceHeader/ProcessControl/TransactionControl/PartnerRoleRoute/
    toRole/PartnerRoleDescription/GlobalPartnerRoleClassificationCode: The role of the recipient. This typically has a value such as Seller and is used as the role of the recipient in the conversation. It must be entered as such in the repository.

  • //ServiceHeader/ProcessControl/TransactionControl/<<ActionControl|
    SignalControl>>/PartnerRoute/fromPartner/PartnerDescription/
    BusinessDescription/GlobalBusinessIdentifier: The business identifier of the sender of this message. The path description has an OR in the middle, using either the ActionControl element or the SignalControl element. For the unique business identifier, RosettaNet specifies the use of the 9-digit DUNS number. It must be entered as such in the repository. The business identifier identifies the sending trading partner in the conversation.

  • //ServiceHeader/ProcessControl/TransactionControl/<<ActionControl|
    SignalControl>>/PartnerRoute/toPartner/PartnerDescription/Business
    Description/GlobalBusinessIdentifier: The business identifier of the recipient of this message. It is similar to the fromPartner business identifier. The business identifier identifies the recipient trading partner in the conversation.

  • //ServiceHeader/ProcessControl/ProcessIdentity/InstanceIdentifier: A supposedly unique alphanumeric identifier for this business process, although the RosettaNet specification also states that the initiating partner's business identifier (DUNS number) should be used. These two numbers combine to form the conversation ID, which is used for monitoring and auditing, not for routing.

    Note: Neither the c-hub nor RosettaNet enforce the uniqueness of this identifier, especially across multiple vendors. Because the identifier does not play an important role in processing the message, its uniqueness is not critical.

  • //ServiceHeader/ProcessControl/ProcessIdentity/initiatingPartner/Global
    BusinessIdentifier: The initiating partner's business identifier (DUNS number). As stated earlier, this is used to construct the conversation ID.

From the service content, nothing is required. Depending on the nature of the message, the RosettaNet API either provides access to the following document identifier:

• //ServiceContent/thisDocumentIdentifier/ProprietaryDocumentIdentifier: The document identifier. This is the initiating document in the RosettaNet business interaction.

  or it provides access to the following document identifiers:

• //ServiceContent/thisMessageIdentifier/ProprietaryMessageIdentifier: The document identifier. This is a follow-on document in the same RosettaNet business interaction.

• //ServiceContent/receivedDocumentIdentifier/ProprietaryDocumentIdentifier: The initiating document identifier.

For information about the RosettaNet API, see the BEA WebLogic Collaborate Developer Guide.

Security

The following sections describe RosettaNet security:

• SSL

• Digital Signature

For information about WebLogic Collaborate security, see Configuring Security.

SSL

When the c-hub decodes a RosettaNet message that it receives by means of SSL, it performs an additional check to verify that the DUNS identifier of the message sender, as retrieved from the message, matches the sender as identified by the certificate. Because the c-hub is acting as a trusted intermediary, this check validates that the sender is who is claimed before the c-hub passes the message to the recipient. If the match fails, the c-hub rejects the message.

Digital Signature

The c-hub processing layers and business protocols do not generate or validate any digital signature associated with the message. Instead, the trading partner clients must validate the digital signature; the c-hub is simply relaying the message. The c-hub validates only the SSL certificate.

The c-hub supports read-only access to a business message. This access ensures that any accompanying digital signature remains valid. You can still introduce logic plug-ins on the c-hub that can validate digital signatures, but you must provide your own third-party public key infrastructure (PKI) library.

RosettaNet Sender

The following sections describe how the c-hub replies to a trading partner that sends a RosettaNet business message:

• RNIF Statement

• Asynchronous Message Transfer

• Validation Disagreement

• Recipient Unavailability

RNIF Statement

Section 3.2.1 of the RNIF states:

"An application that transfers this RosettaNet Object to a remote Web server via a local Web server requests the HTTP protocol to transfer the object as content using the HTTP/1.0 POST request to a target URL. The recipient receives the HTTP request and immediately checks the HTTP headers. If the content-type or transfer encoding is improper, or if the content length fails to match the actual length of the entity body, the recipient returns a 400 (BAD REQUEST) response. If the request is accepted for processing by upper layers in the protocol, a 200 (OK) response will be returned immediately as an acknowledgment of message receipt."

Asynchronous Message Transfer

RNIF 1.1 is a point-to-point protocol and is not designed to interact with a hub. The c-hub delivers messages to recipients by means of asynchronous message transfer. From a RosettaNet perspective, asynchronous message transfer is a "delegated responsibility" model. To route a RosettaNet message and to decide whether or not to reply with an error, the c-hub performs more message-level validation than the recipient needs. After the c-hub accepts a RosettaNet message, the recipient should accept the message without errors. If the recipient notifies the c-hub of a message error, it is too late for the sending trading partner to be notified. The c-hub logs all message responses.

The message persistence capabilities of the c-hub protect the message while it is in the c-hub. The c-hub detects and reports many of the problems that a RosettaNet recipient might detect. If the RosettaNet client starts processing the message and detects errors at the business rule level (message content), the client uses a separate out-of-band error reporting mechanism that is provided by RosettaNet, and this error reporting mechanism is routed through the c-hub like any other RosettaNet message.

Validation Disagreement

If the c-hub and the recipient disagree about the validation:

• If the c-hub rejects a message as invalid that the recipient would accept, then you must determine which party is non-compliant (the sending trading partner, the c-hub, or the recipient) and take appropriate action. For example, if the c-hub is non-compliant, then you might need to modify the RosettaNet protocol or the initialization parameters.

• If the recipient rejects a message that the c-hub accepted, you must determine the non-compliant party. However, under these circumstances the recipient responds to the c-hub with a BAD REQUEST message, which the c-hub logs. The c-hub cannot initiate RosettaNet error responses to the sending trading partner for a number of reasons, including digital signature implications and lack of support for hub-based error-reporting in RNIF.

Recipient Unavailability

The c-hub can accept a RosettaNet message from a trading partner and return an HTTP 200 to the sending trading partner. However, the recipient might not be available when the c-hub is prepared to deliver the message. In this case, the message will be lost. By using retries and timeouts, the RosettaNet client protocol is robust enough to handle lost messages and no response situations. The c-hub logs the delivery status of all RosettaNet messages.

Processing XML

The RosettaNet router uses information in the preamble and service header. The c-hub uses a validating XML parser to parse the preamble and service header. If the c-hub detects an error, it logs the error and returns the status to the sending trading partner.

The RosettaNet router does not use information in the service content section. The service content is the business-specific section of the message and is handled by the receiving client. The c-hub can provide the service content information for monitoring purposes. If needed, the c-hub parses the service content as a "well-formed" (non-validating) XML document in order to retrieve fields. If the service content is not well-formed, the c-hub logs an error message.

For each XML section, the DOM document can be retrieved. You can then use either the DOM or XPath API to access any element of the document.

Logic plug-ins do not prevent you from parsing XML and processing the service content. Logic plug-ins enable you to filter or monitor messages based on the service content section of the message. You are responsible for the parsing, however, in order to do the filtering.

Defining a Conversation

Conversations are defined in the repository. To define a conversation, do one of the following:

• Use the C-Hub Administration Console as described in Setting Up Conversations.

• Use the Bulk Loader to import data into the repository as described the Importing Data into the Repository section in Working with the Bulk Loader.

The following listing is an example of a conversation definition in a repository data file.

Listing 6-5 Example Conversation Definition Values in a Repository Data File

<conversation-def
    name="3A4"
    version="1.1"
    default-durability="<persistent|nonpersistent>"
    default-conversation-timeout="<timeout-in-seconds>">
    <role
        name="Buyer">
    </role>
    <role
        name="Seller">
    </role>
</conversation-def>

The DTD for the repository data file is WLCHub.dtd, which is in the bulkloader subdirectory of your WebLogic Collaborate installation directory. The WLCHub.dtd file describes the format of and values in a conversation definition.

When you use the C-Hub Administration Console to monitor RosettaNet conversations, the console displays a conversation ID that the c-hub constructs from a RosettaNet message:

<protocol-name>:<PIP-id>:<PIP-version>:<initiator-DUNS>:<process-instance-identifier>

In this conversation ID:

• protocol-name is the protocol name as defined in the repository. For example, "RosettaNet."

• PIP-id is the PIP identifier associated with the message. For example, "3A4."

• PIP-version is the version of the PIP being used. For example, "1.1."

• initiator-DUNS is the DUNS number of the trading partner who initiated the RosettaNet dialog. For example, "123456789."

• process-instance-identifier is the process instance identifier value obtained from the RosettaNet service header. For example, "15902235777701132."

RosettaNet handles conversation management externally. Therefore, this conversation definition does not provide a conversation termination mechanism for terminating RosettaNet clients. The conversation definition provides a time-out mechanism to remove RosettaNet entries. The c-hub uses this mechanism only to remove entries from the monitoring mode of the C-Hub Administration Console. Because the c-hub registers these entries in real time from external RosettaNet clients, new messages succeed and are displayed in the monitoring mode.

The conversation definition also enables you to specify conversation persistence. If the conversation persistence field is set, the RosettaNet protocol processes the messages it passes through the c-hub in a persistent fashion. If the c-hub crashes, the c-hub recovers these messages and continues processing them.