# 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
- Handling Responses from Participants
- Dynamically Specifying Business IDs

To learn more about these methods, see ebXML Control Interface.

The ebXML control is a JCX file. To learn about using JCX files, see JCX Files: Extending Controls.

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

If you use arrays as attachment type, certain restrictions apply to the order of your arguments. For more informations, see Specifying XmlObject and RawData Array Payloads.

You can specify business IDs statically (using the @jc:ebxml Annotation) or dynamically. To learn about specifying business IDs dynamically, see Dynamically Specifying Business IDs.

### Handling Responses from Participants

Participants can respond to initiator requests in the following ways:

- acknowledge that the request was received
- reply to the request
- notify that an error occurred

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 onMessage Control 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:

1. properties dynamically bound using selectors (@jc:ebxml-method Annotation) and the DynamicProperties.xml file
2. properties set using the setProperties() method
3. properties set at the JCX instance level using the @jc:ebxml Annotation annotation in the JPD
4. properties set at JCX class level using @jc:ebxml Annotation annotation in the JCX

Dynamic selectors have a higher precedence than static selectors.

#### 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

1. Display the business process in Design View that contains the ebXML control for which you want to specify a dynamic selector.
2. In Design View, select the ebXML control node in the Data Palette.
3. 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.
4. 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.
5. 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.

To set business IDs dynamically using the setProperties method

1. Verify that your application contains a schema project that includes the DynamicProperties.xsd file, and that the schema is already built. To learn about importing schemas, see How do I: Import Schemas into a Project Schemas Folder.
2. Create a Control Send node in a business process.
3. From the Data Palette, drag the setProperties method and drop it onto the Control Send node.
4. 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.

Related Topics

Overview: ebXML Control

Creating an ebXML Control

Example: ebXML Control