A collaboration's Template Definitions window provides the four tabs
listed in Table 14 for defining a collaboration template's
properties.
Table 14. Tabs of the Definitions window
Template Definitions tabs | Description | For more information |
---|---|---|
General | Enables you to define the following information for a collaboration
template:
| "Defining general property information (the General tab)" |
Declarations | Enables you to define template variables and view system-generated template variables. | "Declaring and editing template variables (the Declarations tab)" |
Properties | Enables you to specify the name, type, and value of user-defined collaboration template properties. | Defining collaboration configuration properties (the Properties tab) |
Ports and Triggering Events | Enables you to define the ports and triggering events for the collaboration template. | "Defining ports and triggering events (the Ports and Triggering Events tab)" |
The General tab of the
Template Definitions window (see Figure 21) displays general property information for the collaboration
template, including that listed in Table 15.
Table 15. General template definition information
General template property | Description | For more information |
---|---|---|
Description of the collaboration template
| This field of a collaboration template is optional. In it, you can enter text that is available to all users of the collaboration template. | None |
Support for long-lived business processes | Specifies whether the template supports long-lived business processes. | "Adding support for long-lived business processes" |
Transaction level (for transactional collaborations only) | Sets a minimum transaction level for all operations in the collaboration. | "Specifying the minimum transaction level" |
Collaboration package | The Java package in which the collaboration resides | "Specifying a collaboration package" |
Figure 21 shows the General tab within the Definitions window.
Figure 21. General collaboration properties
Long-lived business process support enables you to deploy a collaboration as a long-lived business process, and to specify a timeout value for service calls in this environment. In order to use this functionality, you must do the following:
When a collaboration is transactional, InterChange Server rolls back the collaboration upon failure of its transaction. The rollback executes template-defined compensations to reverse the collaboration's data modifications. For an explanation of transactional collaborations, see "Using transactional features".
The transaction level determines the mechanisms by which the
collaboration's scenarios are executed. Collaboration objects
execute at one of the transaction levels described in Table 16.
A collaboration template developer sets the minimum transaction level for collaboration objects created from the template. For example, if a collaboration deals with critical data and you want to ensure it is always rolled back when it fails, you can set its minimum transaction level to Minimal Effort. If you design a collaboration for transactional execution, but it can be used successfully without the transactional features, you can set the minimum transaction level to None.
An administrator can raise the transaction level for a collaboration object if its connectors support the higher transaction level. However, the transaction level for a collaboration object cannot be lower than the minimum specified in the template.
Tip |
---|
You can create compensation to permit transactional operation while setting the minimum transaction level of the collaboration templates to None. If greater rigor is needed and the connectors in use can support a higher transaction level, an administrator can raise the transaction level of the collaboration object at bind time. For more information on compensation, see Defining compensation. |
To assign a minimum transaction level to the collaboration template, do the following:
A package is a group of collaborations that have related functions. All collaborations that Process Designer Express accesses belong to the package UserCollaborations or to a subpackage of UserCollaborations. Therefore, the UserCollaborations package includes:
You can create subpackages under UserCollaborations to group custom collaboration templates. For example, if you create several collaboration templates that deal with office supply management, you can create a subpackage called OfficeSupplyMgmt. In it, you can put the PaperClipMgmt collaboration and the PencilInventory collaboration.
If you specify that a collaboration template is part of a package, Process Designer Express uses the package name to create a subdirectory in your Integration Component Library project's Template\Classes directory. (During deployment, the ProductDir\collaborations\classes\UserCollaborations directory is created to store the package information.)
The product installation sets the CLASSPATH environment variable to include all collaborations under UserCollaborations in the class path. Process Designer Express places a collaboration template's .class and .java files in the subdirectory.
To specify a package in which to store the collaboration template:
When you specify the name of an existing package, Process Designer Express adds the collaboration template to the package. When you specify the name of a package that does not yet exist, Process Designer Express creates it.
You can revise an existing collaboration template definition to add or change a package name at any time.
The Declarations tab of the Template Definitions window displays information about the template variables of the collaboration template. Template variables are collaboration variables whose scope is all scenarios in a collaboration; that is, a template variable is global to all scenarios in a collaboration. (They are comparable to class variables in the Java programming language.) For example, a collaboration that involves customer transactions can have a customerID template variable that identifies the customer across all scenarios. You can create or modify template variables at any time during development.
Figure 22 shows the Declarations tab within the Template Definitions window.
Figure 22. Declarations tab of the Template Definitions window
Within the Declarations tab, you can do any of the following tasks:
You can use the Declarations tab to import specific Java classes into the collaboration. A Java class imports a package of other classes to gain access to their functions. For example, a class imports the packages java.math, java.security, and java.text to use their arithmetic, security, and internationalization functions, respectively. Because a collaboration template is a class, it can use classes or groups of classes ( called packages) supplied by the Java Development Kit or from third-party products.
All Java classes, by default, implicitly import the classes in the package java.lang. In addition, Process Designer Express implicitly imports the classes in the package java.util for use in all collaboration templates.
The following import statement imports the java.math classes from the JDK. (The asterisk indicates to import all classes within the specified package.):
java.math.*;
Alternatively, the following statement imports just the package's BigDecimal class:
java.math.BigDecimal;
You can add import statements to your code at any time during the development of a collaboration.
To import Java classes:
java.math.*
If the imported classes are in a third-party package rather than in the JDK, you must edit the ProductDir\bin\cwtools.cfg file [codeGeneration] section to reflect the package path before you compile your template.
Before you deploy a collaboration that uses classes imported from a third-party package, you must update the JCLASSES variable in the system on which the collaboration is deployed. If the imported classes are in a third-party package rather than in the JDK, you must add them to the path of the imported classes in the JCLASSES variable. IBM recommends that you use some mechanism to differentiate those classes in JCLASSES that are standard from those that are custom. For example, you can create a new variable to hold only those custom classes and append this new variable to JCLASSES, as follows:
set DEPENDENCIES=ProductDir/dependencies/CwMacroUtils.jar
where ProductDir is the location in which InterChange Server Express is installed.
On a UNIX system, use the following syntax, where ExistingJarFiles represents the .jar files already included in JCLASSES:
set JCLASSES = $JCLASSES:ExistingJarFiles:$DEPENDENCIES
On a Windows system, use the following syntax, where ExistingJarFiles represents the .jar files already included in JCLASSES::
set JCLASSES = ExistingJarFiles;%DEPENDENCIES%
When importing a custom class, you can get an error message indicating that the InterChange Server software was unable to find the custom class. If this occurs, check the following:
COM.acme.graphics.*;
Or, you can import just the Rectangle custom class:
COM.acme.graphics.Rectangle;
For example, when importing a custom class, you can create a folder called ProductDir\lib\com\crossworlds\package, where ProductDir is the location in which InterChange Server Express is installed and package is the name of your package. Then, place your custom class file under the folder you just created. Finally, in the CLASSPATH variable in the start_server.bat file, include the path ProductDir\lib.
You can also use the Declarations tab to declare your own template variables that are used by the collaboration.
To use a variable, you must first declare it by specifying its type and name. A variable in a collaboration template can be one of the following data types:
To declare template variables, do the following:
You can declare variables whose values remain persistent across multiple invocations of a collaboration. Suppose you want to keep a counter of an action within the collaboration, and you want this counter to be incremented with each separate run of the collaboration. Use the variable table in the Declarations tab to create a integer variable named ctr that is public.
Later, within the collaboration code itself, increment the counter:
ctr = ctr+1;
The ctr variable increases with each collaboration execution.
If a collaboration is to be deployed as a long-lived business process, ensure that all variables you want to persist are defined as global template variables or global port variables.
In addition, ensure that those variables are of one of the following types:
Variables of other types do not persist in a long-lived business process.
Process Designer Express automatically declares the following collaboration variables:
Table 17 lists and describes these system-generated variables.
Table 17. System-generated variables
Variable | Description |
---|---|
triggeringBusObj
| The triggeringBusObj variable contains the flow trigger (triggering event or triggering access call) for a scenario. The flow trigger is a business object and a verb. A triggering event represents an application event and its data. The arrival of the flow trigger starts the execution of a scenario. This variable is a template variable; that is, its scope is the entire collaboration. |
currentException
| The currentException variable contains an exception object raised by the immediately preceding action, subactivity, or iterator. Process Designer Express implicitly declares currentException, whose scope is the action that immediately follows the raising of an exception. A scenario must check the value of currentException on the transition link or code fragment that immediately follows the activity that generated the exception. |
Port Variables
| Process Designer Express declares a template variable for the business object associated with each port in the collaboration. These generated declarations are visible under the Declarations tab of the Template Definitions window. The name of each port variable is the name of the port with BusObj appended. For example, if the port name is SourceInvoice, the variable name is SourceInvoiceBusObj. The declaration also instantiates a BusObj of the same type for which the port is defined. It initially sets the attributes of the business object to null. You can use these port variables to handle the triggering event. For more information on this, refer to "Copying the triggering event". |
Collaboration templates have two types of configuration properties:
An administrator works with both types of properties when configuring a collaboration.
As a collaboration developer, you decide whether a collaboration needs collaboration-specific configuration properties. If it does, you define their names and default values. These configuration properties enable a collaboration user to specify data that influences how the collaboration behaves.
Table 18 provides some examples of the types of properties you can
create.
Table 18. Examples of collaboration-specific configuration properties
The use of collaboration-specific configuration properties is optional, and you can use an unlimited number of them in a template. You can add these properties at any time during development. If you know at the outset the properties that the collaboration needs, you can create them before modeling scenarios. However, when you are in the midst of scenario modeling, you can define additional properties to support the collaboration's logic.
To create a collaboration-specific configuration property for the collaboration template:
To delete a collaboration-specific configuration property, select the name of the property from the list in the left pane of the tab, then click Delete.
If you want to support long-lived business processes (LLBP) with dynamic service call timeout values, you can use either a Java variable or a collaboration-specific property. If you want to use a collaboration-specific property, you must create it when defining the collaboration template. The use of collaboration-specific properties enables the timeout value to be set during runtime, rather than using a static value provided during the initial creation of the service call. Use an integer data type when creating properties for dynamic timeout values.
For example, if you plan to have a service call from the To port that sends a business object with a create request, you can define a collaboration property called CreateTimeout. When you define the service call, use the CreateTimeout property to specify the point at which that service call times out. For details on creating service calls, see Service calls.
Note that you can also used a fixed timeout value that is specified during the creation and definition of a service call; in this situation, no collaboration property is needed. See Defining the service call type.
The Ports and Triggering Events tab of the Template Definitions window displays information about the following:
In a collaboration template, a port is a variable that represents a business object that the collaboration object receives or produces at runtime.
A business object represents the triggering event or action. When a collaboration receives a business object from a connector, it usually responds with an action. These received business objects are referred to as triggers or triggering events.
For detailed information on using the Ports and Triggering Events tab to define a triggering event, see Assigning triggering events to scenarios.
When a collaboration completes an operation, it usually sends a business object to the connector that initiated the action. Thus, InterChange Server Express often refers to ports in terms of triggering or sending events.
Important |
---|
IBM recommends use of this dynamic update feature only in a development environment. Possible complications can result from updating a business object. Dynamic update can impact other functionality in the system, including how to process any events that use the old business object definition and how to resubmit unresolved flows that were originally submitted on the old business object definition. These and other scenarios can cause a mismatch between the business object definitions being processed and the business object definitions in memory. Therefore, in the production system, IBM recommends that you perform updates to business object definitions only when no events are being processed on the system. |
For more discussion of collaboration ports, refer to the chapter on collaborations in the Technical Introduction to IBM WebSphere InterChange Server.
To create a port, do the following:
At the top of the window is a table that contains port names, business object types, and verbs. The table is empty if you have not yet created a port for this collaboration template.
Follow these guidelines for defining a name for a port:
Because InterChange Server Express requires that all collaboration ports be bound, you must also bind the unused port or ports to a Port connector. A Port connector is a generic connector definition that is used to close an unused port. Note that the Port connector must be used in conjunction with the correct collaboration logic; any service call sent to a port bound to a Port connector blocks the collaboration thread.
To change the name of a port, you must delete and re-create the port using the new name; you cannot simply edit its name. Do the following to rename a port:
Table 19 summarizes what happens when you delete and re-create a
port.
Table 19. Result of changing a port name
What Process Designer Express does | What you must do |
---|---|
The system-generated template variable that uses the
port name changes.
| If you have code that uses the variable declared with the old port name, change the variable name in the code. Find all action nodes and service calls in which the variable declared with the old port name appears. The compiler catches any remaining incorrect names. |
The assignment of flow triggers ( triggering events or triggering access calls) is deleted. | Reassign the flow triggers. See "Compiling a collaboration template". |