Introducing ebXML Solutions

This topic provides an introduction to implementing ebXML solutions with Oracle 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 Oracle 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.

About ebXML Solutions

An ebXML solution is any Oracle 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 WLI. 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

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, see ebXML specifications 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):

ebXML Support in Oracle WebLogic Integration

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

Supported ebXML 1.0 and 2.0 Features

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

Table 2-1 Oracle 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 Oracle 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.

ebXML Concepts

This topic describes ebXML concepts that you need to understand before implementing ebXML business processes in Oracle 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. Oracle 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.

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.

Oracle WebLogic Integration provides a mechanism in Oracle Workshop for WebLogic business processes for retrieving the ebXML message envelope that relates to the Header container from incoming business messages. For more information, see @com.bea.wli.jpd.EbXML and @EBXMLControl.EbXML in the Java Docs for Oracle WebLogic Integration Classes.

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.

Oracle 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.

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. Configure reliable messaging in the Oracle WebLogic Integration Administration Console, as described in “Defining an ebXML 1.0 or 2.0 Binding” in Trading Partner Management in Using Oracle WebLogic Integration Administration Console Help.

Of the eight qualities of service policies defined in the ebXML 2.0 Specification, Oracle 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 Oracle WebLogic Integration resends a message in specific situations, such as timeouts, network failures, and so on. Interval—Number of seconds that Oracle 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 Oracle Workshop for WebLogic 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 Javadoc for Oracle WebLogic Integration Classes.
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 file. Each ebXML control in the initiator business process and each business process JPD 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 ( @EBXMLControl.EbXML on the ebXML control in initiator business processes and the @com.bea.wli.jpd.EbXML 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 @EBXMLControl.EbXML).

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 “ Receiving Multiple Events” in Guide to Building Business Processes
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 @com.bea.wli.jpd.EbXML (for participant business processes) and @EBXMLControl.EbXML (in the callback of the ebXML control for initiator business processes). For example:

For a participant business process:

@com.bea.wli.jpd.EbXML.ebxml-method message-envelope="{env}"

public void request(XmlObject payload, XmlObject env) {

}

For an initiator business process:

@EBXMLControl.EbxmlMethod 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 Oracle WebLogic Integration, initiator business process use an ebXML control to enable Oracle Workshop for WebLogic 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:

ebXML Participant Business Processes

In Oracle WebLogic Integration, you can easily create a new ebXML participant business process using a Oracle Workshop for WebLogic 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 @com.bea.wli.jpd.EbXML in the Javadoc for Oracle WebLogic Integration Classes. 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:

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 Oracle WebLogic Integration.
Tutorial: Building ebXML Solutions to learn basic concepts that are unique to ebXML solutions. These tutorials are available at WebLogic Integration Sample Code

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. For more information, see Tutorial: Building ebXML Solutions.

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.

Using the Oracle WebLogic Configuration Wizard, create a new domain based on the Oracle WebLogic Integration domain template. For instructions, see Creating Oracle WebLogic Domains Using the Configuration Wizard in the Oracle WebLogic 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 serviceName attribute (and others if needed) in the @EBXMLControl.EbXML
For participant business processes, you change the ebxmlServiceName attribute (and others if needed) in the @com.bea.wli.jpd.EbXML.

Rename the JPD and 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 Javadoc for Oracle WebLogic Integration Classes.
For more information about building ebXML participant business processes, see Building ebXML Participant Business Processes in the Guide to Building Business Processes.

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 Oracle WebLogic Integration solutions, see Deploying Oracle WebLogic Integration Solutions.

If necessary, using the Oracle WebLogic Configuration Wizard, create a new domain based on the Oracle WebLogic Integration domain template. For instructions, see Creating Oracle WebLogic Domains Using the Configuration Wizard in the Oracle WebLogic documentation.
Start Oracle WebLogic Server in production mode.
Using the Oracle 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 more information, see Importing and Exporting Data in Trading Partner Management in Using Oracle WebLogic Integration Administration Console Help.

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.
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 more information, see “Defining Protocol Bindings” in Trading Partner Management.
For protocol bindings, you can (optionally) define signature transforms, as described in Configuring Signature Transforms for ebXML Bindings in Adding Protocol Bindings to a Trading partner in Trading Partner Management.
Define the services that you will use in your deployment. For more information, 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 more information, see Adding Services in Trading Partner Management.

Using the Oracle WebLogic Server Administration Console and Oracle 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 more information, see Deploying Oracle WebLogic Integration Solutions.
Deploy the application and other Oracle WebLogic Integration resources associated with your ebXML solution. For more information, see Deploying Oracle WebLogic Integration Solutions

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 Viewing Statistics and Monitoring Messages in Trading Partner Management in Using Oracle WebLogic Integration Administration Console Help.

Introducing Trading Partner Integration

Introducing ebXML Solutions

About ebXML Solutions

About ebXML

ebXML Specifications

SOAP Specifications

ebXML Support in Oracle WebLogic Integration

Supported ebXML 1.0 and 2.0 Features

Unsupported ebXML 2.0 Features

ebXML Concepts

ebXML Protocol Layer

ebXML Business Messages

Diagram of an ebXML Business Message

Logical MIME Parts of an ebXML Business Message

Message Attachments

Reliable Messaging

ebXML Business Processes

Guidelines for Building ebXML Business Processes

ebXML Initiator Business Processes

ebXML Participant Business Processes

Tasks for Implementing an ebXML Solution

Before You Begin

Planning the ebXML Solution

Building the ebXML Solution

Deploying the ebXML Solution

Managing the ebXML Solution