Using an ebXML Control

All WebLogic Workshop controls follow a consistent model. Many aspects of using ebXML controls are identical or similar to using other WebLogic Workshop controls. To learn about WebLogic Workshop controls, see Using Built-In Java Controls.

After you have added an ebXML control to an initiator business process, you can use methods on the control to exchange ebXML messages with participant trading partners. In the Design View, you expand the node for the ebXML control in the Data Palette to expose its methods, and then drag and drop the methods you want onto the business process. Common tasks include:

Sending Messages to Participants

To send an ebXML message to a participant, you use a send message method in a Control Send node. By default, the JCX instance includes a generated send method named request. To add the Control Send node to a business process, you drag this method from the Data Palette onto the business process. For business processes that involve multiple round-trips, you need to create a separate Control Send node for each operation that involves sending an ebXML message to the participant.

Note: The default return type for the request method is void. However, you can also specify the return type to be XmlObject. If you use XmlObject as the return type, the content the XmlObject is the ebXML envelope data.

After creating the Control Send node, you need to specify the payload parts and their Java data types. Valid data types include:

Type

Description

XmlObject

Data in untyped XML format.

XmlObject[]

An array containing one or more XmlObject elements.

RawData

Any non-XML structured or unstructured data for which no MFL file (and therefore no known schema) exists.

RawData[]

An array containing one or more RawData elements

MessageAttachment[]

Array containing one or more parts of an ebXML business message. Message parts can be untyped XML data (XmlObject data type) or non-XML data (RawData data type). Used when sending different kinds of payloads (XML and non-XML) in the same message. The actual number of message parts might not be known until processed. To learn about working with MessageAttachment[] objects, see Using Message Attachments.

Attachments can also be typed XML or typed MFL data as long as you specify the corresponding XML Bean or MFL class name in the parameter.

Handling Responses from Participants

To handle responses from participants, initiator business processes use the following callback methods:

Method Name

Description

onAck

Handles the acknowledgement of the message receipt from the participant.

onError

Handles an error sent by the participant.

response

Handles the message reply sent by the participant.

To receive an ebXML message from a participant, you use the appropriate method. To add the method to a business process, you drag it from the Data Palette onto the business process, which creates a Control Receive node. For business processes that involve multiple round-trips, you need to create a separate Control Receive node for each operation that involves receiving an ebXML message from the participant.

For the response method, if you specify non-default in the ebxml-action-node, you can rename the Control Receive node to make it more descriptive, such as getInvoice. However, if you specify default in the ebxml-action-node, you must use the default name (onMessage) and the business process can have only one onMessageControl Receive node.

For the response method, after creating the Control Receive node, you need to specify the payload parts and their Java data type for the incoming message. To learn about valid data types, see Sending Messages to Participants.

The onError and onAck methods are system-level methods. Both use the EnvelopeDocument argument, which will contain an ebXML envelope when the message is received. As they are system-level methods, these arguments are not seen in the default control but you can drag them onto the business process from the Data Palette. If your application contains a schema project that includes the envelope.xsd file, and if the schema is already built, you can extract the values you want by creating a query (in the XQuery language) using the mapper functionality of WebLogic Workshop. To learn about creating queries with the mapper functionality, see Transforming Data Using XQuery.

You can retrieve the message envelope of an incoming ebXML message by using the envelope annotation in the @jc:ebxml-method tag. To learn more about the envelope annotation, see @jc:ebxml-method Annotation.

Dynamically Specifying Business IDs

The ebXML control adds the capability of dynamically binding business IDs for the initiator (from property) and the participant (to property) of the control. Dynamic binding of properties can be achieved the following ways:

Using selectors

Using the setProperties() method

Order of Precedence

The hierarchy of property settings is as follows, starting with the approach having the highest precedence:

Using Selectors

Using a dynamic selector, ebXML controls allow you to decide at run time which one of multiple trading partners to send a business message to. When you specify a dynamic selector, you build and test an XQuery that retrieves the business ID you need.

To use a dynamic selector

Display the business process in Design View that contains the ebXML control for which you want to specify a dynamic selector.

In Design View, select the ebXML control node in the Data Palette.

Locate the from-selector or to-selector property in the Property Editor and select the associated xquery parameter. Click the button next to the xquery field indicated by three dots (...). The Dynamic Selector query builder is displayed.

In the Start Method Schema area, select an element from the schema to associate it with the start method of the control. The resulting query appears in the XQuery area.

Click OK.

Using setProperties

The setProperties method accepts an ebXMLPropertiesDocument parameter. The ebXMLPropertiesDocument type is an XML Beans class that is generated out of the corresponding schema element defined in DynamicProperties.xsd. The DynamicProperties.xsd file is located in the system folder of New Process Applications or in the system folder of the Schemas project.

If your application contains a schema project that includes the DynamicProperties.xsd file, and if the schema is already built, you can extract the values you want by creating a query (in the XQuery language) using the mapper functionality of WebLogic Workshop. To learn about creating queries with the mapper functionality, see Transforming Data Using XQuery.

From the Data Palette, drag the setProperties method and drop it onto the Control Send node.

In the Send Data tab, select Transformation, specify variables that contain the to and from values, and then create a transformation to map them to the corresponding elements in ebXMLPropertiesDocument.

To display the current property settings, use the getProperties() method.