Chapter 4. Life cycles. IBM Version 3 Release 5.0

Chapter 4. Life cycles

In addition to having data, a record has something associated with it called its state. A record's state is used to associate the record with a phase in its life cycle.

Human beings have a life cycle that consists of such phases as infant, toddler, child, adolescent, and adult. Records also have phases in their life cycle. The phases that a particular record goes through in its lifetime depend on the business object from which it was created.

For many records, the life cycle is very simple. They have only one phase that is typically called "new" or "created".

Some records have a more complicated life cycle. For example, a record that describes a book might use these states to describe the phases of its life cycle:

Table 20. Sample states of a book's life cycle

State

Work in Progress

Prepublication

Published

Abandoned

Out of Print

Description

The record has this state while the book is being written.

The state of the record after the book has been written and while the book is being prepared for publication.

The book has been published.

Publication of the book has been abandoned.

The book was published but is no longer being published.

The state of a record changes in response to an action. We will illustrate this by continuing the example of a business object that describes a book.

When the book is created, its state is Work in Progress. When the book is complete, the state changes to Prepublication. While the book is in prepublication, its release may be delayed for marketing purposes. When the book is printed, the state changes to Published. If the book is abandoned when its state is Work in Progress or

Prepublication, its state becomes Abandoned. If the book is abandoned when its state is Published, its state becomes Out of Print.

Life cycle diagrams

It is difficult to understand the relationships between actions and states by reading a description like the preceding one. The relationships are usually much easier to understand when they appear in a diagram. The following figure shows a type of diagram called a life cycle diagram that illustrates the relationship between the states and events discussed in the preceding paragraph.

© Copyright IBM Corp. 2011, 2015

107

Figure 19. Sample life cycle diagram

The boxes in the figure represent the states of the record. The vertical lines under the boxes help show transitions between the states. The arrows between the lines represent transitions from one state to another; these transitions are called state transition actions. The words in the arrows are the labels users see for the station transition actions that cause the transitions.

When any state transition action is invoked, the system saves the record, regardless of the state transition action's name.

The odd shape that looks like the tail end of an arrow (such as the Marketing

Delay transition in the figure) indicates a transition from a state to the same state.

A state transition that does not go anywhere may seem pointless at first. The value of such a transition has to do with the fact that when a transition happens, it causes the record to be saved and may call a workflow and/or set the values of fields. Read more about workflows in "Overview of workflows".

Life cycle transitions

Every state in a life cycle has a set of state transition actions associated with it.

When a record is being edited by a form, the state transition actions are included in the form's action buttons. When you see actions such as Save or Save & Close in a form's action buttons, it is because the record's current state has state transition actions that can be triggered by those action buttons.

State transition actions also can trigger events. See "Launch conditions" for more details.

Synchronous workflows can be triggered by a state transition action and asynchronous workflows can be triggered by the event generated in response to the state transition action. See "Synchronous versus asynchronous workflows" for a discussion.

The same state transition action name may have a different meaning depending on a record's state. In the previous figure, we see the action named Abandon meaning different things, depending on the current state of the business object. If the state is

Work in Progress or PrePublication, the result of Abandon is that the state of the business object becomes Abandoned. If the current state of the business object is

Published, the result of Abandon is that the state of the business object becomes Out

of Print.

108

© Copyright IBM Corp. 2011, 2015

Example: Specifying state transition actions

The IBM TRIRIGA Application Platform uses state transition actions to model the life cycle of records created from a business object. Every business object has a defined set of state transition actions. Use the Data Modeler's State Transitions panel to specify a business object's state transition family. To access the State Transitions panel, click the BO State Transition menu item of the Data Modeler's Tools menu.

The State Transitions panel appears. For a new business object that does not yet have a state transition family, the State Transitions panel looks like the following figure.

Figure 20. Initial state transition window

We will explain how to use the State Transitions panel by working through an example. The example is the creation of a state transition family for a cstBook business object that will model the life cycle shown in "Life cycle diagrams".

As you can see in the previous figure, when you start from nothing, a new business object's state transition family is created with a single state named null.

The alternatives to starting from nothing are described in "State transition family reuse".

Null state

The null state has a special meaning. It has to do with the way records are created.

A record is created in a special state named null to indicate that its fields have not yet been set to their proper values. While the record is in the null state, it does not fully exist. While the record is in the null state, queries will not find it and it is not stored in the database.

When the record transitions to a different state (not null), the transition tells the platform that the record's fields have been set to their proper values. When a record's state changes to something other than null, the record can be found by queries and is stored in the database.

The way to delete a record is to change its state to null.

A transition from null state to null state does not cause the control number to be calculated.

Example: Defining states and transitions

The first thing to do is add a state named cstWorkInProgress. To add a state, click the Add State action in the menu at the top of the State Transitions panel. The State

Transitions panel now looks like the following figure.

Chapter 4. Life cycles

109

Figure 21. State Transitions panel with second state

The new state has no name. When new states are added, they automatically become the selected state. The form to edit the new state's properties appears in the left side of the panel. Set the name of the new state to cstWorkInProgress.

The next thing to do is to add a state transition action from the null state to the

cstWorkInProgress state. To add this transition, first click the null state. Then click the Add Transition action in the left panel. Nothing happens right after you click the action. Then click the cstWorkInProgress state. After clicking the cstWorkInProgress state, a blank state transition action symbol appears from the null state to the

cstWorkInProgress state. The State Transitions panel now looks like the following figure.

Figure 22. Work in Progress state and transition

Specify the properties of a state transition action with the following fields:

Action

This is the name of the state transition action that will trigger this transition. The state transition action's name is used to identify the action from workflows.

110

© Copyright IBM Corp. 2011, 2015

Actions of the same name will trigger the same event. If you want the same labeled action to trigger different asynchronous workflows, use a different Action name in this field.

Use the naming conventions in "Naming conventions".

Label

This is the text that will be used to identify the state transition action in a menu that a user sees and in life cycle diagrams.

State transition action labels containing two or more words will not wrap/break between the words if the browser window is resized smaller.

Instead, the wrap/break occurs between different labels.

Class or Ejb Name

This field is used to integrate a state transition action with a piece of the internal logic in the IBM TRIRIGA Application Platform. You should not put a value in this field unless specifically told to do so in the documentation or by your IBM TRIRIGA team.

Method Name

This field is used to integrate a state transition action with a piece of the internal logic in the IBM TRIRIGA Application Platform. You should not put a value in this field unless specifically told to do so in the documentation or by your IBM TRIRIGA team.

Default Display

The state transition family is part of the definition of a business object.

When you define a form to edit records created from the business object, one of the things to specify is whether the state transition action to trigger this state transition will appear in the form's action buttons by default. As described in "Sub actions", a sub action can override this with its Inclusion

Exclusion section.

The value of the Default Display property in the corresponding form overrides the value in the business object. See the discussion in

"State-based actions". If you change the Default Display value in the business object after a form already exists, the Default Display property in the form still controls whether or not the state transition action displays to the user.

Read Only

When a state transition action is triggered, the record is read only if the state it is transitioning to is read only. To make a state read only, all of the state transition actions coming out of that state must have this check box checked.

At runtime, a state will be read only if all of the state transition actions visible on the form have the Read Only property checked.

Close Window

If this check box is checked, the window containing the record on which the state transition action appears closes when a user clicks the action button.

Secondary Action

If this check box is checked, the action is automatically put into the More menu for that form. If the check box is not checked, the action appears as a button on the form's menu bar. See "State-based actions" for more details on the effect of this property.

Chapter 4. Life cycles

111

Fill in the fields shown in the previous figure, setting the Action field to cstCreate and the Label field to Create. Click the Apply action above Transition Properties. The name Create appears in the state transition action symbol. Click the

cstWorkInProgress state. The life cycle diagram now looks like the following figure.

Figure 23. Life cycle diagram with new state added

Continue adding the rest of the states and state transition actions. Click the Add

State action. This adds a new state. Set the name of the state to cstAbandoned. Then create a state transition action from the cstWorkInProgress state to the cstAbandoned state. Label this new state transition action Abandon and have it trigger an action named cstAbandon. At this point, the life cycle diagram looks like the following figure.

Figure 24. Life cycle diagram with abandoned state added

Build the rest of the state transition family. The completed life cycle diagram looks like the figure in "Life cycle diagrams".

When you are finished entering the states and state transition actions, click Save to save the diagram. Click Cancel to close the state transition diagram.

The following reviews the remaining actions in the upper right corner:

Print

This action allows you to print the contents of the state transition diagram.

Autosort

Prior to IBM TRIRIGA Application Platform 3.0, whenever you saved a state transition diagram, a built in algorithm rearranged the states for you.

Unfortunately this algorithm did not let you use your own judgment in how to best place the states for optimal readability. Starting in IBM

TRIRIGA Application Platform 3.0, the states retain their ordering when you click Save, and the previous algorithm is tied to the Autosort action.

Note that the Autosort action does not commit to the database, so if you click Autosort and do not like the outcome, you can simply Cancel and reopen the diagram to restore the original ordering.

Import

This is described in "State transition family reuse". Note that, unlike

Autosort, the system saves the results of this action to the database.

112

© Copyright IBM Corp. 2011, 2015

Life cycle diagram manipulation

A life cycle diagram can grow wider and/or taller than the Data Modeler window.

The State Transitions panel has no scroll bars. To see a different part of the diagram, drag it by putting the mouse over any part of the diagram.

State family editor tips

The state family editor in the Data Modeler is very sensitive to the order in which steps are taken when adding new states, state transition actions, sub actions, and the like.

The editor will not allow you to create a technically invalid state family. If an invalid state transition action is added for example, when you attempt to apply the changes, the editor will roll back the state family to its last saved state (or back to a blank state under some conditions). However, the editor usually does not inform you that a rule was violated; it just performs the roll back and your changes are lost.

The following tips, if followed, will ensure you do not lose changes that have been made when editing a state family: v There are two actions that save the state of the diagram. The Apply on the left side saves individual states and state transition actions. The Save on the upper right saves the whole state transition family.

v You only can Save a valid state family (see definition below). If you attempt to

Save an invalid state family, the editor reverts the state family to its last saved state.

v A valid state family consists of the following:

– At least two states, the first of which is named null. Remember that null needs to be lower case.

– At least one transition action between the two states.

– Properly named states and transitions (i.e., no spaces or special characters in the names).

– No "island" states, except in state family templates.

v When adding a sub action to a transition action, make sure the state family has been saved prior to adding the sub action if any state or transition actions have been newly created or modified.

State transition family reuse

In the preceding example, we built a state transition family from nothing. It is unusual to build a state transition family from nothing. Usually you will start out with a copy an existing state transition family. There are three ways to begin with an existing state transition family: v If you are defining a business object that is not its module's base business object, the business object automatically starts out with a copy of the base business object's state transition family.

v If you want to start out with a copy of a different business object's state transition family, click the State Transition panel's Import action and select the

Import from Business Object menu item.

Chapter 4. Life cycles

113

v The IBM TRIRIGA Application Platform is shipped with a collection of generally useful state transition families that are not part of a business object. If you want to use one of these, click the Import from State Family menu item in the

State Transitions panel's Import menu.

Importing a state transition family from another business object or from the State

Family Manager will merge the states and transitions of the imported state transition family with the states and transitions already in the business object's state transition family.

Sub actions

It is possible to add additional information to any of the transitions to specify how they should behave with records created from this business object. These are called sub actions and are a primary method of triggering a workflow.

Transitions that have not had any information added are a single shade of gray, as shown in the following figure.

Figure 25. Transitions with no business-object-specific information

To add business object-specific information to a state transition action, first click the state transition action to select it. Then click the Add Sub Action action in the left panel. The Add Sub Action action causes a SubAction Label Details window to pop up. The window has three fields:

Label

This is the label text that will display in menus the user sees for the action that will trigger the state transition action. If just a single sub action is defined for a state transition action, this label text will be used instead of the label specified for the state transition action in the state transition family. If multiple sub actions are defined for a transition, they will appear in a drop-down menu under the action when the user clicks the action.

If a workflow triggers a state transition action, and that action has multiple sub actions, only the first sub action will be run, where the first sub action is determined by listing the sub action labels alphabetically.

State action labels containing two or more words will not wrap/break between the words if the browser window is resized smaller. Instead, the wrap/break occurs between different action labels.

114

© Copyright IBM Corp. 2011, 2015

Workflow Select

Use this field to associate a synchronous workflow with this state transition action. Workflows are discussed in "Overview of workflows" and

"Workflow building". The specified workflow is launched when the state transition action is triggered.

Audit Action

If actions for the business object are being audited, this check box controls whether or not this particular state transition action will be audited.

The information entered into the window is saved when you click the Apply or Ok action. If you click the Apply action, you continue working in the window. After you click the Apply action (or click the Ok action and then edit the transition information) the window has more fields. After the initial business object-specific information has been saved, the SubAction Label window has two additional sections.

An action is visible on a record's form by default if the action's Default Display property is selected. The Inclusion Exclusion section provides the ability to toggle a given action's visibility. This section lists all state transition actions from the state that this transition comes from. Because the list shows the actions from the state from which the action originates, this function is most useful on a sub action that returns to the same state. If not returning to the same state, make sure the action for which you choose the Inclusion or Exclusion exists in the state to which the action is transitioning.

An action will be included on a form by default if the Default Display property is selected. At runtime you can override the Default Display value with the Include

Exclude section. This override action occurs at runtime for each individual record.

If the intent is to remove an action from the form when the user triggers the action, set the Exclusion radio button for the action(s) that you wish to exclude. If the intent is to include an action on the form when the user clicks this action, set the Inclusion radio button for each action you wish displayed.

If an action is included in a menu, the label text specified in the Label field is displayed in the menu to represent the action.

State transition actions that are not displayed in menus are called hidden actions.

Hidden actions have their Default Display property not selected and typically use the term "hidden" in their action name and label.

Some actions are hidden by default but may be displayed by the use of an

Inclusion set in a sub action. Some actions may be set to display (or not) by default but are displayed (or not) by inclusions or exclusions on the sub action.

For example, the state transition family for triContractLineItem in triCostItem, shown in the following figure, reflects a standard pattern used in the platform. In this Edit Hidden example, the ability to edit a record depends on the parent record. When it goes to an editable state, it triggers Edit Hidden, which changes the sub actions to those with Inclusion set (Save, Save & Close, Delete, and Copy).

Chapter 4. Life cycles

115

Figure 26. State Transitions panel for hidden sub action

Hidden actions cannot be initiated from a menu. However, a hidden action can be initiated from a workflow. Actions in general are discussed in more detail in

"Actions".

Use the State Transition Attribute section to specify that a record's field should be set to a value when the state transition action is triggered. A typical scenario where you might use this would be to set status values for triStatusCL and triPreviousStatusCL as a record moves from one state to another.

To specify that a field should be set to a particular value when the state transition action is triggered, click the Add action. Clicking the Add action causes a State

Transition Attribute window to pop up.

The State Transition Attribute window contains the names of all the fields in the business object. There is a check box to the left of each name. Select a check box to indicate that the state transition action should set a value in the field when it is triggered. After clicking Ok, the State Transition Attribute window goes away and the selected field(s) appear in the State Transition Attribute section of the

SubAction Label Details window.

To specify the value to put in the field when this state transition action is triggered, enter the value in the Constant Value column.

116

© Copyright IBM Corp. 2011, 2015

In order for this to work in classification fields, the Constant Value must be one of the statuses in the classification hierarchy.

If you want the state transition action to set the value of more fields, add more fields to the State Transition Attribute section.

When finished entering business object-specific information, click the Ok action on the SubAction Label Details window. The SubAction Label Details window disappears.

After business object-specific information for a state transition action has been saved, the appearance of the state transition action in the life cycle diagram changes. State transition actions that have business object-specific information associated with them are a different shade of gray.

Chapter 4. Life cycles

117

118

© Copyright IBM Corp. 2011, 2015