Introducing Trading Partner Integration

Introducing ebXML Solutions

This topic provides an introduction to implementing ebXML solutions with WebLogic Integration. It contains the following sections:

This topic focuses on information that is relevant to ebXML solutions only. Before you begin, be sure to read the Introduction to learn basic concepts for integrating trading partners using WebLogic Integration. In addition, for a hands-on walkthrough of building example ebXML solutions, see "Tutorial: Building ebXML Solutions," in Tutorials for Trading Partner Integration, which is available at:

Documentation and Example Files

http://dev2dev.bea.com/code/wli.jsp

Documentation Only

http://download.oracle.com/docs/cd/E13214_01/wli/docs81/tptutorial/ebxml.html

About ebXML Solutions

An ebXML solution is any WebLogic Integration solution that involves exchanging business messages with trading partners using the ebXML business protocol. This topic describes ebXML and how it is supported in WebLogic Integration. It contains the following sections:

About ebXML

The ebXML business protocol is sponsored by UN/CEFACT and OASIS. The ebXML Web site (http://www.ebxml.org) describes ebXML as "a modular suite of specifications that enables enterprises of any size and in any geographical location to conduct business over the Internet. Using ebXML, companies now have a standard method to exchange business messages, conduct trading relationships, communicate data in common terms and define and register business processes."

ebXML Specifications

WebLogic Integration supports the following ebXML specifications:

ebXML Message Service Specification v2.0
ebXML Message Service Specification v1.0

These specification defines the message envelope and header document schema used to transfer ebXML messages with a communication protocol such as HTTP. They provide a set of layered extensions to the base Simple Object Access Protocol (SOAP) and SOAP Messages with Attachments specifications. The ebXML Message Service provides security and reliability features that are not provided in the specifications for SOAP and SOAP Messages with Attachments. For more information about these and other ebXML specifications, see the http://www.ebxml.org/specs/index.htm page on the ebXML web site.

SOAP Specifications

Information about SOAP, including the following documents, can be found at the World Wide Web Consortium (W3C) Web site (http://www.w3c.org):

Simple Object Access Protocol (SOAP) 1.1at the following URL:

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

SOAP Messages with Attachments at the following URL:

http://www.w3.org/TR/2000/NOTE-SOAP-attachments-20001211

ebXML Support in WebLogic Integration

This topic describes supported and unsupported ebXML features in this release of WebLogic Integration.

Supported ebXML 1.0 and 2.0 Features

WebLogic Integration supports the following ebXML 1.0 and ebXML 2.0 features:

Table 2-1 WebLogic Integration Support for ebXML 1.0 and 2.0 Features

Feature	Support
Packaging	For ebXML 1.0 and 2.0—SOAP, SOAP headers, and attachments
Security	Transport-level security: HTTP/S Message-level security: digital signatures (XML DSig) for protection of the entire message from message tampering (ebXML 1.0 and 2.0). For more information, see Trading Partner Integration Security.
Reliable Messaging	ebXML 1.0: Best effort, and Once and only once ebXML 2.0: At least once, At most once, Best effort, and Once and only once For more information, see Reliable Messaging.
Clustering, High Availability, and Recovery	For ebXML 1.0 and 2.0

Unsupported ebXML 2.0 Features

This release of WebLogic Integration does not support certain optional features of ebXML2.0, including:

Message Status Service
Synchronous reply mode of communication
Message Order Module
Multi-Hop Module

This release does not provide XML DSIG at each payload level of an ebXML message.

Interoperability with WebLogic Integration - Business Connect

WebLogic Integration - Business Connect is a lightweight client that implements the ebXML business protocol. WebLogic Workshop business processes can exchange ebXML business messages with trading partners that use WebLogic Integration - Business Connect. For more information about WebLogic Integration - Business Connect, see the following URL:

http://download.oracle.com/docs/cd/E13215_01/wlibc/docs81/index.html

Note: When exchanging ebXML messages with a trading partner that uses WebLogic Integration - Business Connect, you can only use one version of the ebXML Message Service protocol (either ebXML 1.0 or ebXML 2.0). WebLogic Integration - Business Connect uses the same HTTP endpoint for a given trading partner regardless of the ebXML version. You cannot configure more than one protocol binding for a given partner in WebLogic Integration that uses the same HTTP endpoint.

In addition, XML Digital Signatures cannot be used to when receiving ebXML messages from WLI Business Connect using ebXML MS 1.0. Instead, ebXML MS 2.0 should be used.

ebXML Concepts

This topic describes ebXML concepts that you need to understand before implementing ebXML business processes in WebLogic Integration. It contains the following sections:

ebXML Protocol Layer

The ebXML protocol layer provides the ability to send and receive messages via the Internet according to the ebXML Message Service specifications for transport, message packaging, and security. The ebXML 1.0 and 2.0 message service specifications are independent of the communication protocol used. WebLogic Integration supports the HTTP(S) communication protocol.

ebXML Business Messages

A business message is the basic unit of communication between trading partners. Business messages are exchanged as part of a conversation. The roles in a conversation are implemented by business processes, which choreograph the exchange of business messages.

Diagram of an ebXML Business Message

The following figure represents the structure of a business message exchanged in a conversation based on the ebXML business protocol.

Figure 2-1 ebXML Business Message

ebXML Business Message

An ebXML business message contains one XML business document and one or more attachments. An ebXML message is a communication protocol-independent MIME/Multipart message envelope, referred to as a message package. All message packages are structured in compliance with the SOAP Messages with Attachments specification.

Logical MIME Parts of an ebXML Business Message

The message package shown in the preceding figure illustrates the following logical MIME parts:

Header Container—Logical container in which one SOAP 1.1-compliant message is stored. This SOAP message is an XML document; its root element is the SOAP Envelope, which, in turn, contains the following elements:

SOAP Header—Contains ebXML-specific header elements, including the ebXML MessageHeader element that specifies details such as from and to business IDs, service that relates to the business process, and action that relates to a node in the business process. The SOAP Header is a generic mechanism for adding features to a SOAP message.
SOAP Body—Container for message service handler control data and information related to the payload parts of the message.

Payload Container—Zero or more payloads. Each payload can contain XML or non-XML (binary) data.

WebLogic Integration provides a mechanism in WebLogic Workshop business processes for retrieving the ebXML message envelope that relates to the Header container from incoming business messages. For more information, see jpd:ebxml-method Annotation and jc:ebxml Annotation in the WebLogic Workshop Help.

Message Attachments

An ebXML message can have any combination of payloads. The payloads can be all binary, all XML, or a mixture of both. Any payload is sent as a MIME attachment to the SOAP message—the SOAP body is not used to carry the payload.

WebLogic Integration provides a MessageAttachment[] data type that business processes can use to retrieve payloads from an ebXML message, particularly when payloads consist of mixed data types or when the number of payloads or the order of payloads is not known in advance. It provides methods for determining the content of a payload (isXmlObject and isRawData) and retrieving the contents of the payload (getXmlObject and getRawData) as untyped XML data (XmlObject data type) or non-XML data (RawData data type). To learn about working with MessageAttachment objects, see Using Message Attachments in the WebLogic Workshop Help.

Reliable Messaging

The ebXML business protocol supports reliable messaging, an optional but important capability that allows you to configure different levels of quality of delivery service. Reliable messaging has a reliability versus performance trade-off, as increasing the level of guarantee increases run-time requirements on system resources. You configure reliable messaging in the WebLogic Integration Administration Console, as described in "Defining an ebXML 1.0 or 2.0 Binding" in "Defining Protocol Bindings" in Trading Partner Management in Managing WebLogic Integration Solutions.

Of the eight qualities of service policies defined in the ebXML 2.0 Specification, WebLogic Integration supports the following four (non-multihop) policies, which determine how acknowledgements and duplicate messages are handled:

Table 2-2 Supported Reliable Messaging Policies

Policy	Description
Best Effort (ebXML 1.0 and 2.0)	Best effort. No reliable messaging (no acknowledgement or duplicate elimination).
Once and Only Once (ebXML 1.0 and 2.0)	Requires acknowledgement and duplicate elimination. If a message is not acknowledged, it is resent. If a duplicate message is received, it is ignored. If this policy is selected, you can specify: Number of Retries—Number of times WebLogic Integration resends a message in specific situations, such as timeouts, network failures, and so on. Interval—Number of seconds that WebLogic Integration waits before trying to resend a message. Persistence Duration—(Optional) Amount of time the message will be kept in the repository. After this time, the message will be deleted and any subsequent message sent with same ID will not be considered a duplicate. If specified, the configured persistence duration must be greater than the internally set TimeToLive, which is calculated as: ( ( Retries +1) * RetryInterval) < TimeToLive < Persistence Duration
Atleast Once (ebXML 2.0 only)	Requires acknowledgement, but not duplicate elimination. If selected, you can specify the number of retries and persistence duration.
Atmost Once (ebXML 2.0 only)	Requires duplicate elimination, but not acknowledgement.

ebXML Business Processes

This topic describes WebLogic Workshop business processes that implement ebXML conversations. It contains the following sections:

Guidelines for Building ebXML Business Processes

When designing business processes for ebXML solutions, consider the following guidelines:

You should thoroughly understand the content, choreography, roles, and other aspects of the business processes that you want to implement. For example, you should understand:

the design pattern
the number and nature of business messages exchanged
the contents of each business message
the success path for the conversation (such as request / response sends and receipt acknowledgements)
the possible failure paths, such as retries, timeouts, and errors

You should thoroughly understand data transformations, if any, that occur between the ebXML business message and back-end systems. For each transformation, you use a transformation control to convert the service content of the ebXML business message to / from the format(s) used in the private processes. For more information, see Creating a Transformation Control and a Transformation Method in the WebLogic Workshop Help.
Initiator business processes can have multiple conversations with different participants. Within a single business process, each ebXML conversation requires its own separate ebXML control instance. If the conversation needs to involve a different participant, or if it involves the same participant with different reliable messaging or security, create a different ebXML control JCX file. Each ebXML control JCX in the initiator business process and each business process JDP on participant side represents a service in the TPM repository.
Decide which action mode you want to use for the initiator and participant business processes. The action mode determine the value specified in the eb:Action element in the message header of the ebXML message, which becomes important in cases where multiple message exchanges occur within the same conversation. You can use one of the following values in the ebxml-action-mode business process property:

default—Sets the eb:Action element to SendMessage (default name) and onMessage is the control callback method name.
non-default—Sets the eb:Action element to the name of the method (on the ebXML control) that sends the message in the initiator business process. For sending a message from the initiator to the participant, this name must match the method name of the Client Request node in the corresponding participant business process. For sending a message from the participant to the initiator, the method name in the callback interface for the client callback node in the participant business process must match the method name (on the ebXML control) in the control callback interface in the initiator business process.

Using non-default is recommended to ensure recovery and high availability. If unspecified, the ebxml-action-mode element is set to non-default.

Determine how you want to specify the business process properties:

Statically—using hard-coded annotations (jc:ebxml Annotation on the ebXML control in initiator business processes and the @jpd:ebxml Annotation in participant business processes).
Dynamically—using pass-in values, such as business IDs, and calling the setProperties method (only applicable to the ebXML control using jc:ebxml Annotation).

Note: To ensure proper routing, the ebXML service name specified in the initiator and participant business processes must match. In addition, for non-default action mode, the method names in the ebXML control instance in the initiator business process must match the method names in the corresponding participant business process.

To explicitly handle acknowledgements and errors, you can use onAck and onError nodes.

For default Action mode, you must use an Event Choice node, as the order in which acks and messages arrive is not guaranteed. For more information about the Event Choice node, see " in Guide to Building Business Processes (available at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/wfguide/wfguideIntro.html).
For non-default Action mode, these nodes can be modeled in any form, including sequentially.

To retrieve message envelopes for incoming business messages, use the jpd:ebxml-method Annotation (for participant business processes) and jc:ebxml Annotation (in the callback of the ebXML control for initiator business processes). For example:

For a participant business process:

@jpd:ebxml-method message-envelope="{env}" public void request(XmlObject payload, XmlObject env) { }

For an initiator business process:

@jc:ebxml-method envelope="{env}" public void onMessage(MessageAttachment[] reply, XmlObject env);

To retrieve message envelopes for outgoing business messages, you specify the return value of the send method as XMLObject and provide explicit casting in the business process, as in the following example:

For an initiator business process:

public XmlObject send( messageAttachement[] msg )
XmlObject envelope = (XmlObject) control.send(msg)

For a participant business process:

public XmlObject send( messageAttachement[] msg )
XmlObject envelope = (XmlObject) callback.send(msg)

Thoroughly test the implementation by simulating the choreography between the initiator and participant business processes with sample data. By default, the Trading Partner Management module runs in Test (development) mode, which allows you to run business processes on the same machine (collocated) using preconfigured trading partners and a default binding that uses the ebXML 2.0 protocol. The endpoints for both partners use 127.0.0.1:7001. The delivery-semantics is Once and Only Once. The ebxml service name can be anything as long as it is same for both the initiator and participant business processes. For more information, see Default TPM Repository Settings.

ebXML Initiator Business Processes

In WebLogic Integration, initiator business process use an ebXML control to enable WebLogic Workshop business processes to exchange business messages and data with trading partners via ebXML. You use ebXML controls only in initiator business processes to manage the exchange of ebXML business messages with participants. The ebXML control provides methods for sending business messages, acknowledgements, and errors, and it provides callback methods to handle responses from participants.

For detailed information about using the ebXML control in business processes, see the following topics in ebXML Control in the WebLogic Workshop Help:

For an introduction to initiator business processes, see Initiator and Participant Business Processes.

ebXML Participant Business Processes

In WebLogic Integration, you can easily create a new ebXML participant business process using a WebLogic Workshop template, the ebXML participant business process file. This template provides a head start for building public participant business processes for ebXML conversations. Although this file is not required to build ebXML participant business processes, it includes the nodes and business process annotations needed to integrate easily with ebXML initiator business processes, as well as standard choreography patterns such as acknowledgements, time-outs, retries, and errors. For information about using participant business processes, see Building ebXML Participant Business Processes and @jpd:ebxml Annotation in the WebLogic Workshop Help. For an introduction to participant business processes, see Initiator and Participant Business Processes.

Tasks for Implementing an ebXML Solution

This topic provides a high-level, end-to-end overview of the tasks involved with implementing an ebXML solution. It includes the following topics:

Note: This topic describes, in a general way, the tasks that are typically involved in implementing an ebXML solution. The process of implementing ebXML solutions is iterative, and it can vary in scope and sequence depending on your unique business requirements and environment.

Before You Begin

Before you begin implementing an ebXML solution, we recommend that you review the following documents:

Introduction, to learn basic concepts for integrating trading partners using WebLogic Integration.
This chapter, to learn basic concepts that are unique to ebXML solutions.
Tutorial: Building ebXML Solutions in Tutorials for Trading Partner Integration, which is available at:

http://dev2dev.bea.com/code/wli.jsp

Planning the ebXML Solution

Once you have decided to use ebXML as the business protocol for your trading partner integration (as described in Phase 1: Plan the Solution), you need to plan the solution by determining certain factors in your implementation:

With which trading partners will you integrate?
For each trading partner, you need to determine:

Which business process(es) will you integrate?
What information about that trading partner is required for your implementation (for example, their business ID and other basic profile information). For more information, see Trading Partner Profiles.

For each business process, you need to determine:

Which ebXML version (1.0 or 2.0) is required for exchanging business messages?
What role (initiator or participant role) will your organization play in the business message exchange?
Do you need to create business processes for just your role, or for both roles in the business process?
What are the back-end integration requirements for each business process? Will you use private business processes, and if so, what private business processes are required? What is the data format of, and connections with, associated back-end systems?
Does your implementation need to meet legal standards for nonrepudiation, which is described in NonRepudiation?
What qualities of service are required for reliable messaging, as described in Reliable Messaging?

The Tutorials for Trading Partner Integration provide examples of different ebXML solutions. To learn more, see Tutorial: Building ebXML Solutions available at http://download.oracle.com/docs/cd/E13214_01/wli/docs81/tptutorial/ebxml.html

Building the ebXML Solution

After planning your ebXML solution, you build the business processes that implement the design patterns you are using. For more information about design-time tools, see Phase 2: Design, Build, and Test the Solution. For conceptual information about ebXML business processes, see ebXML Business Processes.

The Tutorial: Building ebXML Solutions in Tutorials for Trading Partner Integration (available at http://dev2dev.bea.com/code/wli.jsp) provides a detailed examples of the typical tasks required to build an ebXML solution.

To build an ebXML solution, you would typically complete the following steps:

Using the BEA WebLogic Platform Configuration Wizard, create a new domain based on the WebLogic Integration domain template. For instructions, see Creating WebLogic Configurations Using the Configuration Wizard in the WebLogic Platform documentation.

From the Tutorials for Trading Partner Integration, copy the example implementation associated with the design pattern that you want to use, if available.

Change the ebXML annotations for the new business processes:

For initiator business processes, you change the ebxml-service-name attribute (and others if needed) in the @jc:ebXML Annotation, which is described at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/javadoc-tag/jc/ebxml.html

For participant business processes, you change the ebxml-service-name attribute (and others if needed) in the @jpd:ebxml Annotation, which is described at the following URL.

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/javadoc-tag/jpd/ebxml.html

Rename the JPD and JCX files and change the names of other components to be more descriptive of the new business process implementation, if you want.

For more information about modifying the ebXML control in initiator business processes, see ebXML Control in the WebLogic Workshop Help, which is available at:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/controls/controlsebXML.html

For more information about building ebXML participant business processes, see Building ebXML Participant Business Processes in the WebLogic Workshop Help, which is available at the following URL:

http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/integration/wfguide/wfguideEbXML.html

Ensure that the ebXML Service name is the same for both the initiator and participant business processes.

For non-default Action mode, ensure that method names are the same for both the initiator and participant business processes.

Change the implementation of any back-end integration as needed.

Make any other changes to the business processes as needed.

Test the ebXML solution using the default TPM repository configuration (described in Default TPM Repository Settings) and security settings (described in Default Domain Security Configuration).

Deploying the ebXML Solution

Once you have built and tested your ebXML solution, you deploy the solution in a production environment. For more information about deployment tools, see Phase 3: Deploy the Solution. For detailed information about deploying WebLogic Integration solutions, see Deploying WebLogic Integration Solutions, which is available at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs81/deploy/index.html

To deploy an ebXML solution, you would typically complete the following steps:

If necessary, using the BEA WebLogic Platform Configuration Wizard, create a new domain based on the WebLogic Integration domain template. For instructions, see Creating WebLogic Configurations Using the Configuration Wizard in the WebLogic Platform documentation.

Start WebLogic Server in production mode.

Using the WebLogic Integration Administration Console, complete the following tasks:

Note: If you have already defined trading partner information in your development environment, you can export this information to an external file, and then import this file into the production environment. For instructions, see "Exporting Management Data" and "Importing Management Data" in Trading Partner Management.

Add trading partners to the TPM repository, including basic profile information, such as trading partner IDs. For instructions, see "Adding Trading Partner Profiles" in Trading Partner Management in Managing WebLogic Integration Solutions.

For each trading partner, define the protocol bindings (including ebXML version—1.0 or 2.0—and other settings) to be used for message exchanges with this trading partner. For instructions, see "Defining an ebXML 1.0 or 2.0 Binding" in Trading Partner Management.

For protocol bindings, you can (optionally) define signature transforms, as described in "Configuring Signature Transforms for ebXML Bindings" in Trading Partner Management.

Define the services that you will use in your deployment. For instructions, see "Adding Services" in Trading Partner Management.

For each trading partner, define the service profiles (protocol bindings and URL endpoints for local and remote trading partners) associated with each service. For instructions, see "Adding Service Profiles to a Service" in Trading Partner Management.

Using the WebLogic Server Administration Console and WebLogic Integration Administration Console, implement security for your deployment, as described in Implementing Security for Trading Partner Integration.

Configure your domain (clustering, high availability, load balancing, fail-over, and so on) as needed for your production environment. For instructions, see Deploying WebLogic Integration Solutions, which is available at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs81/deploy/index.html

Deploy the application and other WebLogic Integration resources associated with your ebXML solution. For instructions, see Deploying WebLogic Integration Solutions, which is available at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs81/deploy/index.html

Managing the ebXML Solution

Once you have deployed your ebXML solution, you would typically monitor run-time performance, message volumes, resource utilization, and other factors to ensure optimum operation on your solution. For more information about monitoring tools, see Phase 4: Administer and Tune the Solution.

For instructions on monitoring trading partner integration resources, see the following topics in in Trading Partner Management in Managing WebLogic Integration Solutions:

"Viewing Statistics"
"Monitoring Messages"