RosettaNet Control

RosettaNet is a consortium of major companies working to create and implement industry-wide, open e-business process standards. These standards form a common e-business language, aligning processes between supply chain partners on a global basis. RosettaNet is a subsidiary of the Uniform Code Council, Inc. (UCC). To learn about RosettaNet, see


http://www.rosettanet.org

The RosettaNet control enables BEA Workshop for WebLogic Platform business processes to exchange business messages and data with trading partners via RosettaNet. You use RosettaNet controls only in initiator business processes to manage the exchange of RosettaNet business messages with participants. For an introduction to RosettaNet solutions, see Introducing Trading Partner Integration.

Topics Included in This Section

Overview: RosettaNet Control

Creating a RosettaNet Control

Using a RosettaNet Control

Example: RosettaNet Control

Related Topics

Overview: RosettaNet Control

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

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

At run-time, the RosettaNet control relies on trading partner and service information stored in the TPM repository. To learn about the TPM repository, see Introducing Trading Partner Integration. To learn about adding or updating information in the TPM repository, see Trading Partner Management in Using The WebLogic Integration Administration Console.

Creating a RosettaNet Control

To create a new RosettaNet control

In the Package Explorer pane, double-click the business process (Process.java file) to which you want to add the Rosettanet control. The business process is displayed in the Design view.
Click on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.

Note:

If the Data Palette view is not visible in BEA Workshop for WebLogic Platform, click
Window > Show View > Data Palette from the menu bar.

Select Rosettanet.
The Insert control:Rosettanet dialog box appears. In the Insert control:Rosettanet dialog box enter the following details:

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

The Create Control dialog-box appears.

In the Create Control dialog box enter the following details:

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

The Insert control: Rosettanet dialog-box appears (see Figure 11-1).

Figure 11-1 Insert Control: Rosettanet

Insert Control: Rosettanet

In the Insert control: Rosettanet dialog box, specify the following information (see Table 11-1).

Note:

Where applicable, the values entered here must match their corresponding settings in the TPM repository.

Table 11-1 Rosettanet Fields
Field	Description
`from`	Sender’s DUNS number. Must be defined in the TPM repository.
`to`	Recipient’s DUNS number. Must be defined in the TPM repository.
`rnif-version`	Version of the RNIF (RosettaNet Implementation Framework). One of the following values: 1.1 2.0
`pip`	RosettaNet PIP code, such as `3B2`. Must be a valid PIP code as defined in `http://www.rosettanet.org`.
`pip-version`	RosettaNet PIP version. Must be a valid version number associated with the PIP.
`from-role`	RosettaNet role name for the sender as defined in the PIP specification, such as Buyer, Initiator, Shipper, and so on. A PIP request might be rejected if an incorrect value is specified.
`to-role`	RosettaNet role name for the recipient as defined in the PIP specification, such as Seller, Participant, Receiver, and so on. A PIP request might be rejected if an incorrect value is specified.
`method-arg-type`	Required. Type of attachment. Includes the standard RNIF XML parts. One of the following values: `XmlObject`—Default. Represents data in untyped XML format. The XML data is not specified at design time. `RawData`—Represents any non-XML structured or unstructured data and for which no MFL file (and therefore no known schema) exists. Not recommended, as the payload includes standard RNIF XML parts. `MessageAttachment[]`—Array containing one or more parts of a business message. Message parts can be untyped XML data (`XmlObject` data type) or non-XML data (`RawData` data type). Used when sending different kinds of payloads (XML and non-XML) in the same message. The actual number of message parts might not be known until processed. To learn about working with `MessageAttachment` objects, see Using Message Attachments . To learn more about data types, see Working with Data Types.

Click Finish.

A RosettaNet control instance is displayed in the Controls tab.

Using a RosettaNet Control

All WebLogic Workshop controls follow a consistent model. Many aspects of using RosettaNet controls are identical or similar to using other WebLogic Workshop controls.

After you have added a RosettaNet control to an initiator business process, you can use methods on the control to exchange RosettaNet messages with participant trading partners. In the Design View, you expand the node for the RosettaNet control in the Data Palette to expose its methods, and then drag and drop the methods you want onto the business process. Common tasks include:

Sending Messages to Participants

The RosettaNet control provides methods for sending the initial request message to a participant and also for responding to the participant’s reply. To add the method to a business process, you drag it from the Data Palette onto the business process, which creates a Control Send node.

Sending a Request Message

You use the sendMessage method to send a RosettaNet request message to participants. After creating the Control Send node in the business process, you need to specify the payload parts and their Java data types. Valid data types include:

Table 11-2 Data Type
Type	Description
`XmlObject`	Data in untyped XML format.
`RawData`	Any non-XML structured or unstructured data for which no MFL file (and therefore no known schema) exists.
`MessageAttachment`	Data in both untyped XML and non-XML format. To learn about working with `MessageAttachment` objects, see Using Message Attachments.

Responding to Participant Replies

After sending a RosettaNet message, the initiator business process awaits a response from the participant. After receiving the participant’s response to the request, a business process can either acknowledge and accept the response, reject the response, or notify the participant that an error has occurred. The RosettaNet control provides the following methods for responding to participant replies:

Table 11-3 Method Type
Method Name	Description
`sendAck`	Sends a RosettaNet acknowledgement of receipt to the participant.
`sendError`	Sends a RosettaNet error to the participant.
`sendReject`	Sends a RosettaNet rejection to the participant.

Handling Messages from Participants

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

Table 11-4 Callback Methods
Method Name	Description
`onAck`	Handles the acknowledgement of the message receipt from the participant.
`onError`	Handles an error sent by the participant.
`onMessage`	Handles the message reply sent by the participant.

To receive a RosettaNet message from a participant, you use the appropriate method. To add the method to a business process, you drag it from the Data Palette onto the business process, which creates a Control Receive node.

For the onMessage method, after creating the Control Receive node, you need to specify the payload parts and their Java data types for the incoming message. To learn about valid data types, see Sending Messages to Participants.

The onError and onAck methods are system-level methods. Both use the XmlObject argument, which will contain a RosettaNet payload. These arguments are not seen in the default control but you can drag them onto the business process from the Data Palette. If your application contains a schema project that includes the Exception schema file (for RNIF2.0), and if the schema is already built, you can extract the values you want by creating a query (in the XQuery language) using the mapper functionality of WebLogic Workshop. To learn about creating queries with the mapper functionality, see Transforming Data Using XQuery.

Retrieving Message Elements

You can retrieve specific message elements from your RosettaNet messages by using the RosettaNetContext XMLBean. The following message elements can be retrieved and are returned as java.lang.string:

Table 11-5 Message Elements
Element Name	Description
`from`	Sender’s DUNS number.
`to`	Recipient’s DUNS number.
`pip`	RosettaNet PIP code specified for the message.
`pip-version`	PIP version specified for the message.
`from-role`	RosettaNet role name for the sender as defined in the PIP specification. Examples include: Buyer, Initiator, Shipper, and so on.
`to-role`	RosettaNet role name for the recipient as defined in the PIP specification. Examples include: Seller, Participant, Receiver, and so on.
`failure-report-administrator`	Trading partner id of the trading partner which is specified to be the failure administrator. (In WebLogic Integration, this is specified in the sender trading partner’s binding).
`global-usage-code`	Indicates whether the message was sent in test or production mode.
`debug-mode`	Returns `true` if the message was sent in debug mode.
`message-tracking-id`	Instance id of the action to which this message is in reply.
`protocol-name`	Name of the protocol used.
`protocol-version`	Version of the protocol used.
`conversation-id`	Id of the conversation.
`process-instance-id`	Instance id of the receiving process.
`process-uri`	URI of the receiving process.
business-action	The business action of the message, such as: Purchase Order Request, Purchase Order Confirmation, etc.
document-datetimestamp	The time and date the document was created.
proprietary-identifier	A unique number which tracks the document.

When you use the RosettaNetContext XMLBean, be sure to import the following classes:

Initiator business process receiving a message:

public void rn_onMessage(RosettaNetContextDocument doc, 
                         XmlObject msg)
   {
     System.out.println(">>>>> ContextInitiator.rn_onMessage()");
     RosettaNetContextDocument.RosettaNetContext context =
        doc.getRosettaNetContext();
     System.out.println("    from=" + context.getFrom());
     System.out.println("    to=" + context.getTo());
     System.out.println("    pip=" + context.getPip());
     System.out.println("    failure-report-admin=" +
        context.getFailureReportAdministrator());
   }

Initiator business process sending a message:

public void rnSendMessage() throws Exception
   {
     String rnInfo = "Service Content";
     XmlObject xObj = XmlObject.Factory.parse(rnInfo);
     RosettaNetContextDocument doc = rn.sendMessage(xObj);
     System.out.println(doc.toString());
   }

Participant business process receiving a message:

public void onMessage(RosettaNetContextDocument doc, XmlObject msg)
   {
     System.out.println(">>>>> ContextParticipant.onMessage()");
     RosettaNetContext context = doc.getRosettaNetContext();
     System.out.println("    from=" + context.getFrom());
     System.out.println("    to=" + context.getTo());
     System.out.println("    pip=" + context.getPip());
     System.out.println("    failure-report-admin=" +
        context.getFailureReportAdministrator());
   }

Participant business process interface for callbacks:

@CallbackInterface()

public interface Callback extends ServiceBrokerControl
{

/**

* com.bea.control.annotations.MessageBuffer enable="false"

*/

@com.bea.wli.common.MessageBuffer(enable = false)

public RosettaNetContextDocument sendReply(XmlObject msg);

/**

* com.bea.control.annotations.MessageBuffer enable="false"

*/

@com.bea.wli.common.MessageBuffer(enable = false)

public void sendReceiptAcknowledgement();

/**

* com.bea.control.annotations.MessageBuffer enable="false"

*/

@com.bea.wli.common.MessageBuffer(enable = false)

public void sendError(String msg);

@com.bea.wli.jpd.Callback()

public Callback callback;

Participant business process sending a reply:

public void reply()
   {
     XmlObject xObj = null;
     try {
       xObj = XmlObject.Factory.parse("Service Content");
     } catch (Exception e) {
       e.printStackTrace();
     }

     RosettaNetContextDocument doc= callback.sendReply(xObj);
     System.out.println(doc.toString());
   }

Dynamically Specifying Business IDs

The RosettaNet control adds the capability of dynamically binding business IDs for the initiator (from property) and the participant (to property) of the control. Dynamic binding of properties can be achieved the following ways:

Order of Precedence

The hierarchy of property settings is as follows, starting with the approach having the highest precedence:

properties dynamically bound using selectors (RosettaNetControl Annotation) and the DynamicProperties.xml file
properties set using the setProperties() method
properties set at the control instance level using the RosettaNet Annotation in the Process.java file.
properties set at Control file class level using RosettaNet Annotation in the Control file.

Using Selectors

Using a dynamic selector, RosettaNet controls allow you to decide at run time which one of multiple trading partners to send a business message to. When you specify a dynamic selector, you build and test an XQuery that retrieves the business ID you need.

To use a dynamic selector

Display the business process in Design view that contains the RosettaNet control for which you want to specify a dynamic selector.
In Design view, select the RosettaNet control node in the Data Palette.
Locate the from-selector or to-selector property in the Properties pane and select the associated xquery parameter. Click the button next to the xquery field indicated by three dots (...). The Dynamic Selector query builder is displayed.
In the Start Method Schema area, select an element from the schema to associate it with the start method of the control. The resulting query appears in the XQuery area.
Click OK.

Using setProperties

The setProperties method accepts a RosettaNetPropertiesDocument parameter. The RosettaNetPropertiesDocument type is an XML Beans class that is generated out of the corresponding schema element defined in DynamicProperties.xsd. The DynamicProperties.xsd file is located in the system folder of New Process Applications or in the system folder of the Schemas project.

If your application contains a schema project that includes the DynamicProperties.xsd file, and if the schema is already built, you can extract the values you want by creating a query (in the XQuery language) using the mapper functionality of WebLogic Workshop. To learn about creating queries with the mapper functionality, see Transforming Data Using XQuery.

To set business IDs dynamically using the setProperties method

Verify that your application contains a schema project that includes the DynamicProperties.xsd file, and that the schema is already built.
Create a Control Send node in a business process.
From the Data Palette, drag the setProperties method and drop it onto the Control Send node.
In the Send Data tab, select Transformation, specify variables that contain the to and from values, and then create a transformation to map them to the corresponding elements in RosettaNetPropertiesDocument.

Example: RosettaNet Control

http://download.oracle.com/docs/cd/E13214_01/wli/docs102/tptutorial/rosettanet.html

Using Integration Controls

RosettaNet Control

Topics Included in This Section

Overview: RosettaNet Control

Creating a RosettaNet Control

Using a RosettaNet Control

Example: RosettaNet Control

Related Topics

Overview: RosettaNet Control

Creating a RosettaNet Control

To create a new RosettaNet control

Using a RosettaNet Control

Sending Messages to Participants

Sending a Request Message

Responding to Participant Replies

Handling Messages from Participants

Retrieving Message Elements

Dynamically Specifying Business IDs

Order of Precedence

Using Selectors

To use a dynamic selector

Using setProperties

To set business IDs dynamically using the setProperties method

Example: RosettaNet Control