Providing template property information

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:
  • Template description
  • Support for Long-lived business processes (LLBP)
  • Minimum transaction level
  • Package information
"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)"

Defining general property information (the General 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


Adding support for long-lived business processes

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:

Specifying the minimum transaction level

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.

Table 16.
Transaction levels
Transaction level Effect System behavior
None Collaboration is not transactional. If an error occurs during execution of the collaboration, the system just sends it to the log and then terminates execution.
Minimal Effort
Collaboration is transactional; it has compensations defined for its scenario's subtransactions. If an error occurs during execution of that scenario, InterChange Server rolls back the scenario, executing the compensation for each subtransactional step.
Best Effort
Does what Minimal Effort does; in addition to compensations, data isolation is used to ensure correctness. InterChange Server checks that data is virtually isolated for the duration of its use in the transactional collaboration by checking that the data's value has not changed since its previous use. Best-Effort isolation checking leaves a small window of time during the isolation check when the data is vulnerable to changes by other application transactions.
Stringent
Does everything that Best Effort does, but eliminates the data isolation window of vulnerability. Application locks the data when the isolation is checked. Supported by applications whose APIs support an atomic "test and set" operation.

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:

  1. Ensure the Template Definitions window is open and the General tab is displayed.
  2. Use the Minimum Transaction Level pull-down menu to select the minimum transaction level you want to use. If you are editing a collaboration template that is not transactional, keep the default value of None.
  3. Click Apply to save the changes.

Specifying a collaboration package

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:

  1. Ensure the Template Definitions window is open, and the General tab is displayed.
  2. In the Package field, enter the name of the 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.

  3. Click Apply to save the changes.

You can revise an existing collaboration template definition to add or change a package name at any time.

Declaring and editing template variables (the Declarations tab)

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:

Importing Java packages

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:

  1. Ensure the Template Definitions window is open and that the Declarations tab is displayed.
  2. Place the cursor in left heading cell of the import table. Right-click and select Add, as shown in Figure 23. A new row is added to the table.
    Note:
    You can also add a new row by clicking on the last row currently in the table.

    Figure 23. Adding an import statement


  3. Type the import statement in the Import column. For example:
    java.math.*
     
  4. Optionally, enter a brief description of the import statement in the Comment column.
  5. Click Apply to save the changes.
  6. Repeat step 2 through step 5 to add additional import statements. You can have an unlimited number of import statements in a collaboration template.

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:

  1. Place the CwMacroUtils.jar file in its own directory. For example, create a \dependencies directory below the product directory and place the .jar file in it.
  2. Edit the file used to start ICS (by default, ProductDir\bin\start_server.bat or ProductDir/bin/CWSharedEnv.sh) to include the new path for the CWMacroUtils.jar file. Add the following entry to the file:
    set DEPENDENCIES=ProductDir/dependencies/CwMacroUtils.jar
     

    where ProductDir is the location in which InterChange Server Express is installed.

  3. Add the new DEPENDENCIES variable to the JCLASSES entry as follows, depending on your operating system.

    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%
     
  4. In each collaboration that uses the classes, include the PackageName.ClassName specified in the CwMacroUtils.jar file.
  5. Restart ICS to make the methods available to the collaborations.

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:

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.

Declaring template variables

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:

Note:
LongText and Date are product-specific designations for special-purpose strings in business object attributes. Use the String data type in your code to represent a variable for a business object attribute whose type is LongText or Date.

To declare template variables, do the following:

  1. Ensure the Template Definitions window is open and the Declarations tab is displayed.
  2. Place the cursor in left heading cell of the variable table. Right-click and select Add. A new row is added to the table.
    Note:
    You can also add a new row by clicking on the last row currently in the table.
  3. Use the drop-down menu in the Type column to specify the type of variable you want to declare.
  4. Specify the variable's name in the Name column.
  5. Specify the variable's initial value in the Initial Value column.
  6. Specify any modifiers you want to apply to the variable (for example, public, private, protected) in the Modifier1, Modifier2, and Modifier3 columns. Note that you do not have to specify a modifier in all three columns.
    Note:
    Do not use the modifier Static when defining template variables.
  7. Click Update to add the new variable to the list of declarations at the top of the tab, and then click Apply to save the changes.

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.

Special considerations for template variables used with long-lived business processes

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.

System-generated variables

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".

Defining collaboration configuration properties (the Properties tab)

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
Type of property Example
A value that the collaboration uses to set the value of an attribute. A collaboration can request an application to generate invoices for customers. The collaboration can set the value of a Rate attribute in an Invoice business object. If the collaboration has a property called BILLING_RATE, an administrator can raise or lower the rate based on the current business practice.
Value of true or false, which determines whether the collaboration takes a particular execution path. InterChange Server Express collaborations that synchronize changes to entities across applications generally have a property called CONVERT_CREATE. When the collaboration receives an Update event, it checks the destination application for the entity to be updated. If the entity does not exist, the collaboration checks the value of the CONVERT_CREATE property. If the property is set to true, the collaboration converts the Update request to a Create request.

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:

  1. Ensure the Template Definitions window is open and that the Properties tab is displayed.

    Figure 24. Adding collaboration-specific properties


  2. Click the Add button to create a configuration property. The Name dialog box opens.
  3. Type the property's name in the Name field, and then click OK.
    Note:
    By convention, configuration property names are uppercase and use underscores to separate words. IBM recommends that configuration property names clearly communicate the purpose or function of the property, because administrators need to read and understand each property.
  4. Use the Property Type drop-down menu to select the property's type.
  5. If desired, provide a description of the new property in the Description field.
  6. If the property type is a string, specify a value in the Max Length field.
  7. Optionally, use the Max Multiple Values field to specify the maximum number of multiple values accepted for the property. Note that the number you specify in this field also limits the number of default values the property can have. For example, if you set Max Multiple Values to 2, you can have only two default values for the property, regardless of how many possible values are associated with the property. If you do not specify a value in this field, the default is 1.
    Note:
    The Max Multiple Values attribute of a collaboration-specific property is not often used. Most collaboration-specific properties accept only a single value.
  8. Click Add in the Value pane. A new row is added to the table, and the Property Value dialog box opens.
  9. Enter a value in the Value field, or specify a range of values in the Range From field, and then click OK. The dialog box closes and the Value column is populated with the information.
  10. If the value is a default value, click the checkbox in the IsDefaultValue column.
  11. Repeat step 8 through step 10 for each value you want to add to the property definition.
  12. Click Update.
  13. Repeat step 2 through step 12 to add as many configuration properties as you need.
  14. When you are finished adding configuration properties, click Apply to save the changes.

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.

Adding properties to support long-lived business processes

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.

Defining ports and triggering events (the Ports and Triggering Events tab)

The Ports and Triggering Events tab of the Template Definitions window displays information about the following:

Note:
If you add, modify, or delete a business object to or from the repository using Business Object Designer or System Manager, InterChange Server dynamically updates the list of business object definitions displayed in Process Designer Express. You do not have to restart InterChange Server or Process Designer Express to see the results of dynamic changes in the business-object field of the Ports and Triggering Events table of the Template Definitions window.
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.

Creating a port

To create a port, do the following:

  1. Ensure the Template Definitions window is open and the Ports and Triggering Events tab is displayed.

    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.

  2. Click Add Port to add a new port to the Ports table.
  3. Enter the port name in the Port column of the table.

    Follow these guidelines for defining a name for a port:

  4. Select the port's type from the drop-down list in the BO Type column. This is the type of business object definition that this port supports.
  5. Click Apply to save changes.

Note:
In some cases, not all ports in a collaboration object are needed; in this situation you must configure the collaboration logic to prevent the execution of service calls to the unused port or ports.

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.

Changing a port name

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:

  1. Select the port in the table on the Ports and Triggering Events tab.
  2. Click Delete Port.
  3. Follow the instructions in Creating a port to create a port with the new name.

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".

Copyright IBM Corp. 2003, 2004