Tutorials for Trading Partner Integration

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

Tutorial: Building RosettaNet Solutions

This topic describes how to implement RosettaNet solutions for trading partner integration in Oracle 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 Oracle WebLogic Integration, consider reading the following material:

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 Oracle WebLogic integration using RosettaNet message definitions specified as DTD files. However, it is recommended to use W3C XSD files instead, since many of the Oracle 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 (.java), schemas, and other files that illustrate how to implement RosettaNet PIPs using Oracle WebLogic Integration. 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 Oracle Workshop for WebLogic. For more information, see Building RosettaNet Participant Business Processes.
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 Package Explorer pane 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).
rosettanet
Contains the EAR folder
System
Schema project for standard Oracle WebLogic Integration system schemas.

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 Oracle 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 Oracle Workshop for WebLogic, if you have not already done so.
  2. From the File menu, choose Import

    3. The Import wizard appears.

  3. Expand General and select Existing Projects into Workspace (see Figure 2-1).
    4. Figure 2-1 Import
    PIP3B2Participant Business Process
  4. Click Next.
  5. Check Select root directory, and click Browse, then navigate to the tptutorialapps folder that you created in Step 3: Install the Tutorial Files.
  6. Select the rosettanet folder and click OK.
  7. Ensure all the files are selected and click Finish.
    8. Note: If you are prompted to select a Oracle WebLogic Integration domain and server, select the Oracle WebLogic Integration domain that you created in Step 1: Create a New Oracle WebLogic Integration Domain (such as c:\bea\user_projects\domains\tptutorial)

    The Package Explorer pane displays the contents of the RosettaNet tutorial application (see Figure 2-2), which is described in Folders in the RosettaNet Tutorial Application.

    Figure 2-2 RosettaNet Tutorial Application


    RosettaNet Tutorial Application

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.java) 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.java). The Failure Notifier process also writes a notification on the Oracle 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 Oracle WebLogic Server Console to show that it has received the message.

Components of the PIP0A1 Example

When you open the PIP0A1Processes folder in Oracle Workshop for WebLogic, the Package Explorer pane displays the contents of the folder (see Figure 2-3).

Figure 2-3 PIPOA1 Processes

PIPOA1 Processes

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.java
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.
PIPA01Control.java
Process control definition file that wraps PIPA01.java for use in other processes. Automatically generated by right-clicking the PIPA01.java file in the Package Explorer tab and choosing Generate > Process Control.
Rn.java
RosettaNet control definition file used to exchange messages with the failure administrator business process. For more information about the RosettaNet control, see RosettaNet Control.
PIP0A1ReportAdmin.java
Business process that demonstrates the back end business logic used to process error messages and notifications.
PIP0A1Transformation.java
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.

Walkthrough of the Failure Notifier Business Process

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

  1. In the Package Explorer pane in Oracle Workshop for WebLogic, expand pips > src, and open the PIP0A1Processes folder.
  2. Double click the PIP0A1.java file.
  3. If necessary, collapse the Retry block paths to see only the main (success) path.
    4. Figure 2-4 PIPOA1 Business Process


    PIPOA1 Business Process

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 getStaticProperties extracts the RosettaNet Context properties from the incoming message. For more information about RosettaNet Context, see Interface RosettaNet Control.
  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 Package Explorer pane, 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 Oracle 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 Oracle 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. Figure 2-5 OnTimeout Path


    OnTimeout Path

    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.java. To view the participant business process in Oracle Workshop for WebLogic, in the Package Explorer pane, double click on PIPA01ReportAdmin.java.

Figure 2-6 Report Administrator Business Process

Report Administrator Business Process

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 Oracle 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.java) constructs an Notify of Advance Shipment message and sends it to the Receiver (participant process- PIP3B2Participant.java).
  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.java) 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 Oracle Workshop for WebLogic, the Package Explorer pane displays the contents of the folder (see Figure 2-7).

Figure 2-7 PIP3B2 Processes

PIP3B2 Processes

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.java
Public initiator business process that sends the message, waits for the acknowledgement, and handles failures. Uses Rn.java, a RosettaNet control instance.
Rn.java
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.
The annotations on this control instance in PIP3B2.java include the PIP name and version, role names.
PIP3B2Control.java
Process control definition file that wraps PIP3B2.java for use in other processes. Automatically generated by right-clicking the PIP3B2.java file in the Package Explorer pane, and choosing Generate > Process Control.
PIP3B2Private.java
Private business process that invokes the PIP3B2.process business process via a process control.
This private business process can utilize the full power of Oracle 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.java 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.java
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.
PIP3B2ParticipantPrivate.java
Private business process that represents the backend processing of the shipment notice.
PIP3B2ParticipantPrivateControl.java
Process control that wraps the private process for use in PIP3B2Participant.java. Automatically generated by right-clicking the PIP3B2ParticipantPrivate.java file in the Package Explorer pane, and choosing Generate > Process Control.

Walkthrough of the Shipper Business Process

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

  1. On the Package Explorer pane in Oracle Workshop for WebLogic, expand pips > src and open the PIP3B2Processes folder.
  2. Double-click the PIP3B2.java 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. Figure 2-8 PIP3B2 Business Process


    PIP3B2 Business Process

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. Figure 2-9 OnTimeout Path


    OnTimeout Path

    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. Figure 2-10 OnError Message Path


    OnError Message Path

    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 Oracle Workshop for WebLogic, open the PIP3B2Participant.java file.

Figure 2-11 PIP3B2Participant Business Process

PIP3B2Participant Business Process

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:
    • Sends a receipt acknowledgement through the Send receipt acknowledgement Client Response node if the message is correct.
    • Sends an error message through the send Exception Client Response node if there is a problem with the message.
  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 Oracle 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.java is purposely configured to trigger an error and invoke the PIP0A1 example when you run the process.

Running the PIP3B2 Example

By default, Oracle 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 Oracle WebLogic Integration server. For more information about the Test and Production modes, see “Configuring the Mode and Message Tracking” in Trading Partner Management.

To run the PIP3B2 example:

  1. If Oracle WebLogic Server is not already running, from the Oracle Workshop for WebLogic menu, choose Window > Show View > Other > Server > Servers, and click OK. A Server view is displayed in which the Server and its state are shown.
  2. In the Package Explorer, expand Pips > PIP3B2Processes, select and right-click on PIP3B2Participant.java, click Run As, and click Run On Server.
  3. In the Define a New Server dialog box, select either a Choose an existing server option or Manually define a server (if there is no server defined), and click Next.
  4. In the Oracle WebLogic Server dialog box, to manually define a server, click Browse, and select the Oracle WebLogic Integration domain that you created in Step 1: Create a New Oracle WebLogic Integration Domain (such as c:\bea\user_projects\domains\tptutorial), and then click OK.
  5. Click Finish.

    6. The samples domain integration server is started, and the RequestQuote application is deployed on it. When Oracle WebLogic Server is running, the following indicator is visible in the Servers view:


    PIP3B2Participant Business Process

  6. After the application is deployed, the Test Browser is displayed.
  7. Click the Test Form tab.
  8. In the Test Form page, Click Browse, beside the xml pro (file value) field. and navigate to [file location]\rosettanet\pips\WebContent\PIP3B2Processes\sampledata\3B2AdvanceShipmentNotificationMessageBase.xml

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

  9. Click onMessage.
  10. In a few moments, the end-to-end choreography will execute. The client response will echo back the XML message.Bring up your Oracle WebLogic Server Console
  11. In a few moments, you should see the following messages on the console:
  1. Optionally, you can open the Oracle 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 Oracle Workshop for WebLogic, the Package Explorer pane displays the contents of the folder.

PIP3B2Participant Business Process

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.java
Public business process that exchanges messages with the seller, waits for the acknowledgement, and handles failures. Uses the RosettaNet control instance (Rn.java).
Rn.java
RosettaNet control definition file used to exchange messages with the Seller via RNIF. For more information about the RosettaNet control, see RosettaNet Control.
The annotations on this control instance in PIP3A4.java include the PIP name, version, and role names.
PIP3A4Control.java
Process control definition file that wraps PIP3A4.java for use in other processes. Automatically generated by right-clicking the PIP3A4.java file in the Package Explorer pane and choosing Generate > Process Control.
PIP3A4Private.java
Private business process that invokes the PIP3A4 process via a process control. This business process can utilize the full power of Oracle 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.java
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 Annotation Type RosettaNet.
PIP3A4ParticipantPrivate.java
Private business process that represents the backend processing of the purchase order and the creation of the PO Confirmation.
fc.java
File control definition file which is used to read the PO Confirmation sample file from the local file system.
PIP3A4ParticipantPrivateControl.java
Process control that wraps the private process for use in PIP3A4Participant.java Automatically generated by right-clicking the PIP3A4ParticipantPrivate.java file in the Package Explorer pane and choosing Generate > Process Control.
PIP3A4ParticipantTransformation.java 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.java) for PIP3B2. To view this business process:

  1. In Oracle Workshop for WebLogic, open the PIP3A4.java 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. PIP3B2Participant Business Process

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:
    • Sends a receipt acknowledgement through the Send PO Ack receipt acknowledgement Control Send node if the message is correct.
    • Sends an error message through the sendError Control Send node if there is a problem with the message.
  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: Oracle 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. PIP3B2Participant Business Process

    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. PIP3B2Participant Business Process

    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.java) on the Seller side is less complex than the initiator business process. To view the participant business process in Oracle Workshop for WebLogic, open the PIP3A4Participant.java file.

PIP3B2Participant Business Process

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:
    • Sends a receipt acknowledgement to the Buyer through the Send receipt acknowledgement Client Response node if the PO is correct.
    • Sends an error message through the send Exception Client Response node if there is a problem with the PO.
  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 Oracle 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.java file so that it can find the correct sample data file:
    1. In the Package Explorer pane, double-click the fc.java file.
    2. In the Source view, set the directory-name attribute to:

      3. [file location]\tptutorialapps\rosettanet\PIP3A4Processes

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

  2. If Oracle WebLogic Server is not already running, from the Oracle Workshop for WebLogic menu, choose Window > Show View > Other Server > Servers, and click OK. A Server view is displayed in which the Server and its state are shown.
  3. In the Package Explorer, expand PIP3A4Processes and select and right-click on PIP3A4Participant.java, click Run As, and click Run On Server.
  4. In the Define a New Server dialog box, select either a Choose an existing server option or Manually define a server (if there is no server defined), and click Next.
  5. In the Oracle WebLogic Server dialog box, to manually define a server, click Browse, and select the Oracle WebLogic Integration domain that you created in Step 1: Create a New Oracle WebLogic Integration Domain (such as c:\bea\user_projects\domains\tptutorial), and then click OK.
  6. Click Finish.

    7. The samples domain integration server is started, and the RequestQuote application is deployed on it. When Oracle WebLogic Server is running, the following indicator is visible in the Servers view:


    PIP3B2Participant Business Process

  7. After the application is deployed, the Test Browser is displayed.
  8. Click the Test Form tab.
  9. In the Test Form page, Click Browse, beside the xml pro (file value) field. and navigate to [file location]\rosettanet\pips\WebContent\PIP3A4Processes\sampledata\3A4PurchaseOrderRequestMessageBase_0010.xml

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

  10. Click onMessage.

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

  11. Bring up your Oracle WebLogic Server Console

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

  1. Optionally, you can open the Oracle 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 Oracle Workshop for WebLogic, 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:
    • For public initiator business processes, you change the pip and pip-version, to-role, and from-role attributes (and others if needed) in the Interface RosettaNetControl.
    • For public participant business processes, you change the pip-name, pip-role and pip-version attributes (and others if needed) in the Annotation Type RosettaNet.
  6. Rename the Process and control 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 Oracle WebLogic integration using RosettaNet message definitions specified as DTD files. However, it is recommended to use W3C XSD files instead, since many of the Oracle 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.


  Back to Top       Previous  Next