Using Workflows with RosettaNet

 

The following sections explain how to develop workflows for WebLogic Collaborate for the RosettaNet business protocol:

• Understanding RosettaNet

• Understanding PIP Workflow Instances

• Getting Started

• Working with Workflows

• RosettaNet Template Variables

• Receiving a RosettaNet Message

• Sending a RosettaNet Message

• Validating a Message

• Message Attachments

These procedures refer to the workflow diagrams in the RosettaNet samples. To access a workflow diagram, run the WebLogic Process Integrator Studio. For information about defining WebLogic Collaborate workflows, see Creating Workflows for BEA WebLogic Collaborate.

 

---

Understanding RosettaNet

The following RosettaNet documents are required reading if you want to implement your own PIP using the support for RosettaNet provided by WebLogic Collaborate, and recommended reading if you want to fully understand the sample RosettaNet PIP implementations:

• Creating Workflows for BEA WebLogic Collaborate

• The following documents are available in the "Standards" section at the RosettaNet Web site (http://www.rosettanet.org):

  • RosettaNet Implementation Framework v1.1 (RNIF 1.1) —The RNIF is an open, common networked-application framework designed to allow RosettaNet Supply Chain and Solution Partners to collaborate in executing RosettaNet PIPs.

  • RosettaNet Implementation Framework v2.0 (RNIF 2.0)

  • RNIF Technical Advisories—RNIF Technical Advisories are updates and additional information for RNIF 1.1 and RNIF 2.0.

  • RNIF Technical Recommendations—Technical Recommendations describe features or enhancements not yet available in a published version of the RNIF v1.1. Implementation of Technical Recommendations is optional.

  • RNIF Business Signals, Service Header & Preamble—The RNIF Business Signals, Service Header & Preamble document contains message guidelines and XML document type definitions (DTDs) for the RNIF Business Signals, Service Header and Preamble.

  • Understanding a PIP Blueprint—reference for PIP blueprint components and evaluation. Available under Supporting Documents in the Standards Section.

  • PIPs of interest—PIPs are specialized system-to-system, XML-based dialogs that define business processes between supply chain companies. Each PIP includes a technical specification based on the RosettaNet Implementation Framework (RNIF), a Message Guideline document with a PIP-specific version of the Business Dictionary, and XML document type definitions (DTDs) for PIP-specific messages.

 

---

Understanding PIP Workflow Instances

WebLogic Collaborate implements the standard RosettaNet PIP definitions through the use of WebLogic Process Integrator public workflows. These workflow interface with other trading partners, while private workflows are used for message generation and resolution.

Figure 3-1 Message Workflow

 

Figure 3-1 shows the process by which PIP workflows pass messages between trading partners. Generally speaking, RosettaNet-oriented workflows send messages as follows:

1. Buyer private process initiates a RosettaNet message. Data is retrieved and formatted into a RosettaNet message structure, and the appropriate PIP is determined.

2. Buyer public process creates RosettaNet message using appropriate PIP workflow. Message is sent to Seller.

3. Seller public process receives message, processes header information, and passes validated Buyer information, plus message content, to private process.

4. Seller private process resolves message content and generates a reply. The reply is processed into a RosettaNet message structure and passed to the public process.

5. Seller public process creates RosettaNet reply message and sends it to Buyer.

6. Buyer public process receives reply message, processes header information, and passes validated Seller information, plus message content, to private process.

7. Buyer private process resolves content of reply message.

 

---

Getting Started

Before you develop a PIP workflow, you should create a schema file from the PIP specification's DTD file. WebLogic Collaborate uses the schema file to validate RosettaNet messages. Schema files are not required if you do not intend to use validation. WebLogic Collaborate includes full implementations of PIPs 0A1 and 3A2, both of which can be used under both RosettaNet 1.1 and 2.0. You should use the schema files from these PIPs as a model for your own PIP schema file. These schema files are available in:

WLC_HOME\rosettanet\schemas

For more information on the use of custom schemas, refer to Administering BEA WebLogic Collaborate.

While most RosettaNet workflow development tasks are identical to those used for developing standard XOCP-oriented workflows, there are some differences. The standard procedures are documented in Creating Workflows for BEA WebLogic Collaborate; you should refer to them before creating RosettaNet workflows. The existing RosettaNet templates also provide a useful template base that you can use when creating new PIPs and workflows for them.

The remainder of this section discusses issues involving the creation of RosettaNet-specific workflows.

 

---

Working with Workflows

The RosettaNet PIP templates are public workflows, that allow you to connect to a trading partner. These workflows are designed to work with private workflows that:

• Provide raw source and recipient data

• Structure data into standard RosettaNet message body forms

• Process received data

• Initiate public workflows to send data

• provide an interface to private applications

Starting a Public Workflow

To start a public workflow from a private workflow within WebLogic Process Integrator, choose Actions —> Collaborate —> Start Public Workflow. For more information, see Creating Workflows for BEA WebLogic Collaborate.

Starting a Private Workflow

To start a private workflow from a public workflow within WebLogic Process Integrator, you must choose Actions —> Start Workflow. For more information, see Creating Workflows for BEA WebLogic Collaborate.

 

---

RosettaNet Template Variables

RosettaNet workflows implemented under WebLogic Collaborate require a number of workflow variables to operate. These variables are used in three ways:

• Input variables are used to receive data into the workflow. The content of a variable is set by the calling private workflow.

• Output variables are used to send data out of the workflow. The content, created by the PIP when it completes, is passed back to the calling workflow.

• System variables are used to track within the workflow assorted data that are required for a RosettaNet workflow to operate properly.

All system variables are required for a RosettaNet workflow. Requirements for input variables are based on the actual input requirements of the PIP, but all RosettaNet workflows require the input variables listed in the following table. Output variables are also based on the requirements of individual PIPs, but the set shown in the table is required for all RosettaNet workflows.

Table 3-1 Required RosettaNet Workflow Variables

Workflow Variable	Type	Description	Usage	Supports
attachmentDescriptorInput	xml	The XML description of the attachments for a message	Input (optional)	RNIF 2.0
fromContactName	string	The sender's contact name	Input (mandatory)	RNIF 1.1
fromDUNS	string	The DUNS of the sender	Input (mandatory)	RNIF 1.1, RNIF 2.0
fromEMail	string	The sender's email	Input (mandatory)	RNIF 1.1
fromLocation	string	The location of the sender	Input (mandatory)	RNIF 2.0
fromPhone	string	The sender's phone number	Input (mandatory)	RNIF 1.1
fromSupplyChain	string	The supply chain code of the sender: Information Technology or Electronic Components	Input (mandatory)	RNIF 1.1
globalUsageCode	string	The global usage code: either Test or Production	Input (mandatory)	RNIF 1.1, RNIF 2.0
PIPInput	xml	The PIP message content to be sent; must match the PIP specification	Input (mandatory)	RNIF 1.1, RNIF 2.0
toDUNS	string	The DUNS of the receiver	Input (mandatory)	RNIF 1.1, RNIF 2.0
toLocation	string	The location of the receiver	Input (mandatory)	RNIF 2.0
toSupplyChain	string	The supply chain code of the receiver: Information Technology or Electronic Components	Input (mandatory)	RNIF 1.1
validateServiceContent	boolean	Flag to indicate whether the service content should be validated against the schema: True—validation required False—no validation required	Input (mandatory)	RNIF 1.1, RNIF 2.0
validateServiceHeader	boolean	Flag to indicate whether the service header should be validated against the schema: True—validation required False—no validation required	Input (mandatory)	RNIF 1.1, RNIF 2.0
NOF0A1Party1	string	The party name to be used for OA1 failure notification	Input (mandatory)	RNIF 1.1, RNIF 2.0
NOF0A1Party2	string	The party name to be used for OA1 failure notification	Input (mandatory)	RNIF 1.1, RNIF 2.0
attachmentDescriptorOutput	xml	The XML description of the attachments for a message	Output	RNIF 2.0
reason	string	Contains the reason for PIP exit: SUCCESS—if it was successful. Otherwise the reason description. If PIP 0A1 Notification of Failure is invoked, the failure reason will be returned in this field.	Output	RNIF 1.1, RNIF 2.0
PIPOutput	xml	The PIP message content received	Output	RNIF 1.1, RNIF 2.0
actionCode	string	The action code of a message	System	RNIF 1.1, RNIF 2.0
actionCodeVersion	string	The version of the action code	System	RNIF 1.1, RNIF 2.0
businessActivityID	string	The business activity of the message	System	RNIF 1.1, RNIF 2.0
docId	string	The document ID	System	RNIF 1.1
exceptionError	boolean	Indicates whether an exception signal was received	System	RNIF 1.1, RNIF 2.0
fromClass	string	The sender's partner classification code	System	RNIF 1.1
fromRole	string	The role of the sender	System	RNIF 1.1, RNIF 2.0
fromService	string	The sender's service code	System	RNIF 1.1, RNIF 2.0
functionCode	string	The global function code: Request or Response	System	RNIF 1.1
initiatingPartnerDUNS	string	The DUNS of the partner that initiated the process	System	RNIF 1.1, RNIF 2.0
inReplyToActionCode	string	In response to action code	System	RNIF 1.1, RNIF 2.0
inReplyToActionCodeVersion	string	In response to action code version	System	RNIF 1.1, RNIF 2.0
inReplyToMessageId	string	In response to message ID	System	RNIF 1.1, RNIF 2.0
isSignal	boolean	Indicates whether a signal was received	System	RNIF 1.1, RNIF 2.0
messageCode	string	The status of a message send	System	RNIF 1.1, RNIF 2.0
messageTrackingId	string	The ID of a message	System	RNIF 1.1, RNIF 2.0
PIP	string	The PIP name	System	RNIF 1.1, RNIF 2.0
PIPVersion	string	The version of the PIP	System	RNIF 1.1, RNIF 2.0
retryCount	integer	The retry count for the PIP	System	RNIF 1.1, RNIF 2.0
SERVICE_CONTENT_SCHEMA	string	The schemas used to validate the service content	System	RNIF 1.1, RNIF 2.0
serviceContent	xml	Temporary holder of the service content	System	RNIF 1.1, RNIF 2.0
signalCode	string	The code of the signal	System	RNIF 1.1, RNIF 2.0
signalCodeVersion	string	The version of the signal	System	RNIF 1.1, RNIF 2.0
timeout	boolean	Indicates whether a timeout has occurred	System	RNIF 1.1, RNIF 2.0
timeStamp	string	The timestamp for a message	System	RNIF 1.1, RNIF 2.0
toClass	string	The receiver's partner classification code	System	RNIF 1.1
toRole	string	The role of the receiver	System	RNIF 1.1, RNIF 2.0
toService	string	The service of the receiver	System	RNIF 1.1, RNIF 2.0
transactionCode	string	The global transaction code	System	RNIF 1.1
validationError	boolean	Indicates whether a validation error occurred	System	RNIF 1.1, RNIF 2.0

An important point to note when using these workflow variables is that all input variables must be initialized when you start a public process workflow. The values used to initialize the input variables do not need to be exposed or transmitted.

In addition, while you must set the NOF0A1 parties, there are no conventions for distinguishing among users in NOF0A1. Because the actual destination for the PIP is determined by the workflow, you may assign either identity to yourself or your trading partner.

 

---

Receiving a RosettaNet Message

WebLogic Collaborate supports two different methods of receiving RosettaNet messages-----Start nodes and Event nodes. These two different node types are used depending on the circumstances under which the message is received.

Start Nodes

You can configure a workflow so that WebLogic Collaborate starts it automatically when WebLogic Collaborate receives the first message for a PIP instance. To configure this action, declare received PIPs as Start node events. Your receiving workflow starts and processes the incoming PIP. For an example, see the Participant Workflow discussion in Starting Collaborative Workflows in Creating Workflows for BEA WebLogic Collaborate.

The PIP3A2 Supplier workflow template serves as an example of how to configure a workflow template definition to be started by an incoming message. In this example, the starting event is set as a Collaboration Event. The workflow is automatically started and the output and system variables are set when a RosettaNet message has been received.

Event Nodes

Workflows can contain events that are triggered when a message is received for the PIP instance associated with the workflow. For an example, see the Initiator Workflow discussion in Starting Collaborative Workflows in Creating Workflows for BEA WebLogic Collaborate.

Implementing Timeouts

Workflows can use an optional timeout path to wait for an incoming RosettaNet message. If the workflow waits for a response to a sent message (for example, the 3A2 Buyer workflow), you must create a separate timeout path to wait for the response. This path, illustrated in the 3A2 Buyer workflow template, consists of a timer, set for the appropriate timeout period, and a stop node.

Out of Sequence Reception of Signals

RNIF 1.1 and RNIF 2.0 define different standards for reception of signals and replies. These differing standards affect how your PIP workflow resolves these messages.

RNIF 1.1 specifies that replies must always follow signals. Thus, you might see a signal/response pattern as follows:

1. Initiator —> (request) —> recipient

2. Initiator (receipt acknowledgment) recipient

3. Initiator (response) recipient

4. Initiator —> (handling acknowledgment) —> recipient

RNIF 2.0 allows out-of-sequence receipt of signals. For example, a workflow might receive a reply before the receipt acknowledgment. Thus, RNIF 2.0 allows a signal/response pattern such as the following:

1. Initiator —> (request) —> recipient

2. Initiator (response) recipient

3. Initiator (receipt acknowledgment) recipient

4. Initiator —> (receipt acknowledgment) —> recipient

This pattern must be processed accurately in your workflow design. The PIP 3A2 Customer workflow template provides a useful example of how to handle this. The RNIF 1.1 version of the PIP template processes the signal, followed by the response. The RNIF 2.0 version provides logic to process the signal and the response separately.

 

---

Sending a RosettaNet Message

A workflow can send a RosettaNet message by invoking an integration action called Send Business Message. To select this action:

1. Select Add Action from a node.

2. Choose Integration Actions—>Collaborate—>Send Business Message.

For example, when you choose the Send Business Message action, the following screen appears.

Figure 3-2 RosettaNet 2.0 Send Business Message Dialog

 

Depending on the message type that you select, various options are available for the message.

Message Type	Field Name	Description
Action	Message Type—Action	Indicates that a RosettaNet Action Business Message is to be sent.
Action	Input Content Value	A mandatory WebLogic Process Integrator workflow XML variable containing the XML data to represent the service content.
Action	Attachment Descriptor Value	An optional WebLogic Process Integrator workflow XML variable containing the XML data for describing the attachment(s) to be sent as part of the RosettaNet message.
Action	Output Status Variable	An optional WebLogic Process Integrator workflow Integer variable to contain the send status of the message.
Receipt Acknowledgment	Message Type—Receipt Acknowledgment	Indicates that a RosettaNet Receipt Acknowledgment signal is to be sent. No other data values are required.
Exception	Message Type—Exception	Indicates that a RosettaNet Receipt Exception Acknowledgment signal is to be sent.
Exception	Error Code	The Error Code (as defined by RosettaNet) to be sent.
Exception	Error Description	A brief description of the error.
Exception	Output Status Variable	An optional WebLogic Process Integrator variable to contain the send status of the message.

 

---

Validating a Message

The message validation process uses the Xerces 1.2.0 DOM parser, which supports an alpha implementation of the XML Schema specification. The Xerces 1.2.0 DOM parser is packaged with the WebLogic Collaborate software.

The following sections describe how WebLogic Collaborate validates RosettaNet messages and provide a bibliography for further reading about message validation:

• RosettaNet Message Validation

• Recommended Reading About Message Validation

RosettaNet Message Validation

BEA WebLogic Collaborate provides message validation services for both RNIF 1.1 and RNIF 2.0 messages. In either case, you use the appropriate DTDs to perform message validation. Depending on the values specified in the validateServiceContent and validateServiceHeader workflow variables, you may validate either, both, or neither:

• If validateServiceContent is true, all messages sent and received for a template are validated against the appropriate schema.

• If validateServiceHeader is true, the service header of all messages sent and received for a template are validated against the appropriate schema.

For an explanation of the exception handling process, see the RNIF at the following URL:

http://www.rosettanet.org 

The example XML schema files and document type definition (DTD) files are located on your WebLogic Collaborate installation at:

WLC_HOME/rosettanet/schemas

Recommended Reading About Message Validation

The following information is recommended reading to fully understand the example XML schemas; it is required reading if you are planning to implement your own XML schemas:

• Information about XML schema tools, usage, specifications, and development is available at the following URL:

  http://www.w3.org/XML/Schema 

  XML Schema Part 0: Primer provides good descriptions of the features and capabilities of XML schema.

• Information about the Xerces implementation of the XML Schema specification is available at the following URL:

  http://xml.apache.org/xerces-j/schema.html

Performance Tuning and Message Validation

Message validation is used primarily while setting up and configuring your system with a partner. Once you are satisfied that invalid message generation issues have been removed from the system, you may optionally turn off message validation to boost performance. As noted elsewhere, there is no requirement for message validation to be performed during message processing. Rather, it is assumed that valid messages are being sent.

 

---

Message Attachments

RNIF 2.0 includes support for optional message attachments in the RosettaNet action message. Attachments are not file type-specific, and may contain binary data. Examples of possible attachments include Word documents, GIF images, PDF files, and so on. The information for each attachment is contained in the service header of the message.

BEA WebLogic Collaborate provides support for attachments by allowing a user application (for example a private workflow) to provide a description of the attachment, contained in a BEA-specific structured XML file, as an input to the PIP workflow. The XML file is a description of the file attachment. It is not the actual attachment. It only specifies which files should be attached by WebLogic Collaborate.

The following is the DTD information describing the attachments:

Listing 3-1 WebLogic Collaborate Attachment DTD Information for RosettaNet

<!ELEMENT WLCRosettaNet ( Attachment+ )>
<!ELEMENT Attachment (
                       description?,
                       Type,
                       Id,
                       LocalLocation
                       )>
<!ELEMENT description ( FreeFormText ) >
<!ELEMENT FreeFormText ( #PCDATA ) >
<!ATTLIST FreeFormText xml:lang CDATA #IMPLIED >
<!ELEMENT Type ( #PCDATA ) >
<!ELEMENT Id ( #PCDATA ) >
<!ELEMENT LocalLocation ( #PCDATA ) >

The following table describes the elements used in the DTD.

Table 3-2 RosettaNet Attachment Elements

Element	Description
Description	An optional description of the attachment.
Type	The MIME type qualifier code of the attachment.
ID	The Universal Resource Identifier for the attachment.
LocalLocation	On sending: Contains the full path (on the local system) of the file for sending as an attachment. On receiving: Contains the full path (on the local system) of the file attachment that was received.

 

When the message is received, any attachments are stored locally in the WLC_HOME/runtime/rnattachments directory. The filename of the stored attachment is prefixed with a timestamp. For example, you might use the following XML description for an attachment.

Listing 3-2 Sample XML Attachment

<?xml version ="1.0"?>

<!DOCTYPE  WLCRosettaNet SYSTEM "WLCRosettaNet.dtd">

<WLCRosettaNet>

  <Attachment>

    <description>

      <FreeFormText>Product user guide in PDF</FreeFormText>

    </description>

    <Type>application/pdf</Type>

    <Id>"[e-mail]"</Id>

    <LocalLocation>c:\pdf\myfile.pdf</LocalLocation>

  </Attachment>

  <Attachment>

    ...

  </Attachment>

</WLCRosettaNet>

This sample would generate the following data in the service header and in the MIME header.

Listing 3-3 Sample Service Output

<Attachment>

  <description>

    <FreeFormText>Product user guide in PDF</FreeFormText>

  </description>

  <GlobalMimeTypeQualifierCode>PDF

  </GlobalMimeTypeQualifierCode>

  <UniversalResourceIdentifier>

   cid:[e-mail]

  </UniversalResourceIdentifier>

</Attachment>

Listing 3-4 Sample MIME Header

Content-Type: application/pdf; name="myfile.pdf"  

Content-ID: <[e-mail]>

Content-Description: Product user guide in PDF