Using Integration Controls

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

ebXML Control

Ebxml Wizard

The ebXML protocol (Electronic Business using eXtensible Markup Language) is a modular suite of specifications that enables enterprises of any size and in any geographical location to conduct business over the Internet. It is sponsored by UN/CEFACT and OASIS. To learn about ebXML, see http://www.ebXML.org.

The ebXML control enables Oracle Workshop for WebLogic business processes to exchange business messages and data with trading partners via ebXML. The ebXML control supports both the ebXML 1.0 and ebXML 2.0 messaging services. You use ebXML controls in initiator business processes to manage the exchange of ebXML business messages with participants. For an introduction to ebXML solutions, see Introducing Trading Partner Integration.

 

Topics Included in This Section

Overview: ebXML Control

Describes the ebXML control.

Creating an ebXML Control

Describes how to create and configure a ebXML control.

Using an ebXML Control

Describes how to use an ebXML control in a business process.

Example: ebXML Control

Provides links to ebXML examples.

Related Topics

Introducing Trading Partner Integration

Trading Partner Management

Interface EBXMLControl

Building ebXML Participant Business Processes

Annotation Type EbXML

Annotation Type EbXML method

 

Overview: ebXML Control

You use ebXML controls in initiator business processes to exchange ebXML business messages with participants. The ebXML control provides methods for sending and receiving business messages, as described in Interface EBXMLControl. Callbacks handle ebXML messages, acknowledgements, and errors received from the participant.

You should not use ebXML controls in participant business processes to respond to incoming messages. Instead, you use Client Request nodes to handle incoming business messages from the initiator and Client Response nodes to handle outgoing business messages to the initiator. To learn about building participant business processes that use ebXML, see Building ebXML Participant Business Processes. To learn about designing business processes that use ebXML, see Introducing Trading Partner Integration.

At run-time, the ebXML control relies on trading partner and service information stored in the TPM repository. To learn about the TPM repository, see Introducing Trading Partner Integration.

To learn about adding or updating information in the TPM repository, see Trading Partner Management in Using the Oracle WebLogic Integration Administration Console.

 

Creating an ebXML Control

This topic describes how to create a new ebXML control. Each ebXML control instance represents a single ebXML conversation. For each separate ebXML conversation in a business process, you must add a separate ebXML control instance.

To create a new ebXML control
  1. In the Package Explorer pane, double-click the business process to which you want to add the ebXML control. The business process is displayed in the Design view.
  2. Click Ebxml Wizard on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.
    3. Note: If the Data Palette view is not visible in Oracle Workshop for WebLogic, click Window > Show View > Data Palette from the menu bar.
  3. Select Ebxml.

    4. The Insert control: Ebxml dialog box appears as shown in Figure 4-1.

    Figure 4-1 Insert control: Ebxml


    Insert control: Ebxml

  4. In the Insert control: Ebxml dialog box enter the following details:
    • In the Field Name, type the variable name used to access the new ebXML control instance from your business process. The name you enter must be a valid Java identifier.
    • In the Insertion point: from the drop-down list select the point where you want the field name to be inserted in the process file.
    • Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box.
    • Click Next.

      • The Create Control wizard appears.

  5. In the Create Control wizard enter the following details:
    • In the Name field, type the name of your new control extension file.
    • Decide whether you want to add comments as configured in the properties of the current project and select or clear the Generate comments check box.
    • Click Next.

      • The Insert control: Ebxml dialog box appears (see Figure 4-2).

      Figure 4-2 Ebxml Wizard


      Ebxml Wizard

  6. In the Insert control: Ebxml dialog box, specify the following information as shown in Table 4-1.

    7. Table 4-1 Insert Control Properties
    Field
    Description
    from
    Optional. Business ID for the initiator in this conversation. One of the following values:
    • Empty—Uses the default trading partner.
    • Static Value—Business ID of the initiating trading partner. The specified business ID must be configured in the TPM repository.
    To specify the initiator business ID dynamically, use selectors or use the setProperties method in a Control Send node, as described in Dynamically Specifying Business IDs.
    You can also obtain this value by using XQuery selectors on process variables or method parameters in an incoming message.

    Note: If the value of the "from" trading partner is left unspecified via the to attribute, to-selector attribute, or via setProperties, the system will use the ID of the local trading partner marked as "default" in the TPM console.

    to
    Optional. Business ID for the participant in this conversation. One of the following values
    • Empty—Uses the default trading partner.
    • Static Value—Business ID of the participating trading partner. The specified business ID must be configured in the TPM repository.
    To specify the participant business ID dynamically, use selectors or use the setProperties method in a Control Send node, as described in Dynamically Specifying Business IDs.
    You can also obtain this value by using XQuery selectors on process variables or method parameters in an incoming message.
    serviceName
    Required. Name of an ebXML service. For initiator and participant business processes that participate in the same conversation, the settings for ebxml-service-name must be identical. This service name corresponds to the eb:Service entry in the ebXML message envelope.
    method-arg-type
    Required. Type of attachment. One of the following values:
    • XmlObject—Default. Represents data in untyped XML format. The XML data is not specified at design time.
    • XmlObject[]—Array containing one or more XmlObject elements.

    Note: The XmlObject[] option is not available from the drop-down menu on the control wizard window. It has to be specified in source view, see Specifying XmlObject and RawData Array Payloads .

    • RawData—Represents any non-XML structured or unstructured data for which no MFL file (and therefore no known schema) exists.
    • RawData[]—Array containing one or more RawData elements.

    Note: The RawData[] option is not available from the drop-down menu on the control wizard window. It has to be specified in source view, see Specifying XmlObject and RawData Array Payloads.

    • 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.
    To learn more about data types, see Working with Data Types.
    ebxmlActionMode
    Action mode for this ebXML control. Determines 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. One of the following values:
    • default—Sets the eb:Action element to SendMessage (default 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 is set to non-default.
    xQueryVersion
    Specify the version of the XQuery used.

  7. Click Finish.

    8. An ebXML control instance is displayed in the Controls tab.

After you create the control file, the name of the control file becomes available as a service on the Services tab in the Oracle Workshop for WebLogic.

Specifying XmlObject and RawData Array Payloads

The XmlObject[] and RawData[] payload options are only available in source view. You can configure your ebXML control to use these options after you have created it.

To Specify the Payload in Source View
  1. Open your control definition file. You can do this by double-clicking on the file in the Package Explorer pane.
  2. Click the Source view tab.
  3. In the request and response methods, change the payload specified to the payload type that you want to use.

    4. The following restrictions apply to payload specifications:

    • If an array of any type is used, an argument of the same type cannot follow that array in the argument list. In other words, an array must be the last argument specified of that type.
    • If a MessageAttachment[] type is one of your arguments, no other array (including a MessageAttachment[]) is allowed in the argument list.
  4. After you have applied your changes, save and close your control definitions file.
Note: The order of arguments which you used in the control definition file and the order of the arguments in the node on the participant business process which is listening for your message must match.

To learn more about the request and response methods, see Interface EBXMLControl.

 

Using an ebXML Control

All Oracle Workshop for WebLogic controls follow a consistent model. Many aspects of using ebXML controls are identical or similar to using other Oracle Workshop for WebLogic 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:

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

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 control file 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 (see Table 4-2).

Table 4-2 Data Types
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 @EBXMLControl.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:

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

Table 4-3 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.

Table 4-3).

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 Oracle Workshop for WebLogic. 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 from the com.bea.control.EBXMLControl.EbXMLMethod based annotations. To learn more about the envelope annotation, see EBXMLControl.EbxmlMethod 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:

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 (see EBXMLControl.EbxmlMethod Annotation) and the DynamicProperties.xml file
  2. Properties set using the setProperties() method
  3. Properties set at the control instance level using the Annotation EBXMLControl.EbXML in the business process.
  4. Properties set at control class level using Annotation EBXMLControl.EbXML in the 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. In the Data Palette, select the ebXML control.
  2. In the Properties pane, locate the from-selector or to-selector attributes.
  3. Select an element from the schema to associate it with the control. The resulting query appears in the XQuery area.

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 schemas/system folder, or in the utility folder of the Process Applications.

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 Oracle Workshop for WebLogic. 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.
  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.

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

 

Example: ebXML Control

For examples of how to use the ebXML control, see Tutorial: Building ebXML Solutions.


  Back to Top       Previous  Next