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:

• Business Messages and Message Envelopes

• Run-Time Message Processing

• Working with Message-Context Documents

• Working with XPath Expressions

 

---

Business Messages and Message Envelopes

A business message is the basic unit of communication exchanged between trading partners in a conversation. A business message contains the list of intended recipients for the message. A business message is represented in the B2B integration API by the com.bea.b2b.protocol.messaging.Message interface. The following classes implement this interface and represent protocol-specific business messages:

• com.bea.b2b.protocol.xocp.messaging.XOCPMessage

• com.bea.b2b.protocol.rosettanet.messaging.RNMessage

On receipt of a business message, the B2B engine creates a message envelope that acts as a container for the business message as it is processed through the B2B engine. Message envelopes are instances of the com.bea.b2b.protocol.messaging.MessageEnvelope class.

The message envelope is used for routing purposes and is analogous to a paper envelope for a letter: the message envelope contains the business message plus addressing information, such as the identity of the sender (return address) and a recipient of the business message (destination address), as shown in the following figure.

Figure 2-1 Message Envelope Containing an XOCP Business Message

 

Message envelopes also contain other information about the business message. For detailed information about the MessageEnvelope class, see the BEA WebLogic Integration Javadoc.

 

---

Run-Time Message Processing

The WebLogic Integration B2B engine 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.

Note: The XOCP business protocol is deprecated as of this release of WebLogic Integration. For information about the features that are replacing it, see the BEA WebLogic Integration Release Notes.

• After a trading partner sends an XOCP business message to the B2B engine, a 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 message processing and determines the intended recipients for the message.

• Before WebLogic Integration 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 the message. The second filter logic plug-in is on the receive side of message processing. It can prevent a specific trading partner from receiving a specific business message.

The following figure provides an overview of how the B2B engine processes a message.

Figure 2-2 Overview of Message Processing

 

WebLogic Integration provides a router for supported business protocol. The following figure provides a detailed look at the routers.

Figure 2-3 WebLogic Integration B2B Routers

 

WebLogic Integration provides a filter for supported business protocol. The following figure provides a detailed look at the filters.

Figure 2-4 WebLogic Integration B2B Filters

 

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

Figure 2-5 XOCP Message Processing

 

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

• Send Side

• Receive Side

Send Side

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

• Message XPath Expression

• Transport Service

• Decoder

• Scheduling Service

• XOCP Router

• Routing Service

Message XPath Expression

When sending an XOCP business message, the B2B engine for the sending trading partner can specify a message XPath expression that defines the intended recipients of the business message. This message XPath expression is defined in a business process management (BPM) workflow or in a locally-run B2B integration application. For more information about message XPath expressions, see Creating Message 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 B2B engine.

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 B2B engine. If customer-supplied software uses one of these URLs, messages are not processed correctly.

   For information about configuring business protocols, see Administering B2B Integration.

Decoder

The decoder does the following:

1. Processes the protocol-specific message 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 Integration

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

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

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 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 router expressions in the following order:

   1. Message XPath expression

      Message XPath expressions are included in the business message and therefore always apply to the routing of that business message.

   2. Trading partner XPath router expressions

      These XPath router expressions are defined in the repository for the sending trading partner and apply to all XOCP business messages sent by that trading partner. Each sending trading partner can have multiple trading partner XPath router expressions.

      Each trading partner XPath router 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. Business protocol XPath router expressions

      These XPath router expressions are defined in the repository and apply to all XOCP business messages using a particular business protocol.

      As with trading partner XPath router expressions, each business protocol XPath router 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.

   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. The B2B engine continues to process the message, unless the set of recipient trading partners is empty. In that case, the XOCP router logic plug-in does not forward the message to the next component for processing.

Customer-Supplied Router 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 customer-supplied logic plug-ins, see Creating and Adding Logic Plug-Ins (Deprecated).

After customer-supplied router logic plug-ins are processed, the B2B engine continues to process the message, unless the set of recipient trading partners is empty. In that case, the customer-supplied router logic plug-in does not forward the message to the next component for processing.

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 the B2B engine 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 the 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 Integration

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 business protocol, conversation, sending trading partner, and receiving trading partner. 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 filter 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 filter expressions in the following order:

   1. Trading partner XPath filter expressions.

      These XPath filter expressions are defined in the repository for a recipient trading partner, and apply to all XOCP business messages destined for that trading partner. Each recipient trading partner can have multiple trading partner XPath filter expressions.

      Each trading partner XPath filter expression can examine different parts of the message-context document and return a Boolean result that indicates acceptance or rejection of the message. Processing continues until an expression evaluates to false or all expressions have been processed.

   2. Business protocol XPath filter expressions

      These XPath filter expressions are defined in the repository and apply to all XOCP business messages.

      As with trading partner XPath filter expressions, each business protocol XPath filter expression can examine different parts of the message-context document and return a Boolean result that indicates acceptance or rejection of the message. Processing continues until an expression evaluates to false or all expressions have been processed.

   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 B2B engine. Otherwise, the B2B engine continues to process the message.

Customer-Supplied Filter 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 Logic Plug-Ins (Deprecated).

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 B2B engine. Otherwise, the B2B engine 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 Management Applications for B2B Integration.

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.

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 Message XPath Expressions

• Creating Trading Partner XPath Expressions

• Creating Business Protocol 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 router 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 router 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 router expression to send bid requests to all sellers in a particular area code or to sellers that can handle large orders.

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

  In the XOCP filter logic plug-in, XPath expressions determine whether or not the B2B engine sends a particular business message to a particular trading partner. An XPath filter 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
Message	Evaluated: first # of XPath expressions: one Defined in: BPM workflows or B2B Java applications Purpose: defines recipients Applies to: XOCP business messages from the sender BPM workflows or B2B application	Not applicable
Trading partner	Evaluated: second # of XPath expressions: one or more Defined in: repository (via WebLogic Integration B2B Console or Bulk Loader) Purpose: adds and removes recipients Applies to: all XOCP business messages from the sender trading partner	Evaluated: fourth # of XPath expressions: one or more Defined in: repository (via WebLogic Integration B2B 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
Business protocol	Evaluated: third # of XPath expressions: one or more Defined in: repository (via WebLogic Integration B2B Console or Bulk Loader) Purpose: adds and removes recipients Applies to: all XOCP business messages from all sender trading partners	Evaluated: fifth # of XPath expressions: one or more Defined in: repository (via WebLogic Integration B2B 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 router 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 router expressions can be used.

Table 2-2 Example for XPath Router Expressions

XPath Expression	Resulting Set of Recipient Trading Partners
1. The message XPath expression selects trading partners A and B.	A, B
2. The first trading partner XPath router expression adds trading partner C.	A, B, C
3. The second trading partner XPath router expression replaces all previously selected trading partners with trading partner D.	D
4. The first business protocol router expression, adds trading partners B and F.	D, B, F
5. The second business protocol router expression removes trading partner F.	D, B

 

In the XOCP filter logic plug-in, each XPath filter 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 filter expression can return true or false using different selection criteria. When an XPath filter 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 in the WebLogic Integration B2B Console

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

For more information on XPath Expressions, see Advanced Configuration Tasks in Administering B2B Integration.

Creating Message XPath Expressions

When sending an XOCP business message, the sender trading partner can specify a message XPath expression, which defines the intended recipients for the business message. The message XPath router expression is defined in a business process management workflow or in a WebLogic Integration B2B Java 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 trading partner defines this XPath expression and sends it along with the message. An XPath expression is defined for B2B integration as follows:

• If a BPM workflow is used to exchange business messages, the XPath expression is defined in the workflow template and applied when a trading partner sends the message to another trading partner. Use the Send Business Message dialog box in the WebLogic Integration Studio to define the XPath expression. For more information, see Creating Workflows for B2B Integration.

• If a Java application is used to exchange business messages, the XPath expression is defined in the Java application. 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 B2B Integration.

  Note: In many cases, a trading partner sends a business message to another single, known trading partner; for example, when replying to a request from that trading partner. In this case, the sender trading partner can bypass the evaluation of XPath expressions in the XOCP router logic plug-in by specifying the name of the recipient trading partner 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 B2B Integration. 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 Integration B2B Console as described in Using Logic Plug-Ins in Online Help for the WebLogic Integration B2B Console.

  The following table describes the properties that you set when using the B2B Console to define XPath expressions.

  Table 2-3 Properties for XPath Expressions in the B2B Console

  Component	Description
  XPath Expression	XPath router or filter 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.

  
   

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

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

Creating Business Protocol XPath Expressions

A business protocol XPath expression is an XPath expression that is defined in the WebLogic Integration repository for a particular business protocol. Business protocol XPath router expressions apply to all incoming business messages using that protocol. Business protocol XPath filter expressions apply to all outgoing XOCP business messages.

Business protocol XPath expressions are defined in the repository. You can use the following tools to create 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 B2B Integration. 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 Integration B2B Console as described in Using Logic Plug-Ins in Online Help for the WebLogic Integration B2B Console.

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

  For example, an 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 B2B Console to create the following XPath expression for the XOCP filter logic plug-in:

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