Skip navigation.

eDocs Home > BEA WebLogic Integration 8.1 Documentation > Tutorials for Trading Partner Integration > Tutorial: Building ebXML Solutions

Tutorials for Trading Partner Integration

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Tutorial: Building ebXML Solutions

The ebXML language (Electronic Business using eXtensible Markup Language) is a business protocol that enables enterprises to conduct business over the Internet. WebLogic Workshop uses ebXML controls for initiator processes and ebXML Participant Business Processes templates for participant processes to build business processes systems which exchange ebXML business messages between trading partners. The ebXML control provides the initiator business process with predefined customizable methods for sending and receiving ebXML messages in a conversation. The ebXML Participant Business Process template provides a head start for building public participant business processes for ebXML conversations. Although the template 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. The purpose of this tutorial is to demonstrate the different options available for ebXML trading partner management in WebLogic Workshop and WebLogic Integration.

 

Before You Begin

This topic describes tasks that you should perform before you begin using this tutorial. It contains the following sections:

Prerequisites

To use this tutorial, you must have:

Suggested Reading

To gain a detailed understanding of how ebXML solutions are implemented in WebLogic Integration, consider reading the following material:

To learn how to build business processes and create data transformations in WebLogic Workshop, consider completing the following tutorials:

 

Tutorial Overview

In this tutorial, the first couple of examples contains detailed instructions of how to use the WebLogic Workshop user interface and the WebLogic Integration Administration Console user interface to perform the steps outlined in the example. The preceding examples build on the skills you learn in the first couple of sections, but do not outline the steps in quite as much detail.

The tutorial is organized into these parts:

Step 1: Getting Started

This section describes how to create the business process application in which you will create the business processes and other components required for the examples of the tutorial. It also describes how to import the sample data and schemas which are included in the zipped archive of the tutorial files.

Step 2: Sending an XML Message through an One-Way ebXML Exchange

This example demonstrates how to send an XML message from one trading partner to another through a simple one-way ebXML exchange. In this example, you will learn how to create participant and initiator business processes as well as, how to create and configure ebXML and file controls. The section also contains a detailed description of how to deploy and test business processes using the WebLogic Workshop Test Browser.

Step 3: Selecting the Trading Partner Information Dynamically Through Typed XML

This example is similar to the preceding one except for that this example demonstrates how to specify the trading partner information dynamically by using an XQuery selector, rather than specifying it statically in the ebXML control. It also describes how to configure the ebXML control to use typed XML data and specific method names.

Step 4: Sending Raw Data (Binary File) Through an ebXML Exchange

In this example, you learn how to use ebXML to send binary data between two trading partners through a Message Broker channel.

Step 5: Creating a Roundtrip ebXML Conversation

This section describes how to implement an ebXML conversation in which when a request message (order) is received, a response (invoice) message is sent back by adding a Client Response node to the participant business process and using the ebXML control callback feature to send the response message.

Step 6: Implementing the Public/Private Pattern

This example illustrates how to use subprocesses to implement the public/private pattern. The public/private pattern can be used to keep the details of backend integration contained to a private process definition, while the public process definitions are dedicated to trading partner interaction.

Step 7: Using the TPM Control and Callbacks

In this section, you learn how to at run time obtain trading partner information from the TPM repository. You also learn how to use the onAck callback of the ebXML control.

Step 8: Setting Partner ID Dynamically Based on Directory Name

In this example, you investigate the already built application included with the tutorial files to learn how to read the name of a sub-directory and use that as the partner ID. The business process sets the partner ID dynamically using the setProperties method included in the ebXML control.

Step 9: Creating a Distributed Setup

This example briefly explains how to move to a distributed setup where one trading partner operates in one WebLogic Integration instance while the other trading partner operates in another instance. This is the setup that you would use in a production scenario where the two trading partners are running on two physically separated systems.

Step 10: Configuring Non-Default Protocol Settings

In this section you will learn how to add a service and a service profile in the WebLogic Integration Administration Console, which will give you control over trading partner communications.

Step 11: Exchanging Messages with WebLogic Integration - Business Connect

This example describes how to send messages between WebLogic Integration and WebLogic Integration - Business Connect. WebLogic Integration - Business Connect is a separate application which enables you to securely exchange large volumes of documents with your trading partners. You must have a current license of WebLogic Integration - Business Connect to be able to complete this example.

 

Step 1: Getting Started

Before you start the ebXML tutorial, you have to complete the procedures described in Setting Up the Tutorials. If you have not yet completed these procedures, please do so before proceeding with this section.

In this step, you use WebLogic Workshop to create application, in which you build the ebXML tutorial business processes. You then import the sample data and schemas provided in the zipped archive that came with the tutorial files (see, Step 3: Install the Tutorial Files). The sample data and schemas are used to illustrate the functionality of the ebXML tutorial examples. Lastly, you create two directories on your hard drive which are used throughout the tutorial to read files from and to write files to.

This section contains the following procedures:

Creating the Business Process Application

WebLogic Integration extends the WebLogic Workshop to allow the building of integrated enterprise applications. An application in turn contains projects and files. A project can contain several components including, business processes, Web services, and XML files. In this section, you will create the Business Process Application in which you will later build the ebXML tutorial processes and process components.

To Create a Business Process Application

  1. Start WebLogic Workshop:

    2. To Start WebLogic Workshop on Windows:

    1. Invoke WebLogic Workshop from the Start menu by choosing:

      2. Start—>Programs—>BEA WebLogic Platform 8.1—>WebLogic Workshop 8.1.

      If this is the first time WebLogic Workshop is started since it was installed, the samples project, which contains sample services installed with WebLogic Workshop, is displayed. Otherwise, the project which was opened last is displayed.

    To Start WebLogic Workshop on Linux:

    1. Using a file system browser or shell, locate the Workshop start script at:

      2. $HOME\bea\weblogic81\workshop\Workshop.sh

      Where HOME is your Workshop install directory.

    2. Start WebLogic Workshop using one of the following methods:

      3. -Use the following command from the command line:

       sh Workshop.sh

      -From a file system browser, double-click Workshop.sh.

  2. From the WebLogic Workshop menu, click File—>New—>Application. The New Application dialog box is displayed.


    3.  
  3. In the New Application dialog box, select Process in the left pane, and select Process Application in the right pane.
  4. In the Directory field, select the directory in which you want to create your application. The examples in this tutorial assumes that the application will be created in: C:\myapps\tptutorialapps. If you create the directory in a different location or use another name, adjust the instructions accordingly.
  5. In the Name field, enter ebXML.
  6. Click the arrow beside the Server field to display a list of servers. Then choose the server which you created when you set up your domain in Step 1: Create a New WebLogic Integration Domain.
  7. Click Create.
  8. Your Process Application is created and displayed in the Application pane. If the Application pane is not visible in WebLogic Workshop, choose View—>Application from the menu bar.


    9.  

    The Application pane displays a hierarchical representation of the files and resources available in your application. The components we will work with in this tutorial includes the following:

    ebXML—The application folder.

    ebXMLWeb—A Web application project folder. Every application contains one or more projects. Projects represent WebLogic Server Web applications. In other words, when you create a project, you are creating a Web application. (The name of your project is included in the URL your clients use to access your application.)

    Web Applications are J2EE deployment units that define a collection of Web resources such as business processes, Web services, JSPs, servlets, HTML pages, and can define references to external resources such as EJBs.

    Note: The Web application project folder is named by appending Web to the name you gave your application.

    Schemas—A Schemas project that contains the XML Schemas and the Message Broker channel file used in the application. It also contains ebXML envelope schemas that are used to package ebXML messages.

  9. Expand the ebXMLWeb folder.

    10. The processes folder inside the ebXMLWeb folder is created when you created your business process application. Since we do not need it for our tutorial, you can delete it:

  10. Right-click on the processes folder and select Delete from the drop-down menu.
  11. Click Yes in the confirmation dialogue.

You have now completed the first step in this tutorial and are ready to start creating the tutorial ebXML business processes. For more information about business process applications, see Guide to Building Business Processes available at: http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideIntro.html

Importing the Tutorial Sample Data

In this tutorial, we use sample data files to send in the ebXML messages. You can use your own XML data files if you wish, but some sample data files have been provided for you in the tptutorial.zip archive that you downloaded from the http://dev2dev.bea.com web site (see, Step 3: Install the Tutorial Files).

To Import the Sample Data Into Your Project Application

  1. In the Application pane, right click on ebxmlWeb.
  2. Select Import... from the drop-down menu.

    3. The Import File window opens.

  3. In the Import File window, navigate to [unzip location]\tptutorialapps\ebxml\ebxmlWeb\sampledata where [unzip location] is the directory to which you unzipped the files from the tptutorial.zip (see, Step 3: Install the Tutorial Files).
  4. Click Import.

    5. A folder named sampledata which contains the files sampleinvoice.xml and sampleorder.xml is added to your Application pane.

Note: Instead of the preceding steps, you could simply drag and drop the sampledata folder from any file browser directly into your Application pane in Weblogic Workshop.

Importing the Tutorial Schemas

In this tutorial, specific schemas are used for the XML data that is sent by the ebXML messages. This section describes how to import the schemas into your schemas folder in your ebXML application.

To Import the Tutorial Schemas

  1. In the Application tab, right-click on a Schemas folder. (If the Application tab is not visible in WebLogic Workshop, choose View—>Application from the menu bar.)
  2. From the drop-down menu, select Import....

    3. The Import Files dialog box is displayed.

  3. Navigate to: [unzip location]\tptutorialapps\ebxml\Schemas. Where [unzip location] is the directory to which you unzipped the files from the tptutorial.zip file (see,Step 3: Install the Tutorial Files).
  4. Select b2bborder.xsd and b2binvoice.xsd by clicking on the files while holding down the ctrl key.
  5. Click Import.

When a XSD or MFL file is imported, a build of the current Schemas project folder is triggered. (The build verifies that the schema file is well formed. For XSD files, it also verifies that the element and attribute names in the XML Schema do not conflict with the XSD files that have already been imported into the current Schemas project folder.) For more information about what gets generated when you import schemas, see Importing Schemas available at http://edocs.bea.com/workshop/docs81/doc/en/integration/dtguide/dtguidemapperimportschemas.html.

Creating the Read and Write Directories

To demonstrate how messages can be exchanged by ebXML, several of the examples in this tutorial write out files to and read files from directories on your hard drive. Before you start working with any of the examples in this tutorial, create the following two directories on your hard drive:

Note: This is assuming that you created your application in Creating the Business Process Application on the C drive. If you created the application on another drive, please place the above directories at the root level of that drive.

 

Step 2: Sending an XML Message through an One-Way ebXML Exchange

In this example, you will learn how to send an XML message from one trading partner to another using ebXML. Imagine that one of the trading partners is accepting and processing orders. We refer to this partner as the seller and it is the participator of the ebXML conversation. The other trading partner, which we call the buyer, sends an XML order to the seller. The buyer is the initiator of the conversation. The seller accepts the message and simply writes it out to a file. This section contains the following procedures:

Building the Seller Business Process

The Seller business process is the participator of our ebXML conversation. When building ebXML participator processes, you can use the ebXML Participant Process file which comes pre-configured with the nodes, variables, and other components necessary for building participants processes. In this example, you add a File control to the business process which writes the test data out to a file located on your hard drive. This section includes the following tasks:

To Create the Seller Business Process File

  1. In the Application pane, right-click ebxmlWeb and select New—>Folder....

    2. The New Folder dialogue opens.

    Note: If the Application pane is not visible in WebLogic Workshop, choose View—>Application from menu bar.

  2. In the New Folder dialogue, enter ebxml as the name of your new folder.
  3. Click OK.

    4. A new folder named ebxml is added as a sub folder under ebxmlWeb in the Application pane.


     
  4. In the same way as described in the preceding steps, create another new folder as a sub folder under ebxml and name it oneway.
  5. Right-click on oneway and select New—>Process File in the drop-down menu.

    6. The New File window opens.


     
  6. In the New File window, select Processes from the left pane and ebXML Participant Process File from the right pane.
  7. In the File name field, enter Seller.jpd.
  8. Click Create.

    9. A new ebXML participant process file is created in your oneway folder in the Application pane and is displayed in Design View.


     


     

    The ebXML participant process file is created pre-configured with the nodes and business process annotations needed to integrate easily with ebXML initiator business processes. For more information about ebXML participant process files, see Building ebXML Participant Business Processes available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideEbXML.html.

  9. In this example, we will not respond to the buyer process, so we can delete the Respond to request node: right-click on the node and select Delete from the drop-down menu.

In this example, instead of responding to the buyer process, we add a File control which will write out the incoming ebXML messages to a file. This File control is then added to the business process as a Control Send with Return node.

To Create the File Control and the Control Node

  1. In the Controls section of the Data palette, select Add—>Integration Controls—>File.

    2. The Insert Control - File window opens.


     
  2. In the Insert Control - File window, enter the following:
    1. In the STEP 1, enter file as the name of the variable to use for the File control. This name must be a valid Java identifier.
    2. In STEP 2, select the Create a new File control to use option and enter File as the name of the new JCX file that will be created.
    3. In STEP 3, enter /tptutorial as the directory-name. This is the directory to which the message received by the Seller.jpd will be written. In this tutorial, we always use the tptutorial directory that you created in the Creating the Read and Write Directories section as the directory to read from and write to.
    4. In STEP 3, enter order.xml as the file mask This is the name of the file to which the message received by the Seller.jpd will be written.
    5. In STEP 3, select XmlObject as the type of data contained in the received message from the file-type drop-down menu.
  3. Click Create.

    4. The File control instance is added to your list of controls in the Data palette, and a JCX file corresponding to the File control is added to the Application palette. For more information about File controls, see File Control available at http://edocs.bea.com/workshop/docs81/doc/en/integration/controls/controlsFile.html. For more information about JCX files, see JCX Files: Extending Controls available at http://edocs.bea.com/workshop/docs81/doc/en/workshop/guide/devenv/conJwiFiles.html.

  4. In the Data palette, expand the File control by clicking on the + next to it.

    5. The methods associated with the File control are displayed.

  5. Select the FileControlPropertiesDocument write(XmlObject someData)method.
  6. Drag the selected method into Design View and drop it on the which appears immediately following the Receive request node.

    7. A new Control Send with Return node named write is added to your business process. For more information about Control Send with Return nodes, see Interacting With Resources Using Controls available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideControls.html.

The next step in our procedure is to configure the Control Node we just created with the correct variables and method assignments.

To Configure the Control Node

  1. Double-click the new write node.

    2. The write node builder is invoked.

  2. Click Send Data.
  3. From the Select variables to assign drop-down menu, select payload as the variable to assign to the write method.
  4. Click Apply to apply your selection.
  5. Click Close to close the node builder.
  6. Select File—>Save or enter Ctrl+S to save your work.

Your seller side ebXML process is now complete. The process is invoked when an XML message is received from the Buyer initiator process by the Receive request node, the Receive request node assigns the XML to a variable, and the write node writes the XML message to a file named order.xml via the File control.

Note: The grey check box icon is there because the receive data tab of the node has not been configured which marks the node as incomplete. However, since the example is not receiving any data, no more configuration is necessary for the business process to run properly.

To View the ebXML Source View Parameters

The ebXML binding information and service name of the business process is displayed in the Property Editor in Source View. To view these properties:

  1. Click the Source View tab.
  2. Click on public class Seller implements com.bea.jpd.ProcessDefinition to display the Property Editor for the Seller class.
  3. In the Property Editor, note the following:

For more information about Source View ebXML process annotations, see @jpd:ebxml Annotation available at http://edocs.bea.com/workshop/docs81/doc/en/integration/javadoc-tag/jpd/ebxml.html.

We are now ready to test the Seller business process. WebLogic Workshop provides a browser-based interface through which you can test the functionality of your business process. Using this Test View interface, you play the role of the client, invoking the business process's methods and viewing the responses.

To Test the Seller Process

  1. If it is not already running, start WebLogic Server. to do so, choose Tools—>WebLogic Server—>Start WebLogic Server—>from the WebLogic Workshop menu.

    2. If WebLogic Server is running, the following indicator is visible in the status bar at the bottom of the WebLogic Workshop visual development environment:


     
  2. Click on the WebLogic Workshop menu.

    3. WebLogic Workshop builds your project. If there are no errors in the project, a Web browser is launched to display the Workshop Test Browser, through which you can test your business process using sample input values.

    Note: It may take a while before the Test Browser window is launched after the application has completed the built process.

  3. If not already displayed in the Test Browser window, click Test Form.
  4. To enter test data, do one of the following:
  5. Click request.

    6. The Test Form page refreshes to display a summary of your request parameters.

  6. Click Refresh to refresh the summary.
  7. Scroll down to the Operation request section to see the content of the sampleorder.xml file.
  8. Using a file browser or command line tool, navigate to your C:\tptutorial directory.

    9. It now contains a file named order.xml with identical content to that of sampleorder.xml. This file was written by the File control that you created and configured in the section To Create the Seller Business Process File.

  9. Return to WebLogic Workshop and click on the tool bar to stop and close the Test Browser.

For more information about the different options in the Test Browser and how to use it to test your business processes, see Running and Testing Your Business Process available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideTest.html.

Your Seller business process is now deployed and ready to accept ebXML messaged. By default the protocols specified in the default ebXML 2.0 binding will be used, so no additional configurations are required. In production scenarios however, you typically create a TPM service profile using the WebLogic Workshop Administration Console. For more information about creating service profiles, see Adding Service Profiles to a Service in Trading Partner Management (available at http://edocs.bea.com/wli/docs81/manage/tpm.html) in Managing WebLogic Integration Solutions.

Building the Buyer Business Process

The Buyer business process is the initiator of our ebXML conversation. After creating the Buyer business process, we will use an ebXML control to communicate with the Seller participator business process. This section contains the following procedures:

To Create the Buyer Business Process File

  1. In the Application pane, right-click on oneway and select New—>Process File.

    2. The New File window opens.


     

    Since we are creating a initiator business process file this time and will use a ebXML file control to communicate with the participator process, we will create a default process file rather than an ebXML participant process file.

  2. In the New File window, select Processes from the left pane and Process File from the right pane.
  3. Enter Buyer.jpd in the File name field.
  4. Click Create.

    5. A new Buyer.jpd file is added to your Application pane and displayed in Design View.


     

    The Buyer.jpd file contains a Start node, a Starting Event place holder and a Finish node.

  5. Double-click on the Starting Event place holder.

    6. The Starting Event selection window is displayed.

  6. Select Invoked via a Client Request.
  7. Click OK.

    8. A Client Request node is added as the Starting Event to your business process.

We will now configure the Client Request node with the correct methods and variable types.

To Configure the Client Request Node

  1. Double-click the Client Request node.

    2. The Client Request node builder is invoked.

  2. In the General Settings tab:
    1. Change the method name from clientRequest to startBuyer.
    2. Click Add.
    3. If not already selected, select the XML option.
    4. Scroll down to the un-typed XML types.
    5. Select XmlObject.
    6. Click OK

      7. The XmlObject parameter type is added to the pane.

    7. Click Apply to specify the XMLObject type as the expected type of the startBuyer method.
  3. Click Receive Data.
  4. In the Receive Data tab:
    1. Select Create New Variable... from the Select Variables to Assign drop-down menu.

      2. The Create Variable window opens.

    2. Enter order as the variable name.
    3. Note that the type XmlObject is preselected for you since this is the type you specified on the General Settings tab.
    4. Click OK.

      5. The new order variable is added to the Select variables to assign drop-down list.

    5. Click Apply.
    6. Click Close.

    Your Client Request node is completed. To learn more about Client Request nodes, see Receiving Messages From Clients available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideClientsReceiveNode.html. To learn more about variables and data types, see Working with Data Types available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideDataTypesWorking.html.

It is now time to add the ebXML control which will be used to communicate with the Seller process. This control represents what would normally be the remote service we are trying to contact, although in this example, the service runs on the same machine as the Buyer process.

To Create the ebXML Control and Control Node

  1. In the Controls section of the Data palette, select Add—>Integration Controls—>ebXML.

    2. The Insert Control - ebXML window opens.


     
  2. In the Insert Control - ebXML window, enter the following:
    1. In the STEP 1, enter sellerControl as the name of the variable to use for the control. This name must be a valid Java identifier.
    2. In STEP 2, select the Create a new File control to use option and enter SellerControl as the name of the new JCX file that will be created.
    3. In STEP 3, enter Seller as the ebxml-service-name. This value must always match the value in the participant (in our case the Seller) business process. This service name corresponds to the eb:Service entry in the ebXML message envelope.
    4. In STEP 3, leave the from field blank. This will default to the 000000001 at runtime, the default trading partner.
    5. In STEP 3, enter 000000002 in the to field. This sets the participating trading partner id as a static value.
    6. In STEP 3, select XmlObject as the type of data contained in the received message from the message-arg-type drop-down menu.
  3. Click Create.

    4. The ebXML control instance is added to your list of controls in the Data palette, and a JCX file corresponding to the ebXML control is added to the Application palette. You can double-click on the JCX file to open it in Design View and review the values which you just entered. For more information about ebXML controls, see ebXML Control. available at http://edocs.bea.com/workshop/docs81/doc/en/integration/controls/controlsebXML.html. For more information about JCX files, see JCX Files: Extending Controls available at http://edocs.bea.com/workshop/docs81/doc/en/workshop/guide/devenv/conJwiFiles.html.

  4. In the Data palette, expand the ebXML control by clicking on the + next to it.

    5. The methods associated with the ebXML control are displayed.

  5. Select the void request(XmlObject payload)method. The name of the method on this control must match the method name of the Receive request node in the participant process.
  6. Drag the selected method into Design View and drop it on the which appears immediately following the Client Request node.

    7. A new Control Send node named request is added to your business process. For more information about Control Send nodes, see Interacting With Resources Using Controls available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideControls.html.

We will now configure the request node with the correct variable assignment.

To Configure the Request Node

  1. Double-click the new request node.

    2. The request node builder is invoked.

  2. Click Send Data.
  3. From the Select variables to assign drop-down menu, select order as the variable to assign to the request method.
  4. Click Apply to apply your selection.
  5. Click Close to close the node builder.
  6. Select File—>Save or enter Ctrl+S to save your work.

Your buyer side ebXML process is now complete. The process sends a message to the Seller business process which is then written to a file named order.xml via the File control in the Seller process.

To Test the Buyer Business Process

  1. Click on the WebLogic Workshop menu. (For more detailed instructions refer back to, To Test the Seller Process.)
  2. To enter test data, do one of the following:
  3. Confirm that the order.xml file was written out correctly to the C:\tptutorial directory by checking that the time stamp of the file is current.

This part of the tutorial is now complete. You have successfully sent an XML message over ebXML from one trading partner to another. The participant (Seller) process wrote the XML out to the file system.

 

Step 3: Selecting the Trading Partner Information Dynamically Through Typed XML

In this example we build on what you learned in the previous exercise, Step 2: Sending an XML Message through an One-Way ebXML Exchange. You will learn how to specify the trading partner information dynamically using an XQuery selector rather than specifying it statically in the ebXML control. Then you will customize the ebXML control in the initiator (buyer) process and the participant process file (Seller) to use typed XML and business specific method names.

This step contains the following procedures:

Building the SelectorSeller Business Process

In this procedure, you create an ebXML participant business process which will accept typed XML data instead of the XmlObject variable you used in the previous example's participant process. This section contains the following tasks:

To Create the SelectorSeller Business Process File

  1. Create a sub folder named selector under \ebxml\oneway in your Application tab. (For detailed instructions, refer back to To Create the Seller Business Process File.)
  2. Create a new ebXML Participant Process File named SelectorSeller.jpd.

    3. Your Application tab should look similar to the following.


     
  3. As in the previous example, remove the Respond to request node.

The next step involves configuring the Receive request node to accept XML data of a type that is specified in the Schemas which you imported into your application in Importing the Tutorial Schemas.

To Configure the Receive Request Node

  1. Double-click the Receive request node.

    2. The Receive request node builder is invoked.

  2. In the General Settings tab:
    1. Change the method name from request to processOrder.
    2. Select XmlObject payload.
    3. Click Remove
    4. Click Add.
    5. If not already selected, select the XML option.
    6. Expand the b2border.xsd by clicking on the + next to it.
    7. Select Order from the expanded list.
    8. Click OK

      9. The OrderDocument parameter type is added to the pane.

    9. Click Apply to specify the OrderDocument type as the expected type of the processOrder method.
  3. Click Receive Data.
  4. In the Receive Data tab:
    1. Select Create New Variable... from the Select Variables to Assign drop-down menu.

      2. The Create Variable window opens.

    2. Enter order as the variable name.

      3. Note: The type of the variable is already specified to be com.bea.tutorial.order.OrderDocument which is what you specified in the preceding steps.

    3. Click OK.

      4. The new order variable is added to the Select variables to assign drop-down list.

    4. Click Apply.
    5. Click Close.

    Your Client Request node is completed. To learn more about Client Request nodes, see Receiving Messages From Clients available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideClientsReceiveNode.html. To learn more about variables and data types, see Working with Data Types available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideDataTypesWorking.html.

    As in the previous example, you will add a file control to the business process file, which will write the order variable out to a file.

To Create the File Control and Control Node

Refer to the instructions in To Create the File Control and the Control Node to create a new File control. To save time, you can also drag and drop File.jcx from the \ebxml\oneway folder in the Application tab directly on to the Design View of the SelectorSeller. The control definitions you created earlier will be reused in a new instance for this business process.

To Configure the Control Node

  1. Double-click the new write node.

    2. The write node builder is invoked.

  2. Click Send Data.
  3. From the Select variables to assign drop-down menu, select order as the variable to assign to the write method.
  4. Click Apply to apply your selection.
  5. Click Close to close the node builder.
  6. Select File—>Save or enter Ctrl+S to save your work.

This concludes the creation of the SelectorSeller business process.

To Test the SelectorSeller Process

  1. Click on the WebLogic Workshop menu. (For more detailed instructions refer back to, To Test the Seller Process.)
  2. To enter test data, do one of the following:
  3. Confirm that the order.xml file was written out correctly to the C:\tptutorial directory by checking that the time stamp of the file is current

You are now ready to go on and create a SelectorBuyer initiator process.

Building the SelectorBuyer Business Process

For the initiator process in this example you use an XQuery selector to retrieve the trading partner ID dynamically rather than specifying it statically in the ebXML control as done in the previous example. This section contains the following tasks:

To Create the SelectorBuyer Business Process File

Create a business process file named SelectorBuyer.jpd in the selector folder by following the instructions in To Create the Buyer Business Process File.

To Configure the Client Request Node

  1. Double-click the Client Request node.

    2. The Client Request node builder is invoked.

  2. In the General Settings tab:
    1. Click Add.
    2. If not already selected, select the XML option.
    3. Expand the b2border.xsd by clicking on the + next to it.
    4. Select Order from the expanded list.
    5. Click OK

      6. The OrderDocument parameter type is added to the pane.

    6. Click Apply to specify the OrderDocument type as the expected type of the processOrder method.
  3. Click Receive Data.
  4. In the Receive Data tab:
    1. Select Create New Variable... from the Select Variables to Assign drop-down menu.

      2. The Create Variable window opens.

    2. Enter order as the variable name.

      3. Note: The type of the variable is already specified to be com.bea.tutorial.order.OrderDocument which is what you specified in the preceding steps.

    3. Click OK.

      4. The new order variable is added to the Select variables to assign drop-down list.

    4. Click Apply.
    5. Click Close.

    Your Client Request node is completed. To learn more about Client Request nodes, see Receiving Messages From Clients available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideClientsReceiveNode.html. To learn more about variables and data types, see Working with Data Types available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideDataTypesWorking.html.

In the next step you add a ebXML control and configure this control with an XQuery selector.

To Create the ebXML Control

  1. In the Controls section of the Data palette, select Add—>Integration Controls—>ebXML.

    2. The Insert Control - ebXML window opens.

  2. In the Insert Control - ebXML window, enter the following:
    1. In the STEP 1, enter selectorSellerControl as the name of the variable to use for the control. This name must be a valid Java identifier.
    2. In STEP 2, select the Create a new ebXML control to use option and enter SelectorSellerControl as the name of the new JCX file that will be created.
    3. In STEP 3, enter SelectorSeller as the ebxml-service-name. This value must always match the value in the participant (in our case the SelectorSeller) business process. This service name corresponds to the eb:Service entry in the ebXML message envelope.
    4. In STEP 3, leave the from field blank. This will default to the 000000001 at runtime, the default trading partner.
    5. In STEP 3, leave the to field blank. This will be determined at runtime by the XQuery selector which you will define in the next section.
    6. In STEP 3, select XmlObject as the type of data contained in the received message from the message-arg-type drop-down menu.
  3. Click Create.

    4. The ebXML control instance is added to your list of controls in the Data palette, and a JCX file corresponding to the ebXML control is added to the Application palette. You can double-click on the JCX file to open it in Design View and review the values which you just entered. For more information about ebXML controls, see ebXML Control available at http://edocs.bea.com/workshop/docs81/doc/en/integration/controls/controlsebXML.html. For more information about JCX files, see JCX Files: Extending Controls available at http://edocs.bea.com/workshop/docs81/doc/en/workshop/guide/devenv/conJwiFiles.html.

You will now modify the control definition file of the ebXML control. In the next section, you change the method name, change the message type, and add an XQuery selector.

To Modify the ebXML Control Definition File

  1. In the Data Palette, right-click on the ebXML selectorSellerControl.
  2. Select Edit from the drop-down menu.

    3. The SelectorSellerControl is displayed in Design View.

  3. Right-click on the arrow going to the request method, as illustrated in the following graphic.


    4.  
  4. Select Rename from the drop-down menu.
  5. Enter processOrder.
  6. Press the Enter key.

    7. The method name now matches the name of the method on the participant business process. This method name corresponds to the eb:Action element in the ebXML message envelope.

  7. Right-click on the arrow going away from the response method.
  8. Select Delete from the drop-down menu.

    9. You deleted the pre-configured response method since we are not sending a response in this example.

  9. Click on processOrder.

    10. The ebXML Source View opens.

  10. Change the line void processOrder(XmlObject payload); to void processOrder(OrderDocument payload);
  11. The tooltip editor displays a suggested package to import, press Alt+Enter to accept.

    12. This ebXML control is now set up to use XML typed according to the schema you imported in To Import the Tutorial Schemas rather than generic untyped XML.

  12. Click the Design View tab.
  13. Double-click the arrow which points to processOrder.

    14. The Property Editor window opens with a graphical representation of the Start Method Schema. In this example, we assume that the target trading partner ID is contained in the Supplier ID element.

  14. Click Supplier_ID to select it.

    15. A selector XQuery statement is generated.

  15. Click OK.
  16. Select File—>Save or enter Ctrl+S to save your work.
  17. Close the SelectorSellerControl.jcx by clicking the x in the top right corner of the window.

The ebXML control is now configured to pick out the trading partner ID from the message according to the specifications of the XQuery statement you generated in the selector. The next step is to add a processOrder Control Send node to the business process.

To Create the processOrder Control Send Node

  1. In the Data Palette, expand the selectorSellerControl by clicking on the + next to it.
  2. Select the void processOrder(OrderDocument payload) method. The name of the method on this control must match the method name of the Receive request node in the participant process.
  3. Drag the selected method into Design View and drop it on the which appears immediately following the Client Request node.

    4. A new Control Send node named processOrder is added to your business process. For more information about Control Send nodes, see Interacting With Resources Using Controls available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideControls.html.

  4. To specify the order variable as the input variable:
    1. In the Data Palette, select order from the list of XML variables.
    2. Drag and drop it onto the processOrder Control Send node.

This concludes the creation of the SelectorBuyer business process. In this section, you learned how to customize the participant and initiator processes to use typed XML and custom method names. You also learned how to use and XQuery selector to extract the target trading partner ID form the payload message rather than declaring it statically. The next section describes how to test your business processes.

To Test the SelectorBuyer Process

  1. Click on the WebLogic Workshop menu. (For more detailed instructions refer back to, To Test the Seller Process.)
  2. To enter test data, do one of the following:
  3. Confirm that the order.xml file was written out correctly to the C:\tptutorial directory by checking that the time stamp of the file is current.

 

Step 4: Sending Raw Data (Binary File) Through an ebXML Exchange

In this example, we will use ebXML to send binary data between two trading partners through a Message Broker channel. This example builds on the examples describes in previous sections. If at any time you need more information about how to complete a task that was previously explained, refer back to the preceding sections. This section contains the following procedures:

Building the BinarySeller Business Process

This example builds on what you have learned in the previous examples. If at any time you need more detailed instructions, refer back to Building the Seller Business Process. This section contains the following tasks:

To Create the BinarySeller Business Process

  1. Create a new folder in your application under \ebxml\oneway\binary.
  2. Create a new ebXML participant process in this folder named BinarySeller.jpd.
  3. Remove the Respond to request node.
  4. Modify the Receive request node as follows:
    1. Remove the XmlObject parameter data type.
    2. Add a RawData parameter data type (found in NonXML option).
    3. Create a new variable named data of type RawData.
    4. Specify the new variable as the one to assign to the request method.
  5. Create a new File control with the following values specified:
  6. Drag and drop the write method of the file control after the Receive request node in the business process.
  7. Double-click the write node and on the Send Data tab, specify data as the variable to assign to the write method.

To Test the BinarySeller Business Process

  1. Click on the WebLogic Workshop menu. (For more detailed instructions refer back to, To Test the Seller Process.)
  2. Use any binary file (for example an image file) as binary payload test data.
  3. Confirm that the data.bin file was written out correctly to the C:\tptutorial\binary-in directory by checking that the time stamp of the file is current.

Building the BinaryBuyer Business Process

For the initiator side of this example, the process will look very similar to those in previous examples, except that it will be invoked through a subscription to a file event which will cause the process to pick up a file from a directory. This section contains the following tasks:

To Create the BinaryBuyer Business Process File

Use the instructions outlined in detail in Building the Buyer Business Process to complete the following tasks:

  1. In the ebxml\oneway\binary folder, create a new business process named BinaryBuyer.jpd.
  2. Double-click the Starting Event and select the Subscribe to a Message Broker channel and start via an event (Timer, Email, File, Adapter, etc.) option.

Before you can start to configure the Message Broker Subscription node, you need to create a subscription channel file to which the subscription node can listen for events.

To Create the Channel File

  1. In the Application tab, right-click on the Schemas folder.
  2. Select New—>Channel File
  3. Enter tptutorial.channel as the file name.
  4. Click Create.

    5. The new channel file is created, added under the Schemas folder in the Application tab, and displayed on screen. An application build is also started automatically to build the Schemas project.

  5. In the channel file code, locate the following line:
    <channel name="SampleRawDataChannel" messageType="rawData"/>
  6. Remove the comment tags <!-- and --> preceding and following the line.
  7. Select—>File—>Save or enter Ctrl+S to save the channel file.

    8. The Schemas project builds again.

  8. Close the Channel file by clicking the x in the top right corner of the window.

The sample channels defined in the file are now available for selection in the subscription node. For more information about channels, see Publishing and Subscribing to Channels available at http://edocs.bea.com/workshop/docs81/doc/en/integration/howdoI/howPubSub.html.

To Configure the Subscription Node

  1. Double-click the Subscription node.

    2. The Subscription node builder is invoked.

  2. On the General Settings tab, select the SampleRawDataChannel from the Channel name drop-down list.
  3. In the Receive Data tab:
    1. Create a variable named data of type RawData
    2. Select it to be the variable to assign to the subscription method.
  4. Click Apply.
  5. Click Close.

You have now completed the configuration of your subscription node. To learn more about subscription nodes, see Subscription Start (Asynchronous) available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideStartSub.html and Subscription Start (Synchronous) available at http://edocs.bea.com/workshop/docs81/doc/en/integration/wfguide/wfguideStartSyncSub.html.

In the next section, you create a ebXML control to be used to communicate with the participator business process.

To Create the ebXML Control

  1. Use the instructions in To Create the ebXML Control and Control Node to create an ebXML with the following values:
  2. Click Create.
  3. From the Data Palette, drag and drop the void request(RawData payload) method on the target appearing in the business process below the Subscription node.
  4. From the Data Palette, drag and drop the data variable in the Non-XML list onto the request node.

The BinaryBuyer business process is now complete, run and test it to ensure that it is working properly.

To Test the BinaryBuyer Business Process

  1. Click on the WebLogic Workshop menu. (For more detailed instructions refer back to, To Test the Seller Process.)
  2. Use an image file as the binary payload test data.
  3. Confirm that the data.bin file was written out correctly to the C:\tptutorial\binary-in directory by checking that the time stamp of the file is current.

Note: Before you test your business process, make sure that you have completed the To Create the Channel File section. If you do not create a channel file before testing the process, you will encounter an error.

Creating a File Event Generator

In this section you create the file event which will invoke the BinayBuyer business process when a raw data type file is dropped in a directory.

To Create the File Event

  1. Create the following new directory on your hard drive:
  2. If not already running, start your WebLogic Server by selecting Tools—>WebLogic Server—>Start WebLogic Server.
  3. After the Server is running, open the WebLogic Administration Console by selecting Tools—>WebLogic Integration—>WebLogic Administration Console.
  4. Log in to the console using the server user name and password that you specified in the Step 1: Create a New WebLogic Integration Domain section.
  5. Click Event Generators.

    6. The Event Generators page opens.

  6. Click Create New.
  7. Enter TPTutorial as the Generator Name.
  8. Click Submit.

    9. The File Event Generator Definition page opens

  9. Click Define a New Channel Rule.

    10. The File Generator Channel Rule Definition page opens.

  10. Enter the following parameters:
  11. Click Submit.

You have completed creating the File Event. For more information about the WebLogic Administration Console and Event Generators, see Event Generators available at http://edocs.bea.com/wli/docs81/manage/evntgen.html.

To Test the Sending Raw Data Example

  1. Click on the WebLogic Workshop menu to deploy and run the BinaryBuyer business process.
  2. Put a binary file in the binary-out directory you created earlier. In a few seconds it should disappear and a file named data.bin should appear in the binary-in directory.

Note: About Message Tracking: In this and previous examples, all messages sent via ebXML are tracked in the tracking database. In the WebLogic Administration Console, navigate to Trading Partner Management—>Message Tracking to look at the messages. Basic message information and payload information are both tracked. You can also navigate from the message to the process that created or consumed the message. For more information see, Trading Partner Management (available at http://edocs.bea.com/wli/docs81/manage/tpm.html) in Managing WebLogic Integration Solutions.

 

Step 5: Creating a Roundtrip ebXML Conversation

This example illustrates how to implement an ebXML conversation in which a request message (order request) is followed by a response message (invoice). The first part of the conversation is identical to the one-way scenario you developed earlier. In this example, you add a Client Response node to the participant business process and use the ebXML control callback for the response message. This section contains the following procedures:

Building the RoundtripSeller Business Process

This example builds on the previous examples that you have completed. If at any time you need more detailed instructions, refer back to Building the Seller Business Process to complete the following sections:

To Create the Business Process File and Configure the Receive Request Node

  1. Create a new folder in your application named roundtrip as a sub folder of the ebxml folder.
  2. In the roundtrip folder, create a new ebXML participant process named RoundtripSeller.jpd, but do not delete the Respond to request node.
  3. Double-click the Receive request node and configure as follows:
    1. Rename the method to processOrder.
    2. Remove the XmlObject payload parameter type.
    3. Add the parameter type OrderDocument (from b2border.xsd)
    4. Create a new variable named order of type OrderDocument and select it as the variable to be assigned to the method.
    5. Click Apply, then click Close.

For illustration purposes, this example simplifies the order/invoice process.The seller will again write the incoming order out to file and for the response, the seller will read an invoice document from the file system. The invoice will be the same for each order. In production scenarios, the seller process could instead read the information from a database, obtain it from a message queue, or get it from a backend application as an event from an Application View control. The process could also delegate processing of the order to a subprocess, which is illustrated in the next example Step 6: Implementing the Public/Private Pattern. For more information about Application View controls, see Application View Control available at http://edocs.bea.com/workshop/docs81/doc/en/integration/controls/controlsAppView.html.

To Create the File Controls and Configure the Control Nodes

  1. Add a new File control named file and configure it to write out order.xml to C:\tptutorial\

    2. Note: To save time, you can drag and drop the File.jcx in the oneway folder onto the RoundtripSeller.jpd Design View. This will create a new instance of the File.jcx.

  2. Drag and drop the write method to the target that appears below the Receive request node.
  3. Double-click on the write node.
  4. Configure the node to send the order variable to the write method.
  5. Create a new directory on your hard drive named C:\tptutorial\invoice.
  6. Copy the file C:\myapps\tptutorialapps\ebxml\ebxmlWeb\sampledata\sampleinvoice.xml to the C:\tptutorial\invoice directory
  7. Rename sampleinvoice.xml to invoice.xml.
  8. Create a second new File control named invoiceFile and configure it to read an XmlObject (invoice.xml) from the C:\tptutorial\invoice directory by using the following configurations:
  9. Drag and drop the read method to the target that appears below the write node.
  10. Double-click the read node.
  11. Click Receive Data.

    12. The method expects untyped XML (XmlObject) but our invoice.xml file contains typed XML so we will need to do a simple transformation between the two.

  12. Select the Transformation Option.
  13. Click Select Variable—>Create New Variable....

    14. The Create Variable window opens.

  14. Enter invoice as variable name.
  15. Expand b2binvoice.xml and select Invoice.
  16. Click OK.

    17. The Create Variable window closes and your new variable is listed in the variable pane of the node builder.

  17. Click Create Transformation.

    18. The Transformation Tool window opens.

  18. Drag and drop the XmlObjectDoc in the Source Schema pane to the Invoice root in the Target Schema pane.

    19. An XQuery transformation is created a corresponding transformation control is created and stored in the RoundtripSellerTransformation.dtf file, which was created in your Application pane when you opened the Transformation tool.

  19. Close the Transformation Tool window by clicking on the x in the top right corner of the window.
  20. Click Yes in the Save Before Closing dialogue window.
  21. Click Close in the node builder.

The transformation you created in the preceding steps, only transforms from one data type to another. In production scenarios, you would use the Transformation Tool to convert from the backend system format to the format expected by the trading partner. You can also use the Transformation Tool to manipulate data. For more information about the Transformation Tool, see Guide to Data Transformation available at http://edocs.bea.com/workshop/docs81/doc/en/integration/dtguide/dtguideIntro.html.

The next step in this example is to configure the Respond to request node.

To Configure the Respond to Request Node

  1. Double-click the Respond to request node.
  2. Rename the method name to onInvoice.
  3. Remove the XmlObject payload parameter type.
  4. Add a parameter of type Invoice from the b2binvoice.xsd schema.
  5. Click Apply.
  6. Click Send Data.
  7. Select invoice from the Select variables to assign drop-down list.
  8. Click Apply.
  9. Click Close.

You have completed building the seller (participant) side of this example. The seller will receive an order document from the buyer, write it out to file, read in an invoice file and send it to the buyer. The name of the ebXML service created for this transaction is RoundtripSeller. The message exchange will be carried out as a single ebXML conversation. The Trading Partner Integration (TPI) system automatically manages the ebXML conversation and ensures that the same conversation ID is used within the same participant process instance.

To Deploy the RoundtripSeller Business Process

  1. Click on the WebLogic Workshop menu to deploy the business process.
  2. Close the Test Browser window.

Testing the process at this point would create an exception on the callback method since you have not yet created the initiator process. That is why you only deploy the process so that it will run properly when you test the initiator process later on.

Building the RoundtripBuyer Business Process

This section builds on the tasks that you have learned in previous examples. If at any time you need more detailed descriptions, refer back to Building the Buyer Business Process while completing the following tasks:

To Create the Business Process and Configure the Client Request Node

  1. In the roundtrip folder, create a new business process named RoundtripBuyer.jpd.
  2. Double-click the Starting Event.
  3. Select Invoked via a Client Request.
  4. Click OK.
  5. Double-click the Client Request node and configure as follows:
    1. Change the method name to startBuyer.
    2. Add a parameter type of type Order from the b2border.xsd schema