# 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. To learn about WebLogic Workshop controls, see Using Built-In Java 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
- Handling Messages from Participants
- Retrieving Message Elements
- Dynamically Specifying Business IDs

To learn more about these methods, see RosettaNetControl Interface.

The RosettaNet control is a JCX file. To learn about using JCX files, see JCX Files: Extending Controls.

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

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.

Note: Attachments can also be typed XML or typed MFL data as long as you specify the corresponding XML Bean or MFL class name in the parameter.

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

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

Participants can respond to initiator requests in the following ways:

- acknowledge that the request was received
- reply to the request
- notify that an error has occurred

To handle responses from participants, initiator business processes use the following 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:

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:

    com.bea.wli.control.rosettanetContext.RosettaNetContextDocument;
    com.bea.wli.control.rosettanetContext.RosettaNetContextDocument.RosettaNetContext;

The following are code examples of how to use RosettaNetContext:

Note: If you use the code samples provided in this section, remember to also modify the the return type of your corresponding methods in your RosettaNet control definition file (JCX file). In other words, public void sendMessage() needs to be changed to public RosettaNetContextDocument sendMessage().

- 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());
       }

Where Service Content is the service content of your RosettaNet message.

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

    public interface Callback
       {
         /**
         * @common:message-buffer enable="false"
         */
         public RosettaNetContextDocument sendReply(XmlObject msg);
         /**
         * @common:message-buffer enable="false"
         */
         public void sendReceiptAcknowledgement();
         /**
         * @common:message-buffer enable="false"
         */
         public void sendError(String msg);
       }

    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());
       }

Where Service Content is the service content of your RosettaNet message.

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

- Using selectors
- Using the setProperties() method

#### Order of Precedence

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

1. properties dynamically bound using selectors (@jc:rosettanet Annotation) and the DynamicProperties.xml file
2. properties set using the setProperties() method
3. properties set at the JCX instance level using the @jc:rosettanet Annotation annotation in the JPD
4. properties set at JCX class level using @jc:rosettanet Annotation annotation in the JCX

Dynamic selectors have a higher precedence than static selectors.

#### 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

1. Display the business process in Design View that contains the RosettaNet control for which you want to specify a dynamic selector.
2. In Design View, select the RosettaNet control node in the Data Palette.
3. Locate the from-selector or to-selector property in the Property Editor 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.
4. 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.
5. 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

1. Verify that your application contains a schema project that includes the DynamicProperties.xsd file, and that the schema is already built. To learn about importing schemas, see How do I: Import Schemas into a Project Schemas Folder.
2. Create a Control Send node in a business process.
3. From the Data Palette, drag the setProperties method and drop it onto the Control Send node.
4. In the Send Data tab, select Transformation, specify variables that contain the to and from values, and then create a transformation to map them to the corresponding elements in RosettaNetPropertiesDocument.

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

Related Topics

RosettaNet Control

Overview: RosettaNet Control

Creating a RosettaNet Control

Example: RosettaNet Control