Routing and Filtering Business Messages

 

The following sections describe how to use routing, filtering, and Xpath expressions to control the flow of business messages exchanged among trading partners using BEA WebLogic Collaborate:

• Run-Time Message Processing

• Working with Message-Context Documents

• Working with XPath Expressions

 

---

Run-Time Message Processing

BEA WebLogic Collaborate uses logic plug-ins, acting as either routers or filters, to direct the flow of business messages to trading partners. The following example illustrates how this process is implemented for XOCP business messages.

• After a trading partner sends an XOCP business message to WebLogic Collaborate, the logic plug-in, acting as an XOCP router, determines the trading partners to which the message is sent. The router logic plug-in is on the send side of WebLogic Collaborate message processing and determines the recipients to which the sending trading partner intends to send the message.

• Before WebLogic Collaborate sends the business message to a recipient trading partner, a second logic plug-in, acting as an XOCP filter, determines whether or not the trading partner should receive it. The second logic plug-in is on the receive side of WebLogic Collaborate message processing and it can prevent a specific trading partner from receiving a specific business message.

The following figure provides an overview of how WebLogic Collaborate processes a message.

Figure 2-1 Overview of Message Processing

 

A router is provided for each business protocol that WebLogic Collaborate supports. The following figure provides a detailed look at the routers.

Figure 2-2 WebLogic Collaborate Routers

 

A separate filter is provided for each business protocol that WebLogic Collaborate supports. The following figure provides a detailed look at the filters.

Figure 2-3 WebLogic Collaborate Filters

 

The following figure provides a detailed look at how WebLogic Collaborate processes an XOCP business message. Processing for RosettaNet business messages is handled in a similar manner, as discussed in Implementing RosettaNet for BEA WebLogic Collaborate.

Figure 2-4 XOCP Message Processing

 

The following sections explain how the send and receive sides of WebLogic Collaborate process an XOCP business message:

• Send Side

• Receive Side

Send Side

The following sections describe the components on the send side of WebLogic Collaborate and explain how they process an XOCP business message:

• WebLogic Collaborate XPath Expression

• Transport Service

• Decoder

• Scheduling Service

• XOCP Router

• Routing Service

WebLogic Collaborate XPath Expression

When sending an XOCP business message, the WebLogic Collaborate instance for the sending trading partner can specify a local XPath expression that defines the intended recipients for the business message. The local XPath expression is defined in a WebLogic Process Integrator workflow or in a locally-run WebLogic Collaborate application. For more information about XPath expressions, see Creating WebLogic Collaborate XPath Expressions.

Transport Service

The transport service reads the incoming XOCP business message and does the following:

1. Wraps the message in a message envelope to expedite processing as it travels through the WebLogic Collaborate instance.

2. Forwards the message to the appropriate decoder based on the business protocol, such as XOCP, RosettaNet, or cXML. The URL at which the transport service receives the message identifies the protocol and the delivery channel. Each delivery channel/business protocol combination has a unique URL. A trading partner uses this URL to access a particular delivery channel using a particular business protocol.

   Warning: A URL for a delivery channel/business protocol combination can be used only by the WebLogic Collaborate instance. If customer-supplied software uses one of these URLs, messages are not processed correctly.

   For information about configuring business protocols, see Administering BEA WebLogic Collaborate.

Decoder

The decoder does the following:

1. Processes the protocol-specific headers.

2. Identifies the sending trading partner.

3. Enlists the sending trading partner in a conversation.

4. Prepares a reply to return to the sender.

5. Forwards the message to the scheduling service.

Scheduling Service

The scheduling service enqueues the message to store it for subsequent retrieval by the XOCP router.

XOCP Router

The XOCP router is a chain of logic plug-ins that specifies the recipients for the XOCP business message. Each logic plug-in can add trading partners to or remove trading partners from the set of recipient trading partners.

The logic plug-ins in the XOCP router are arranged in the following order:

1. XOCP router logic plug-in—provided by WebLogic Collaborate

2. Customer-supplied logic plug-ins—optional logic plug-ins that you can create

3. XOCP router enqueue logic plug-in—provided by WebLogic Collaborate

The following sections describe these logic plug-ins.

XOCP Router Logic Plug-In

The XOCP router logic plug-in does the following:

1. Creates a message-context document.

   A message-context document is an XML document that the XOCP router logic plug-in generates from the XOCP business message and associated information in the repository. The message-context document describes header and content information about the XOCP business message, such as the hub, business protocol, conversation, sending trading partner, and receiving trading partners. The XOCP router logic plug-in uses XPath expressions to evaluate the message-context document. For more information about message-context documents, see Working with Message-Context Documents.

2. Evaluates the message-context document against the XPath routing expressions, which can refer to values in the message-context document. This evaluation results in a set of trading partners that are targeted to receive the XOCP business message.

   The XOCP router logic plug-in uses the XPath routing expressions in the following order:

   1. Sender WebLogic Collaborate instance XPath expression

      For information about WebLogic Collaborate XPath expressions, see Working with XPath Expressions and Creating WebLogic Collaborate XPath Expressions.

   2. Sequence of sending trading partner XPath routing expressions

      These XPath routing expressions are defined in the repository and are defined for the sending trading partner. Each trading partner XPath routing expression applies to all XOCP business messages that WebLogic Collaborate receives from a particular sending trading partner. Each sending trading partner can have multiple trading partner XPath routing expressions.

      Each trading partner XPath routing expression can examine different parts of the message-context document and select a different set of recipient trading partners. The trading partners produced by each expression can either replace the previously generated set of recipient trading partners or add to the current set.

   3. Sequence of WebLogic Collaborate XPath routing expressions

      These XPath routing expressions are defined in the repository and are defined for WebLogic Collaborate. Each WebLogic Collaborate XPath routing expression applies to all XOCP business messages that WebLogic Collaborate receives for all sending trading partners. WebLogic Collaborate can have multiple XPath routing expressions.

      As with trading partner XPath routing expressions, each WebLogic Collaborate XPath routing expression can examine different parts of the message-context document and return a Boolean result that indicates acceptance or rejection of the message.

      You can add XPath expressions to the repository for use by the XOCP router logic plug-in. For information about XPath expressions, see Working with XPath Expressions.

3. Discards the message-context document.

4. If the set of recipient trading partners is empty, then the XOCP router logic plug-in does not forward the message to the next component in WebLogic Collaborate. Otherwise, the WebLogic Collaborate instance continues to process the message.

Customer-Supplied Logic Plug-Ins

You can create logic plug-ins and add them to the XOCP router. If you create a new logic plug-in, you must add it to the chain after the XOCP router logic plug-in and before the XOCP router enqueue logic plug-in. The order of the logic plug-ins in the XOCP router chain is specified in the XOCP business protocol definition.

A customer-supplied logic plug-in does not have to provide router functionality to be part of the XOCP router. For example, a customer-supplied logic plug-in can provide billing functionality by keeping track of the number of messages sent by a particular sending trading partner and then billing the trading partner for those messages. Even when a customer-supplied logic plug-in does not provide routing or filtering functionality, it can be added only to the XOCP router or the XOCP filter. For more information about logic plug-ins, see Creating and Adding Plug-Ins.

If the set of recipient trading partners is empty after the processing performed by a customer-supplied router logic plug-in, then the customer-supplied router logic plug-in does not forward the message to the next component in WebLogic Collaborate. Otherwise, WebLogic Collaborate continues to process the message.

XOCP Router Enqueue Logic Plug-In

The XOCP router enqueue logic plug-in does the following:

1. Enqueues the XOCP business message along with the intended recipients.

2. Forwards the message to the routing service.

Routing Service

The routing service does the following:

1. Performs the final validation of the message recipients.

2. Creates a separate message envelope for each validated recipient trading partner.

3. Forwards each copy of the message envelope to the XOCP filter.

Receive Side

The following sections describe the components on the receive side of WebLogic Collaborate and explain how they process an XOCP business message:

• XOCP Filter

• Scheduling Service

• Encoder

• Transport Service

XOCP Filter

The XOCP filter is a chain of logic plug-ins that determines whether or not to send an XOCP business message to an intended recipient. These logic plug-ins are evaluated after the XOCP router logic plug-ins; they can modify or override the XOCP router results. Each logic plug-in can determine not to send the message.

The logic plug-ins in the XOCP filter are arranged in the following order:

1. Customer-supplied logic plug-ins—optional logic plug-ins that you can create

2. XOCP filter logic plug-in—provided by WebLogic Collaborate

The following sections describe these logic plug-ins.

XOCP Filter Logic Plug-In

The XOCP filter logic plug-in does the following:

1. Creates a message-context document.

   A message-context document is an XML document that the XOCP filter logic plug-in generates from the XOCP business message and associated information in the repository. The message-context document describes header and content information about the XOCP business message, such as the hub, business protocol, conversation, sending trading partner, and receiving trading partners. The XOCP filter logic plug-in uses XPath expressions to evaluate the message-context document. For more information about message-context documents, see Working with Message-Context Documents.

2. Evaluates the message-context document against the XPath filtering expressions, which can refer to values in the message-context document. This evaluation determines whether or not to send the message to the intended recipient.

   The XOCP filter logic plug-in uses the XPath filtering expressions in the following order:

   1. Sequence of trading partner XPath filtering expressions.

      These XPath filtering expressions are defined in the repository and are defined for the recipient trading partner. Each trading partner XPath filtering expression applies to all XOCP business messages that WebLogic Collaborate receives for a particular recipient trading partner. Each recipient trading partner can have multiple trading partner XPath filtering expressions.

      Each trading partner XPath filtering expression can examine different parts of the message-context document and return a Boolean result that indicates acceptance or rejection of the message.

   2. Sequence of WebLogic Collaborate XPath filtering expressions

      These XPath filtering expressions are defined in the repository and are defined for WebLogic Collaborate. Each WebLogic Collaborate XPath filtering expression applies to all XOCP business messages that WebLogic Collaborate receives for all recipient trading partners. WebLogic Collaborate can have multiple XPath filtering expressions.

      As with trading partner XPath filtering expressions, each WebLogic Collaborate XPath filtering expression can examine different parts of the message-context document and return a Boolean result that indicates acceptance or rejection of the message.

      You can add XPath expressions to the repository for use by the XOCP filter logic plug-in. For information about XPath expressions, see Working with XPath Expressions.

3. Discards the message-context document.

4. If the XOCP filter logic plug-in cancels delivery of the XOCP business message to the intended recipient, then the XOCP filter logic plug-in does not forward the message to the next component in the WebLogic Collaborate instance. Otherwise, WebLogic Collaborate continues to process the message.

Customer-Supplied Logic Plug-Ins

You can create logic plug-ins and add them to the XOCP filter. If you create a new logic plug-in, you must add it to the chain before the XOCP filter logic plug-in. The order of the logic plug-ins in the XOCP filter chain is specified in the XOCP business protocol definition.

A customer-supplied logic plug-in does not have to provide filter functionality to be part of the XOCP filter. For example, a customer-supplied logic plug-in can provide sampling functionality by keeping track of the types of messages sent to a particular recipient trading partner. Even when a customer-supplied logic plug-in does not provide routing or filtering functionality, it can be added only to the XOCP router or the XOCP filter. For more information about logic plug-ins, see Creating and Adding Plug-Ins.

If the customer-supplied logic plug-ins cancel delivery of the XOCP business message to the intended recipient, then the customer-supplied filter logic plug-in does not forward the message to the next component in the WebLogic Collaborate instance. Otherwise, WebLogic Collaborate continues to process the message.

Scheduling Service

The scheduling service does the following:

1. Performs additional internal operations related to quality of service issues and conversation management. For information about quality of service, see Programming BEA WebLogic Collaborate Messaging Applications.

2. Forwards the message to the encoder.

Encoder

The encoder transforms the message as necessary to support the business protocol and forwards the message to the transport service.

Transport Service

The transport service sends the message to the recipient.

 

---

Working with Message-Context Documents

For information about how message-context documents are created and used, see XOCP Router Logic Plug-In and XOCP Filter Logic Plug-In. This section describes the DTD for the message-context document.

The following listing is the Document Type Definition (DTD) for the message-context document.

Listing 2-1 Document Type Definition for Message-Context Document

<!--	Copyright (c) 2001 BEA Systems, Inc. -->
<!--	All rights reserved                  -->

<!-- This DTD describes the message context document for XPATH routers and filters -->

<!ELEMENT wlc (business-protocol, conversation, sender, trading-partner+) >
<!ATTLIST wlc context ( message-router | trading-partner-router | hub-router | trading-partner-filter | hub-filter ) #REQUIRED >

<!ELEMENT business-protocol EMPTY >
<!ATTLIST business-protocol name CDATA #REQUIRED >
<!ATTLIST business-protocol version  CDATA #REQUIRED >

<!ELEMENT conversation EMPTY >
<!ATTLIST conversation name CDATA #REQUIRED >
<!ATTLIST conversation version CDATA #REQUIRED >
<!ATTLIST conversation sender-role CDATA #REQUIRED >
<!ATTLIST conversation receiver-role CDATA #REQUIRED >

<!-- A sender is a trading-partner that has sent a message from a role in a conversation. -->
<!ELEMENT sender ( trading-partner ) >

<!-- A Trading Partner represents an entity such as a company that sends or receives messages. -->
<!ELEMENT trading-partner ( address, extended-property-set* ) >
<!ATTLIST trading-partner email CDATA #IMPLIED >
<!ATTLIST trading-partner fax CDATA #IMPLIED >
<!ATTLIST trading-partner name ID #REQUIRED >
<!ATTLIST trading-partner phone CDATA #IMPLIED >

<!ELEMENT address ANY >

<!ELEMENT extended-property-set ANY >
<!ATTLIST extended-property-set name CDATA #REQUIRED >

 

---

Working with XPath Expressions

This section describes XPath expressions and how to create them:

• About XPath Expressions

• Creating WebLogic Collaborate XPath Expressions

• Creating Trading Partner XPath Expressions

• Creating WebLogic Collaborate XPath Expressions

About XPath Expressions

XPath is the XML path language that is defined by the World Wide Web Consortium. The XOCP router logic plug-in and the XOCP filter logic plug-in use XPath expressions to evaluate message-context documents. You can add XPath expressions to the repository for use by the XOCP router logic plug-in and the XOCP filter logic plug-in.

XPath expressions in the XOCP router logic plug-in and XOCP filter logic plug-in perform the following functions:

• An XPath routing expression uses the XPath syntax to select a set of trading partners from the message-context document. These trading partners are the intended recipients of the XOCP business message. Each XPath routing expression must evaluate to a set of trading partners.

  In the XOCP router logic plug-in, XPath expressions specify the business criteria for message distribution. For example, a buyer can use an XPath routing expression to send bid requests to all sellers in a particular area code or to sellers that can handle large orders.

• An XPath filtering expression uses the XPath syntax to return a Boolean result that indicates acceptance or rejection of the message. Each XPath filtering expression must evaluate to a Boolean true or false result.

  In the XOCP filter logic plug-in, XPath expressions determine whether or not WebLogic Collaborate sends a particular business message to a particular trading partner. An XPath filtering expression in the XOCP filter logic plug-in acts as a gatekeeper that filters out unwanted business messages for a receiving trading partner.

The following table provides an overview of the various types of XPath expressions.

Table 2-1 Overview of Types of XPath Expressions

Type of XPath Expression	XOCP Router Logic Plug-In	XOCP Filter Logic Plug-In
Run-Time	Evaluated: first # of XPath expressions: one Defined by: WebLogic Collaborate instance (in workflow or application) Purpose: defines recipients Applies to: XOCP business messages from the sending WebLogic Collaborate instance	Not applicable
Trading partner	Evaluated: second # of XPath expressions: one or more Defined in: repository (via Administration Console or Bulk Loader) Purpose: adds and removes recipients Applies to: all XOCP business messages from the sending trading partner	Evaluated: fourth # of XPath expressions: one or more Defined in: repository (via Administration Console or Bulk Loader) Purpose: determines whether or not to send the message to the recipient Applies to: all XOCP business messages to the recipient trading partner
XOCP hub	Evaluated: third # of XPath expressions: one or more Defined in: repository (via Administration Console or Bulk Loader) Purpose: adds and removes recipients Applies to: all XOCP business messages from all sending trading partners	Evaluated: fifth # of XPath expressions: one or more Defined in: repository (via Administration Console or Bulk Loader) Purpose: determines whether or not to send the message to the recipient Applies to: all XOCP business messages to all recipient trading partners

 

In the XOCP router logic plug-in, each XPath routing expression can examine different parts of the message-context document and select a different set of recipient trading partners. The trading partners produced by each expression can either replace the previously generated set of recipient trading partners or add to the current set.

The following table steps through an example that shows how XPath routing expressions can be used.

Table 2-2 Example for XPath Routing Expressions

XPath Expression	Resulting Set of Recipient Trading Partners
1. The XOCP spoke XPath expression selects trading partners A and B.	A, B
2. A trading partner XPath routing expression adds trading partner C.	A, B, C
3. A subsequent trading partner XPath routing expression replaces all previously selected trading partners with trading partner D.	D
4. An XOCP hub XPath routing expression adds trading partners B and F.	D, B, F
5. A subsequent XOCP hub XPath routing expression removes trading partner F.	D, B

 

In the XOCP filter logic plug-in, each XPath filtering expression can examine different parts of the message-context document to determine whether or not to forward the message to the recipient trading partner. Each XPath filtering expression can return true or false using different selection criteria. After an XPath filtering expression returns false, the message is blocked from further evaluation and is not sent to the intended recipient.

An XPath expression can refer to the following kinds of information:

• Trading partner attributes, including:

  • Standard attributes, such as the trading partner name or a postal code

  • Extended attributes, which are custom attributes defined by the WebLogic Collaborate administrator

• Message information, such as the type of business document, a purchase order number, or an invoice amount

For more information on XPath Expressions, see Administering BEA WebLogic Collaborate.

Creating WebLogic Collaborate XPath Expressions

When sending an XOCP business message, the WebLogic Collaborate instance for the sending trading partner can specify a WebLogic Collaborate XPath expression that defines the intended recipients for the business message. The WebLogic Collaborate XPath expression is defined in a WebLogic Process Integrator workflow or in a WebLogic Collaborate application. This XPath expression selects a subset of <trading-partner> nodes from the message-context XML document that the XOCP router logic plug-in generates.

The sending WebLogic Collaborate instance defines this XPath expression and sends it to the XOCP hub along with the message. WebLogic Collaborate defines an XPath expression as follows:

• If WebLogic Collaborate uses a workflow to exchange business messages, the XPath expression is defined in the workflow definition template and applied when the WebLogic Collaborate instance sends the message to another WebLogic Collaborate instance. Use the Send Business Message dialog to define the XPath expression. For more information, see Creating Workflows for BEA WebLogic Collaborate.

• If WebLogic Collaborate uses a WebLogic Collaborate application to exchange business messages, the XPath expression is defined in the WebLogic Collaborate application when it sends the message to another WebLogic Collaborate instance. Call the setExpression method on the com.bea.b2b.protocol.messaging.Message instance, passing the XPath expression as the parameter. For more information, see Creating Workflows for BEA WebLogic Collaborate.

  Note: In many cases, a WebLogic Collaborate application sends a business message to a single, known trading partner; for example, when replying to a request from that trading partner. In this case, a WebLogic Collaborate application can bypass the evaluation of XPath expressions in the XOCP router logic plug-in by specifying a trading partner name instead of an XPath expression. To specify a trading partner name, call the setRecipient method instead of setExpression on the com.bea.b2b.protocol.messaging.Message instance.

Creating Trading Partner XPath Expressions

A trading partner XPath expression is an XPath expression that is defined for a trading partner. For routing, a trading partner XPath expression is used by the XOCP router logic plug-in and is defined for the sending trading partner. For filtering, a trading partner XPath expression is used by the XOCP filter logic plug-in and is defined for the receiving trading partner.

Trading partner XPath expressions are defined in the repository. You can use the following tools to create trading partner XPath expressions for the XOCP router logic plug-in and the XOCP filter logic plug-in:

• Bulk Loader as described in Working with the Bulk Loader in Administering BEA WebLogic Collaborate. The format for an XPath expression in a repository data file is:

  <xpath-expression expression="//TradingPartner1" location="ROUTER" type="APPEND"/>

  For more information about XPath syntax and usage, see the "XML Path Language Specification," published by the World Wide Web Consortium, at the following URL:

  http://www.w3.org/TR/xpath.html

• WebLogic Collaborate Administration Console as described in the BEA WebLogic Collaborate Administration Console Online Help.

  The following table describes the properties that you set when using the WebLogic Collaborate Administration Console to define XPath expressions for trading partners and the WebLogic Collaborate instance.

  Table 2-3 Properties for XPath Expressions

  Component	Description
  XPath Expression	XPath routing or filtering expression as previously described.
  Type	Flag that specifies whether the results of evaluating the XPath expression append or replace the results of the evaluations of the previous XPath expressions.

  
   

As another example, a trading partner might want to route requests to trading partners that are located in California. To do this, the trading partner can use the detail window on the Trading Partners tab in the WebLogic Collaborate Administration Console to create the following XPath expression for the XOCP router logic plug-in:

/hub/trading-partner[extended-property-set/state='California']

Creating WebLogic Collaborate XPath Expressions

A WebLogic Collaborate XPath expression is an XPath expression that is defined for a business protocol. For routing, a WebLogic Collaborate XPath expression is used by the XOCP router logic plug-in and is defined for all the XOCP business messages that pass through the WebLogic Collaborate instance. For filtering, a WebLogic Collaborate XPath expression is used by the XOCP filter logic plug-in and is defined for all the XOCP business messages that pass through the WebLogic Collaborate instance.

WebLogic Collaborate XPath expressions are defined in the repository. You can use the following tools to create WebLogic Collaborate XPath expressions for the XOCP router logic plug-in and the XOCP filter logic plug-in:

• Bulk Loader as described in Working with the Bulk Loader in Administering BEA WebLogic Collaborate. The format for an XPath expression in a repository data file is:

  <xpath-expression expression="//TradingPartner1" location="ROUTER" type="APPEND"/>

  For more information about XPath syntax and usage, see the "XML Path Language Specification," published by the World Wide Web Consortium, at the following URL:

  http://www.w3.org/TR/xpath.html

• WebLogic Collaborate Administration Console as described in the BEA WebLogic Collaborate Administration Console Online Help.

  Table 2-3 describes the properties that you set when using the WebLogic Collaborate Administration Console to define an XPath expression.

For example, a WebLogic Collaborate administrator might want to filter messages for trading partners that are shippers so that they receive only shipping requests, while all other types of trading partners receive all messages. To do this, the administrator can use the Business Protocol Definitions tab in the WebLogic Collaborate Administration Console to create the following XPath expression for the XOCP filter logic plug-in:

/hub/trading-partner/extended-property-set/business='shipper') OR (/hub/trading-partner/extended-property-set/business!='shipper')