Skip navigation.

eDocs Home > BEA WebLogic Integration 8.1 Documentation > Tutorials for Trading Partner Integration > Tutorial: Building RosettaNet 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 RosettaNet Solutions

This topic describes how to implement RosettaNet solutions for trading partner integration in BEA WebLogic Integration. It contains the following sections:

RosettaNet is a business protocol that enables enterprises to conduct business over the Internet. To learn about RosettaNet, see http://www.rosettanet.org.

 

Tutorial Goals

This tutorial has the following goals:

 

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 RosettaNet 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:

To learn more about the RosettaNet business protocol and how to implement RosettaNet solutions, see:

 

Note About Obtaining RosettaNet W3C XSD Schemas

The RosettaNet W3C XSD schemas for selected PIPs are included in the RosettaNet Self-Test Kit (STK) which can be downloaded from the Developer Tools area on the RosettaNet Ready Web site, available at: http://www.rosettanet.org.

If the schema for the PIP you are using is not available on this web site, it is possible to implement RosettaNet solutions in WebLogic integration using RosettaNet message definitions specified as DTD files. However, it is recommended to use W3C XSD files instead, since many of the WebLogic Integration tools such as the XQuery mapping tools (used to define data transformations) only support XSD schemas.

If you want to use the graphical XQuery mapping tools, you need to convert the RosettaNet DTD files to W3C XSD files (using a tool like XML Spy Enterprise Edition) and then import the XSD files into your project. Make sure that you refer to the RosettaNet Message Guidelines for the PIP which DTD file you are converting and add the appropriate validation rules for Service Content Validation to your XSD file after the conversion. For instructions on how to convert the files using XML Spy, see Converting RosettaNet DTD Schemas to XSD Schemas.

In this tutorial, all the XSDs necessary to complete the examples are included in the tutorial files.

 

Tutorial Overview

The RosettaNet example includes business process definitions (JPDs), schemas, and other files that illustrate how to implement RosettaNet PIPs using WebLogic Integration 8.1. The example business process files implement common design patterns and provide a head start for building initiator and participant business processes for RosettaNet conversations. Rather than build the business processes from scratch, you can easily adapt the example files to implement any PIP.

This topic contains the following sections:

The PIPs implemented in this tutorial follow RosettaNet Implementation Framework (RNIF) 2.0.

PIPs Implemented In These Examples

The following table describes the RosettaNet examples that are provided in this tutorial:

Table 2-1 RosettaNet Examples 

PIP

Description

0A1

Implements PIP0A1: Notification of Failure.

You can initiate this business process from any other business process in which a RosettaNet notification of failure is required. For example, you can use this business process in conjunction with the RosettaNet Participant Business Process template provided in WebLogic Workshop. For more information, see Building RosettaNet Participant Business Processes in the WebLogic Workshop Help.

3B2

Implements PIP3B2: Notify of Advance Shipment. Described in Step 3: Open the PIP3B2: Notify of Advance Shipment Example.

3A4

Implements PIP3A4: Request Purchase Order. Described in Step 4: Open the PIP3A4: Request Purchase Order Example.

Folders in the RosettaNet Tutorial Application

The following table describes the folders you see in your application tab when you open the in the \tptutorialapps\rosettanet directory:

Table 2-2 Folders in \tptutorialapps\rosettanet 

Directory

Description

PIP0A1Schema

Schema project for the PIP0A1 schema.

PIP3A4Schema

Schema project for the PIP3A4 schema.

PIP3B2Schema

Schema project for the PIP3B2 schema.

pips

Contains business process folders for each example PIP implementation (PIP0A1Processes, PIP3A4Processes, and PIP3B2Processes) and the private administrator alert notification (privateAdmin).

System

Schema project for standard BEA WebLogic Integration system schemas.

Modules

Empty by default. Standard WebLogic Workshop folder for compiled Java code.

Libraries

Empty by default. Standard WebLogic Workshop folder for compiled Java code.

Security Roles

Empty by default. Standard WebLogic Workshop folder for defining security roles for this application.


 

RosettaNet Design Patterns

RosettaNet PIPs follow one of the following design patterns:

Table 2-3 RosettaNet PIP Design Patterns 

Directory

Description

Asynchronous single-action activity

Involves a single action message and a receipt acknowledgment:

  • Initiator sends a business message to the participant.

  • The participant sends a receipt acknowledgement to the initiator.

The PIP3B2 (Notify of Advance Shipment) example, which implements this design pattern, is described in Step 3: Open the PIP3B2: Notify of Advance Shipment Example.

Asynchronous two-action activity

Involves actions messages and receipt acknowledgments from both trading partners:

  • Initiator sends a business message to the participant.

  • The participant sends a receipt acknowledgement to the initiator.

  • The participant sends a business message to the initiator.

  • The initiator sends a receipt acknowledgement to the participant.

The PIP3A4 (Request Purchase Order) example, which implements this design pattern, is described in Step 4: Open the PIP3A4: Request Purchase Order Example.

Synchronous one-action / two-action activity

Synchronous versions of the above design patterns, in which an immediate response is required. The current release of BEA WebLogic Integration does not support synchronous design patterns.

Note: Synchronous RosettaNet design patterns usually do not implement the receipt acknowledgments described in the asynchronous single-action and two-action activity design patterns.


 

The example PIP implementations provided in this tutorial allow you to quickly and easily build any PIPs that following the same design patterns, as described in Implementing New PIPs Based on the Example PIPs.

For more information about RosettaNet design patterns and conversation choreography, see the following documents:

 

Tutorial Steps

This section describes the following tutorial steps:

Before you proceed through these steps, make sure that you have reviewed the material in Before You Begin.

Step 1: Open the RosettaNet Example Application

The RosettaNet example application contains all the PIP implementations described in PIPs Implemented In These Examples.

To open the RosettaNet example application:

  1. Start WebLogic Workshop, if you have not already done so.
  2. From the File menu, choose Open—>Application.
  3. Navigate to the tptutorialapps folder that you created in Step 3: Install the Tutorial Files.
  4. Open the rosettanet folder
  5. Open the rosettanet.work file.

    6. Note: If you are prompted to select a WebLogic Integration domain and server, select the WebLogic Integration domain that you created in Step 1: Create a New WebLogic Integration Domain (such as c:\bea\user_projects\domains\tptutorial)

    The Application tab displays the contents of the RosettaNet tutorial application, which is described in Folders in the RosettaNet Tutorial Application.


     
  6. On the Application tab, right-click the root rosettanet folder and choose Properties.
  7. In the Application Properties dialog, verify that the Server Home Directory points to the WebLogic Integration domain that you created in Step 1: Create a New WebLogic Integration Domain (such as c:\bea\user_projects\domains\tptutorial), and then click the OK button.
  8. On the Application tab, select the root rosettanet folder and select Build—>Build Application (or press F7) to build your application.

    9. Note: You may see green compilation warnings in the build tab. You can ignore these warnings, the example will still execute correctly.

  9. On the Application tab, double-click the pips folder to display folders containing the example business processes.

Step 2: Open the PIP0A1: Notification of Failure Example

This topic describes the example implementation of PIP0A1: Notification of Failure. It contains the following sections:

For detailed information about PIP0A1, see http://www.rosettanet.org.

About the PIP0A1 Example

PIP0A1 is an example of how to implement the PIP0A1 Notification of Failure. The PIP0A1Processes folder contains business process definitions for PIP0A1. The PIP0A1Schemas schema project contains the schema file for the PIP0A1 message.

The PIP0A1 demonstrates how to set up business logic, properly process error messages, and then, based on the business logic and error messages, open the correct channel to use when sending notifications of failure to the appropriate failure administrator. In this tutorial, the PIP0A1 Notification of Failure scenarios are:

Note: For demonstration purposes, the business processes in the tutorial examples are purposely configured to trigger Notification of Failure.

The following steps provides a brief overview of the PIP A01 business logic:

  1. The PIP0A1 Failure Notifier business process (PIP0A1.jpd) receives a Notification of Failure request from either the PIP3A4 Seller or the PIP3B2 Receiver side.
  2. The Failure Notifier processes the Notification of Failure request and sends a Notification of Failure message to the appropriate Report Administrator (in this case the PIP0A1ReportAdmin.jpd). The Failure Notifier process also writes a notification on the WebLogic Server Console to show that it has sent the message.
  3. The Report Administrator process validates the Notification of Failure message and sends a receipt acknowledgement to the Failure Notifier. The process also writes a notification on the WebLogic Server Console to show that it has received the message.

Components of the PIP0A1 Example

When you open the PIP0A1Processes folder in WebLogic Workshop, the application tab displays the contents of the folder.


 

The following table summarizes the components of the PIP0A1 example:

Table 2-4 Components of the PIP0A1: Notification of Failure Example 

Role / Component

Description

PIPA01.jpd

The initiator business process that receives the Notification of Failure from the PIP3A4 initiator or the PIP3B2 participant. It then sends a Notification of Failure to the failure administrator business process by using an instance of the RosettaNet control.

Rn.jcx

RosettaNet control definition file used to exchange messages with the failure administrator business process. For more information about the RosettaNet control, see RosettaNet Control in the WebLogic Workshop Online Help.

PIPA01Control.jcx

Process control definition file that wraps PIPA01.jpd for use in other processes. Automatically generated by right-clicking the PIPA01.jpd file in the Application tab and choosing Generate Process Control.

PIP0A1ReportAdmin.jpd

Business process that demonstrates the back end business logic used to process error messages and notifications.

PIP0A1Transformation.dtf

Transformation control definition file which is used to generate XQueries. To learn more about transformation and XQueries, see Guide to Data Transformation.

getStaticProperties.xq

XQuery that was generated when the getStaticProp Control Send with Return node was configured.

getFailureNotificationDoc.xq

XQuery that was generated when the getFailureNotificationDoc Control Send with Return node was configured.

Sample Data

Directory which contains sample XML data illustrating typical elements and data suggested by RosettaNet Message guidelines.

Note: The data in this directory is not used in this tutorial since the input used when running the example is generated through an XQuery.


 

Walkthrough of the Failure Notifier Business Process

This section describes the example initiator business process (PIP0A1.jpd). To view this business process:

  1. On the Application tab in WebLogic Workshop, open the PIP0A1Processes folder.
  2. Double click the PIP0A1.jpd file.
  3. If necessary, collapse the Retry block paths to see only the main (success) path.


    4.  

Success Process Path

The success path of the business process is as follows:

  1. The Client Request node named Start receives a notification of failure message.
  2. The Control Send with Return node named getStaticProp extracts the RosettaNet Context properties from the incoming message. For more information about RosettaNet Context, see RosettaNet Control Interface.
  3. The setProperties Control Send node maps the extracted properties to a document based on the PIP0A1 Schema
  4. The Control Send with Return node named getFailureNotification uses the PIPA01 transformation query to map the RosettaNet Context properties to a document based on the PIPA01 Schema.

    5. To view the fields that are being mapped, in the Application tab, double click on the getFailureNotification.xq file.

  5. The Perform node named setDocType sets the DOCTYPE DTD value in the transformation output.

    6. Note: This step is necessary since the WebLogic Integration transformation output by default does not contain the DOCTYPE property.

  6. The group named Retry block contains a Control Send node named Send Notification of Failure and a Control Receive node named Receipt acknowledgement. This block sends a notification of failure to the PIP0A1ReportAdmin business process and waits for an acknowledgement that the message was received.

    7. For demonstration purposes, the Send Notification of Failure node also prints a message to the WebLogic Server Console after it has sent the message to the PIP0A1ReportAdmin process.

  7. The Client Response node at the end of the business process is a place holder for any business logic that would take place after the Notification of Failure message is sent to the PIP0A1ReportAdmin business process.

Failure Paths

The OnTimeout path handle failure management, such as in the event of a network failure. To view the failure path:

  1. Expand the OnTimeout path next to the group of nodes named Retry block.


    2.  

    This path represents a standard BPM OnTimeout construct. The timeout value is set to two hours (the standard PIP retry interval) and three retries (the standard PIP retry count). Thus, if for any reason the acknowledgement fails to arrive within two hours, the group will be retried and the sendNotification of Failure step will be executed again. The OnTimeout path contains a condition that determines whether retries have been exhausted and, if so, logic could be added to the path which takes the appropriate action.

Walkthrough of the Report Administrator Business Process

The participant business process of the PIP0A1 example is named PIPA01ReportAdmin.jpd. To view the participant business process in WebLogic Workshop, in the Application tab, double click on PIPA01ReportAdmin.jpd.


 

The Report Administrator business process includes the following steps:

  1. The Notification of Failure message arrives at the Client Request node named Receive NoF.
  2. The Perform node named Print NOF on System Console prints an acknowledgement on the WebLogic Server Console window. This node is a place holder for any business logic that would take place in a PIP0A1 Report Administrator business process used in production mode.
  3. The Client Response node named Send NoF Receipt Acknowledgment sends an acknowledgement back to the Failure Notifier process.

The following two examples in this tutorial, both utilize the PIP0A1 notification of failure example. To see how the example works, complete either Running the PIP3B2 Example or Running the PIP3A4 Example.

Step 3: Open the PIP3B2: Notify of Advance Shipment Example

This topic describes the example implementation of PIP3B2: Notify of Advance Shipment. It contains the following sections:

For detailed information about PIP3B2, see http://www.rosettanet.org.

About the PIP3B2 Example

PIP3B2 is an example of the asynchronous single action activity design pattern described in RosettaNet Design Patterns. The PIP3B2Processes folder contains business process definitions for PIP3B2. The PIP3B2Schemas schema project contains the schema file for the PIP3B2 message. The sampledata directory contains sample XML documents that you can use in section Running the PIP3B2 Example.

The following steps provides a brief overview of the PIP3B2 business logic:

  1. The Shipper (initiator process PIP3B2.jpd) constructs an Notify of Advance Shipment message and sends it to the Receiver (participant process- PIP3B2Participant.jpd).
  2. The Receiver validates the message and sends a receipt acknowledgement to the Shipper.
  3. The Receiver submits the message to the backend system (PIP3B2ParticipantPrivate.jpd) for further processing.
  4. The backend system encounters a problem during processing and invokes the PIP0A1 example.

Components of the PIP3B2 Example

When you open the PIP3B2Processes folder in WebLogic Workshop, the application tab displays the contents of the folder.


 

The following table summarizes the components of the PIP3B2 example:

Table 2-5 Components of the PIP3B2: Notify of Advance Shipment Example 

Role / Component

Description

Shipper (Initiator)

RosettaNet role name.

PIP3B2.jpd

Public initiator business process that sends the message, waits for the acknowledgement, and handles failures. Uses Rn.jcx, a RosettaNet control instance.

Rn.jcx

RosettaNet control definition file which is used to exchange messages with the Receiver via RNIF. For more information about the RosettaNet control, see RosettaNet Control in the WebLogic Workshop Online Help.

The annotations on this control instance in PIP3B2.jpd include the PIP name and version, role names.

PIP3B2Control.jcx

Process control definition file that wraps PIP3B2.jpd for use in other processes. Automatically generated by right-clicking the PIP3B2.jpd file in the Application tab and choosing Generate Process Control.

PIP3B2Private.jpd

Private business process that invokes the PIP3B2.jpd business process via a process control.

This private business process can utilize the full power of BEA WebLogic Integration to access the backend systems, assemble the information, and transform the request data into the data format required for PIP3B2.

PIP3B2PrivateTransformation.dtf and PIP3B2PrivatepIP3B2ControlStart.xq (the associated.xq file)

Example transformation file. Automatically generated when a transformation is defined in a process node.

PIP3B2Transformation.dtf and getStaticProperties.xq (the associated.xq file)

Example transformation file. Automatically generated when a transformation is defined in a process node.

Receiver (Participant)

RosettaNet role name.

PIP3B2Participant.jpd

Public business process that receives the RNIF message and sends the receipt acknowledgement to the Shipper. The RosettaNet annotations include the PIP name, version, and role. For more information, see @jpd:rosettanet Annotation. in the WebLogic Workshop online help.

PIP3B2ParticipantPrivate.jpd

Private business process that represents the backend processing of the shipment notice.

PIP3B2ParticipantPrivateControl.jcx

Process control that wraps the private process for use in PIP3B2Participant.jpd. Automatically generated by right-clicking the PIP3B2ParticipantPrivate.jpd file in the Application tab and choosing Generate Process Control.


 

Walkthrough of the Shipper Business Process

This section describes the example initiator business process (PIP3B2.jpd) for PIP3B2. To view this business process:

  1. On the Application tab in WebLogic Workshop, double-click the PIP3B2Processes folder.
  2. Double-click the PIP3B2.jpd file.
  3. If necessary, collapse the OnTimeout and On Error Message paths, as well as the Set static properties for header and Retry block groups to see only the main (success) path.


    4.  

Success Path

The success path is the main path of the business process:

  1. The Client Receive node named Start invokes the process when the Notify of Advance Shipment XML document (in this tutorial, the client request comes from the private process) is received.
  2. The Set static properties for header group contains a Control Send with Return node named getStaticProperties and a Control Send node named setStaticProperties. These two nodes extract the RosettaNet properties from the message and then map them to a document based on the PIP3B2 Schema.
  3. The Retry block group contains a two nodes. The Control Send node named sendMessage sends a message to the Receiver (participant) via the sendMessage method on the RosettaNet control. The Control Receive node named Receipt acknowledgement waits for the receipt acknowledgement callback (rn_onAck method) from the Receiver.
  4. Once the acknowledgement is received, the process responds to the private process via the Client Response node named Return Success.

Because PIP3B2 implements the single-action activity design pattern, no business action is returned from the Receiver—only a business signal (Receipt Acknowledgment or Exception). The response to the private process merely indicates a successful completion and returns no data.

Failure Paths

The OnTimeout and On Error Message paths handle failure management, such as in the event of a network failure. To view the failure paths:

  1. Expand the OnTimeout path next to the group of nodes named Retry block.


    2.  

    This path represents a standard BPM OnTimeout construct. The timeout value is set to two hours (the standard PIP retry interval) and three retries (the standard PIP retry count). Thus, if for any reason the acknowledgement fails to arrive within two hours, the group will be retried and the sendMessage step will be executed again. The OnTimeout path contains a condition that determines whether retries have been exhausted and, if so, the PIP 0A1 (Notification of Failure) subprocess is triggered (via a Control Send node), and the process responds to the private process with an error and finishes.

  2. Expand the On Error Message path next to the PIP3B2 node at the top of the process.


    3.  

    The Global Process Timeout is configured for the standard PIP timeout value of 24 hours. If the whole process fails to complete within this time, the PIP0A1 (Notification of Failure) subprocess is triggered and an error is returned to the private process.

    Finally, the Receiver might reject the message for a variety of reasons (for example, the message fails validation). The message rejection is represented as the onError callback on the RosettaNet control. You can see that the global On Error Message handler is prepared to receive the error at any time and, if it does, it starts a subprocess to notify the administrator of the problem, returns an error to the private process, and exits. Notice that, if we cannot successfully send the message (for example, due to network problems), the business process starts the PIP0A1 (Notification of Failure) to try to notify the remote partner of the problem. Similarly, upon receipt of an error from the Receiver, the business process should notify the local administrator as well as the remote administrator.

Walkthrough of the Receiver Business Process

To view the participant business process in WebLogic Workshop, open the PIP3B2Participant.jpd file.


 

The participant business process includes the following nodes:

  1. The Client Request node named Receive Advance Shipping Notice receives the Notify of Advance Shipment message.
  2. The Check if Notification of Advance Shipment Decision node validates the message and:
  3. In the Invoke private process group, the Control Send node named processShipment, passes the Notify of Advance Shipment to a private business process for further processing while the get Private Response Control Receive node waits for an acknowledgement from the private process.

Walkthrough of the Private Business Processes

The private processes on both sides are place holders for processes which in production environments would interact with backend applications. For example, the shipment notice can be inserted into an ERP application via the Application View control and BEA adapters, sent on a message queue, and written out to file or database.

The public/private process pattern used in this example is not mandatory and is merely a recommended approach. You are free to partition your processes as best suits your environment. It is entirely possible to not use the private processes and implement all the necessary backend integration as well as RosettaNet interactions in a single process. However, separating processes into public (those that only deal with RosettaNet choreography) and private (those that deal with backend system integration) may improve the reuse and maintainability of your application.

In this example, the PIP3B2ParticipantPrivate.jpd is purposely configured to trigger an error and invoke the PIP0A1 example when you run the process.

Running the PIP3B2 Example

By default, BEA WebLogic Integration runs in Test (development) mode, which allows you to run the PIP3B2 example business processes on the same machine (collocated). In a production environment, each trading partner would run its respective business process on its own separate BEA WebLogic Integration server. For more information about the Test and Production modes, see "Configuring the Mode and Message Tracking" in Trading Partner Management (available at http://download.oracle.com/docs/cd/E13214_01/wli/docs81/manage/tpm.html) in Managing WebLogic Integration Solutions.

To run the PIP3B2 example:

  1. If it is not already running, start WebLogic Server. To do so, select 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. Open PIP3B2Participant.jpd and click on the WebLogic Workshop menu.

    3. If your application is not already built, WebLogic Workshop builds your project.

    Note: You may see green compilation warnings in the build tab. You can ignore these warnings, the example will still execute correctly.

    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.

    Do not actually try to execute it from the test browser. This step is needed to "prime" the participant process.

  3. Return to WebLogic Workshop, open PIP3B2Private.jpd and click on the WebLogic Workshop menu.
  4. In the test browser, Click Browse, and navigate to [file location]\rosettanet\pips\PIP3B2Processes\sampledata\3B2AdvanceShipmentNotificationMessageBase.xml

    5. Where [file location] is the directory in which you installed the tutorial files as described in Step 3: Install the Tutorial Files.

  5. Click clientRequest.
  6. In a few moments, the end-to-end choreography will execute. The client response will echo back the XML message.Bring up your WebLogic Server Console
  7. In a few moments, you should see the following messages on the console:
  1. Optionally, you can open the BEA WebLogic Integration Administration Console and observe message tracking and process tracking entries.

Step 4: Open the PIP3A4: Request Purchase Order Example

This topic describes the example implementation of the PIP3A4: Request Purchase Order. It contains the following sections:

For detailed information about PIP3A4, see http://www.rosettanet.org.

About the PIP3A4 Example

PIP3A4 is an example of the asynchronous two-action activity design pattern described in RosettaNet Design Patterns. The PIP3A4Processes folder contains business process definitions for PIP3A4. The PIP3A4Schemas schema project contains the schema file for the PIP3A4 message. The sampledata directory contains sample XML documents that you can use when Running the PIP3A4 Example.

The PIP3A4 Request Purchase Order involves the following steps:

  1. The Buyer (initiator) constructs a Purchase Order Request message and sends it to the Seller (participant).
  2. The Seller validates the message and sends a receipt acknowledgement to the Buyer.
  3. The Seller then submits the order request message to the backend system for further processing.
  4. The Seller's backend system generates a Purchase Order Confirmation (which confirms the availability of requested products and the expected ship dates).
  5. The Seller sends the confirmation to the Buyer.
  6. The Buyer acknowledges the receipt of the message to the Seller.
  7. The Buyer passes the Purchase Order Confirmation to its backend system for processing, but encounters an error during processing which triggers the PIP A01 example.

Components of the PIP3A4 Example

When you open the PIP3A4Processes folder in WebLogic Workshop, the application tab displays the contents of the folder.


 

The following table describes the components of the PIP3A4 example implementation.

Table 2-6 Components of the PIP3A4 (Request Purchase Order) Example 

Role / Component

Description

Buyer (Initiator)

RosettaNet role name.

PIP3A4.jpd

Public business process that exchanges messages with the seller, waits for the acknowledgement, and handles failures. Uses the RosettaNet control instance (Rn.jcx).

Rn.jcx

RosettaNet control definition file used to exchange messages with the Seller via RNIF. For more information about the RosettaNet control, see RosettaNet Control in the WebLogic Workshop Online Help.

The annotations on this control instance in PIP3A4.jpd include the PIP name, version, and role names.

PIP3A4Control.jcx

Process control definition file that wraps PIP3A4.jpd for use in other processes. Automatically generated by right-clicking the PIP3A4.jpd file in the Application tab and choosing Generate Process Control.

PIP3A4Private.jpd

Private business process that invokes the PIP3A4 process via a process control. This business process can utilize the full power of BEA WebLogic Integration to access the backend systems, assemble the information, and transform it into the required format for PIP3A4.

PIP3A4PrivateTransformation.dtf and the associated.xq files

PIP3A4Transformation.dtf and the associated getStaticProperties.xq file

Example transformation file. Automatically generated when a transformation is defined in a process node.

Seller (Participant)

RosettaNet role name.

PIP3A4Participant.jpd

Public business process that receives the message and sends the receipt acknowledgement, responds with a message and receives acknowledgement. The RosettaNet annotations include the PIP name, version, and role. For more information, see @jpd:rosettanet Annotation. in the WebLogic Workshop online help.

PIP3A4ParticipantPrivate.jpd

Private business process that represents the backend processing of the purchase order and the creation of the PO Confirmation.

fc.jcx

File control definition file which is used to read the PO Confirmation sample file from the local file system.

PIP3A4ParticipantPrivateControl.jcx

Process control that wraps the private process for use in PIP3A4Participant.jpd. Automatically generated by right-clicking the PIP3A4ParticipantPrivate.jpd file in the Application tab and choosing Generate Process Control.

PIP3A4ParticipantTransformation.dtf and the associated getStaticProperties1.xq file

Example transformation file. Automatically generated when a transformation is defined in a process node.


 

Walkthrough of the Seller Business Process

This section describes the example initiator business process (PIP3A4.jpd) for PIP3B2. To view this business process:

  1. In WebLogic Workshop, open the PIP3A4.jpd file.
  2. If necessary, collapse the OnTimeout and On Error Message paths, as well as any groups to see only the main (success) path.


    3.  

Success Path

The success path business logic is as follows:

  1. The Client Request node named Start receives the Purchase Order Request XML document message (in this tutorial, the client request comes from the private process).
  2. The Set properties that go into service header group contains a Control Send with Return node named getStaticProperties and a Control Send node named setStaticProperties. These two nodes extract the RosettaNet properties from the message and then map them to a document based on the PIP3B2 Schema.
  3. The Retry block group contains two nodes. The Control Send node named sendMessage sends a message to the Seller (participant) via the sendMessage method on the RosettaNet control. The Control Receive node named Receipt acknowledgement waits for the receipt acknowledgement callback (rn_onAck method) from the Receiver.
  4. Once the acknowledgement is received, the business process waits for the Purchase Order Confirmation at the Control Receive node named onMessage.
  5. The Correctnonamespace Perform Node adds the correct name space to the received XML Bean. (This step is necessary since Schemas in the project folder cannot have the same name space.)
  6. After receiving the Purchase Order Confirmation, the Decision node validates the message and:
  7. The business process responds to the private process with the PO Confirmation through the Return PO ack Client Response node.
  8. The Process Message Perform node is purposely configured to trigger an error and invoke the PIP0A1 example.

Note: BEA WebLogic Integration allows the receipt acknowledgement and business message to be received in either order, in conformance with RosettaNet specifications. If the initiator receives the response message before the receipt acknowledgement, the response message is queued for later processing.

Failure Paths

The OnTimeout and On Error Message paths handle failure management, such as in the event of a network failure. To view the failure paths:

  1. Expand the OnTimeout path next to the group of nodes named Retry block.


    2.  

    This path represents a standard BPM OnTimeout construct. The timeout value is set to two hours (the standard PIP retry interval) and three retries (the standard PIP retry count). Thus, if for any reason the acknowledgement fails to arrive within two hours, the group will be retried and the sendMessage step will be executed again. The OnTimeout path contains a condition that determines whether retries have been exhausted and, if so, the PIP 0A1 (Notification of Failure) subprocess is triggered (via a Control Send node), and the process responds to the private process with an error and finishes.

  2. Expand the On Error Message path next to the PIP3A4 node at the top of the process.


    3.  

    The Global Process Timeout is configured for the standard PIP timeout value of 24 hours. If the whole process fails to complete within this time, the PIP0A1 (Notification of Failure) subprocess is triggered and an error is returned to the private process.

    Finally, the Receiver might reject the message for a variety of reasons (for example, the message fails validation). The message rejection is represented as the onError callback on the RosettaNet control. You can see that the global On Error Message handler is prepared to receive the error at any time and, if it does, it starts a subprocess to notify the administrator of the problem, returns an error to the private process, and exits. Notice that, if we cannot successfully send the message (for example, due to network problems), the business process starts the PIP0A1 (Notification of Failure) to try to notify the remote partner of the problem. Similarly, upon receipt of an error from the Receiver, the business process should notify the local administrator as well as the remote administrator.

Walkthrough of the Buyer Business Process

The participant business process (PIP3A4Participant.jpd) on the Seller side is less complex than the initiator business process. To view the participant business process in WebLogic Workshop, open the PIP3A4Participant.jpd file.


 

The participant business process includes the following steps:

  1. The Client Request node Receive PO message receives the Purchase Order Request message.
  2. The Check for noNamespace and do the correction Perform node adds the correct name space to the received XML Bean. (This step is necessary since Schemas in the project folder cannot have the same name space.)
  3. The Decision node validates the PO and:
  4. In the Invoke Private Process group, the processOrder Control Send node passes the PO Request to a private business process for further processing, while the onPOAck Control Receive node waits for the response back from the private process. The private process constructs the response that was sent after reading the confirmation using a File Control.
  5. The Controls Send with Return node named getStaticProp extracts the RosettaNet Context properties from the incoming message. These properties are needed only in case of errors. These properties can be saved for later use and contains the information that is needed to construct the PIP0A1 Notification of Failure. For example: from / to / message id / etc.
  6. In the Retry block group, the Send PO Acknowledgement Client Response node sends the Purchase Order Confirmation message to the buyer using the sendReply callback method, while the Receive receipt acknowledgement Client Request node waits for the receipt acknowledgement.

Unlike the 3B2 participant business process, which merely receives the message, the 3A4 participant business process sends out a response, so it is necessary to account for failure scenarios, such as network failures or validation failure. Open the onTimeout path on the Retry Block to display the time-outs and retries. Note that this path is similar to the onTimeout path in the 3B2 initiator business process described in Walkthrough of the Shipper Business Process. In addition, there is a global onMessage handler that handles errors returned by the Buyer.

Walkthrough of the Private Business Processes

As in the 3B2 example, the private processes on both sides are merely place holders for backend business logic. The participant private process actually echoes the received message. You would typically customize these processes to tie them with the backend applications. For example, the shipment notice can be inserted into an ERP application via the Application View control and BEA adapters, sent on a message queue, written out to file or database.

The public/private process pattern used in this example is not mandatory and is merely a recommended approach. You are free to partition your processes as best suits your environment. It is entirely possible to not use the private processes and implement all the necessary backend integration as well as RosettaNet interactions in a single process. However, separating processes into public (those that only deal with RosettaNet choreography) and private (those that deal with backend system integration) may improve the reuse and maintainability of your application.

Running the PIP3A4 Example

To run the PIP3A4 example:

  1. This example uses a File Control to read the PO Confirmation message from your local file system. Before you can run the example, you have to set the directory path in the fc.jcx file so that it can find the correct sample data file:
    1. In the Application tab, double-click the fc.jcx file.
    2. Click the Source View tab.
    3. Set the directory-name attribute to:

      4. [file location]\tptutorialapps\rosettanet\pips\PIP3A4Processes\sampledata

      Where [file location] is the directory in which you installed the tutorial files as described in Step 3: Install the Tutorial Files.

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

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


     
  3. Open PIP3A4Participant.jpd and click on the WebLogic Workshop menu.

    4. If the project is not already built, WebLogic Workshop builds your project.

    Note: You may see green compilation warnings in the build tab. You can ignore these warnings, the example will still execute correctly.

    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.

    Do not actually try to execute it from the test browser. This step is needed to "prime" the participant process.

  4. Return to WebLogic Workshop, open PIP3A4Private.jpd and click .
  5. In the test browser, Click Browse, and navigate to [file location]\rosettanet\pips\PIP3A4Processes\sampledata\3A4PurchaseOrderRequestMessageBase_0010.xml

    6. Where [file location] is the directory in which you installed the tutorial files as described in Step 3: Install the Tutorial Files.

  6. Click clientRequest.

    7. In a few moments, the end-to-end choreography will execute. The client response will echo back the XML message.

  7. Bring up your WebLogic Server Console

    8. In a few moments, you should see the following messages on the console:

  1. Optionally, you can open the BEA WebLogic Integration Administration Console and observe message tracking and process tracking entries.

 

Implementing New PIPs Based on the Example PIPs

This topic describes implementing new PIP based on the example PIPs in this tutorial. It contains the following topics:

About Implementing New PIPs

You can implement a new PIP based on an existing PIP implementation with a similar design pattern. For example, PIP 3A2: Request Price and Availability, is an example of a message send with response design pattern. Therefore, the business process choreography is identical to that of PIP3A4. The main differences are that the request and response message schemas are different and the annotations must be changed. You can duplicate and rename the 3A4 processes and change the schema type of the messages to easily create a PIP 3A2. implementation. For detailed information about PIP3A4, see http://www.rosettanet.org.

Copying and Customizing PIP Implementations

To implement a new PIP based on an existing PIP implementation, complete the following tasks:

  1. Download the PIP distribution, including the specification and any DTDs, from the RosettaNet web site at http://www.rosettanet.org.
  2. Optionally, convert any DTDs to XSD files, as described in Converting RosettaNet DTD Schemas to XSD Schemas.
  3. Copy the example PIP implementation associated with the design pattern that you want to use.
  4. In WebLogic Workshop, import the schema for the new PIP into the project and then change the schema definition to the new PIP.
  5. Change the RosettaNet annotations for the new PIP:
  6. Rename the JPD and JCX files and change the names of other components to be more descriptive of the new PIP implementation, if you want.
  7. Change the implementation of any private business processes as needed.
  8. Make any other changes as needed.

Converting RosettaNet DTD Schemas to XSD Schemas

The RosettaNet W3C XSD schemas for selected PIPs are included in the RosettaNet Self-Test Kit (STK) which can be downloaded from the Developer Tools area on the RosettaNet Ready Web site, available at: http://www.rosettanet.org.

If the schema for the PIP you are using is not available on this web site, it is possible to implement RosettaNet solutions in WebLogic integration using RosettaNet message definitions specified as DTD files. However, it is recommended to use W3C XSD files instead, since many of the WebLogic Integration tools such as the XQuery mapping tools (used to define data transformations) only support XSD schemas.

If you want to use the graphical XQuery mapping tools, you need to convert the RosettaNet DTD files to W3C XSD files (using a tool like XML Spy Enterprise Edition) and then import the XSD files into your project. Make sure that you refer to the RosettaNet Message Guidelines for the PIP which DTD file you are converting and add the appropriate validation rules for Service Content Validation to your XSD file after the conversion.

When converting the files, consider the following issues:

In some cases, two different schemas will contain identical element definitions, which results in schema compilation problems. The name collisions can be avoided by using explicit targetNamespace. For example for the 3A4 Purchase Order Request W3C Schema in this tutorial we use: <xs:schema id="Pip3A4PurchaseOrderRequest" targetNamespace="Pip3A4PurchaseOrderRequest" xmlns="Pip3A4PurchaseOrderRequest">

After you build the schema projects, the PIP types will become available in the type system for use in parameter and variable types.

 

Skip navigation bar  Back to Top Previous Next