Defining scenarios

A scenario is the collaboration template code that handles a particular incoming business object or set of business object. This business object can represent an event (from a connector) or an access call (from an access client). You can think of a scenario as an event-handling method of your collaboration template class. Activity diagrams contain the code specifying how to handle the event.

About scenarios

You use scenarios to partition the business problem that a collaboration solves. You can group all the logic of the collaboration into a single scenario or you can create several scenarios, each dealing with one aspect of the problem. Grouping all collaboration logic into a single scenario is analogous to a program that contains all of its logic in a main() function, while using multiple scenarios is analogous to a program that is structured into separate functions.

You typically name scenarios according to the function they perform. When a collaboration contains multiple scenarios, each of which handles one type of business object, consider naming each scenario according to the business object that it handles. For example, if the collaboration handles one type of business object with different possible verbs, you can develop Create, Update, and Delete scenarios. If the collaboration handles different types of business objects, you can develop a scenario for each business object definition.

A scenario handles only one triggering flow (triggering event or triggering access call) with each execution. However, the same scenario can potentially handle a set of possible triggering flows. For example, the same scenario can handle a Create, Update, or Delete flow.

In general, when identical logic handles different types of business object, it is more efficient to use a single scenario for those business objects. This eliminates the need to test and debug multiple pieces of code.

Note:
A scenario cannot pass control to another scenario in the same collaboration. If your preliminary plans for partitioning the collaboration logic indicate that one scenario must call another, put all of the collaboration logic into the same scenario. Within the scenario, design is very flexible. Alternatively, you can create a collaboration group, dividing the logic among collaborations in the group.

Creating a scenario

Perform the following steps to create a new scenario:

  1. From within Process Designer Express, click Template --> New Scenario. The Create Scenario dialog box is displayed.
  2. Type the scenario's name in the Scenario Name field.

    The name is a string that can contain alphanumeric characters and underscores. If the scenario handles events with a particular verb, it can be useful to include the verb in the scenario name.

  3. Optionally, enter a description in the Description field.
  4. Click OK. In the template tree view, the name of the new scenario displays in the scenario tree. In addition, the diagram editor opens in the main window.
  5. You must assign at least one flow trigger to a scenario. Failure to assign the flow trigger causes a runtime error. For instructions on assigning triggering events to your new scenario definition, see Assigning triggering events to scenarios.

Assigning triggering events to scenarios

You assign a triggering event to a scenario in the Ports and Triggering Events table of the Ports and Triggering Events tab. For each scenario that you create, you must assign its triggering event. The triggering event is represented by a business object and a verb.

Note:
The general term for the incoming business object and verb that a scenario receives is a " flow trigger". If the flow trigger originates from a connector, it is called a triggering event. If the flow trigger originates from an access client, it is a triggering access method. The Ports and Triggering Events tab enables you to assign a flow trigger to a scenario, regardless of whether it is a triggering event or a triggering access method. This section uses the terms "triggering event" and "event" because flow triggers received from connectors are by far the most common.

A collaboration's port definitions specify the types of business objects that the collaboration can send and receive. After defining the collaboration's ports and scenarios, you must specify:

Figure 25 illustrates these associations in a collaboration template whose port, From, supports business object type Widget. The Create scenario handles triggering event Widget.Create and the Delete scenario handles triggering event Widget.Delete.

Figure 25. Relationship of port, triggering event, and scenario


Specify the scenario for each flow trigger as follows:

  1. Ensure the Template Definitions window is open and that the Ports and Triggering Events tab is displayed.
  2. In the Ports and Triggering Events table, locate the row that represents the port from which the flow trigger arrives, and the business object that represents the flow trigger.
  3. In that row, click the drop-down list in the Create column. The list contains all of the scenarios defined for the template; select the scenario you want.
  4. Repeat step 2 and step 3 for each port, business object, and verb whose flow trigger you want to assign.
  5. After you have finished assigning triggering events, click Apply to save the assignments.

Defining scenario variables

After the scenario has been created, you can add scenario-specific variables in the Scenario Definitions dialog box (see Figure 26).

Figure 26. Scenario Definitions dialog box


Scenario variables are collaboration variables whose scope is all actions and links in a single scenario. (They are comparable to class variables in the Java programming language.) You can set scenario variables at any time during the collaboration template development process.

To add variables to the scenario definition, do the following:

  1. Open the Scenario Definitions dialog box by doing one of the following:
  2. Right-click the left heading cell of the variable table, and then click Add from the context menu. A new row appears in 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 list 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, transient, 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 include the keywords public and static in the declaration of a scenario variable.
  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.

Special considerations for scenario variables in a long-lived business processes

Scenario variables do not persist automatically as part of the event flow context of a long-lived business process. If you want to use scenario variables within a long-lived business process collaboration, you must manually set the variable to null before the service call, and then re-initialize the variable after the service call completes. These tasks are done in the action node that makes the service call.

In the following example, a scenario variable called poolName is set to null in the action node before the service call takes place:

String poolName;
 poolName = null;
 

After the service call completes, poolName is re-initialized in the action node, as follows:

poolName = getConfigProperty("Pool_A");
 

Deleting a scenario

You can use Process Designer Express to delete scenarios. Deletion of scenarios cannot be undone.

To delete a scenario definition, do the following:

  1. From the template tree view, select the scenario you want to delete.
  2. Click Template --> Delete Scenario. A dialog box appears to confirm the deletion.
  3. Click Yes to delete the scenario.

Copyright IBM Corp. 2003, 2004