Defining Conversation Properties for Workflow Templates

 

The following sections describe how to define templates and template definitions for workflows that implement roles in WebLogic Collaborate conversation definitions:

• About Using the WebLogic Collaborate Plug-In to Define Templates

• About Templates and Template Definitions

• Creating a Workflow Template

• Linking Templates to Conversations

• Linking Templates to Collaboration Protocols

• Logging Messages

• About Working with WebLogic Process Integrator Variables for Workflows

 

---

About Using the WebLogic Collaborate Plug-In to Define Templates

To create workflows for conversation roles in BEA WebLogic Process Integrator, you use the WebLogic Collaborate plug-in to the WebLogic Process Integrator Studio. The first step in creating these workflows is defining workflow templates and template definitions for those workflows. In addition to the standard properties for templates and template definitions described in Defining and Maintaining Workflows in Using the BEA WebLogic Process Integrator Studio, you must define additional properties not described in that document that allow the workflows based on those template definitions to be used in the WebLogic Collaborate environment.

For example, suppose you link a workflow template definition to a particular role in a conversation definition and version that is bound to a collaboration agreement in the WebLogic Collaborate repository. You must also define some additional attributes, such as the protocol to which the conversation role implemented by the workflow is bound, and additional configuration data that might be required by the protocol.

For general information about defining workflow templates, see Defining and Maintaining Workflows in Using the BEA WebLogic Process Integrator Studio.

 

---

About Templates and Template Definitions

The topic Defining and Maintaining Workflows in Using the BEA WebLogic Process Integrator Studio contains a comprehensive discussion about templates and template definitions, specifically about the differences between the types of information you provide in the template and the template definition.

The only data required in a template definition that you cannot define in a template is the expiration date and whether the template definition is active. However, it is good practice to set all conversation properties in the template, such as the following:

• Conversation name and version

• Conversation role

• Conversation protocol

Then, when you create a template definition, you have the flexibility of overriding any conversation properties defined in the template, as appropriate. However, the primary advantage to assigning these properties in the template instead of the template definition is that you can specify properties for all template definitions contained in a given template.

Notes: Due to a limitation in WebLogic Process Integrator, template properties are not exported when you export a template definition. That is, the properties that a template definition inherits from a template are not exported. You should consider your export requirements when you determine the properties to define in a template versus a template definition.

Template definition properties are exportable, but are specific to only one template definition.

The sections that follow show how to define conversation properties in the template; however, it is possible to define all these properties in the template definition, instead.

 

---

Creating a Workflow Template

To create a workflow template in the WebLogic Process Integrator Studio using the WebLogic Collaborate plug-in, complete the following steps:

1. Do one of the following:

   • To create a new template, right-click the template that will contain the new template in the folder tree, and select Create Template from the pop-up menu.

   • To open an existing template, right-click the template in the folder tree and select Open from the pop-up menu.

2. Right-click the template name and select Properties from the pop-up menu to display the Template Properties dialog box, shown in the following figure.

   Figure 2-1 Template Properties Dialog Box

   
    

3. Complete the fields on the General page, as described in Defining and Maintaining Workflows in Using the BEA WebLogic Process Integrator Studio.

4. Click OK to save your changes.

 

---

Linking Templates to Conversations

Before you use a WebLogic Process Integrator workflow to exchange business messages in BEA WebLogic Process Integrator, you must first link the workflow template to a particular conversation definition (a conversation name, version, role, and protocol) in the BEA WebLogic Process Integrator repository.

To link a workflow template to a conversation definition:

1. Open the Template Properties dialog box, as described in Creating a Workflow Template.

2. In the Template Properties dialog box, select the Collaborate tab, shown in the following figure.

   Figure 2-2 Collaborate Page

   
    

3. Complete the following fields on the page titled Conversation.

   Table 2-1 Fields on the Conversation Page

   Field	Description
   Conversation Name	Name of the BEA WebLogic Process Integrator conversation definition in the WebLogic Collaborate repository to link with this workflow template definition.
   Conversation Version	Version number of the conversation definition in the WebLogic Collaborate repository to link with this workflow template definition.
   Role in Conversation	Role in the conversation definition to link with this workflow template definition. In order for a trading partner to receive messages in this conversation, it must be registered in this role in the conversation at run time.
   Business Protocol	Business protocol for the conversation definition linked with this workflow template definition. The following business protocols are available: XOCP-1.1 RosettaNet-2.0 RosettaNet-1.1 If you choose XOCP, an additional subtab becomes available so you can choose Quality of Service (QoS) settings for the business messages exchanged via the XOCP protocol. If you choose one of the RosettaNet protocols, see Implementing RosettaNet for BEA WebLogic Collaborate for information about how to define conversation properties for workflows used in RosettaNet-based conversations.
   Conversation Initiator	Select this option if the workflow starts a conversation.

   
    

4. Click OK to save your changes.

 

---

Linking Templates to Collaboration Protocols

In general, linking a template to a specific protocol affects what you see in many of the WebLogic Collaborate plug-in dialog boxes and tabs throughout the Studio. As this document explains how to use various components of the WebLogic Collaborate plug-in to perform various tasks, such as defining workflow start properties, sending and receiving business messages, and terminating conversations, you will see how the appearance of each plug-in component varies, depending on the protocol chosen for the workflow template.

For example, Table 2-1 explains that if you choose the XOCP protocol while configuring a workflow template, an additional tab is displayed in which you can specify Quality of Service (QoS) settings for business messages exchanged in workflows based on that template.

With respect to linking a template to a protocol, do the following:

• If you link a workflow template to one of the supported RosettaNet protocols, click OK in the Template Properties dialog box. The task of defining the template is complete.

• If you link the template to the XOCP protocol, you can optionally specify QoS settings in the QoS tab that is displayed, as explained in the following section.

Defining the Quality of Service for XOCP Message Delivery in the Workflow Template

The Quality of Service (QoS) is a set of attributes that are defined for reliable business message publishing. You can set QoS attributes only for business messages sent via the XOCP protocol.

In WebLogic Process Integrator, you can define the QoS in the following:

• In the workflow template, where the settings apply to all Send Business Message actions, unless the QoS is specifically overridden by the definition of the action.

• In the workflow template definition, where the settings also apply to all Send Business Message actions unless specifically overridden by the definitions of the action.

• In the Send Business Message action, where the settings apply to the specific action only, but override the settings specified in either the template or the template definition. For more information, see Defining the Quality of Service for Message Delivery for a Send Business Message Action.

To specify the Quality of Service in the workflow template:

1. Select the tab labeled QoS, shown in the following figure.

   Figure 2-3 Quality of Service Properties Page

   
    
    

2. Complete the following fields on the Quality of Service page.

   Table 2-2 Quality of Service Properties

   Field	Description
   Delivery Confirmation	Degree to which message delivery confirmation is required: Up to C-Hub (the default), Up to C-Hub Router, or All Destinations. Your selection determines which options are available in the Message Token Assignments dialog box, as described in Assigning Message Token Information to WebLogic Process Integrator Variables. You can choose one of the following values: Up to C-Hub—Delivery confirmation is required when a message reaches WebLogic Collaborate (default). Select this option to provide basic delivery confirmation with maximum run-time performance. Up to C-Hub Router—Delivery confirmation is required when a message reaches the router in WebLogic Collaborate. This option provides the list of trading partners selected by the WebLogic Collaborate router to receive the message. All Destinations—Delivery confirmation is required from all destinations. Select this option to provide the maximum delivery confirmation details. May affect run-time performance.
   Durability	If you select the box labeled Message Persistence, messages are saved in a persistent state. This option increases the likelihood of recovery from a system failure but requires additional processing that might affect run-time performance. If Message Persistence is not selected, messages are not saved in a persistent state. This option improves run-time performance but reduces the likelihood of recovery from a system failure.
   Number of Retries	Maximum number of retries for sending a message (default is 0). The WebLogic Process Integrator process engine repeatedly attempts to send a message until it either successfully sends the message or exceeds the maximum number of retries. A WebLogic Process Integrator exception is thrown if the maximum number of retries is exceeded.
   Correlation ID	Message identification string that can be used to correlate the message with other business messages in the application (default is none). For example, a trading partner might want to specify a correlation ID in a request so that replies to that request can be matched to the original request. The WebLogic Collaborate messaging system includes this property with the message.
   Send Timeout	Timeout value in days, hours, minutes, and seconds for sending a message (default is 0, which means no timeout). The WebLogic Process Integrator process engine waits until either a delivery confirmation is received or the timeout period is exceeded.
   Notes	Optional descriptive text.

   
    

3. Click OK to save your settings.

 

---

Logging Messages

The WebLogic Collaborate plug-in to the Studio provides a means to send messages— for example, debug messages, run-time information, or application messages—to the WebLogic Collaborate log at any point during the execution of a collaborative workflow. This functionality is provided via the Log action, which you can add to any node in the workflow. This action can provide a useful debugging tool during the workflow design process.

To add a Log action to a node in the workflow, complete the following steps:

1. Open the workflow in which you want to add the Log action, making sure that the workflow is active and not expired.

2. In any dialog box where you can specify an action, click Add to display the Add Action dialog box.

   Figure 2-4 Add Action Dialog Box

   
    

3. Click the Integration Actions folder to expand it.

   Figure 2-5 Add Action Dialog Box with Workflow Actions

   
    

4. Click the WebLogic Collaborate folder to expand it.

5. Select Log. The Log action dialog box is displayed.

   Figure 2-6 Log Action Dialog Box

   
    

6. Enter the message you want to send to the WebLogic Collaborate log, or use the Expression Builder to build the message to be sent to the log. For information about using the Expression Builder, see Using Expressions and Conditions in Using the BEA WebLogic Process Integrator Studio.

 

---

About Working with WebLogic Process Integrator Variables for Workflows

A WebLogic Process Integrator variable is typically used to store application-specific information required by the workflow at run time. Variables are created and assigned values largely to control the logical path through a workflow instance. The same workflow template definition is instantiated multiple times and can be traversed in different ways if the flow contains decision nodes.

The guidelines for working with variables that apply to noncollaborative workflows also apply to collaborative workflows. (They are fully explained in Using the BEA WebLogic Process Integrator Studio.) When creating workflows, keep the following guidelines in mind:

• You must define workflows that require variables during run time in the Studio as WebLogic Process Integrator variables. During workflow execution, you can access a WebLogic Process Integrator variable in the following ways:

  • Within the workflow instance, such as in a decision node

  • Within an Enterprise Java Bean (EJB) or Java class that starts a workflow or manipulates business messages sent or received by the workflow

• As with structured programming languages, it is always good practice to define your variables before you create your workflows. With WebLogic Process Integrator, defining variables before creating workflows provides two distinct benefits:

  • It encourages you to plan your workflows more thoroughly before you create them, leading to a more efficient and deliberate design cycle.

  • When you identify variables in various dialog boxes and tabs in the Studio, the variables appear in selection boxes. This is not only convenient for choosing variables; it also reduces the risk of error in associating a variable type and name with a given node in a workflow.

• Java applications that start workflows programmatically can access WebLogic Process Integrator variables specific to the workflow at any time by referencing the workflow instance object that you obtain when you start the workflow.

Note: Applications that start workflows programmatically must use the WebLogic Process Integrator Integration API. For more information, see Developing Applications that Start Conversation Initiator Workflows.

Associations Between WebLogic Process Integrator Variables and Java Data Types

If you want to access a WebLogic Process Integrator variable within a business operation, you need to know how WebLogic Process Integrator variable types correspond to Java data types. The following table shows how they are related.

Table 2-3 WebLogic Process Integrator Variables and Java Data Types

WebLogic Process Integrator Variable Type	Java Data Type
String	java.lang.String
Integer	java.lang.Long
Double	java.lang.Double
Date	java.util.Date
Boolean	java.lang.Boolean
Complex Object	java.lang.Object (must implement Serializable)
XML	org.w3c.dom.Node

 

Rules for Defining WebLogic Process Integrator Variables

The rules for defining WebLogic Process Integrator variables for collaborative workflows are the same as those for WebLogic Process Integrator workflows:

• You can access workflow variables programmatically in the following situations:

  • After the instance is created but before it is started, as described in Step 5: Get Input Variables from the Workflow Instance.

  • During the execution of a Manipulate Business Message action, as described in Defining the Manipulate Business Message Action.

  • After the instance completes, you can access output variables.

• Before an application can set an input variable for a workflow instance, you must first define the variable for that workflow in the Studio. (Note that this application must use the WebLogic Process Integrator Integration API (package com.bea.b2b.wlpi) in the application to set those variables that are passed to the workflow.)

• For a workflow that has been started by an application, you can use the workflow instance in that application to set or retrieve variables.

• If you define an output variable (a variable that is passed out of the workflow), you can access its value after the workflow has finished.

• Actions for accessing business messages use Java object variables for manipulating, sending, or receiving business messages. However, the objects stored in the variables through these actions belong to an internal class that encapsulates the business message. As a consequence, these variables should be accessed only through message manipulators. Directly accessing these variables will result in undefined behavior. For more information, see Defining WebLogic Process Integrator Variables for Business Messages.

• When setting variables in the Compose Business Message and Extract Business Message Parts actions, make sure the variables have the following appropriate types:

  • The part of the business message that holds an XML document may be stored in or retrieved by a WebLogic Process Integrator XML variable type.

  • Any business message part may be stored in or retrieved from a file. A WebLogic Process Integrator variable of type String contains the filename.

    Note that the variables that specify binary attachments to a business message must contain a source file or destination file, as appropriate.

Defining Variables

For complete details about defining WebLogic Process Integrator variables in the Studio, see Working with Workflow Components in Using the BEA WebLogic Process Integrator Studio.