BEA Logo BEA WebLogic Collaborate Release 1.0.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   WebLogic Collaborate Doc Home   |   C-Hub Administration   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Configuring Business Protocols

 

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

 


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:

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

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:

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:

  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:

  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.

 


Working with the RosettaNet Router

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

Processing Messages

The following sections describe message processing for the RosettaNet router:

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:

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:

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

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:

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.

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:

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

Security

The following sections describe RosettaNet security:

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

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:

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:

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:

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.