IBM TRIRIGA Application Platform

Version 3.2

Application Building for the

IBM TRIRIGA Application Platform
Note
Before using this information and the product it supports, read the information in “Notices” on page 745.

This edition applies to version 3, release 2, modification 0 of IBM® TRIRIGA® Application Platform and to all subsequent releases
and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2011. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 Table of Contents

Support ......................................................................................... xii

Chapter 1: Platform Overview................................................... 1

Data Model ...................................................................................... 1
User Interface .................................................................................. 2
Form Builder ............................................................................. 3
Navigation Item .......................................................................... 4
Portals ..................................................................................... 5
Queries / Reports .............................................................................. 5
Workflows ....................................................................................... 6
Other Features ................................................................................. 7
Common Skills for Platform Tools ........................................................... 8
Custom Menus ............................................................................ 8
Create-Publish-Revise Cycle ........................................................... 9
Managing Panels ........................................................................11
Naming Conventions ...................................................................13

Chapter 2: Data Modeling ....................................................... 19

Modules ......................................................................................... 21
Organizing into Modules ...............................................................21
Creating Modules .......................................................................22
Editing Module Properties .............................................................24
Adding a Business Object to a New Module ........................................25
Creating a Business Object .................................................................. 25
A Business Object’s Basic Information ..............................................26
Existing Business Object’s Properties ...................................................... 32
Modify a Published Business Object ........................................................ 34

© Copyright IBM Corporation 2011. | i

 Specifying Fields ..............................................................................36
Adding a Field to the Business Object .............................................. 37
Editing Properties of an Existing Field .............................................. 40
Deleting a Field ........................................................................ 44
Determining a Unique Name for Records ........................................... 48
Control Number Generation .......................................................... 53
Other Mapping Properties ............................................................ 56
Automatically Added Fields .......................................................... 56
Publishing Business Objects .................................................................57
Deleting Business Objects ....................................................................59
Associations ....................................................................................60
Defining Associations .........................................................................61
Associate Business Object Panel ..................................................... 64
Add Associations from the Data Modeler ........................................... 67
Add Associations from the Association Manager .................................. 71
Associations with a Base Business Object .......................................... 72
Organization of a Record ....................................................................74
Pros and Cons of Using Smart Sections ............................................. 86
Note Sections ........................................................................... 86
Discussion Thread Sections ........................................................... 87
Links ..................................................................................... 88

Chapter 3: Data Types ........................................................... 93

Binary ...........................................................................................95
Boolean .........................................................................................96
Business Object ................................................................................98
Classification ................................................................................. 100
Defining Classification Fields ........................................................101
Creating and Editing Classifications ................................................103
Classification with Additional Data ................................................109
Classification Rollup ........................................................................ 110
Color .......................................................................................... 111
Control Number ............................................................................. 113
Date ........................................................................................... 115
Date and Time ............................................................................... 117

ii | : © Copyright IBM Corporation 2011.

 Duration ...................................................................................... 119
Financial Rollup ............................................................................. 121
Image ......................................................................................... 122
Label Only .................................................................................... 123
List ............................................................................................ 124
Dependent Lists ....................................................................... 126
Modifying Lists ........................................................................ 127
Creating New Lists ................................................................... 129
Note ........................................................................................... 134
Number ....................................................................................... 136
Property Override Relationship .................................................... 140
Password ..................................................................................... 143
System Read Only ........................................................................... 145
Text ........................................................................................... 149
Locator Fields ......................................................................... 151
Time .......................................................................................... 159
Unit of Measure ............................................................................. 160
Url ............................................................................................. 162
List Versus Classification .................................................................. 164
Units of Measure ............................................................................ 165
Managing Units of Measure .......................................................... 167
Number Formats ...................................................................... 174
Money .................................................................................. 178
Base Currency Fields ................................................................. 180
Formulas ..................................................................................... 184

Chapter 4: Life Cycles ......................................................... 187

Life Cycle Diagrams ......................................................................... 188
Life Cycle Transitions ...................................................................... 189
Specifying State Transition Actions ...................................................... 189
The null State ......................................................................... 190
Defining States and Transitions .................................................... 190
Scrolling the Life Cycle Diagram ................................................... 195
Important State Family Tips .............................................................. 195
Reusing Existing Transition Families ..................................................... 196

© Copyright IBM Corporation 2011. | iii

 Sub Actions ................................................................................... 197

Chapter 5: Overview of Workflows ...........................................205

Identifying Needs for Workflows .......................................................... 206
Synchronous vs. Asynchronous Workflows ............................................... 207
Launch Conditions ........................................................................... 208
Organizing a Workflow into Tasks ........................................................ 210
Temporary vs. Permanent Data ........................................................... 211
System Events ............................................................................... 212
Transaction Scope and Processing ........................................................ 214
Variables, Parameters, and Return Values .............................................. 216

Chapter 6: Building User Interfaces ..........................................219

Structure of Forms .......................................................................... 223
Form ........................................................................................... 224
Laying Out a Form’s Structure ............................................................ 227
Form Properties ............................................................................. 229
Tabs .....................................................................................233
Overview of Sections .................................................................238
Form Sections ..........................................................................247
Fields ...................................................................................247
Buttons .................................................................................265
Smart Sections .........................................................................268
Multi Tab Sections ....................................................................275
Query Sections ........................................................................277
Report Sections ........................................................................283
Graphics Sections .....................................................................285
Excel Sections .........................................................................291
Gantt Sections .........................................................................297
Availability Sections ..................................................................318
Stacking Sections ......................................................................324
Group By Sections .....................................................................328
Actions ........................................................................................ 339
Section Actions ........................................................................340
Field and Button Actions .............................................................363
Includes/Forms .............................................................................. 368

iv | : © Copyright IBM Corporation 2011.

 Style Sheets .................................................................................. 369
State-Based Actions ........................................................................ 370
User Messages ............................................................................... 378
User Message Records ................................................................ 378
triUserMessageHelper ................................................................ 380

Chapter 7: Creating Workflows ............................................... 381

Workflow Manager .......................................................................... 381
Workflow Editor ............................................................................. 384
No Ok, Apply, or Cancel ............................................................. 388
Workflow State Transitions ......................................................... 388
Workflow Naming Standards .............................................................. 388
Workflow Tasks .............................................................................. 393
Start Task .............................................................................. 394
User Action Task ...................................................................... 406
Approval Task ......................................................................... 414
Create Record Task .................................................................. 416
Object Mapping ....................................................................... 425
Modify Records Task ................................................................. 432
Retrieve Records Task ............................................................... 440
Query Task ............................................................................ 452
Associate Records Task .............................................................. 464
Trigger Action Task .................................................................. 473
Delete Reference Task .............................................................. 478
Add Child Task ........................................................................ 485
Set Project Task ...................................................................... 492
Schedule Task ......................................................................... 510
Modify Metadata Task ............................................................... 511
End Task ............................................................................... 518
Stop Task .............................................................................. 518
Switch Task ............................................................................ 519
Workflow Condition Builder ......................................................... 521
Fork Task .............................................................................. 530
Loop Task .............................................................................. 533
Break Task ............................................................................. 536

© Copyright IBM Corporation 2011. | v

 Iterator Task ...........................................................................540
Call Workflow Task ...................................................................543
Custom Task ...........................................................................554
DataConnect Task .....................................................................561
Variable Definition Task .............................................................568
Variable Assignment Task ............................................................570

Chapter 8: Temporary Data ....................................................573

Accessing Temporary Data ................................................................. 574
Get Temp Record Task ..................................................................... 575
Save Permanent Record Task .............................................................. 578

Chapter 9: Hierarchies .........................................................581

Hierarchy Modules .......................................................................... 581
Examples of Hierarchies ................................................................... 584
Creating Hierarchies ..................................................................584
Is Parent Of ............................................................................586
Includes .................................................................................587
Biological Hierarchy ..................................................................588
Auto-Populate ............................................................................... 598
Parent-Child Reports ....................................................................... 599

Chapter 10: Calendar and Time Based Events ..............................601

Calendars ..................................................................................... 601
Events ......................................................................................... 606
Manual Event Scheduling ................................................................... 607
Manually Scheduling a Single Occurrence .........................................612
Manually Scheduling a Daily Occurrence ..........................................613
Manually Scheduling a Weekly Occurrence .......................................614
Manually Scheduling a Monthly Occurrence .......................................616
Manually Scheduling a Yearly Occurrence ........................................618
Manually Scheduling an Ad Hoc Occurrence ......................................619
Event Shadowing ......................................................................619
Schedule Workflow Task ................................................................... 621
Event Records ................................................................................ 631
Scheduled Events ............................................................................ 633

vi | : © Copyright IBM Corporation 2011.

Chapter 11: Integration with External Applications....................... 635
E-Mail ......................................................................................... 636
Form Reports ................................................................................ 636
IBM TRIRIGA DataConnect ................................................................. 638
Data Integrator .............................................................................. 638
Financial Transactions ..................................................................... 639
IBM TRIRIGA Connector for Business Applications ..................................... 640
Java Objects ................................................................................. 640

Chapter 12: Notifications...................................................... 641

Notification Content ........................................................................ 642
Notification Helper ......................................................................... 644
triPeople ..................................................................................... 646
Attach Format File Task ................................................................... 646
Notification Example ....................................................................... 653

Chapter 13: Security ........................................................... 655

Authentication .............................................................................. 656
Passwords .................................................................................... 660
Single Sign-On ............................................................................... 660
License Management ....................................................................... 662
IBM TRIRIGA Application Platform License ....................................... 663
Groups ........................................................................................ 663
General Tab ........................................................................... 665
Members Tab .......................................................................... 667
Access Tab ............................................................................. 668
The Admin Group ..................................................................... 672
Organization and Geography .............................................................. 674
Projects ...................................................................................... 675
Using Projects ......................................................................... 676
Creating and Managing Projects ................................................... 679
Workflows and Projects ............................................................. 681
Reports ....................................................................................... 682
Audit Trail .................................................................................... 686
Workflow Instances .................................................................. 695
Lifetime of Workflow Instances .................................................... 698

© Copyright IBM Corporation 2011. | vii

 About Audit Trails .....................................................................699
Filtering Visible Records ................................................................... 700
Workflows Bypass Security ................................................................. 701

Chapter 14: Offline Excel Spreadsheets .....................................703

IBM TRIRIGA Object Map ................................................................... 705
Records to Excel ......................................................................707
Excel to Records ......................................................................709
Populate File Task .......................................................................... 713
Distill File Task .............................................................................. 722
Using E-Mail .................................................................................. 731

Notices ............................................................................745
Trademarks .................................................................................. 747

viii | : © Copyright IBM Corporation 2011.

Chapter 1
In this chapter:
The reasons why you should
or should not read this book.
Introduction

This book is intended for people who are building or customizing an

application that runs on the IBM® TRIRIGA® Application Platform.
Many topics discussed in this book describe useful things you can do to
without needing a professional programmer. This is one of the major
benefits of the IBM TRIRIGA Application Platform.
Some applications need to work with other applications that run out-
side the IBM TRIRIGA Application Platform. To accomplish this cooper-
ation with applications that run outside the IBM TRIRIGA Application
Platform, it may be necessary to resort to techniques that do require
the involvement of a professional programmer or other I.T. person-
nel. Sections of this book that discuss techniques that require the
involvement of a professional programmer or other I.T. personnel spe-
cifically mention this requirement.

About the Platform

There are two attributes of the IBM TRIRIGA Application Platform that
make applications built on it more valuable than applications built on
other platforms:
• The IBM TRIRIGA Application Platform allows a person building an
application to focus on what the application is supposed to do
rather than how to do it. Traditional technologies used to build
applications require someone building an application to focus on
how the application will do the things it is supposed to do.
Breaking down an application’s tasks this way requires a person
with programming skills to focus on a great many details. A great
deal of training may be needed for a person to know how to han-

© Copyright IBM Corporation 2011. ix

 dle these details. Because programmers building applications with
traditional technologies are forced to focus on the details of how
the application is supposed to do what it does, their understand-
ing of what the application is supposed to do often suffers.
Because the platform allows a person building an application to
focus on what the application is supposed to do, the result is usu-
ally an excellent fit for business needs. Even better, people need
just a few weeks of training to be able to build applications using
the IBM TRIRIGA Application Platform! This means that business
people who know what the application is really supposed to do
can build an application without going through a programmer.
Building applications on the IBM TRIRIGA Application Platform is a
relatively rapid process that does not require the involvement of
programmers for most applications. Customizing canned applica-
tions to the exact needs of a business is also a relatively rapid
process. Rapid application building and customization by business
people who only need a few weeks of training results in dramati-
cally lower costs of acquisition. Modifying applications built on
the IBM TRIRIGA Application Platform to meet changing business
needs is also a relatively rapid process. This translates into a dras-
tically lower cost of ownership.
• The IBM TRIRIGA Application Platform comes with predefined busi-
ness objects* that can be used to represent things needed by most
business applications, such as people, currencies, and schedules.
Building applications using these predefined business objects
saves people time they would otherwise spend having to create
these things themselves.
Building applications using these common predefined business
objects has another more important benefit. Applications that use
the same business objects to represent the same data automati-
cally share the data contained in the business objects. The data in
these common business objects will never need to be entered
twice!

* A business object is what the IBM TRIRIGA Application Platform uses to describe real world
entities.

x | Chapter 1: © Copyright IBM Corporation 2011.

IBM TRIRIGA Application Platform
License
To build or customize applications on the IBM TRIRIGA Application
Platform, you will need to access many features of the platform that
are available to you only if your user ID has been assigned an IBM
TRIRIGA Application Platform license. If you do not have an IBM
TRIRIGA Application Platform license, ask your platform administra-
tor or IBM TRIRIGA representative about obtaining an IBM TRIRIGA
Application Platform license.

Other Information Sources

There are things important to know about the IBM TRIRIGA Applica-
tion Platform that are not part of the process of developing or cus-
tomizing an application. These things are outside the scope of this
book, but appear in other books that IBM TRIRIGA publishes. IBM
TRIRIGA documents are available in PDF format from IBM TRIRIGA
Information Centers.
For information about installing and configuring the IBM TRIRIGA
Application Platform, see the installation instructions that come with
the software and the book IBM TRIRIGA Application Platform 3 Instal-
lation and Implementation Guide.
For information about specific applications, see the documentation
provided for the application.

About Application Building for the

IBM TRIRIGA Application Platform 3
This document is part of the Application Building for the IBM TRIRIGA
Application Platform 3 collection of user guides. The collection is
intended to provide you with an understanding of the basic tools to
build or customize applications running on the IBM TRIRIGA Applica-
tion Platform. The following user guides are in the Application Build-
ing for the IBM TRIRIGA Application Platform 3 collection:
• Application Building for the IBM TRIRIGA Application Platform 3
(this book)

About Application Building for the IBM TRIRIGA Application Platform 3

© Copyright IBM Corporation 2011. | xi
 • Application Building for the IBM TRIRIGA Application Platform 3:
Calculations
Covers the following major topics:
Extended Formulas
Financial Transactions and Rollups
• Application Building for the IBM TRIRIGA Application Platform 3:
Data Management
Covers the following major topics:
DataConnect
Data Integrator
• Application Building for the IBM TRIRIGA Application Platform 3:
Performance Framework
Covers the following major topics:
Performance Management
Data Structures
Metrics
Hierarchy Flattener
Appendix A: List of Fact Tables
Appendix B: Fact Tables and Metrics Supported
Glossary

Support
IBM Software Support provides assistance with product defects,
answering FAQs, and performing rediscovery. View the IBM Software
Support site at www.ibm.com/support.

xii | Chapter 1: © Copyright IBM Corporation 2011.

In this chapter:
• A description of the basic
CHAPTER 1
Platform Overview
nature of the IBM TRIRIGA
Application Platform.
• A summary of features
needed to support
applications.
• An explanation of common
skills needed to use
platform-provided tools.

The IBM TRIRIGA Application Platform is a self-contained environment

for building and running business applications. Already built into the
platform is much of the common logic used for business applications.
To build a simple application that runs in the IBM TRIRIGA Application
Platform environment, you need only add four things:
• A description of how the application’s data is organized.
• A description of what the application’s user interface will look
like.
• Descriptions of the reports and queries that the application will
support.
• Custom logic needed for the business processes that the applica-
tion will support.
In the rest of this chapter is an overview of how the platform allows
you to organize these four things. There is also an overview of other
platform facilities needed to support more advanced application fea-
tures.
The chapter concludes with an explanation of some common skills you
will need to use the tools that the platform provides.
Until all of the builder tools are globalized, to avoid the confusion of
seeing some of the text in English and some in the user’s language,
application builders should be logged in as US English users.

Data Model
The IBM TRIRIGA Application Platform maintains a description of the
data that applications use. This description is called the data model.

© Copyright IBM Corporation 2011. 1

 When you use the platform to build an application, you should start
The Data Model with the data model. This is because the other pieces of the applica-
is Independent tion, the user interface, the reports, and the custom logic, all use the
data model.
of the User
Interface The data model is organized into five main parts:

It is common for most busi- • Field definitions describe individual pieces of data. A field con-
ness objects in a data model tains an individual piece of data.
to closely match the organi- • Business objects describe sets of fields that are stored and manip-
zation of information visible ulated together. Business objects are used to create records. A
in the application’s user record contains actual data for the fields described by the busi-
interface. However, this is ness object used to create the record.
not a requirement.
• Associations describe how business objects relate to each other.
A business object may be • Modules organize business objects. A module is a collection of
used to create records that business objects. Each business object belongs to exactly one
are used only for behind-
module.
the-scenes processing. The
information in such records • State transitions control the life cycle of records created from a
may not appear anywhere in business object. The life cycle of most records is that it is cre-
an application’s user inter- ated, modified, and possibly deleted. A record’s life cycle is
face. determined by the state transitions in the business object used to
create it.
The IBM TRIRIGA Application Platform provides a tool named the Data
Modeler that is used to describe and manage modules, business
objects, associations, and field definitions. This use of the Data Mod-
eler is described in Chapter 2.
The state transitions that are used by records created from a busi-
ness object also are described and managed using the Data Modeler.
The IBM TRIRIGA Application Platform provides a library of pre-built
state transition families you can draw upon when you are setting up
state transitions for a business object. The library of pre-built state
transition families is managed by a tool named the State Family Man-
ager. The State Family Manager and this use of the Data Modeler are
described in Chapter 4.

User Interface
The user interface of an application that runs on the IBM TRIRIGA
Application Platform has three essential pieces:
• Access to the major parts of an application is through a portal. A
portal can provide access to the major parts of an application

2 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

 through menus. A portal also can include more sophisticated
graphical components.
There is an overview of portals on page 5.
• Navigation items allow people to create, view, and edit related
types of records, among other things. If people working in differ-
ent roles need different views of records or different ways to
manipulate the same records, their needs can be served by creat-
ing multiple navigation items that manage some of the same kinds
of records but in different ways. There is an overview of naviga-
tion items and their use on page 4.
• Creation, viewing, and editing of records is done using forms.
Each form is associated with a business object. However, one
form can display or edit data from any combination of records.
The only restriction on the records that can be manipulated by
one form is the form’s ability to navigate to the records. The busi-
ness object that the records were created from is not important.
Different forms may access some of the same records in order to
provide a different presentation of the contents of those records.
There is an overview of forms in the next part of this chapter.

Form Builder
The IBM TRIRIGA Application Platform provides a tool named the Form
Builder for the purpose of defining and managing forms to create,
view and edit the contents of records. The Form Builder is discussed
in detail in Chapter 6.
Each form created by the Form Builder is associated with a business
object. Multiple forms can be associated with the same business
object. This allows different forms to provide different views of the
data in the same kinds of records.
The fields in a form can contain values for a record created using the
business object with which the form is associated. A form also can
display values from fields in other records. A form can even display
label fields that are not connected with any record at all.
Forms utilize workflows to control the interaction between the user
and the form. A workflow is a sequence of tasks you can specify to be
performed automatically. There is an overview of workflows on
page 6.
Workflows can be used with forms to customize the behavior of the
form in a number of important ways, including these:

© Copyright IBM Corporation 2011. User Interface | 3

 • Workflows can copy values between records and forms.
• Workflows can be used to provide immediate feedback if a person
enters a wrong value in a field.
• Workflows can dynamically change the display properties of a
form. The possibilities include changing the color of a label, the
font of a field, or even hiding and unhiding parts of the form.
• Workflows can evaluate the overall consistency and correctness of
the data in a form before allowing the data to be saved.
Workflows can be run implicitly as a result of changing the value of a
field. Workflows can be run explicitly by a person clicking an action.
Forms created by the Form Builder are organized into tabs that con-
tain sections that contain the fields. Actions to launch a workflow can
be associated with an entire form, an individual tab, or a section of
the form. Also, buttons can be put anywhere in a form. A workflow
can be run when someone clicks a button.

Navigation Item
Navigation items allow people to create, view and edit related types
of records, among other things. A navigation item can be configured
to display is a collection of forms, results of a query, and hierarchical
data. Navigation items can be configured to display a default master/
detail query, known as a manager query, that provides a standard way
for the records of a form to be displayed. If users working in different
roles need different views of records or different ways to manipulate
the same records, their needs can be served by creating navigation
items that use a customized query to manage some of the same kinds
of records but in different ways.
The Navigation Builder is a tool provided by the IBM TRIRIGA Applica-
tion Platform to create, maintain, and organize navigation items in
menus or portals. The Navigation Builder gives access to navigation
items that determine what kinds of records to display. Navigation
items are also flexible and generic enough to represent menus, portal
quick link sections, display hierarchical data, run reports, and link to
other builder tools.
The Navigation Builder and navigation items are described in the IBM
TRIRIGA Application Platform 3 User Experience User Guide.

4 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

Portals
A portal is the home page for an application. When someone signs in
to the IBM TRIRIGA Application Platform, the first thing they see is
their portal. At the top of the portal is the header region containing a
logo, Sign Out link, and related information. Immediately below is the
menu region, which displays menu options. The rest of the portal, the
content area, consists of more complex graphical components.
The portal and menu that a person sees when he or she signs in is
determined by the settings in the My Profile record that defines the
person’s user id. My Profile records are described on page 656 under the
heading “Authentication”.
Menus are managed with a tool named the Navigation Builder, which
is described in the IBM TRIRIGA Application Platform 3 User Experi-
ence User Guide.
A tool named the Portal Builder is used to create and manage named
portals and to control the arrangement and creation of portal sec-
tions within each named portal. The Portal Builder is described in the
IBM TRIRIGA Application Platform 3 User Experience User Guide.

Queries / Reports
The IBM TRIRIGA Application Platform has facilities to produce a vari-
ety of reports or queries. The mechanisms for producing reports can
be divided into two categories: internal and external.
There are two internal report generating mechanisms for producing
two different kinds of reports. One internal mechanism is for produc-
ing what is called a form report. A form report presents the contents
of a single record. A form report may also include the contents of a
record’s multi-record smart sections or query sections.
Internally generated form reports are a very flexible way to format
the contents of a record. A form report provides you with all the flexi-
bility of Microsoft Word or Excel to format the contents of records.
The tool you use to lay out the format of a form report is either
Microsoft Word or Excel. Form reports are described in the IBM
TRIRIGA Application Platform 3 Reporting User Guide.
The other internal report generating mechanism is the Report Man-
ager. The Report Manager generates tabular reports or graphs. The
Report Manager is described in the IBM TRIRIGA Application Platform 3
Reporting User Guide.

© Copyright IBM Corporation 2011. Queries / Reports | 5

 There are three particularly interesting features of reports generated
by the Report Manager:
• Reports generated by the Report Manager can be included in
forms that are part of a user interface. Reports that are gener-
ated primarily for use within a user interface are usually called
queries.
The inclusion of queries in a user interface is under the control of
the Form Builder tool. There is an overview of the Form Builder
tool on page 3.
• Reports generated by the Report Manager allow users to drill
down into underlying records. Just click a piece of data in a
report and an appropriate form will pop up to allow you to view or
edit the contents of records that the report data came from.
• If a report or query is configured to allow it, you can edit the val-
ues you see in a report directly in the report. This feature allows
you to edit the values in any number of records all at the same
time.
Editable reports are discussed in the IBM TRIRIGA Application Plat-
form 3 Reporting User Guide.
Externally generated reports are produced using the IBM TRIRIGA
Advanced Reporting tool. This tool allows more flexibility in format-
ting reports that the internally generated reports. Information about
this tool can be found in the IBM TRIRIGA Application Platform 3
Reporting User Guide.

Workflows
A workflow is a specified sequence of tasks that is performed auto-
matically. Use a workflow to specify the tasks you need an applica-
tion to perform automatically but that the IBM TRIRIGA Application
Platform does not already know how to do.
Many concepts need to be understood to successfully create a work-
flow. Having a background in programming is helpful in learning to
create workflows, but it is not necessary.
The major concepts needed to create a workflow are described in
Chapter 5. The details you need to know to create a working work-
flow are described in Chapter 7.

6 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

Other Features
This overview of IBM TRIRIGA Application Platform features has
focused on features of the platform needed to build and support core
features of most business applications. The platform has many other
interesting features:
• The platform has the ability to associate calendars and schedules
with records. This feature can be used to track the availability of
resources or to initiate actions at predetermined times. This fea-
ture is discussed in Chapter 10.
• The platform has the ability to export the metadata that makes
up an application from the environment in which that application
was developed to an XML file. The XML file then can be imported
to other platform installations. This feature is discussed in the IBM
TRIRIGA Application Platform 3 Object Migration User Guide.
• The platform has a variety of features to allow applications run-
ning on the platform to work with applications running outside the
platform. The platform is able to work directly with a variety of
technologies including Excel, database tables, and SOAP. There is
an overview of these features in Chapter 11.
• The platform has the ability to organize records into a hierarchy.
This is especially useful for organizing some types of data such as
organization structures, location levels, and geographical subdivi-
sions. The platform also has the ability to roll up totals through a
hierarchy. Hierarchies are discussed in Chapter 9.
• The platform has a variety of security related features to allow an
administrator to exercise a great deal of control over who can
access what kinds of data and what people can do with the data.
The platform’s security features are discussed in Chapter 13.
• The platform has features to help adapt applications to work in
different countries and in different languages. These features are
discussed in IBM TRIRIGA Application Platform 3 Localization User
Guide.
• Information for application developers who are building or cus-
tomizing an IBM TRIRIGA Workplace Performance Management
application that runs on the IBM TRIRIGA Application Platform can
be found in the book Application Building for the IBM TRIRIGA
Application Platform 3: Performance Framework.

© Copyright IBM Corporation 2011. Other Features | 7

 Common Skills for Platform Tools
The IBM TRIRIGA Application Platform provides a variety of tools for
building applications. There are some skills and concepts that are
common to using many of these tools. Some of these skills are
explained in the remainder of this chapter.

Custom Menus
Some of the tools in the IBM TRIRIGA Application Platform use menus
that look and work a little bit differently from most other menus.
Figure 1-1 shows an example of one of these menus.

Figure 1-1. Custom Menu

These custom menus may not appear directly under the word in the
menu bar that is clicked to make the menu appear. The example in
Figure 1-1 shows the mouse on the word View and the menu appear-
ing to the left of the word.
After one of these custom menus appears, you cannot make it disap-
pear by just moving the mouse. You must click one of the menu items
to make it disappear.
At the bottom of these menus is an item labeled Close. The Close
menu item is the menu item to click when you do not want to click a
menu item. Clicking the Close menu item makes the menu disappear
without doing anything else.

8 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

Create-Publish-Revise Cycle
Applications that run on the IBM TRIRIGA Application Platform are
made up of a variety of metadata*, such as:
• business objects
• forms
• workflows
The pieces of metadata that make up an application have interdepen-
dencies. If you save a piece of metadata that is wrong or incomplete,
then you break everything that uses that piece of metadata.
To avoid breaking an application, when you are editing a piece of
metadata, you may decide to avoid saving the metadata until you are
finished editing it. If the metadata in question is small and simple,
this may not be an issue. However, if the metadata in question is
large, it is a good practice to save your work frequently to minimize
the consequences of any editing mishaps.
At first glance, there seems to be no way to achieve both of these
goals at once. However, the IBM TRIRIGA Application Platform has a
feature that allows you to achieve both goals at once.
Whenever you are editing a piece of metadata, after you have saved
it the first time there will be a menu item in the Tools menu to pub-
lish the metadata. The changes you make to the metadata do not
actually take effect until you publish the metadata. No matter how
many times you save metadata you are editing, the previously pub-
lished version of the metadata will continue to be used until you pub-
lish the edited metadata.
When you first create a piece of metadata, it is not available for use
until you publish it. You cannot publish a piece of metadata until
after the first time it is saved.
The life cycle diagram in Figure 1-2 shows the typical life cycle of a
piece of metadata.
Here are descriptions for the states of metadata shown in Figure 1-2:
null
A piece of metadata is in this state when it is first created. The
metadata is not available for use while it is in this state. All you

* Metadata is data that describes data. For example, records are data. Business objects
describe records, so business objects are metadata.

© Copyright IBM Corporation 2011. Common Skills for Platform Tools | 9

 Figure 1-2. Metadata Life Cycle

can do with metadata in this state is edit it and save it. Saving the
metadata puts it in the Created state.
Created
A piece of metadata is in this state after it is saved for the first
time until it is published for the first time. The metadata is not
available for use while it is in this state.
While the metadata is in this state, you can edit it, save it, or
publish it. Publishing the metadata puts it in the Pending
Publication state.
Pending Publication
A piece of metadata is in this state after a publish action has been
performed on it. It stays in this state until the platform has fin-
ished its internal processes related to publishing the metadata.
This process takes a few minutes for business objects. It is almost
instantaneous for other kinds of metadata.
Published
A piece of metadata is in this state after it has been published.
While it is in this state, the piece of metadata is available for use.
Also, while a piece of metadata is in this state, you cannot edit it.
The only action you can perform on a piece of metadata in this
state is Revise. Performing a Revise action on a piece of meta-
data puts it in the Under Revision state.
Under Revision
A piece of metadata is in this state after a Revise action has been
performed on it. While a piece of metadata is in this state, you

10 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

 can edit it. Also, while a piece of metadata is in this state, you
can perform a Save or Publish action on the metadata.
Performing a Save action on metadata in this state saves your
edits but does not make any of the changes available for use. The
metadata will continue to be used in exactly the same form it was
in the last time it was published.
Performing a Publish action on metadata in this state saves your
edits, makes them available for use, and puts the metadata in the
Pending Publication state.

Managing Panels
Many of the tools provided in the IBM TRIRIGA Application Platform
environment have a user interface that is organized into panels.
Figure 1-3 shows an example of this. The user interface in Figure 1-3
contains panels named Navigation, Layout, Properties, and
Components. The different panels are used to display different kinds
of information.
The following paragraphs are not about the information contained in
the panels. Rather, they explain how to manage and manipulate the
panels themselves. There are five things that you are generally able
to do with a tool’s panels:
• Hide a panel so that it is not visible in the user interface.
• Force a hidden panel to be visible in the user interface.
• Move panels around in the user interface.
• Change the size of a panel.
• Restore the panels in a tool’s user interface to their default con-
figuration.
To hide a panel, just click the X in panel’s upper right corner. After
you click the X, the panel will no longer be visible in the user inter-
face.
To force a hidden panel to be visible again, use the View menu. Tools
that have a panel-based user interface have a View menu that looks
similar to Figure 1-1 on page 8.
Most of the items in these View menus have the same name as pan-
els. Clicking a View menu item forces the panel with the same name
as the item to become visible if hidden.
To drag a panel to a different position in the window, move the
mouse to the rectangle at the top of the panel that contains the name

© Copyright IBM Corporation 2011. Common Skills for Platform Tools | 11

 Figure 1-3. User Interface Organized into Panels

of the panel and the X. Hold down the left mouse button. After a
short amount of time, the contents of the panel will be covered by
the same color as the border. If you continue to hold down the mouse
button while moving the mouse, you will be able to drag the panel to
where you want it in the window.
To change the size of a panel, move the mouse to the border of the
panel. Hold down the left mouse button. After a short amount of
time, the contents of the panel will be covered by the same color as
the border. If you continue to hold down the mouse button while mov-
ing the mouse, you will change the size of the panel. Another way to
change the size of a panel is to move the mouse to the rectangle at
the top of the panel that contains the name of the panel and the X,

12 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

hold down the Ctrl key and hold the left mouse button while moving
the mouse.
To restore the panels to their default configuration, click Reset in the
menu.

Naming Conventions
IBM TRIRIGA follows a set of naming conventions in its applications
and in all custom development that it does on behalf of its custom-
ers. IBM TRIRIGA suggests you also follow these naming conventions.
Following these conventions will reduce unexpected interactions
between IBM TRIRIGA’s applications and applications created by oth-
ers. Following these conventions will help ensure that upgrades go
smoothly.

Name Prefix
A three character customer prefix is assigned to all implementations,
typically cst. For IBM TRIRIGA applications, the prefix is tri. If you are
customizing your own implementation or if you are developing your
own application, use a cst prefix for your work.

Design Elements
A specific naming convention has been established for each type of
design element available on the IBM TRIRIGA Application Platform.
These are explained in Figure 1-4.
Design Naming Convention Example Name Label Convention Label Example
Element
Module cst + mixed case, no spaces cstContract none n/a
Business cst + mixed case, no spacesa cstPurchaseOrder User readable Purchase Order
Object name for the
business object
Form [cst +] Business object name + cstPurchaseOrderShortForm User readable Short Form
mixed case, no spacesb name for the Purchase Order
Graphical User
Interface
Navigation cst + mixed case, no spacesc cstPurchasing User readable Purchasing
Collection name for the
navigation col-
lection, suitable
for a menu item
Figure 1-4. Type Specific Naming Conventions for Design Elements

© Copyright IBM Corporation 2011. Common Skills for Platform Tools | 13

Design Naming Convention Example Name Label Convention Label Example
Element
Navigation cst + mixed case, no spaces cstAsset User readable Asset
Item name for the
navigation item,
suitable for a
menu item
Form cst + mixed case, no spaces cstGeneral User readable General
Sections name for section
Smart / [cst +] Business object name + cstOrganizationBillTo User readable Bill To
Query mixed case, no spacesd name for section
Section
Field cst + mixed case, no spaces + cstAssignedFullNameTX User readable Assigned Full
field type suffix name for field Name
(Field type suffixes are
described in Figure 1-5 on
page 15)
Report, cst+“-” + Form Name (or Busi- cst-triPurchaseOrder - Workflow - Form Label (or Employees - All
Query, ness Object Name or Module POs for Current Year Business Object Associated
Graph Name if Report/Graph) - Key- Label or Module Active
word - Contexte Label) - Context Employees
or (What the report
If the query references a new displays to user)
or customized object:
Form Name (or Business cstEmployee - BIRT - Employee
Object Name or Module Contact Details
Name) - Keyword - Context
(Keywords are described in
Figure 1-6 on page 16)
State Family cst + Context (mixed case, no cstActionItem, cstData, none n/a
spaces) cstDocument
State Family cst + (Action) mixed case, no cstDeleted User readable Deleted
State spacesf name for the
Actiong
State Family cst + (Action) mixed case, no cstFinalDelete User readable Final Delete
Action spaces name for the
Action (Transi-
tion)
Security Customer Name + Role IBM TRIRIGA Contact Center Agent none n/a
Group
Figure 1-4. Type Specific Naming Conventions for Design Elements (continued)
a Business object names cannot be changed once the business object is published.
b This is the system name for the Graphical User Interface. Each business object can have many forms.
c This is the system name for the navigation collection. Each business object can be in multiple navigation collections.
d A section name cannot exceed 30 characters, so there may not be enough space for the full business object name.
Choose a name that reflects the intent of the section.

14 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

e No spaces between the “cst-” and the tri object name.
Context should include filters to states, data filters, association filters, if editable etc. For queries tied to a
$$RECORDID$$ or other platform key, make sure to include the type of context record in the context part of the name.
The ID of the report should be CUSTOM, or use your company’s numbering standards for reports. SYSTEM is reserved
for IBM TRIRIGA delivered reports.
Keywords are described in Figure 1-6 on page 16.
f The 'null' state is the exception to this rule. A record is in a null state before it is created or permanently deleted.
The system then permanently removes the records in the null state after a configured time period with the Cleanup
Agent.
g State Transitions should not be labeled Cancel.

Field Type Suffixes

Names of fields should have an uppercase suffix that corresponds to
the field’s type. These suffixes are shown in Figure 1-5.
Field Type Suffix Convention Example
Action Button AB cstLookupGeographyAB
Binary BI cstOrganizationBI
Boolean BL cstProcessFlagBL
Business Objecta BO cstOrganizationBO
Classification CL cstRollupLocHeadCL
Classification Rollup CR cstBuildingCommonCR
Color CO cstFabricColorCO
Control Number CN cstIdCN
Date DA cstEstimatedStartDateDA
Date and Time DT cstActualStartDT
Duration DU cstMeetingDurationDU
Financial Rollup FR cstCommitedCostsFR
Image IM cstPortraitIM
Label Onlyb LA cstEnterNameHereLA
List LI cstYesNoLI
Note NO cstCommentsNO
Number NU cstRateNU
Password PA cstPasswordPA
System Read Onlyc SY triBusinessObjectIdSY
Text TX cstNameTX
Time TI cstStartTimeTI
UOM UO cstAreaUO
Figure 1-5. Field Type Suffix Conventions

© Copyright IBM Corporation 2011. Common Skills for Platform Tools | 15

 Field Type Suffix Convention Example
URL UR cstExternalInfoUR
Figure 1-5. Field Type Suffix Conventions
a Only used for system-generated fields. Use Text locator fields that use
Association strings and enable Find queries.
b Added with the Form Builder, not with the Data Modeler.
c There are IBM TRIRIGA fields for all of the system read only fields. You
should not add versions of these with other prefixes. Use the Find action
to add them if they do not exist in the business object.

Report, Query, Graph Keywords

The keywords to be used in report, query, or graph names are shown
in Figure 1-6.
Keyword Description
Debug Query to help isolate data issues
Display Query to display data in form query sections
External Query with linked IBM TRIRIGA Advanced Reporting
document
Filter Query to filter data for other queries via Association
filters
Find Query for Find action of locator field or section
FormMetric Query for metric in a form
Formula Query used to provide input values for extended
formulas
Graph Graph reports intended for end users
Graphics Graphcs Editor report
Patch Query used in patch helpers
Portal Query for portal section
Report Report intended for end users
Reserve Calendar / Reserve based query of data associated
with record
Summary Summary Report intended for end users
Workflow Query for workflow Query task
Figure 1-6. Report, Query, Graph Keyword Conventions

Workflows
Workflow naming standards are on page 388.

16 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.

Publish Name
The Publish Name defines a unique value that identifies each record
for a business object. This value can be composed of one or more
fields with combined values that define a record as unique.
Take care when selecting the control number as the published name
as these records cannot be updated via IBM TRIRIGA Data Integrator.
The control number should only be used as the publish name defini-
tion for Log or non-permanent data, such as action forms or helpers.
If the application does not have a requirement for the starting value
of control number, use 1000000.
If a business object has base currency fields, the Conversion Group map-
ping property should refer to a field with a name like triConversionGroupLI
that specifies which conversion group to use for converting to base
currency fields. The default value should be Default. Also, the Exchange
Date property should refer to a field with a name like triExchangeDT that
specifies the effective date to use for converting to Base fields. The
default value should be the current date.
When a user changes the publish name of a business object, the sys-
tem requests confirmation of the change.

© Copyright IBM Corporation 2011. Common Skills for Platform Tools | 17

18 | Chapter 1: Platform Overview © Copyright IBM Corporation 2011.
In this chapter:
• How to define business
CHAPTER 2
Data Modeling
objects to create different
types of records.
• How business objects are
organized into modules.
• How to define fields in
records.
• How to define associations
between types of records.
• How to define smart
sections in records.

All applications that run on the IBM TRIRIGA Application Platform rely
on four basic facilities:
• Records that contain the application’s data.
• Queries or reports that allow people to work with sets of records.
• Workflows that automate the manipulation of records.
• Forms that allow people to work with individual records.
This chapter describes a tool named Data Modeler that is part of the
IBM TRIRIGA Application Platform. The Data Modeler allows you to
define the types of records that an application will use. It also allows
you to define the kinds of relationships that the records may have.
The Data Modeler works by allowing you to edit metadata that
describes records. Metadata is simply data that describes data. The
metadata for records is organized four ways:
Business Objects
A business object describes the properties of a kind of record. To
create a record, you use the business object that corresponds to
the type of record you want to create.
Field Definitions
A field contains an individual piece of data such as 4. Records con-
tain fields that contain the individual pieces of data. A field defi-
nition defines a type of field with a specified name. A business
object contains a list of field definitions that determine which
fields will be in records created from the business object.
Modules
Business Objects are organized into collections called modules.
Each module contains one or more business objects.

© Copyright IBM Corporation 2011. 19

 Associations
In the IBM TRIRIGA Application Platform environment, the word
association is used to mean two different things. It means a con-
nection from one record to another record. If there is an associa-
tion from one record to another, an application looking at the
first record can navigate to other records it has an association
with. Each end of an association has its own name. This kind of
association is a form of data.
The other kind of association is a form of metadata. The meta-
data kind of association is between two business objects. This also
is called an association definition. Each end of a metadata associ-
ation also has its own name. The purpose of a metadata associa-
tion is to define standard data associations that applications may
create or use between records created from the same two busi-
ness objects.
If there is a metadata association between two business objects, a
data association with the same names may exist between two
records created from the same two business objects. The meta-
data association serves as a definition that allows the data associ-
ations it defines to be created.
The diagram in Figure 2-1 shows metadata relationships.

Metadata Defines 4
Module Data Association
Association 1 *
1 1 1

Contains  Connects  Connects 

1..* 2 2

Business Object Defines 4 Digital Record

1 *
1 1

Has list of  Contains 

* 1..*

Field Definition Defines 4 Field

1
*

Figure 2-1. The Organization of Records and the Metadata that Describes Them

20 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

The rest of this chapter describes the metadata in greater detail and
explains the use of the Data Modeler.

Modules
A module is a collection of business objects. Every module has a
name. Business objects with a similar structure or purpose are usually
in the same module.
The IBM TRIRIGA Application Platform comes with a number of
modules already defined. Here are some examples:
• The Geography module contains business objects used to create
records that represent different levels of political or geographic
entities. The business objects defined in the Geography module
include City, Country, State and World Region.
• The Document module contains business objects used to describe and
manipulate documents and files. It contains business objects for
describing individual documents, collections of documents, and file
directories.
• The Meeting module contains business objects used to describe a meet-
ing or meetings.
Before you can define a business object, you must decide which mod-
ule it will be in. You may decide to put some business objects into
modules that are already defined in the IBM TRIRIGA Application Plat-
form and some into new modules. You must create a new module
before you can put business objects in it.

Organizing into Modules

Here are some rules to help you decide in which module to add a new
business object:
1. Business objects that contain some of the same fields should be in
the same module.
2. Business objects that can play the same role in the same business
process should be in the same module.
3. Business objects that have a similar business purpose should be in
the same module.

© Copyright IBM Corporation 2011. Modules | 21

 Creating Modules
Before you actually create a new module, you must decide on a name
for the module. You should choose a name that describes the sort of
business objects that will be in the module. For example, if the busi-
ness objects in a new module will be used to create records that
describe materials used in training courses, it would be reasonable to
choose a name like cstTrainingMaterial. Do not choose a name like X24.
Once you have decided on the name of a new module, you can create
the module.
To create a module, navigate to Tools > Builder Tools > Data Mod-
eler. This makes the Data Modeler visible. Figure 2-2 shows what the
Data Modeler looks like when it first appears.

Figure 2-2. Data Modeler

The Data Modeler is organized into panels. The name of the panel
shown in Figure 2-2 is Object Browser. Other panels that appear as
needed are named Data Modeler, Property, Field List, and
Association List. You can rearrange and otherwise manage the panels
using the procedures discussed on page 11 under the heading
“Managing Panels”.
The panel labeled Object Browser contains a list of modules. Nor-
mally the Object Browser panel is collapsed so you cannot see what

22 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

is in it. When you put the mouse pointer over the left-most part of
the Object Browser panel where the words Object Browser are, it
expands and looks like Figure 2-3.

Deleting Modules
Before you create a mod-
ule, it may be worth tak-
ing the time to ask
yourself if the module is
really needed. The reason
Figure 2-3. Data Modeler with Object Browser Panel Expanded for this extra care is that
the IBM TRIRIGA Applica-
If you click a closed folder ( ) icon next to module, a list of the busi- tion Platform does not
ness objects in the module appears under the module’s name. Also have a way to delete a
the closed folder ( ) icon changes to an open folder ( ) icon. module after it is created.
If you create a module you
If you click an open folder ( ) icon next to a module, the list of busi- do not need, there is no
ness objects under the module’s name disappears. Also, the open way to delete it.
folder ( ) icon changes to a closed folder ( ) icon.
What people usually do
In the menu bar at the top of the Data Modeler, there is a menu with a module that is not
named New. In this menu, click the New Module menu item, which needed is change its name
causes the Property panel to appear and look like Figure 2-4. This by putting an “X” at the
allows you to specify the properties needed to create a new module. beginning of the module’s
name. For example, if you
These are the properties to specify: find yourself with a mod-
Module Name ule named Widget that is
not needed, change the
The value of this property is the name of the module. Naming
name of the module to
conventions are described on page 13. XWidget.

© Copyright IBM Corporation 2011. Modules | 23

 Figure 2-4. Properties for a New Module

Hierarchy Module
This check box should be checked if the module is going to be a
hierarchy module. Hierarchy modules are described in Chapter 9.
If you are not sure what a hierarchy module is, assume all mod-
ules you create are not hierarchy modules; leave this check box
unchecked.
Click the Save Module action near the top of the Data Modeler when
you finish entering a new module’s information. After you click the
Save Module action, you are finished creating the module.
You do not publish a module. Modules are different from most other
kinds of metadata in that they have no publish-revise cycle.*

Editing Module Properties

If you want to edit the properties of an existing module, click the
name of the module in the Object Browser panel. Clicking the name
of the module makes the Properties panel look like Figure 2-5.
Aside from the label at the top of the Properties panel being Edit
Module instead of Create Module, the experience of editing a mod-
ule’s properties is the same as creating a module. Module creation is
described in the preceding part of this chapter.

* The concept of a publish-revise cycle is discussed on page 9 under the heading “Create-
Publish-Revise Cycle”.

24 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 Figure 2-5. Properties for Editing a Module

Adding a Business Object to a New Module

At this point, you can create business objects in the new module. The
first business object you must create in a module is the module’s base
business object. The base business object should have the same name
as the module.
After you have created and published a module’s base business object
and specified the base business object’s fields, you can create other
business objects in the module. When you create another business
object in a module, the new business object is created with a copy of
the sections, fields, association definitions, and state transitions in
the module’s base business object. Once a business object is created,
you are free to add, remove, or modify its sections, fields, associa-
tion definitions, and state transitions. Changing the newly created
business object in any way has no effect on the base business object
or on any other business object.

Creating a Business Object

Once a module exists, you can create business objects in the module.
At a high level, these are the steps for creating a business object:
1. Specify basic information about the business object, including its
name and description. After this step, the business object exists.
Its name and basic properties are established, but the IBM
TRIRIGA Application Platform does not yet know what fields the
records created from the business object will contain.

© Copyright IBM Corporation 2011. Creating a Business Object | 25

 2. Specify associations between the business object and other busi-
ness objects.
3. Specify the business object’s fields.
4. Specify how records created from the business object will be
uniquely identified.
5. Publish the business object.
In the following paragraphs, we describe these steps in greater detail.

A Business Object’s Basic Information

To begin the creation of a business object by specifying its basic infor-
mation, click the New Business Object menu item in the New menu
of the Data Modeler.

26 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

After you click the New Business Object menu item, the Data Mod-
eler’s Property panel looks like Figure 2-6.

Figure 2-6. Properties for a Business Object

There are a number of pieces of information you can enter into the
properties panel shown in Figure 2-6. Some of the information does
not have to be specified when you create a business object. It can be
specified later or not at all.
When you create a business object, there are four pieces of informa-
tion you must specify before the business object can exist. The first

© Copyright IBM Corporation 2011. Creating a Business Object | 27

 three pieces of information are the business object’s name, display
name, and description. The description can wait until later, but all
business objects should have a description from the time they are first
created.
The other piece of information you must specify at this time is
whether the records created from the business object will be stand
alone, embedded, or link records. The default is Stand Alone. This is
controlled by radio buttons shown in Figure 2-6 on page 27 with these
labels:
Stand Alone
Stand alone records contain their own data. Stand alone records
can appear at the top-level organization of reports and queries
(described in the IBM TRIRIGA Application Platform 3 Reporting
User Guide). Stand alone records are the only form of record that
can be managed directly from the results of a query. This is the
default.
Embedded
Embedded records cannot be at the top-level organization of a
query or report. Embedded records cannot be accessed from the
results of a query. An embedded record can be accessed only
through other records. Embedded records can exist only in a
smart section or query section of another record. Smart sections
are described on page 74.
Embedded records cannot be shared between two different smart
sections. Any attempt to put the same embedded record in two
different smart sections will cause a copy of the embedded record
to be put in the second smart section.
Stand alone records can be referenced by any number of smart
sections; embedded records can not be embedded in more than
one.
TIP: Use a Stand Alone business object with a dependent associa-
tion instead of an Embedded business object. IBM TRIRIGA uses
Stand Alone business objects with a dependent association in IBM
TRIRIGA’s standard applications.
Link
Link records were used to blur differences between the types of
records referenced by a smart section. When a link record was
created, it was linked to another record. A link record could be
linked to any record created from a business object in the same
module as the one the link was created from.

28 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 In the past, one of the uses of link business objects was to report
on multiple business objects. Now, Report Builder queries can
report on multiple business objects without using link business
objects. Use Report Builder queries to report on multiple business
objects.
In the past, one of the uses of link business objects was to allow
different business objects to appear in multi-record smart sec-
tions. Now, query sections provide this functionality without using
link business objects or multi-record smart sections. Use Query
sections to display information from different business objects.
Externally Managed
This is not normally selected. The Externally Managed radio but-
ton should only be selected for Fact table business objects. Exter-
nally managed business objects are described in the book
Application Building for the IBM TRIRIGA Application Platform 3:
Performance Framework.
After you have specified one of the above four options, you will be
able to create the business object by clicking the Save BO action.
What follows are brief descriptions of check boxes you can use to
specify other properties of a business object:
Has Staging Table
Identifies business objects for which the IBM TRIRIGA system
maintains staging tables. If the property is checked and the busi-
ness object is published, a staging table is either created or
updated. If the property is not checked and the business object is
published, the publish process deletes the staging table if it
exists. By default the Has Staging Table property is not checked.
A staging table is created for a business object with the Has Stag-
ing Table property checked when the business object is brought in
through object migration and object migration publishes the busi-
ness object.
IBM TRIRIGA DataConnect uses staging tables as a mechanism for
moving external data into the IBM TRIRIGA database. Read more
about DataConnect in Application Building for the IBM TRIRIGA
Application Platform 3: Data Management.
Has Calendar
This is normally unchecked. If it is checked, records created from
this business object will have a calendar associated with them.
Calendars and calendar-based events are described in Chapter 10.

© Copyright IBM Corporation 2011. Creating a Business Object | 29

 Audit Actions
This is normally unchecked. If this is checked, a record is kept of
every action as defined in the state transitions performed on
records created from this business object. The record of actions is
incorporated into an audit trail.
If you are using the Request for Information (RFI) metrics and
reports in IBM TRIRIGA’s Workplace Performance Management
products, Audit Actions must be checked.
Audit trails and other security related issues are discussed in
Chapter 13.
Audit Access
This is normally unchecked. If this is checked, a record is kept of
every time someone views a record created from this business
object.
The next three radio buttons define what auditing will be performed
for data changes made to records created from this business object.
Audit trails and other security-related issues are discussed in Chapter
13.
No Audit
No Audit is the most common choice. When selected, a record is
not kept when a value change is made to a record created from
this business object.
Audit Interactive Data
When selected, a record is kept of every value change made by a
user to a record created from this business object. The record of
changes is incorporated into an audit trail.
Audit All Data
When selected, a record is kept of every value change made to a
record created from this business object, regardless of how the
data is modified. This includes value changes made by a user, due
to a formula calculation or rollup calculation, or by a workflow.
However, this does not include value changes made if the record
is modified by an editable query. Note that selecting this option
may adversely affect the performance of the process.
Require Explanation
This is normally unchecked. If this is checked and Audit Interac-
tive Data is selected, when a user makes a change to a record, a
popup appears requiring them to enter information about why
they made the change.

30 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Show Single Tab
If this check box is checked, records created from this business
object can be used with forms that have single tab operation. If
this check box is not checked, you will not be able to use forms
that only show a single tab with records created from this busi-
ness object.
Approval History
If this check box is checked, forms that work with records cre-
ated from this business object can have a tab that shows the
approval history of the record. Approvals of records are under the
control of Approval workflow tasks, which are discussed on
page 414.
When you are finished setting the properties of a new business object,
click the Save BO action to create the business object. Creating the
business object does not make the business object available for use.
The business object will not be available for use until you publish it.*
You will not be able to publish the new business object until you have
completed two more steps:
• Specify the fields that will be in records created from the busi-
ness object. This step is described on page 36 under the heading
“Specifying Fields”.
• Specify how a unique name will be determined for records cre-
ated from the business object using values in the records’ fields.
The details of this step are specified on page 48 under the head-
ing “Determining a Unique Name for Records”.
Once you have done these things, you are ready to publish the busi-
ness object. The details of publishing a business object are discussed
on page 57.
The immediate consequences of saving the properties of a business
object for the first time are:
• The name of the module is included in the Object Browser panel.
• Some additional properties appear in the Property panel.
Since we are now working with an existing business object, the next
part of this chapter talks about editing the properties of an existing
business object. Once we have finishing discussing existing business

* The create-publish-revise cycle is described on page 9.

© Copyright IBM Corporation 2011. Creating a Business Object | 31

 objects, we will move on to the details of how to add fields to a busi-
ness object.
Copying Business
Objects Existing Business Object’s
If you create a new busi-
ness object by clicking the Properties
New Business Object
One way to be looking at the properties of an existing business object
menu item, the new busi-
ness object is created is to have just saved a new business object for the first time. Here is
with copies of the mod- the more usual procedure for working with an existing business
ule’s base business object’s properties:
object’s sections, fields,
Find the business object in the Object Browser panel.
associations, and state
transitions. Sometimes, it The Object Browser panel is organized by module. You can find
is more convenient for the the name of a business object under the module that contains the
new business object to be business object. If you do not see a list of the module’s business
copied from a different objects under the module’s name, click the closed folder ( ) icon
business object. next to the module’s name. This will cause a list of the module’s
You also can create a new business objects to appear under the module’s name and the
business object by copying closed folder ( ) icon to change to an open folder ( ) icon.
any non-base business Click the business object’s name in the Object Browser panel.
object in a module. To do This will cause the Business Object Properties to appear.
this, view the properties
of the existing business Click the word View in the menu bar.
object you want to copy. This will cause the view menu to appear.
When the business
object’s properties
appear, a Copy BO action
also appears at the top of
the Data Modeler. Clicking
the Copy BO action causes
a Name property to
appear in the Data Mod-
eler’s Property panel. Set
the value of the property
to the name you want the
new business object to
have. Finish by clicking
the Ok action at the top of
the Property panel.

32 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Click the word Diagram in the view menu.
The business object’s details are displayed in the Diagram panel.
The Data Modeler looks like Figure 2-7, except for the business
object’s name.

Figure 2-7. Business Object in Data Modeler Panel

Figure 2-7 shows the Data Modeler’s appearance after you select a
business object named triCountry. Its name appears at the top of the
Diagram panel along with the business object’s state, which is
Published.
If the business object is freshly created, its displayed state will be
Created. Otherwise, the business object’s displayed state may be
Pending Publication, Published, or Revision In Progress. A business
object’s state is explained on page 9 under the heading “Create-
Publish-Revise Cycle”.

© Copyright IBM Corporation 2011. Existing Business Object’s Properties | 33

 The Diagram panel shown in Figure 2-7 on page 33 contains a dia-
gram showing connections between the triCountry business object and
other business objects. These connections are called associations.
Associations are described on page 60.
As you can see in Figure 2-7, after selecting a business object, addi-
tional panels are visible in the Data Modeler. The Properties panel is
in the upper right corner of Figure 2-7. Its displayed title is Business
Object Properties. The other additional panel is the Field List panel.
Fields are discussed on page 36.
When you look at an existing business object’s properties, additional
properties are visible that were not visible before the business object
was created. An example is shown in Figure 2-8 on page 35.
An existing business object has a read-only property named Created
By that shows who created the business object. An existing business
object also has a read-only property named Modified By that shows
who last modified the business object.
There is one other property existing business objects have. The name
of this property is Pre-Create Workflow. If this property has a value,
it is the name of a synchronous workflow.
This property names a synchronous workflow to run when a record is
created from this business object. Such workflows are used to set the
initial contents of a record or its relationships with other records.
Synchronous workflows are discussed on page 207 under the heading
“Synchronous vs. Asynchronous Workflows”.
To specify the value of this property, click the Search icon . Click-
ing the Search icon causes a list of synchronous workflows to
appear. The synchronous workflows in the list will be workflows
launched from records created from the business object. If you select
one of the workflows in the list and click the OK action at the top of
the list, the workflow you selected becomes the value of this prop-
erty.
If you want to clear the value of this property so that it has no value,
click the icon.

Modify a Published Business Object

In the Diagram panel (shown in Figure 2-7 on page 33), when the busi-
ness object’s displayed state is Published, you cannot modify the
business object’s properties, fields or anything else about the busi-

34 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Figure 2-8. Properties of an Existing Business Object

ness object. This is explained on page 9 under the heading “Create-

Publish-Revise Cycle”.
To be able to revise a business object, you must first change its state
to Revision In Progress. To do this, first click the word Tools in the

© Copyright IBM Corporation 2011. Modify a Published Business Object | 35

 menu bar at the top of the Data Modeler. Clicking the word Tools
causes the Tools menu to appear. If the business object whose details
are shown in the Diagram panel has the displayed status Published,
the Tools menu contains an item labeled Revise BO. Clicking the
Revise BO menu item changes the displayed state of the business
object to Revision In Progress.
Once the displayed state of the business object is Revision In
Progress, you are able to make changes to the business object.

Specifying Fields
After a business object exists, you can specify a list of the fields that
records created from the business object will contain. To access a
business object’s list of fields, the business object must be visible in
the Diagram panel. The procedure for making a business object visi-
ble in the Diagram panel is described earlier in this chapter on
page 32 under the heading “Existing Business Object’s Properties”.
Look at Figure 2-7 on page 33 and you will see an example of the Data
Modeler with a business object selected and its Field List panel visi-
ble. The business object’s list of fields appears in the Field List
panel. A Field List panel looks like Figure 2-9.

Figure 2-9. Field List

The Data Modeler’s Field List panel has columns showing these prop-
erties of the fields:

36 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Field Name
The name of a field uniquely identifies it within the IBM TRIRIGA
Application Platform environment. It is the name you see for the
field within the Data Modeler, report filters, workflows, and other
places a person does not see when using an application. Naming
conventions are described on page 13.
Field Label
A field’s label is the name that appears next to it in a form or
report. A label does not have to be unique.
Field Type
Each field can hold only a specified kind of data. The kind of data
that a field can hold is determined by the value of this property.
Some of the data types are Number, Text and Date. There is a sum-
mary of all data types in Figure 3-1 on page 94.
You can use the Data Modeler’s Field List panel to add fields to a
business object, edit the properties of fields, and remove fields from
business objects.

Adding a Field to the Business Object

The procedure for adding a field varies slightly, depending on whether
the IBM TRIRIGA Application Platform already has a definition for the
field you want to add. If the field is already defined, add the field by
searching for it. If the field is not defined, add the field by defining
it.
If you are not sure whether a field with a particular name is defined
or not, you should find out by searching for the field. To search for a
field, begin by looking at the Field List of the business object to which
you want to add a field. The Field List looks like Figure 2-10.
Click the Find action at the top of the Field List. This causes a Field
Search to appear in the Data Modeler’s Property panel. A Field Search
allows you to search for existing fields and add them to the selected
business object. A Field Search is shown in Figure 2-10.
To use a Field Search, enter the search criteria for the field to be
found. The form allows you to specify these search criteria:
Module Name
If you select a value for this, you restrict the search to only fields
used by business objects that are part of the selected module.

© Copyright IBM Corporation 2011. Specifying Fields | 37

 Wildcard
Searches
The search shown in
Figure 2-10 finds every
field having a name that
begins with triActive.
Sometimes you want to Figure 2-10. Field Search
find fields that have a
name or label that con-
Business Object Name
tains a word anywhere in You can only select a value for this if you have specified a mod-
the name or label. For ule. Selecting a business object restricts the search to only fields
example, you may want to used by the selected business object.
find all field names that Name
contain the word “start”
The name of a field is the unique name you see for the field
anywhere in the name.
within the Data Modeler, report filters, work flows and other
You can do this by using a places a person does not see when using an application.
percent sign (%) in a
search string. Percent
Specifying a value for Name restricts the search to fields whose
signs in a search string are name starts with the specified wildcard pattern. See the sidebar
treated as a wildcard. The for an explanation of how to use wildcard patterns.
search string %start Label
matches ActualStartDate, This is the default label that appears next to the field in a form or
ProjectPlanStart and
report.
StartTime. You can also use
a percent sign to find a Specifying a value for Label restricts the search to fields whose
name that has a particular label starts with the specified wildcard pattern. See the sidebar
beginning and end. Enter- for an explanation of how to use wildcard patterns.
ing start%time matches
Start Time and Start Date
Type
Time. Each field can hold only a specified kind of data. The kind of data
that a field can hold is determined by its type. Some of the data
types are Number, Text and Date. There is a summary of all data
types in Figure 3-1 on page 94.
If you specify a data type other than All, only fields having the
specified type will appear in the search results.
After you have finished specifying search criteria, click the Search
action at the top of the Field Search. A list of the fields in the search

38 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

results will appear in the bottom half of the Field Search. It looks like
Figure 2-11.

Figure 2-11. Field Search Results

If the field(s) you are looking for appear in the search results, you can
add the field(s) to the business object by checking the check box to
the left of the field(s) and then clicking the Accept action at the top
of the Field Search. After you click the Accept action, the accepted
field(s) is added to the business object are is displayed in the list of
fields in the List panel.
If the label, default value, or most other things about the found
field(s) do not match the properties you want, you can change them.
The changes you make will affect only the business object’s copy of
the field. The changes will not have any affect on any other field or
business object.
There are two things about an existing field you cannot change. You
cannot change a field’s name or its type. If you find a field with the
right name but the wrong type, you must use a field with a different
name.
Many business objects have a field with the same name. Even if fields
in different business objects share the same name, most other things
about the fields are allowed to be different. However, there is one
thing that must be the same for every field with the same name:

© Copyright IBM Corporation 2011. Specifying Fields | 39

 Every field that has the same name must also have the same data
type.
If the Field Search does not find the field you are looking for, click
the Add action at the top of the List panel. The properties for a new
field appear in the Property panel of the Data Modeler. The proper-
ties for a new field are about the same as the properties for an exist-
ing field shown in Figure 2-12 on page 41, except that you can change
the values of the properties labeled Name and Field Type.
You will see some different properties for the field if you select dif-
ferent types for the new field. The properties that go with a field of a
particular type are described in Chapter 3 as part of the description
of the data type.

Editing Properties of an Existing Field

You can edit the properties of a field by clicking its name in the Field
List panel of the Data Modeler. When you click a field’s name, the
field’s properties appear in the Data Modeler’s Property panel. The
Property panel looks like Figure 2-12 on page 41.
The first property is the Section property. This is a read-only prop-
erty. Section names are used to organize the fields that can be
accessed in records created from a business object. When you are
adding a field directly to a business object, it will always be part of a
section named General. Other kinds of sections are discussed on
page 74 under the heading “Organization of a Record”.
The value of the Field Type property determines the type of data
that the field will hold. There is a summary of the possible values for
Field Type in Figure 3-1 on page 94.
Depending on the value selected for Field Type, additional proper-
ties may appear. You can find a description of the specific properties
for different data types along with their descriptions in Chapter 3.
If you are adding a new field, you can change the values of Field Type
and Name. If you are editing an existing field, these properties are
read-only and cannot be changed.
The Description and Purpose properties should contain whatever
information you think will help people understand what will be stored
in the field and what the field is for. If you are adding a new field,
you can edit the Description and Purpose properties in the normal
way. If you are editing the properties of an existing field, you can still

40 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 Figure 2-12. Form to Edit or Add a new Field
edit the Description and Purpose properties, but the procedure for
editing them is unusual.
When you are editing the properties of a field, the Description and
Purpose properties are grayed out. You cannot edit them directly.
What you can do is first click the Save Field action at the top of the
Data Modeler to ensure that any changes you have made to proper-
ties are not lost. Next, click the label of the Description property.
The label of the Description property is a hyperlink. Clicking it causes
a Field Description form to appear at the bottom of the Property
panel under the properties. The Field Description form looks like
Figure 2-13.

© Copyright IBM Corporation 2011. Specifying Fields | 41

Requiring a Field
in Just Some
Figure 2-13. Field Description
Forms
The Field Description form contains the same information as the cor-
If you want a field to be
required to have a value responding properties of the field. You can edit the values of the
in every form it appears Description and Purpose properties in this form. When you click this
in, check its Required form’s Ok action, the form disappears and the Description and
check box. Purpose properties of the field are updated.
If you want a field to be There is a reason for this unusual procedure for editing a field’s
required to have a value Description and Purpose properties. These properties are intended to
in some but not all of the explain how the field should be used in business objects. They are not
forms it appears in, do not intended to explain how the field is used in a particular business
check its Required check
box.
object. Because the information is not specific to any business object,
all fields with the same name have the same values for Description
If the Required check box and Purpose. If you change a field’s Description or Purpose, the
is checked, every form change will be visible in the properties of the field in every business
must require a value for
object that uses it.
the field. If the Required
check box is not checked, The check box labeled Required determines how this field is treated
forms may require the when it appears in a form. If the Required check box is checked, a
field to have a value or value for the field must be specified. If a value for a required field is
not.
not specified in a form, the contents of the form will not be
accepted.
There are a few circumstances in which the platform supplies the ini-
tial value for a field in a new record by copying the value of a like-
named field from an existing record. For example, if a field has no
default value and the name of the field is the same as a name of a
field in the triPeople business object, the initial value for the field
comes from the triPeople business object that describes the person who
is logged in. Other circumstances related to hierarchy modules are
described in Chapter 9.
This mechanism for automatically providing the initial value of a new
field is called auto-populate. If you want to prevent a field from being
auto-populated, check the check box labeled Do not Auto Populate.
It is a good practice to check this check box unless you specifically
want a field to be auto-populated.

42 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

The check box labeled Result Column establishes a default for
whether or not the field will be used in smart sections that refer to
this business object.* The Result Column check box also determines
whether this field will be available for constructing a dynamic list
(see page 130 for information on dynamic lists). If this check box is
checked, the default is that this field will be used in smart sections
that refer to this business object; otherwise not.
If the Result Column check box is checked, another property appears
immediately below it. This property is labeled Column Sequence. The
number in this field is used to determine the default order in which
fields appear in smart sections that refer to this business object.
The check box labeled Mobile Field is useful for mobile applications
that run with clients that have a small display, such as a phone or
PDA. The setting of this check box determines whether the field is
included in a smaller view of the records created from this business
object.
If the Mobile Field check box is checked, another property appears
immediately under it. This field is labeled Mobile Field Seq. The
number that appears in this field will determine the default order of
fields in the smaller view.
If the Staging Table Field property is checked, the field is included in
the business object’s staging table. Changes to this property after a
staging table is created are not reflected in the staging table until the
business object is republished. By default the Staging Table Field
property is not checked. The Staging Table Field property is sup-
ported in the following field types: Boolean, Business Object, Classifi-
cation, Color, Date, Date and Time, Duration, List, Locator, Number,
Password, Text, Time, UOM, Url. The Staging Table Field is checked
for all Required fields of these types. Only fields in the General sec-
tion are supported to be staging table fields. Fields in a smart section
can be added to the staging table.
The Staging Table Key property identifies fields to be used as keys to
find a record via Upsert or Update. The Insert action does not use the
Staging Table Key property. By default, the Staging Table Key prop-
erty is not checked. It can be selected only when the Staging Table
Field property is selected. The Staging Table Key property is sup-

* Smart sections of a business object are discussed on page 74 under the heading “Organi-
zation of a Record”.

© Copyright IBM Corporation 2011. Specifying Fields | 43

 ported in the following field types: Boolean, Business Object, Classifi-
cation, Color, Date, Date and Time, Duration, List, Locator, Number,
Password, Text, Time, UOM, Url.
IBM TRIRIGA DataConnect uses staging tables. Read more about Data-
Connect in Application Building for the IBM TRIRIGA Application Plat-
form 3: Data Management.
When the Do Audit property is checked, changes in value for this field
are stored in audit tables. If the business object’s Audit Interactive
Data property is selected and a field’s Do Audit property is not
checked, audit data for the field are not stored in audit tables.
Changing the Display Mask property in UOM List fields with any value
other than Currency or in Number fields changes the decimals shown to
the user but does not change the value in the database. The format-
ting in a Number field takes precedence over UOM formatting when
displaying Number fields in query reports or forms. If a value has more
digits to the right of the decimal place than shown in the Display Mask
property, the platform uses Round Half Up to round the value in the
display.

Deleting a Field
Deleting fields from a business object is usually rather straightfor-
ward. Check the check box to the left of the field’s name in the Field
List panel and then click the Delete action at the top of the Field List
panel (shown in Figure 2-9 on page 36). The platform may ask if you
are sure you wish to delete the field(s) and may respond to the
Delete action by telling you that the delete was successful.
You cannot delete fields that are part of the published name. You
have to remove that field from the BO Mapping before the system will
let you delete that field. See “Determining a Unique Name for
Records” on page 48 for information about BO Mapping.
Another possible response to the Delete action is that the field can-
not be deleted because it is in use somewhere. A field cannot be
deleted from a business object if it is referenced by a smart section.
If you do not know which business object and which smart section is
using the field, you will have to find the smart section and business
object that contains it. The IBM TRIRIGA Application Platform can
assist you in this search.
If you check the check box to the left of the field name and then click
the Field Finder menu item in the Data Modeler’s Tools menu, a win-

44 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

dow pops up that contains a list of business objects that use the field.
An example of this is shown in Figure 2-14.

Figure 2-14. Field Finder

There is another way to find where a field is used. Select the field in
the Field List. Once the field’s properties are displayed in the Field
Properties panel, click the Where Used action. A window pops up
showing what references or uses the business object / field. The dis-
play shows the following information: Name, Type, Module, Object,
Form, Action, Additional Information. An example of this is shown in
Figure 2-15.

Figure 2-15. Field Where Used

If you want to export the information in the Where Used window,

click the Export Usage action at the top of the window. You will be
offered the choice of saving or opening a csv file. For most object

© Copyright IBM Corporation 2011. Specifying Fields | 45

 types, clicking the linked object will open the builder for the refer-
ence.
The following lists the references found by Where Used:
Business Object Field
•Query (Display Columns, Order By, Group By, Sum, Filter)
•Smart Sections
•Locator
•Form
•Regular Formulas
•Extended Formulas
•Workflow Create Record Task (Map – Field, Source or Target)*
•Workflow Modify Records Task (Map – Field, Source or Target)*
•Workflow Schedule Task (Map – Field, Source or Target)*
•Workflow Conditions - Start Task, Switch Task, Break Task*
•Workflow Retrieve Records Task (Filter)*
•Workflow Create Record/Modify Records/Schedule Tasks (Map –
Field as part of Expression)*
•Workflow Populate File Task*
•Workflow Distill File Task*
Form
•Form Field Action
•Form Section Action - Popup Form, non Popup Form
•Portal Section, Record Add
•Navigation Item (Master Detail Report, Record Add, Master Detail
Default)
•Navigation Item Action
•Navigation Item Security Override
•Query
•Query Action
•Workflow Modify Metadata Task*
•Workflow Create Task*
•State Transitions (Form)
•System Add
•System Delete

46 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Query
•Form Section Find Action
•Form Field Action (onClick, onChange)
•Form Popup Section Action
•Form Query Section (Query, Availability, Gantt, Group By)
•Portal Section Query
•Scorecard
•Navigation Item (Master Detail Report, Record Open, Report,
Master Detail Hierarchy, Scorecard)
•Navigation Item Dynamic Labels
•Navigation Item Security Override
•Query Action
•Query in a Sub Report
•Query in an Associated Query (Hierarchical Query)
•Query Association Filters
•Workflow Query Task*
•Extended Formulas
Workflow
•Query Action (Pre-Create Workflow)
•Form Field Action
•Form Field Action (Pre Form and Post Form Workflows)
•Form Section Action (Pre Form and Workflow)
•Form Section (Select and Stack Pre-Move)
•Form Section (Synchronous and Stack On-Save)
•Form (Pre-Load Workflow)
•State Transition (BO Sub Action - Workflow Select)
•BO (Pre-Create Workflow)
•Smart Section (Initialize Record)
•Call Workflow*
•Portal Section, Record Add
•Navigation Item (Record Add)
•Navigation Item Action
•Navigation Item Security Override
* For workflow references, the system displays the latest workflow
version containing the reference. The workflows checked for refer-

© Copyright IBM Corporation 2011. Specifying Fields | 47

 ences are in the following statuses: Revision In Progress, Retired, Pub-
Names Limited to lished, and In Progress.
100 Characters
A text field can contain up Determining a Unique Name for Records
to 1000 characters. The
The IBM TRIRIGA Application Platform requires that for every record
name of a record can come
from multiple fields. there is a field or combination of fields whose value uniquely identi-
fies the record. This value or combination of values is called the
Even though the fields that record’s name. The Name property is used to identify the field or
contain a record’s name
combination of fields whose value(s) will uniquely identify the
may contain many more
than 100 characters, the
records. Naming conventions are described on page 13.
platform only looks at the This Name property is one of a business object’s mapping properties.
first 100 characters of a To access a business object’s mapping properties, go to the Data Mod-
record’s name.
eler’s Tools menu and click its BO Mapping menu item. Clicking the
If the first 100 characters of BO Mapping menu item causes the business object’s mapping proper-
two records created from ties to appear in the Data Modeler’s Property panel. When a business
the same business object object’s mapping properties first appear they look like Figure 2-16.
would be the same, the
platform will complain
about a duplicate name and
will not create the record.

Figure 2-16. Initial Mapping Properties

48 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

To set the Name property, click its Find link shown in Figure 2-16.
When you click the Find link, a Select Field form appears under the
mapping properties in the Property panel. The Select Field form looks
like Figure 2-17.

Figure 2-17. Select Field

You use this form to identify a field whose value will be used in the
name of a record. It allows you to identify a field by its smart section
and name.* For the purposes of this form, fields that are not actually
part of a smart section will appear to be part of a smart section
named General.
After you select a field, click the Select Field form’s Ok action. The
Select Field form disappears and the text of the Find link is replaced
with the name of the selected field. This is shown in Figure 2-18.
If a record’s entire name comes from a single field, you are finished
specifying the name. Be sure to click Save Mapping action at the top
of the Data Modeler to save your changes to the mapping properties.
In most cases, a record’s name is the value of a single field. How-
ever, the name of some kinds of records must come from more than
one field. To specify an additional field for the name, click the Add
action to the right of the Name link. Clicking this action adds a drop-
down list and a Find link to the Name property. This looks like
Figure 2-19.
You can use this Find link to specify the additional field. If you decide
it was a mistake to click the Add action, click the Delete action and
the most recently added drop-down list and link are removed.

* We have not yet discussed smart sections. A smart section is a named part of a record.
Smart sections are described in more detail on page 74 under the heading “Organization
of a Record”.

© Copyright IBM Corporation 2011. Specifying Fields | 49

 Figure 2-18. Mapping Properties with One Name Field

50 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 Figure 2-19. Name Setting With Second Field

If a name of records created from a business object comes from val-

ues of more than one field, the values in the name are separated by a
character selected in the drop-down list. The drop-down list between
each of the field links allows you to choose from these characters, as
shown in Figure 2-20:

Figure 2-20. Name Separators

© Copyright IBM Corporation 2011. Specifying Fields | 51

 When a person is using a form to edit a record, the record’s name
appears on the top of the form. If the record’s name comes from mul-
tiple fields, the selected punctuation appears as part of the name.
Let’s look at an example. Figure 2-21 shows the mapping properties
for the triPeople business object in the triPeople module.

Figure 2-21. Mapping Properties for the triPeople Business Object

The meaning of the Name property value shown in Figure 2-21 is that
the name of triPeople records will consist of the value of the Last Name
field followed by a comma, followed by the value of the First Name
field followed by a hyphen, followed by the value of the ID field.

52 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Looking at Figure 2-22, you can see the values of these fields and the
name formed from them at the top of the form.

Figure 2-22. Example of Employee record

At this point, you have completed all the steps that are required to
prepare a business object for being published. Before we discuss pub-
lication of business objects, there are some other topics we will dis-
cuss because, like a record’s name, they are related to a business
object’s mapping properties. If you prefer to skip over these topics
and read about how to publish a business object, skip to page 57.

Control Number Generation

Control Numberis a data type for fields that is described on page 113.
The value of a Control Number field can be the next number in an auto-
matically generated sequence of numbers. A business object can con-
tain at most one Control Number field.
The system generates a record’s control number when the record
transitions from the null state to any other state.
The sequence of numbers generated in a business object’s Control
Number field is controlled by some of the business object’s mapping

© Copyright IBM Corporation 2011. Specifying Fields | 53

 properties. You can see these on the bottom portion of Figure 2-21 on
page 52 located to the right of and below the words Control Number.
The main part of a control number is a sequence number. If a Control
Number field’s Generate on Create check box is checked, then each
time a new record is created from the business object, a sequence
number one greater than previous number is used to form the control
number. The number that is the value of the business object’s map-
ping property labelled Start With will be used as the next sequence
number.
It is common for a control number to have more parts than just its
sequence number. The control number may have a prefix or suffix
that is a fixed piece of text or the value of one of the record’s fields.
A control number may have any number or prefixes or suffixes.
To add a prefix or suffix to a control number, click the Find link to
the right of the Prefix or Suffix label. You can see these in
Figure 2-21 on page 52. When you click one of these Find links, a Type
Field form appears under the mapping properties in the Data Mod-
eler’s Property panel. This Type Field form has more options on it
than the Type Field form used for a business object’s name.
The Type Field Form initially looks like Figure 2-23. While the
Attribute Type radio button is selected, we can specify that the value
of the control number prefix/suffix will come from the field specified
by the selected Section Name and Field Name values.

Figure 2-23. Selecting a Field For a Control Number Prefix/Suffix

If we want the prefix or suffix to be a fixed piece of text, rather than

the value of a field, we can select the Constant Value radio button.
When we select the Constant Value radio button, the Type Field form
looks like Figure 2-24. Whatever text we supply for its Constant Text
field will be the contents of the prefix or suffix being specified.
In order to make sense of a control number that has prefixes or suf-
fixes, there must be a way to tell where each part of the control num-

54 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 Figure 2-24. Fixed Text for a Control Number Suffix or Prefix

ber begins and ends. This is done by specifying that a particular

character will be used as punctuation between each part of the con-
trol number. The character chosen for this purpose is called the
delimiter. For example, a control number that has been specified to
have a hyphen as its delimiter might look like 3243-56-R.
To specify which character will be used as the delimiter, we would
select a character for the value named Delimter. The possible choices
for delimiter character are:
space
- hyphen
. period
, comma
One last setting that is sometimes of use is the check box labeled
Based on Prefix. When this check box is not checked, the sequence
number part of a new record’s control number is always one greater
than the sequence number for the previous record created from the
same business object. When the Based on Prefix check box is
checked, the sequence number for a new record is one greater than
the sequence number for the previous record that had the same
prefix.
For example, suppose that you want line items in a purchase order to
have a control number that is prefixed by the purchase order’s con-
trol number. The line item numbers in a purchase order with control
number 3452 might look like 3452.1, 3452.2, 3452.3, … The difficulty
is that the line items for a purchase order may not be created at the
same time.
It may happen that the first few line items for a purchase order are
created, then another purchase order is created with its own line
items, and then more line items are added to the first purchase
order. The line item numbers for the first purchase order are still
expected to look like 3452.1, 3452.2, 3452.3, …

© Copyright IBM Corporation 2011. Specifying Fields | 55

 To arrange for this to happen, you would first make sure that the
business object for purchase order line items has a smart section that
contains the purchase order’s control number. We could then specify
the purchase order’s control number as the prefix for the line item’s
control number. By checking the Based on Prefix check box, we
would cause the sequence number portion of the line item’s control
numbers to start from the first value for each purchase order and con-
tinue in sequence.

Other Mapping Properties

Two other mapping properties are labeled Cost and Quantity. These
properties help control the way totals are rolled up through records
organized in a hierarchy. These properties and the rolling up of totals
in a hierarchy are described in Chapter 9.
The Image property is used when defining the default fields displayed
in a link.
The Conversion Group and Exchange Date properties are used to
help convert between different currencies. These properties and cur-
rency conversion are described on page 178 under the heading
“Money”.
For any of the above properties the drop-down list next to the prop-
erty allows you to select the field whose value will be used for the
purposes described above. Notice that the Cost and Quantity proper-
ties only allow selection of Number fields; the Image property only
allows selection of Image fields; the Conversion Group property, List
fields; and the Exchange Date property, Date or Date/Time fields.

Automatically Added Fields

There are three fields that the Data Modeler adds to every business
object. You cannot see these three fields within the Data Modeler,
but they are visible from other platform tools that work with a busi-
ness object’s fields.
The three fields are classification fields that can be used to associate
every record with a geography, a location and an organization. The
Business Object data type is discussed on page 98.
The names of the fields are
• GeographyName
• LocationName

56 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 • OrgName

In addition to the many uses these three fields have in business appli-
cations, the platform has a security-related use for the GeographyName
and OrgName fields. These security-related uses are described on
page 674 under the heading “Organization and Geography”.
Two things must be done to take advantage of these fields:
• Geographies, locations and organizations must be entered into the
platform. Entering information about geographies, locations and
organizations is usually done by the people who use or administer
the application because they know the context in which the appli-
cation will be used.
Avoid Breaking
• The other thing that must be done to take advantage of the three Applications
fields is to have a way to set the value of each of the fields. Adding fields or sections to
an existing business object
The simplest way to set the value of the fields is to take advantage of
is usually a safe thing to do.
the IBM TRIRIGA Application Platform’s auto-populate feature, which Except for some unusual sit-
will copy the initial values for these fields from the triPeople or other uations involving hierarchies
record that describes the person who initiated the creation of the and the auto-populate fea-
record. The relevant portions of these records are described on ture, adding fields to a busi-
page 656 under the heading “Authentication”. ness object will not break an
application.
If the auto-populate feature is not sufficient to initialize the three
fields to whatever values are needed, you will need to provide work- Deleting fields or sections
flows to initialize the fields. from a business object can
be dangerous. If a workflow
or anything else uses a field
Publishing Business Objects you have deleted, it will
break. Only if you are cer-
A new business object is not available for use until you publish it. tain that a field is not being
Once you have done all the previously described things to a new busi- used should you feel free to
delete the field.
ness object and added a state transition diagram, you are ready to
publish it. Read about state transition diagrams in Chapter 4. If you are not certain that a
field is not being used by
If you have placed a published business object under revision, none of something, do not delete
the changes you make to the business object affect any records until the field from the business
you publish the business object again. object. Instead, leave the
field in the business object
When you publish a business object, if any records were previously
but remove the field from
created from the business object, they will be made to conform to all forms and reports that
the new definition of the business object. If you added fields to the use the field. This way, peo-
business object, publication will add the fields to all records created ple will not see that the
from the business object. If you deleted fields from the business field is still there, but work-
object, publication will delete the fields from all records created flows that expect it to be
from the business object. there will still see it.

© Copyright IBM Corporation 2011. Publishing Business Objects | 57

 Publishing a business object makes the changes made to the business
object available for the creation of new records. Records cannot be
created from a business object until the first time the business object
is published. Once the business object is published, it becomes possi-
ble to create records from the business object.
Clicking the Publish Business Object action for a business object with
the Has Staging Table property on triggers the following activities:
• If there are any jobs in Processing or Ready state that use the
staging table and business object, the publish fails and a message
is posted to the user immediately.
• Because Publish is handled by an agent and is not an immediate
action, the Publish agent checks the job state again in case a new
job has started or the state of an existing job has changed in the
interim. If there are any jobs in Processing or Ready state that use
the staging table and business object, the publish fails, a notifica-
tion is posted to the user, and details about why the publish failed
are written to the server.log.
See page 29 for more information about the Has Staging Table field
and the DataConnect chapter in Application Building for the IBM
TRIRIGA Application Platform 3: Data Management for more informa-
tion about publishing business objects with the Has Staging Table field
selected.
It is always best to publish business objects on a quiet system. This is
because runtime components using the business object during the
publish process could experience unpredictable behavior since there
are points in time where the database definition and the business
object metadata are not in sync.
After you publish a business object, you can make changes to the
business object without being concerned that a partially completed
set of changes will be reflected in a newly created record. The
changes you make to a business object are not reflected in new
records until after you publish the business object again.
These are the steps for publishing a business object:
• First, make sure that the details of the business object are visible
in the Data Modeler.
• Click the word Tools in the menu bar. The Tools menu will
appear.
• Click the Publish BO menu item in the Tools menu.

58 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

While a business object’s mapping properties are visible, if the busi-
ness object is under revision, a Publish action will be at the top of
the Data Modeler. Clicking this action is another way to publish a busi-
ness object.
The publication of the business object does not happen immediately.
Publication of business objects happens in the background.
There are two simple ways to check whether publication of a busi-
ness object has finished:
• Clicking the word View in the menu bar. The View menu appears.
Click the Diagram menu item in the View bar. The business
object’s details appear in the Diagram panel. If the state of the
business object is Pending Publication, the publication is still
underway. If the state of the business object is Published, the
publication has finished.
• When the publication business object has finished being pub-
lished, a notification is placed in the notification section of your
portal. When you see the notification, you know that publication
is finished.
The subject of the notification will be one of the following,
depending on the outcome of the publish:
• Publication of [BO Name] completed successfully
• Publication of [BO Name] completed with warning(s).
• Publication of [BO Name] completed with error(s).
• Publication of [BO Name] completed with warning(s) and
error(s).
In the event that the notification subject reported warnings and/
or errors, the body of the notification contains more detail about
those warnings and/or errors. The Message ID at the end of each
message corresponds to a detailed stack trace in the server.log.
More information about the server.log can be found in IBM
TRIRIGA Application Platform 3 Administrator Console User Guide.
When an existing business object is republished, the system drops
database columns that are no longer used.

Deleting Business Objects

Deleting a Business Object with the Has Staging Table property on
(checked) triggers the following activities:

© Copyright IBM Corporation 2011. Deleting Business Objects | 59

 • If there is a job in Processing state that uses the staging table and
Business Object, the delete fails and a message is posted to the
user immediately.
• If there is a job in Waiting state, the Business Object and staging
table are deleted and the state of the job is changed to Obsolete.
These are the steps to delete a business object:
• First, make sure that the details of the business object are visible
in the Data Modeler.
• Click the Delete BO menu item in the Tools menu.

Associations
Most records are of limited use all by themselves. Only when they are
associated with other records is their full usefulness realized. For
example, by itself, a record that describes a training course has some
usefulness. Associating it with other records that represent such
things as course materials needed for the course, scheduled sections
of the course, and prerequisites for the course makes the record that
describes the training course much more useful.
In the next part of this chapter we explain how to define the ways
that records can be associated with each other. In the following para-
graphs, we explain the IBM TRIRIGA Application Platform’s concept of
associations.
An association is a connection between records. An association
between two records allows the IBM TRIRIGA Application Platform to
navigate from one of the records to the other.
Each end of an association has a name. This is illustrated in
Figure 2-25.

Has Belongs To
Course Course Section

Figure 2-25. Association

Figure 2-25 shows an association between records that represent a

training course and records that represent scheduled sections of a
training course. Each end of the association has an name that we use
to identify the association from that end. Looking at the association in
Figure 2-25 from one direction, we might say, “Course has Course Sec-

60 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

tion.” Looking at the association from the other direction we might
say, “Course Section belongs to Course.”
There can be any number of records on each end of an association.
There are a number of ways that an association can be created
between two records. Here a few of the ways:
• A person can use the Association tab of a form to explicitly associ-
ate two records.
• A person can put a record in a smart section of another record.
This implicitly creates an association between the records. smart
sections are described on page 74.
• A person can put a record in a locator field, business object field,
or classification field of another record. This implicitly creates an
association between the records. Locator fields are described on
page 151. Business object fields are described on page 98. Classi-
fication fields are described on page 100.
• A workflow is a sequence of automated tasks for the platform to
perform automatically. A workflow can create an association
between records. Workflows are discussed in Chapter 5.
A person cannot explicitly create an association between records until
it is defined in the IBM TRIRIGA Application Platform environment. In
the next part of this chapter, we explain how to define an associa-
tion.

Defining Associations
The platform allows the creation of an association between records
only if there is an association definition that allows it.* Association
definitions are connected to two business objects. Association defini-

* There are some exceptions to this rule. For example, Associate Record tasks in workflows
described on page 464; temporary associations for the section actions of forms described
on page 340; field and button actions described on page 363; and Data Integrator for sin-
gle-direction record-level associations described in the “Data Integrator” chapter of
Application Building for the IBM TRIRIGA Application Platform 3: Data Management.
Unless the association only is used temporarily for custom logic, it is best practice to
explicitly define the association.

© Copyright IBM Corporation 2011. Defining Associations | 61

 tions also have an association name connected with each end of the
association definition. These are often referred to as the forward
association and reverse association strings.
If you create an association definition named Belongs To from the Course
Section business object to the Course business object and an association
named Has in the other direction, you will then be able to create cor-
responding associations between Course Section records and Course
records.
There are two steps to creating an association definition:
• The first step is to ensure that the list of association types
includes the names you need for the association.
• The second step is to tell the platform to create the association
definitions.
To ensure that the names needed to describe the associations are in
the list of association types, navigate to the List Manager by clicking
Tools > Administration > Lists. The List Manager is shown in
Figure 2-26.
To see the list of association types in the List Manager, make sure
that Manage By is set to Name and then select the radio button next to
Association Types. The Association Types list is large, so you may notice a
delay while it loads. You should see a list similar to the one shown
Figure 2-26 in the right side of the List Manager.
Once you are looking at the list of association types, the first thing to
do is see if there already are names in the list suitable for describing
the associations. Some of the more common association types, such as
Has, Belongs To, Uses, and Is Used By are already in the list. If you want to
use names that are not already in the list to describe associations,
you can handle such names in one of two ways:
• If a name with a similar meaning is already in the list, you may
choose to use it. Using a name that is already in the list may
result in more consistent names for associations.
• You can add names to the list. The details of how to add new
names to a list are explained as part of the description of lists
that starts on page 127 under the heading “Modifying Lists”.
Once all the names you want to use for describing associations are in
the list, you are ready to define the associations.
You can define an association with either of the following tools:
• Data Modeler

62 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Figure 2-26. List Manager

• Association Manager
With either tool, you define the association in the Associate Business
Object panel. Regardless of which tool you use to access the Associ-
ate Business Object panel, the data to be entered is the same. We
will describe this panel first, then how to access it from the Data
Modeler (page 67) and the Association Manager (page 71).

© Copyright IBM Corporation 2011. Defining Associations | 63

 Associate Business Object Panel
The Associate Business Object panel defines an association between
two business objects. The properties for the new association are
shown in Figure 2-27.

Figure 2-27. Associate Business Object

The details of the association are defined by specifying its properties.

• For the Module property, select the module in the drop-down list
that contains the business object that will be at one end of the
association definition. This defaults to the module that contains
the selected business object.
• For the Business Object property, select the business object in
the module named by the Module property that will be at one end
of the association. This defaults to the selected business object.
• For the Association property, select the name that will be on the
same side of the association definition as the business object
named by the Business Object property.
• For the Associate Module property, select the module that con-
tains the business object that will be on the other end of the asso-
ciation definition.
• For the Associate Business Object property, select the business
object in the module named by the Association Module property
that will be on the other end of the association definition.

64 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 • For the Reverse Association property, select the name that will
be on the other side of the association definition. Workflow to
• If the Dependent Flag property is checked, it means that the Handle Deletion
existence of records on the other end of the association depends Due to
on the existence of the record on this side of the association. This
is a one-way, asymmetric relationship. Dependency
If you need a workflow run
when a record is deleted
due to the deletion of a
record on the other end of a
Attention: Do not check the Dependent Flag check box unless dependent association,
you thoroughly understand the following explanation. arrange for the workflow to
Otherwise, you may find many records being deleted be launched by a De-
that should not be. Associate system event.

Suppose that the Dependent Flag property for an association defi- There is an overview of
nition is checked and that the association definition has been used workflows in Chapter 5.
to associate a record created from the business object specified De-Associate system events
by the Business Object to other records. If the record is deleted, are discussed on page 212.
the dependent records it is associated with are also deleted.
Similarly, if the record is copied, then the copy of the record
becomes associated with copies of the dependent records, if the
association or corresponding record is identified to be copied.
If records on the other side of the association are deleted or cop-
ied, it has no effect on the record on this side of the association.
For example, you may have Line Items which are dependent on a
Purchase Order. You would create an association definition named
Has from the Purchase Order business object to the Line Item business
object and named Belongs To in the other direction. This associa-
tion would have the Dependent Flag checked. If you defined the
reverse association named Belongs To from the Line Item business
object to the Purchase Order business object and named Has in the
other direction. This association would NOT have the Dependent
Flag checked. With this set up, the line items are dependent on
the purchase order, but the purchase order is NOT dependent on
the line items.
• The Project Containment Disabled check box is visible only when
the Dependent Flag check box is selected. When checked, the
Project Containment Disabled check box disables forcing a child
record into the same project as its parent. The RECORD_PROJECT_
CONTAINMENT property in TRIRIGAWEB.properties controls whether or not
child records are forced into the same project as their parent

© Copyright IBM Corporation 2011. Defining Associations | 65

 record. See the IBM TRIRIGA Application Platform 3 Installation
and Implementation Guide for details about the TRIRIGAWEB.proper-
ties file and the RECORD_PROJECT_CONTAINMENT property. When the
Project Containment Disabled flag is off (the default), child
records will be forced to the project of their parent record.
There are a couple of scenarios where the association definition
may not cover a child. They are as follows:
• The RECORD_PROJECT_CONTAINMENT property is set to Y. A depen-
dent section exists and the association definition backing the
dependent section is not a dependent association. When a
row is added to the dependent section, the child record is
forced into the same project as the parent record. If this is
not the desired behavior, change the association definition to
be dependent and use the Project Containment Disabled flag
to control the behavior.
• The RECORD_PROJECT_CONTAINMENT property is set to Y. The user
or a workflow makes one record a hierarchical child of
another, creating an Is Parent Of association between the two
records. The parent record is not the root of the hierarchy.
When an Is Parent Of association is made, the child record will
be forced into the same project as the parent record. If this
is not the desired behavior, change the association definition
to be dependent and use the Project Containment Disabled
flag to control the behavior.
• The Cascade Read-Only check box is visible only when the Depen-
dent Flag is selected. When checked, the Cascade Read-Only
check box propagates the read-only state of a parent record to
any dependent child records. This creates a dynamic read-only
condition for the dependent child records. The actual state of the
child records does not change.
This cascades read-only to the child regardless of the reason that
the parent is read-only. If the parent is read-only due to security,
record state, or any other reason, the read-only cascades to the
child.
When a record is not already read-only, the platform looks for a
dependent association with the Cascade Read-Only property
selected. If the platform finds more than one direct parent on
which the current record is dependent, it puts a warning in the
log noting that this scenario is not supported and does not cas-
cade any read-only state. If the platform finds exactly one record,
it looks at the record at the other end of the association to see if

66 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 it is read-only. If no records are found or the parent is not read-
only, the platform continues to look recursively for a parent with
the Cascade Read-Only property checked; this continues for a
maximum of five levels deep.
This feature only considers dependent associations. It does not
consider any other way that a child record may be dependent on a
parent record.
The Cascade Read-Only property is disabled by default.

Add Associations from the Data Modeler

You can use the Data Modeler to define associations between busi-
ness objects. Before you define an association, you may want to see if
it is already defined.
After you select a business object in the Data Modeler’s Object
Browser panel, click the word View in the menu bar. The view menu
appears. Click the Diagram menu item in the view menu. The busi-
ness object’s details display in the Diagram panel. Among the details
shown are all defined associations connected to the selected business
object.

© Copyright IBM Corporation 2011. Defining Associations | 67

 When you first select a business object, the display of its details in
the Diagram panel looks like Figure 2-28.

Figure 2-28. Data Modeler Diagram

A simple box with the name of the selected business object appears
at the center of the diagram. For each association that is defined
between the selected business object and other business objects,
there is a line and a box.
Each of the other boxes in the diagram corresponds to an association.
The name of the other business object connected to the association
definition appears in the middle of the box. The association name on
the side of the selected business object appears on the top of the
box. The name on the other side association appears on the bottom of
the box.
The middle part of boxes that correspond to an association are either
dark blue or light blue. A dark blue middle means that there is a
smart section based on the association. A light blue middle means the

68 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

association is a simple association with no corresponding smart sec-
tion.
If you want to change the selected business object to a business
object named in the middle of one of the boxes, just click the name
of the business object in the diagram.
You can get more information about the association definitions con-
nected to a business object by looking at the Data Modeler’s
Association List panel. The Association List panel does not automati-
cally appear. To see it, click the Association List menu item in the
View menu. The Association List panel looks like Figure 2-29.

Figure 2-29. Association List Panel

All association definitions shown in the Association List panel have the
selected business object, in this case Employee, on one end of the asso-
ciation. The information displayed for each association definition is:
• The name of the module that contains the other business object.
• The name of the association on the side of the selected business
object.
• The name of the other business object.

© Copyright IBM Corporation 2011. Defining Associations | 69

 The first definition in the list defines an association named Has that is
Hiding Non- also connected to the Document business object in the Document mod-
Structural ule. The second definition in the list defines an association named
Associated To that is also connected to the Group Details business object in
Associations the System module.
If the size of the Association
List panel is so large as to be The Association List panel initially displays all association definitions
inconvenient, you may want connected to the selected business object. This list is divided into two
it to not display the non- parts by a section bar labeled Other Associated Objects. The associa-
structural associations. tions that appear above the bar are those being used to support a
There is an arrowhead on
structural feature of the data model. Association definitions not being
the right side of the Other used to support a structural feature appear below the bar.
Associated Objects section If you did not find the association you were looking for in the Diagram
bar. When the entire list is
panel or the Association List panel, you need to define the associa-
visible in the Association
List panel, the arrowhead
tion.
points up. If you click it To add an association, select the New Association menu item in the
while it is pointing up, the Data Modeler’s New menu. This causes the Association Properties
association definitions in
panel for a new association to appear. Also, a Save Association action
the Other Associated
Objects section become hid-
appears at the top of the Data Modeler.
den and the arrowhead See the description in “Associate Business Object Panel” on page 64
points down. for detailed information about entering the properties defining an
If you click the arrowhead association.
again, the associations in After you have finished specifying the properties of a new association
the Other Associated
definition, create the association definition by clicking the Save
Objects section are visible
again and the arrowhead Association action at the top of the Data Modeler.
points up. As you create association definitions, they appear in the Diagram
panel and also in the Association List panel in the Other Associated
Objects section.
To edit the properties of an existing association definition, click its
name at the top of one of the boxes in the Diagram panel or on the
association definition in the Association List panel. This causes the
association’s properties to appear and the Save Association action to
appear at the top of the Data Modeler.
When you are finished editing the association’s properties, be sure to
click the Save Association action to save the edits.

70 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Add Associations from the Association
Manager
The Association Manager defines associations and enforces the rela-
tionships between the existing business objects in the system. The
association created is bi-directional, as the association refers to the
section of the selected business object. For example, assume that a
relationship must be described from business object A’s perspective
(where the association is created for that particular business object)
and business object B’s perspective (where the section of that partic-
ular association is related). In such a case, the reverse relationship
from business object B’s perspective also must be defined.
Occasionally a business object may need to have more than one kind
of relationship with another business object. For example, an
Employee (person) may belong to two office locations. One office is
used full time (primary), while the other office is a remote location
(shared) and is used infrequently.
The list of association types is maintained in the Association Type list
through the List Manager. The Association Type list is a system list.
You can add values to the list as required to describe the relationship
between business objects.
To access the Association Manager, navigate to Tools > Builder Tools >
Association Manager. The Association Manager panel appears, as
shown in Figure 2-30 on page 72.
You will see the list of existing modules in the Module panel on the
left.
When you click the radio button to the left of any module, all associa-
tions for that module display in the Associate Business Object List
panel on the right.
The IBM TRIRIGA applications are delivered with a set of pre-defined
associations. When you require a new association, you can create the
association using the Association Manager.

© Copyright IBM Corporation 2011. Defining Associations | 71

 Figure 2-30. Association Manager

Attention: Modifying or deleting an association that is used in

conjunction with other data or processes can produce
unwanted or unexpected results.
To add an association, from the Association Manager shown in
Figure 2-30 on page 72, scroll the Module panel on the left until you
find the module to which the association is to be added. Click the
radio button to the left of the module name and click the Add action
on the Associate Business Object List section bar.
The Associate Business Object panel appears. This panel and its fields
are described in “Associate Business Object Panel” on page 64.

Associations with a Base Business Object

If the business objects specified by an association definition are not
base business objects*, the association definition allows associations

* A base business object is the first business object created in a module. It should have the
same name as the module it is part of.

72 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

to be created only between records created from the specified busi-
ness objects.
If one side of an association definition specifies a base business
object, the association definition will allow records created from any
business object in the specified module to be associated.

© Copyright IBM Corporation 2011. Defining Associations | 73

 Organization of a Record
The fields of a record are organized into sections. Fields that are
directly contained by a record are always in a section named General.
Every record and business object contains exactly one section named
General.

In addition to containing a General section, records also can contain

smart sections. Each smart section in a record has a name. A smart
section can reference fields in one or multiple records, depending on
the smart section’s properties.
A smart section contains fields. A smart section contains a set of
fields for each record it references. Each field in a smart section cor-
responds to a field in a referenced record. The fields in a smart sec-
tion contain either a reference or a copy of the value in the
corresponding field of the referenced record depending on the smart
section properties.
Each smart section in a record is based on an association between the
record that contains the smart section and another record. If a smart
section references a record, these two statements will always be
true:
• The record that contains the smart section has an association with
the record that the smart section references.
• Something was done, either by a user or a workflow, to cause the
smart section to refer to the record. If the record that contains
the smart section does not already have an association with a
record that is added to a smart section, the association is created
automatically.
There are two fundamental varieties of smart sections:
• A single-record smart section can reference one record or none.
The presentation of fields in a single-record smart section is usu-
ally very form-like, with a label next to each field and fields
arranged in different rows and columns.
If you add a record to a single-record smart section that already
references a record, the new record replaces the old one.
• A multiple-record smart section in a record can reference any
number of records. The fields in a multiple-record smart section
are usually presented in a table-like way, with the fields arranged
in columns and the fields for each record in a different row. A

74 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 smart section also can be organized vertically, with the fields in
rows and the records in columns
When you add a record to a multiple-record smart section, the
smart section simply references one more record than it did
before.
IBM TRIRIGA has replaced most pre-configured multiple-record
smart sections with Query sections (described in “Query Sec-
tions” starting on page 277), which are more flexible and power-
ful. Before you use a multi-record smart section, review “Pros and
Cons of Using Smart Sections” on page 86.
A business object contains descriptions of the smart sections that will
be in records created from the business object.
The Data Modeler treats both kinds of smart sections the same way.
You tell the Data Modeler which kind you want by specifying a value
for one of the smart section’s properties.
To create either kind of smart section, first click the association that
the smart section will be based on in the Diagram panel or the
Association List panel. If the association does not exist, follow the
procedure described on page 61 to define the association.
When you are looking at the association’s properties, you will see an
action at the top of the association properties labeled Create
Section. Click this action to create a smart section based on the asso-
ciation.*
When you click the Create Section action, properties of the new
smart section appear in the Data Modeler’s Property panel. The exact
set of properties that a smart section has depends on whether the
smart section will contain stand alone, embedded, or link records.
The properties that are displayed if the smart section will contain
stand alone or link records are shown in Figure 2-31.
Begin by specifying the value of the Section Name property. This is a
name used internally to identify the section. The name must be
unique within the business object.
The next thing to specify is the value of the Section Label property.
This is the default text for a user interface to display to identify the

* If the Create Section action is grayed out, it is usually because the association has not
been created yet. Click the Save Association action at the top of the Data Modeler to
solve this problem.

© Copyright IBM Corporation 2011. Organization of a Record | 75

 Temporary
Associations
Temporary associations dif-
fer from permanent associa-
tions in a few ways:
• Temporary associations
are temporary. They are
created for the benefit
of a workflow. After the
workflow is finished, the
association is removed.
Figure 2-31. Stand Alone Smart Section Properties
• Temporary associations
are identified solely by smart section. It is usually displayed in a bar above the section. It
their name, not by the
does not need to be unique.
type of record on the
other end. The value of the Associated Business Object should already have the
• Temporary associations correct value, which is the association that the smart section will be
are implicitly created by based on.
the platform in response
to certain situations. The value of the Temporary Association property is used by the
They cannot be explic- workflow named by the Workflow to Initialize Record property. If
itly created by a person you are not going to set a value for the Workflow to Initialize Record
or workflow. property, you do not need to set a value for the Temporary
• No association definition Association property.
is required for a tempo-
rary association. The value of the Temporary Association property is the name of an
association the workflow can use to navigate from a record that con-
tains the smart section to the record that was just added to the smart

76 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

section. See the sidebar for more information about temporary associ-
ations.
The next thing to specify about a smart section is whether it will be a
single-record smart section or a multiple-record smart section. If you
select the Associate One Record radio button, the smart section will
be a single-record smart section that can reference either zero or one
records. If you select the Associate Multiple Record radio button, the
smart section will be a multiple-record smart section that can refer-
ence any number of records.
If you selected the Associate One Record radio button, you will not
be able to specify the Vertical Section property. The check box for
the Vertical Section property will be grayed out and forced to the
unchecked state.
If you selected the Associate Multiple Record radio button, you will Dependent
be able to specify the Vertical Section property. A user interface usu- Sections
ally presents a multiple-record smart section with each row of the Smart sections with the
presentation corresponding to a different record and each column to Dependent flag checked are
a different field. If you check the Vertical Section check box, you are known as dependent sec-
requesting the user interface to switch the usual presentation around, tions and can be affected by
so that each column of the presentation corresponds to a different project security.
record and each row to a different field.
The next property you can specify is the Dependent property.

Attention: Do not check the Dependent check box unless you

thoroughly understand the following explanation. Oth-
erwise, you may find many records being deleted that
should not be.
If the Dependent check box is checked, the continued existence of a
record referenced by the smart section depends on its continuing to
be referenced by the smart section. If a record is removed from a
smart section that has the Dependent check box checked, the record
is deleted. Notice that if you have checked the dependency flag for
the association, the Dependent check box is checked and cannot be
changed.
The next property for you to specify determines if values in the smart
section’s fields may be modified by a user. If you select the

© Copyright IBM Corporation 2011. Organization of a Record | 77

 Reference Only radio button, values in the fields of the smart sec-
tion may not be modified by a user.
If you select the Reference With Modify radio button, the smart sec-
tion’s fields may be modified. The values of fields in the underlying
record are used to initialize the values of the smart section’s fields.
After a record becomes referenced by a smart section that has its
Reference With Modify radio button selected, there is no further
connection between their values. Changes to the smart section’s
fields do not affect the underlying record’s fields and changes to the
underlying record’s fields do not affect the smart section’s fields.
The Live Link check box is visible only if the Reference Only radio
button is selected. If the Live Link check box is checked, the corre-
sponding fields in the underlying record are always a directly refer-
enced to the associated record in the smart section. If the Live Link
check box is not checked, modified values for corresponding fields in
the underlying record are copied into to corresponding fields in the
smart section and changes to values of the underlying associated
Stub the Workflow record have no effect on the values in the smart section’s fields.
The Data Modeler allows you
If you want a workflow to run when a record is added to the smart
to associate an existing
workflow with a section of a section, set the value of the Workflow to Initialize Record property
record. You cannot use the to the name of the synchronous workflow that is to run when a record
Data Modeler to create a is added to the smart section. Synchronous workflows are discussed
workflow. starting on page 207.
You must use the Workflow When you add a record to a smart section, there may be some special
Builder to create a workflow. initialization you want done. For example, you may want to set some
You cannot put tasks in a
fields in the newly added record based on the fields in the same
workflow that refer to a sec-
tion until the section is record that contains the smart section.
defined. The workflow you specify in the Workflow to Initialize Record prop-
To define a section with an erty can be responsible for any initialization or bookkeeping that is
associated workflow, first needed when a record is added to the smart section. The workflow is
just create the workflow launched from the record that contains the smart section. It is able to
without any tasks. Next, cre- navigate from the record that contains the smart section to the newly
ate the section in the busi-
ness object, specifying the
added record by traversing a temporary association with the name
name of the workflow. After you specified as the value of the Temporary Association property.
the section is created, fill in To specify a workflow, click the icon. Clicking the icon causes a
the workflow’s tasks.
list of synchronous workflows associated with the selected business
object to appear under the smart section’s properties. You can then
select from the list the workflow that you want to associate with the
smart section.

78 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

If a workflow is already associated with a smart section and you want
to clear the value of the Workflow to Initialize Record property so
that no workflow is associated with the smart section, click the
icon.
The Used by DataConnect property indicates that this smart section
can receive values from DataConnect. Select the Values Required
property to indicate values brought in from DataConnect are required.
Values Required does not affect the smart section unless Used by
DataConnect is checked and the DataConnect action is either Insert or
Upsert/Insert. Read more about DataConnect in Application Building
for the IBM TRIRIGA Application Platform 3: Data Management.
After you finish specifying values for the smart section’s properties,
you are ready to specify which fields of the underlying records will be
part of the smart section. You can see the fields available for use in
the smart section by clicking the down-pointing arrowhead on the
Field List section bar under the smart section’s properties.

© Copyright IBM Corporation 2011. Organization of a Record | 79

 After you click the down-pointing arrowhead, it becomes an up-point-
ing arrowhead and the list of available fields becomes visible. An
example of what this looks like is in Figure 2-32.

Figure 2-32. Stand Alone Smart Section with Field List Showing

The Field List displays the fields in the business object that will be
used to create the records that the smart section will contain. There
are four columns in the Field List:
• Select

80 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 Checking a check box in the Select column means that the field will
be in the smart section.
• Sum Computing Sums
Number fields have a check box in the Sum column of the Field
You can arrange for
List. Use this check box to indicate that you want a sum com- records to have a field
puted for the field. This is discussed in more detail in the sidebar. that contains the sum of a
• DataConnect Key field used in a records sec-
tion.
The Field List contains the DataConnect Key column when the Used
by DataConnect property is selected. Only data types that do not Under the section’s prop-
require a lookup to find their value can be DataConnect keys. erties there is a Field List.
DataConnect keys can be Number, Text, or Control Number data There is an example of a
types. Field List in Figure 2-32.
The Field List allows you
DataConnect keys do not need to be in the smart section; they to specify which fields will
can be in the referenced business object. Selecting the check box be in the section by
in the DataConnect Key column identifies a field as a DataCon- checking a check box in
nect lookup key. Once published, the staging table will have fields the Select column.
for these columns. DataConnect will use the values from these For Number fields, you also
staging table fields to look up entries to add to the smart section. can specify that the busi-
This allows DataConnect to populate the smart section from ness object should have a
inbound data. field that contains the
sum of the values of a
To learn more about DataConnect, read the “DataConnect” chap-
field in the section. You
ter in Application Building for the IBM TRIRIGA Application Plat- specify this by checking
form 3: Data Management. the corresponding check
• Field box in the Sum column.
Contains the label defined for the field in the business object that If you request a sum field,
is the source of the field. the field is added to the
business object’s General
When you first look at the Field List for a smart section, some check section. The name of the
boxes in the Select column may already be checked and greyed out. sum field is composed
The fields initially included in a smart section are the fields in the from the name of the sec-
underlying business object that are defined with their Result Column tion and the name of the
check box checked. The Result Column check box is discussed on field to be summed. For
page 43. example, if there is a field
named One in a section
If a field is UOM-managed, be sure to select the corresponding UOM named Roster, the sum
source field. This ensures that the correct UOM is available in the field for One will be
smart section for display to the user. named Roster One Total.

Sequence Numbers
When you are looking at the properties of an existing multiple-smart
section, it has a property labeled Table Sequence. Single-smart sec-

© Copyright IBM Corporation 2011. Organization of a Record | 81

 tions do not have this property. Smart sections that have not been
saved for the first time do not have this property. Figure 2-33 shows
the properties of an existing multiple-record smart section.

Figure 2-33. Existing Multiple-Record Smart Section

The purpose of the Table Sequence field is to solve a problem related

to the order that information from records appears in reports. Reports
are described in the IBM TRIRIGA Application Platform Reporting 3
User Guide.
You can generate reports that show the contents of a multiple-record
smart section ordered by the contents of any field in the record. If
the records in question have fields named Date or Title, you can have
the report order the information by its date or title.
Sometimes you want the contents of a multiple-record smart section
to be listed in an order that does not correspond to the data it con-

82 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

tains but rather to the order that records were added to a smart sec-
tion. The Table Sequence field gives you a simple way of facilitating
reports that show records in the order they were added to a multiple-
record smart section.
The basic strategy for facilitating reports that show records in the
order they were added to a multiple-record smart section is to add a
Number field to the records for this purpose. The values put in this
field will reflect the order in which their record is added to a smart
section. We call these values sequence numbers.
After you have added a field to a business object to contain sequence
numbers for the records created from it, you need a way to put the
sequence numbers in the field. This is what the Table Sequence prop-
erty is for.
The Table Sequence property contains a list of the Number fields in
the multiple-record smart section. If you select the name of a Number
field as the value of the Table Sequence property, the IBM TRIRIGA
Application Platform will put sequence numbers in the specified field.
That’s all there is to it.

© Copyright IBM Corporation 2011. Organization of a Record | 83

 Embedded Smart Sections
Smart sections that contain embedded records or have the dependent
flag checked have a different set of properties than other smart sec-
tions. Figure 2-34 shows the properties of a smart section that con-
tains embedded records.

Figure 2-34. Embedded Smart Section Properties

Embedded records exist only in the smart section they are created in.
Because the existence of embedded records always depends on the
existence of the record that contains them, the Dependent check box
is always checked and grayed out.
For similar reasons, the properties for a smart section that will con-
tain embedded records has no Reference Only radio button, no Live
Link check box and no Reference With Modify radio button.
There is a property that is unique to smart sections that will contain
embedded records. The property is displayed as a check box labeled
Add Through Find Query. Checking this check box designates that
the user is going to Find one type of record and a workflow is going to
take the information of the records found to create the records that
will be shown in the section. This option is available only in conjunc-
tion with the Associate Multiple Record option.

84 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

Add Through Find Query is a rather elaborate mechanism for adding
records to a smart section that contains embedded records. There is a
simpler mechanism available for adding records to smart sections that
contain other kinds of records. If a smart section contains records that
are not embedded, you can add records to it by finding existing
records and selecting them.
Existing embedded records cannot be added to a smart section in this
straightforward way because embedded records exist only in the
smart section they were created in. If the information you want to
add to a smart section as an embedded record is in another record,
you can add a copy of the record to the smart section if it is the right
kind of record. If the information is in a different kind of record, you
will need to create the embedded record and set its values appropri-
ately.
Because of the many different ways that may be needed to go from a
found record to adding an embedded record to a smart section, the
IBM TRIRIGA Application Platform does not provide any built-in logic
to handle it. Instead, the platform requires you to provide the logic in
a workflow that handles all the details.
The workflow you specify in the Workflow to Initialize Record prop-
erty has more responsibilities when the Add Through Find Query
check box is checked. Normally, the workflow is responsible only for
initialization or bookkeeping. If the Add Through Find Query check
box is checked, the workflow is also responsible for creating the
embedded record and adding it to the smart section.
Another difference in the responsibilities of the workflow if the Add
Through Find Query check box is checked is the way it is expected to
use the temporary association specified by the Temporary
Association property. Instead of using the temporary association to
navigate to a new record, the workflow is expected to use the tempo-
rary association to navigate to the records found that contain the data
that will be the basis for the contents of the embedded records the
workflow is expected to create.

© Copyright IBM Corporation 2011. Organization of a Record | 85

 Pros and Cons of Using Smart Sections
Because multiple-record smart sections and query sections (described
on page 277) are similar in a number of ways, we thought it would be
helpful to summarize their differences to help you decide which is
most appropriate for a need.
If you need to be able to explicitly add or remove records from a
smart section to keep an historical record of what the values of the
referenced record were at the time it was added, use a multiple-
record smart section. Otherwise, if merely having an association with
the containing record is sufficient for inclusion in the section, a query
section is usually the better choice.
A multiple-record smart section contains exactly those records that
have been put in the section. A query section contains the results of a
query.
Users and workflows may explicitly add records to a multiple-record
smart section or remove them. There is no explicit add or remove
operation for a query section. Records appear in a query section
because of the values they contain or the associations they have.
When the content of a multiple-record smart section is to be based on
the values or associations of the records it contains, using a query
section is always the better choice. It results in a simpler and faster
application.
If you want to use a field from an associated business object, in a
business object’s mapping properties (Name, Cost, Quantity, Prefix
or Suffix) you must include it in a single-record smart section that
references the associated business object.
Locator fields are similar to fields in smart sections because a locator
field’s value can be populated with the value of a field from another
record. If your situation calls for a need for a live link to the refer-
enced record's most up-to-date value, you may want to use a smart
section. Locator fields are beneficial if a record containing a locator
field needs to retain the original value of the referenced record as it
was when the locator field was populated with the referenced record.
Locator fields are discussed on page 151.

Note Sections
Note sections are a feature that was supported in older versions of
the platform. This feature is now obsolete. Business objects created

86 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

in an older version of the platform that use note sections will con-
tinue to work as always, but your note section is turned into a note
field.
To allow notes of arbitrary length with formatting to be included in a
record, use a field that has the data type Note. The Note data type is
described on page 134.

Discussion Thread Sections

A Discussion Thread section allows people to write sequences of com-
ments and attach them to a record. The comments can have com-
ments, so the whole discussion is arranged in a hierarchy.
To create a discussion section, first define an association between the
business object that will contain the discussion section and the
Discussion Thread business object in the System module. It is not
important what names you choose for the association.
As soon as you specify that the other end of the association will be
connected to the Discussion Thread business object, the properties
for the discussion appear below the association’s properties. This is
shown in Figure 2-35.

Figure 2-35. Properties for an Association and a Discussion Thread Section

© Copyright IBM Corporation 2011. Organization of a Record | 87

 These are the properties to specify when creating a Discussion Thread
section:
Section Name
This is the name that the platform uses internally to identify the
section. This name must be unique among the business object’s
sections.
Section Label
This is the default label text that will appear in a user interface
to identify the section.
After you have finished specifying the properties of the association
and the Discussion Thread section, click the Save Association action.
This creates both the association and the Discussion Thread section.

Links
As mentioned previously, a link was a special kind of record that
blurred distinctions between types of records created from different
business objects. Link records existed only in a smart section.
In the past, one of the uses of link business objects was to report on
multiple business objects. Now, Report Builder queries can report on
multiple business objects without using link business objects. Use
Report Builder queries to report on multiple business objects.
In the past, one of the uses of link business objects was to allow dif-
ferent business objects to appear in multi-record smart sections.
Now, query sections provide this functionality without using link busi-
ness objects or multi-record smart sections. Use query sections to dis-
play information from different business objects.
We will explain how a link works by first explaining how the other
kinds of records, stand alone and embedded, organize their fields.
Consider the diagram in Figure 2-36. it shows the organization of two
kinds of records that are not links. One is a Textbook record. The other
is a Sample Application record. Figure 2-36 shows three fields of each
record.
Some fields in the records have the same name. They both have a
field named Name and another field named Description. Each record also
has fields with names that the other record does not have. The
Textbook record has a field named Publisher that the Sample Application
record does not. The Sample Application record has a Revision Date field
that the Textbook record does not.

88 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

 Figure 2-36. Records that are Not Links

Clearly, these two records are different. Because they have different
fields, they must be treated differently. Looking for a Publisher field in
a Sample Application record does not work.
Link records are created when a person or workflow adds a record to
a section based on an association with a link business object. Instead
of causing the section to reference the record being added, the sec-
tion creates a new link record that is linked to the record being added
to the section. The section references the link record rather than the
record it was asked to reference.
If the name of a field in a link record is different from any field name
in the record it is linked to, the field’s initial value is determined nor-
mally. However, fields in the link record that have the same name as
a field in the linked record have their initial value copied from the
field with the same name in the linked record. This organization is
shown in Figure 2-37.
Figure 2-37 shows the same records we saw in Figure 2-36, each
linked to a link record created from a business object named Course
Material. The Course Material records are links that have fields with some
of the same names as the Textbook and Sample Application records.

© Copyright IBM Corporation 2011. Organization of a Record | 89

 Figure 2-37. Links

Figure 2-37 shows how the fields of each Course Material link record are
given initial values from the record that it is linked to. The Name,
Description and Publisher fields of the Course Material record linked to the
Textbook record have their initial value copied from like-named fields
in the linked record. The Revision Date field does not get its initial value
from the linked record because the record it is linked to does not
have a field named Revision Date. Similarly, the Name, Description and
Revision Date fields of the Course Material link that is linked to the Sample
Application record have their initial values copied from the like-named
fields in the linked record. The Publisher field does not get its initial

90 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.

value copied from the linked record because the record it is linked to
does not have a field named Publisher.
If a section references records through links rather than directly, all
records in the section appear to have the same number of fields with
the same names and data types.
After the fields of link records are set to their initial values, what
happens to the values after that is determined by the properties of
the section that contains the link records. Whether or not a user
interface should allow the values of the link record’s fields to be mod-
ified and whether or not changes in the linked record will be copied
to the fields of the link record are things that are controlled in the
usual way by the section’s properties: the Reference Only radio but-
ton, the Live Link check box and the Reference With Modify radio
button.
Whether or not a user can click a hyperlink to the linked record in a
single-record smart section is set by the smart section’s Show Embed-
ded Link check box.
There is a restriction on the kinds of records that a link can be linked
to. A link record can be linked only to a record that was created from
a business object in the same module as the business object used to
create the link record.

© Copyright IBM Corporation 2011. Organization of a Record | 91

92 | Chapter 2: Data Modeling © Copyright IBM Corporation 2011.
Chapter 1,
In this chapter: CHAPTER 3
• An explanation of what a
data type is.
• Descriptions of each data
type supported by the IBM
Data Types
TRIRIGA Application
Platform.
• How to manage lists and
classifications.

A property of every field is its data type. A field’s data type deter-
mines the type of data that the field can contain. A good understand-
ing of data types is necessary for defining fields and for most things
that applications do with fields.
Because understanding data types is so important, we have devoted
this chapter to discussing just data types.
Figure 3-1 on page 94 shows a summary of the data types available in
the IBM TRIRIGA Application Platform. Figure 3-1 also shows where to
find more detailed information about each data type.
The description of each data type includes a discussion of what is
involved in specifying a field with that type. Most fields have the
usual properties described on page 40. Only additional properties or
properties that are somehow different will be described.

© Copyright IBM Corporation 2011. 93

 Data Type Description Suffix Where Discussed
Binary Used to contain an arbitrary sequence of bytes BI page 95
that the platform cannot directly manipulate.
Boolean Used to contain a value that is either true or false. BL page 96
Business Object Used to associate a Location, Organization, or BO page 98
Geography with a record.
Classification Used to contain a value selected from a defined CL page 100
hierarchy of values.
Classification Rol- Used for rolling up sums by classification. CR page 110
lup
Color Used to contain a color. CO page 111
Control Number Used to generate and contain unique ID numbers. CN page 113
Date Used to contain a date. DA page 115
Date and Time Used to contain a time and date combination. DT page 117
Duration Used to contain the length of a time interval. DU page 119
Financial RollUp Used to contain totals from other fields involved FR page 121
in financial transactions.
Image Used to contain an image. IM page 122
Label Only Used to specify a label with no corresponding LA page 123
field.
List Used to select a value from a list of values. LI page 124
Note Used to contain arbitrary length formatted text. NO page 134
Number Used to contain numbers. NU page 136
Password Used to contain a text value that can be modified PA page 143
but not displayed in a user interface.
System Read Only Used to access information about a record and the SY page 145
business object used to create it.
Text Used to contain text values TX page 149
Time Used to contain a time of day TI page 159
Unit of Measure Used to contain a Unit of Measure UO page 160
Url Used to contain a URL UR page 162
Figure 3-1. Summary of Data Types

94 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Binary
A Binary field contains a value of arbitrary length that the IBM
TRIRIGA Application Platform cannot directly manipulate*. For exam-
ple, a Binary field can be used to contain an Excel spreadsheet.
A Binary field’s properties are shown in Figure 3-2. A Binary field has
all of the usual field properties discussed on page 40.

Figure 3-2. Form to Edit Properties of a Binary Field

TIP: Binary field names should end with BI for easy identification
later, e.g., cstDataTemplateBI.

* The exception to this is when the binary field stores an Excel spreadsheet and used in con-
junction with the Distill File and Populate File workflow tasks discussed in “Offline Excel
Spreadsheets” on page 703.

© Copyright IBM Corporation 2011. Binary | 95

 Boolean
A Boolean field contains a value that is either true or false. There are
two most common uses for Boolean fields:
• Boolean fields may be used to indicate whether the real world
entity represented by a record is classified in a certain way or
not. For example, a Boolean field may be used to indicate if a
task is a milestone, if a lease includes a particular service, or if a
country uses the Euro as its currency.
For classifications having more than two possibilities, it is usually
simpler and less confusing to use the List or Classification data
types.
• Boolean fields may be used as an alternative to state transitions
to note things about the current state of something. Boolean
fields are sometimes more useful for this purpose if you need to
reason about combinations of states. For example, boolean vari-
ables may be used to note if the data in a record is up to date, if
a document has been reviewed, or if a piece of equipment needs
to be picked up rather than being delivered. Having three Bool-
ean fields to represent these things would avoid having at least
eight states in the state transition family to represent the eight
possible combinations of possibilities.
Boolean fields display as checked/unchecked check boxes in non-edit-
able queries and reports.
Boolean fields can be selected as runtime filters or as static filters in
metric queries.
To filter a Boolean field, use the values TRUE and/or FALSE.

96 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

A form for editing a Boolean field’s properties is shown in Figure 3-3.
The form uses all of the usual field properties discussed on page 40.

Figure 3-3. Form to Edit Properties of a Boolean Field

To minimize user confusion, do not check the Required check box for
a Boolean field. Required is useful for data types that allow a distinc-
tion to be made between fields that contain a value and those that do
not. A Boolean field always contains a true or false value. Since there
is always a value in a Boolean field, making it required is meaningless.
TIP: Boolean field names should end with BL for easy identification
later, e.g., cstDefaultBL.

© Copyright IBM Corporation 2011. Boolean | 97

 Business Object
A Business Object field can contain a Geography, Location or Organization
record, depending on how the field is specified. You may also see this
type of field referred to as a Smart Object field. A Smart Object is an
instance of a Business Object. If a triPeople Business Object is the defi-
nition of a person, a triPeople Smart Object is a specific instance of a
person in the system.

Figure 3-4. Form to Edit Properties of a Business Object Field

Figure 3-4 shows the properties of a Business Object field. A Business

Object field uses all the usual field properties discussed on page 40.
There are some additional properties:

98 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Module
The value of this property can be set to Geography, Location, or
Organization. This setting determines which of these three types of
records this field will refer to.
Full Path
Geography, Location,and Organization records are managed as hierar-
chies by the IBM TRIRIGA Application Platform’s Geography Man-
ager, Location Manager, and Organization Manager, respectively.
If the Full Path check box is not checked, the Geography, Loca-
tion, or Organization that is the value of this field is displayed
using just its own name. This might look like
Atlanta

If the Full Path check box is checked, the Geography, Location, or

Organization that is the value of this field is displayed using its
name and every other name between it and the root of its hierar-
chy. This might look like
\World\North America\USA\Georgia\Atlanta

Hierarchies are discussed in greater detail in Chapter 9.

Association String
It is not necessary to define any associations to use a Business
Object field, but it is a good thing to do. If any associations
between this field’s business object and a business object in the
module specified by the Module property are defined, the associ-
ation names will appear in this property’s drop-down list. If you
choose the name of an association in the drop-down list to be this
property’s value, the platform creates the named association
between a record that contains this field and the record that this
field references as well as the reverse association between these
two records.
TIP: Business Object field names should end with BO for easy identifi-
cation later, e.g., cstOrganizationBO.

© Copyright IBM Corporation 2011. Business Object | 99

 Classification
Classifications are represented as records presented in a hierarchical
fashion. If the type of a field is Classification, a record in the
Classification hierarchy can be chosen as the value of the field.*

You can allow a Classification field’s value to be chosen from any

record in the Classification hierarchy. Consider the classification hierar-
chy shown in Figure 3-5. A Classification field can be defined that may
contain any record shown in this hierarchy.
Usually, a field is restricted to some part of the hierarchy. For exam-
ple, a field might be restricted to the classification Discipline, which
includes everything under Discipline, such as Civil, Electrical, and Electrical
Lighting.

Classifications like the ones under Discipline are useful simply for their
name and what their name implies to people. Because classifications
are represented by records, they can have additional fields that con-
tain data used to determine the outcome of computations. For exam-
ple, a classification that indicates what type of equipment something
is may have a field whose value is the phone number to call if the
equipment needs repair.
The List data type is sometimes a good alternative to Classification.
Figure 3-5. 
There is a comparison of the two types on page 164.
Classification Hierarchy
TIP: Classification field names should end with CL for easy identifica-
tion later, e.g., cstFunctionalRoleCL.
The next section describes how to define a Classification field and
how to create new classifications.

* The IBM TRIRIGA Application Platform’s general purpose way of handling hierarchies is
described in Chapter 9.

100 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Defining Classification Fields
The properties of a Classification field are shown in Figure 3-6.

Figure 3-6. Form to Edit Properties of a Classification Field

The form uses all the usual field properties discussed on page 40. The
form also has additional properties:
Full Path
If the Full Path check box is not checked, the classification that is
the value of this field will be displayed in the user interface using
just the classification’s name. For example, if the classification
labeled Owned Asset in Figure 3-5 on page 100 is selected it will
be displayed as 
Owned Asset

© Copyright IBM Corporation 2011. Classification | 101

 If the Full Path check box is checked, the names of all classifica-
tions in the hierarchy above the selection are included in what is
displayed. For example, if the classification labeled Owned Asset
in Figure 3-5 on page 100 is selected and the value of the Root
Classification property is Asset Ownership it will be displayed as 
\Classifications\Asset Ownership\Owned Asset
Root Classification
The value of this property determines from which portion of the
Classification hierarchy values for this field can be selected. When
you click the icon to the right of this property, a Classification
Selector pops up like the one shown in Figure 3-7. When you
select a classification as the value for Root Classification, it
means the field’s value may be that classification or classifica-
tions under it.
Figure 3-7. Classification Selector Keep in mind that the classification you specify here allows you to
restrict what values are appropriate for this field. For example, if
you specify Classifications here, any classification could be the value
of this field. On the other hand, if you specify Discipline, then you
can restrict the values of this field to more specific classifica-
tions, such as Civil and Electrical.
Association String
It is not necessary to define an association to use a Classification
field. However, if any associations are defined between this
field’s business object and the business object specified by the
Root Classification property or a business object under it in the
classification hierarchy, then the names of the associations
appear in this property’s drop-down list. If you choose the name
of an association in the drop-down list to be the value of this
property, then the platform will create the named association
between a record that contains this field and the record that this
field references as well as the reverse association between these
two records.
If this property has no value, the IBM TRIRIGA Application Plat-
form still creates an association between a record that contains
this field and the record that this field references. The name of
the association will be Classified by followed by the name of the
Classification record that is the value of the Root Classification
property. For example, if this property has no value and the value
of the Root Classification property is Brands, then the name of the
association will be Classified by Brands. Since there is no reverse
association defined, the reverse association will not be created.

102 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Creating and Editing Classifications
When creating a new Classification field, you may find that some of
the classifications you want as possible values for the field are not
available in the Classification Selector panel. If all that is missing are
classifications you want to see in an existing part of the Classification
hierarchy, you can simply add the classifications using the Classifica-
tion Manager.
Sometimes you want to add a whole new branch to the Classification
hierarchy. These are the conceptual steps to adding a new branch to
the Classification hierarchy:
a. Define a new business object in the Classification module that will
be used to create the records that will form the new branch of
the Classification hierarchy.
b. Create an Is Parent Of association from the new business object to
itself so that you can create a sub-hierarchy using just records
created using the new business object.
c. Publish the new business object.
d. All Classification hierarchies have a common parent that is cre-
ated from a Classification business object. You must create an Is
Parent Of association from the Classification business object to the
new business object to allow records created from the new busi-
ness object to be in the hierarchy under the common parent.
e. Create a form to create records created from the new business
object and edit them.
f. Modify the form used to edit Classification records to allow the
creation of the records created from the new business object
under Classification records.
g. Define the new branch of the hierarchy using the new business
object.
We explain the details of these conceptual steps using an example.
Suppose we want to add the classifications shown in Figure 3-8 to the
Figure 3-8. Public Transportation
Classification hierarchy. These classifications will allow one kind of
Mode Hierarchy
record to represent all kinds of public transportation modes. The
application will use a Classification field in a record to know what
kind of public transportation mode it is.
To accomplish the first conceptual step, we will create a business
object in the Classification module named cstPublicTransportationMode.
The steps in doing this will be:
a. Navigate to the Data Modeler.

© Copyright IBM Corporation 2011. Classification | 103

 b. Select the Classification module in the Data Modeler’s Object
Browser panel. Click the New Business Object menu item in the
New menu of the Data Modeler. This causes properties for a new
business object to appear in the Property panel.
c. Set the Name of the new business object to
cstPublicTransportationMode and the Display Name to Public Transportation
Mode. For the Description enter Classifications for different public trans-
portation modes.
d. Specify that the new business object is Stand Alone. All business
objects used for hierarchies should be Stand Alone.
e. Click the Data Modeler’s Save BO action. This creates the
cstPublicTransportationMode business object and causes it to appear in
the Data Modeler.
The next conceptual step is creating an Is Parent Of association.
a. Click the New Association menu item in the New menu. This
causes the properties for a new association to appear in the
Property panel.
b. Set the value of the Association property to Is Parent Of. Set the
value of the Associate Business Object property to
cstPublicTransportationMode.
c. Click the Data Modeler’s Save Association action.
The next conceptual step is to publish the new business object.
a. Click the BO Mapping menu item of the Data Modeler’s Tools
menu. The Mapping Properties of the cstPublicTransportationMode busi-
ness object appear in the Property panel.
b. Click the Find hyperlink in the Name property. This causes a Type
Field form to appear under the Mapping Properties.
c. Make sure that the fields contain the correct values:
• The Section Name field should contain RecordInformation.
• The Field Name field should contain Name.
d. Click the Type Field form’s Ok action and the Type Field form dis-
appears.
e. Click the Save Mapping action near the top of the Data Modeler.
f. While the Mapping Properties are visible, a Publish BO action is
visible near the top of the Data Modeler. Click the Publish BO
action to publish the cstPublicTransportationMode business object.
The next conceptual step is to create an Is Parent Of association from
the Classification business object to the new business object to allow

104 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

you to create new cstPublicTransportation Mode records under the Classifi-
cation hierarchy.
a. Click the Classification business object in the Data Modeler’s
Object Browser panel. Details of the Classification business object
appear.
b. Click the New Association menu item in the New menu. This
causes the properties for a new association to appear in the
Property panel.
c. Set the value of the Association property to Is Parent Of. Set the
value of the Associate Business Object property to
cstPublicTransportationMode.
d. Click the Data Modeler’s Save Association action.
e. Click the Publish BO menu item of the Tools menu.
The next conceptual step is to create a form for the new business
object.
a. Navigate to the Form Builder by clicking the Form Builder menu
item in the Tools > Builder Tools menu.
b. Select the radio button for the Classification module in the left
side of the Form Builder. A list of forms associated with the
Classification module appears in the right side of the Form
Builder.
c. Click the New action at the top of the Form Builder. A Form Wiz-
ard window pops up to allow you to define a new form.*
d. Initially, the Form Wizard’s properties tab shows the properties of
the form itself. Set the value of the Business Object property to
cstPublicTransportationMode. Check the check box for the Default
Form property.
e. Click the Apply action at the top of the Form Wizard’s Layout
tab. The name shown in the Navigation tab will change from Form,
which is just a place-holder name, to cstPublicTransportationMode.
f. Click the Add Tab action at the top of the Form Wizard’s Layout
tab. This causes the properties for a new tab to appear in the
Properties panel of the Form Wizard’s Layout tab.

* Another option is to Copy an existing Classification form. Starting from a copy could save
you some time.

© Copyright IBM Corporation 2011. Classification | 105

 g. Fill in the properties of the new tab as shown in Figure 3-9.

Figure 3-9. Properties for General Tab

h. Click the Apply action at the top of the Form Wizard’s Layout
tab. The General tab now appears in the Navigator panel.
i. Click the Add Section action at the top of the Form Wizard’s
Layout tab. This causes the properties for a new tab to appear in
the Properties panel of the Form Wizard’s Layout tab.

106 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

 j. Fill in the properties of the new section as shown in Figure 3-10.

Figure 3-10. Properties for General Section

k. Click the Apply action at the top of the Form Wizard’s Layout
tab. A list of the fields in the cstPublicTransportationMode business
object appears in the Components panel.
l. Check the check box for the triNameTX and triDescriptionTX fields.
Click the Add action at the top of the Components panel. This
adds two fields to the General section that are based on the
triNameTX and triDescriptionTX fields in the business object. The
General section and its two fields appear in the Layout panel of the
Form Wizard’s Layout tab.
m. Navigate to the Includes/Forms tab of the Form Wizard.
n. Click the Add action on the Includes section bar. A Select Item(s)
panel pops up to allow the selection of records that may be cre-
ated under a cstPublicTransportationMode record.
o. Select the check box next to cstPublicTransportationMode and click the
Ok action at the top of the Select Item(s) panel. This causes the
Select Item(s) panel to disappear and the cstPublicTransportationMode
business object to appear in the Includes section.

© Copyright IBM Corporation 2011. Classification | 107

 p. Navigate back to the Layout tab of the Form Wizard. Click the
Publish action at the top of the Layout tab. This causes the form
to be published. When the publication of the form is done, the
Publish action at the top of the Layout tab is replaced with a
Revise action.
q. Click the Cancel action to close the Form Wizard window.
The next conceptual step is to enable the Classification form to cre-
ate records under Classification using the new business object.
a. Navigate to the Form Builder.
b. Select the radio button for the Classification module in the left
side of the Form Builder. A list of forms associated with the
Classification module appears in the right side of the Form
Builder.
c. Click the hyperlink on the right side of the Form Builder for the
Classification form. Look for triClassification. A Form Wizard window
pops up for viewing and editing the properties of the
Classification form.
d. Click the Revise action at the top of the Form Wizard’s Layout
tab. Wait for the Revise action to be replaced with a Publish
action.
e. Navigate to the Form Wizard’s Includes/Forms tab.
f. Click the Add action at the top of the Includes section. A Select
Item(s) panel appears.
g. In the Select Item(s) panel, select the check box for the
cstPublicTransportationMode business object. Click the Ok action at the
top of the Select Item(s) panel. The Select Item(s) panel disap-
pears. The cstPublicTransportationMode business object is now in the
list in the Includes section.
h. Navigate back to the Layout tab of the Form Wizard. Click the
Publish action at the top of the Layout tab. When the publica-
tion of the form is done, the Publish action at the top of the
Layout tab is replaced with a Revise action.
i. Click the Cancel action to close the Form Wizard window.
The final conceptual step is to add records created from the new
business object to the Classification hierarchy.
cstPublicTransportationMode

a. Navigate to Tools > Classifications.

b. The Hierarchy initially displays the top level of the Classification
hierarchy.

108 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

 c. In the Hierarchy panel, click the word Classifications at the top.
Click the New action on bar below the Hierarchy section bar. A
list of possible types of records you can create under the
Classifications record appears.
d. Click the list item labeled Public Transportation Mode. The system dis-
plays the Public Transportation Mode form, which allows you to create
the new Public Transportation Mode record.
e. Fill in the fields of the form: In the Name field enter Public
Transportation Mode. In the Description field enter Root classification for
Public Transportation Mode.
f. Click the form’s Create action. The record is created. The form
disappears. The Hierarchy now contains Public Transportation Mode.
g. Click Public Transportation Mode in the Hierarchy and click the New
action. A list appears of the kinds of classifications we can add
under Public Transportation Mode. The only item in this list is Public
Transportation Mode.
h. Click Public Transportation Mode. A form appears so we can edit the
new Public Transportation Mode classification.
i. Enter Airline in the Name field and fill in the Description field.
Click the Create action. The form disappears. The Classification
tree redisplays.
Notice that the icon next to Public Transportation Mode now looks like
a plus sign instead of a dot. This is because there is now
something under it. Clicking the icon (not the word) alternately Classification
opens and closes the classification, showing and hiding what is and Projects
under Public Transportation Mode.
Other kinds of records are
j. Repeat the last few steps to enter the rest of the Classification
created in whatever is
hierarchy. currently the active
project. Classificiation
Classification with Additional Data records always are cre-
ated in the Company Level
In the preceding example, we added records to the Classification hier- project, so that they are
archy. As we added them, the records served only to identify accessible to everyone.
different public transportation modes. Projects are described on
page 675.
We could add additional fields to cstPublicTransportationMode records to
control things the application will do based on the public transporta-
tion mode.
For example, we could include fields to contain text that is to be
printed on a report described by a cstPublicTransportationMode record.
There also could be fields to control the color of different parts of the
text.

© Copyright IBM Corporation 2011. Classification | 109

 Classification Rollup
Classification Rollup fields are used to intelligently roll up totals of
data in a hierarchy, based on classification fields.
The properties and use of a Classification Rollup field are fully
described in the “Financial Transactions and Rollups” chapter of the
book Application Building for the IBM TRIRIGA Application Platform 3:
Calculations.
TIP: Classification Rollup field names should end with CR for easy
identification later, e.g., cstBuildingCommonCR.

110 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Color
Color fields contain a color. Color values can be used to control the
color of some things that are displayed.
Figure 3-11 shows the properties of a Color field. A Color field has all
the usual field properties discussed on page 40, except for Read Only.
It is not possible to specify that a Color field is read only.

Figure 3-11. Form to Edit Properties of a Color Field with Basic Color Picker

The Default Value property is used to specify the initial value for the
field. To specify a default value click the icon. A palette of colors
will pop up, as shown on the bottom of Figure 3-11. After you have
selected a color by clicking it, the color palette disappears and a rect-
angle of the selected color appears to the left of the icon.
You may have noticed that above the palette of colors there were two
tabs, Basic and Advanced. We just set the color using the Basic Color
Picker. The alternative is to use the Advanced Color Picker. Click the
icon again. Now click the Advanced tab. The Advanced Color Picker

© Copyright IBM Corporation 2011. Color | 111

 is shown in Figure 3-12. This offers a Photoshop-style method of

Figure 3-12. Advanced Color Picker

choosing the color. You have four ways to specify the color: By select-
ing the area to the left and the color spectrum in the middle; by
entering the r, g, and b values directly; by entering the h, s, and v val-
ues directly; or by entering the hex value directly (do not forget to put
the # in front of the hex value). Note that if you are entering the val-
ues directly, you will need to click inside the Color Picker or press tab
for the color to update. When you are satisfied, click Apply and the
selected color appears in the Default Value property. Most other
places in IBM TRIRIGA that have color fields also provide the option of
using the Advanced Color Picker.
TIP: Color field names should end with CO for easy identification
later, e.g., cstDisplayColorCO.

112 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Control Number
A Control Number field contains a string that uniquely identifies a
record. The use for a control number is described more fully on
page 48 under the heading “Determining a Unique Name for Records”.
The system generates a record’s control number when the record
transitions from the null state to any other state.
Figure 3-13 shows the properties of a Control Number field. A Control
Number field uses all the usual field properties discussed on page 40.

Figure 3-13. Form to Edit Properties of a Control Number Field

The Do not Auto Populate and Read Only check boxes are grayed out
and always checked. You cannot uncheck either check box.
If the Generate on Create check box is checked, the Control Number
field is set to a generated value the first time that the record transi-
tions to a state other than null. This is usually desirable.
The generated value is based on a counter associated with the busi-
ness object. There are other settings that control the format of gen-

© Copyright IBM Corporation 2011. Control Number | 113

 erated control numbers described under the heading “Control Number
Generation” on page 53. If we use the default values for these set-
tings, the control numbers generated for records created from the
same business object are 1, 2, 3, etc.
If the Generate on Create is not checked, no value is automatically
put in the Control Number field. This is useful only if you have a work-
flow to set a value in the field.
It is not usually a good idea to check a Control Number field’s
Required check box. The value of a Control Number field is usually
not set until the first time the record that contains the Control Num-
ber field is saved. If the Required check box is checked, a form will
not allow the record to be saved until the Control Number field has a
value. Since control number fields are always read-only, you will be
unable to put a value in the field or save the record.
IBM TRIRIGA Data Integrator does not properly handle updates to
records for business objects containing publish names that include a
Control Number field with the Generate on Create check box
selected. In this scenario, Data Integrator is unable to determine that
a record included in an upload file already exists in the system, caus-
ing new records to be created each time the file is uploaded. For
more information, see the “Data Integrator” chapter of Application
Building for the IBM TRIRIGA Application Platform 3: Data Manage-
ment.
TIP: Control Number field names should end with CN for easy identifi-
cation later, e.g., cstControlNumberCN.

114 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Date
A Date field contains a date.
Figure 3-14 shows the properties of a Date field. A Date field has all
the usual field properties discussed on page 40. There are some addi-
tional properties:

Figure 3-14. Form to Edit the Properties of a Date Field

The Default Value property is used to specify a fixed or relative ini-

tial value for the field. To specify that the initial value of the field
should be relative to the current date, just select the radio button

© Copyright IBM Corporation 2011. Date | 115

 labeled Current Date. When the Current Date radio button is
selected, the Default Value property looks like Figure 3-15.

Figure 3-15. Date Field Default Value Property with Current Date Selected

If you leave the value of zero, then the default value is the current
date. If you put in a value greater than zero, then the default value
will be that many days before or after the current date. What deter-
mines whether it is a number of days before or after the current date
is whether the value selected in the drop-down list is + or -.
To specify that the initial value should be a fixed date, select the
lower radio button and enter a date into the field next to it.
The Validation property is used to specify what validation should be
applied to values people enter for the field in a user interface. Only
one value is supported for this property: Valid Date.
The Formula Type property is visible only if the Formula check box is
checked. If the Formula check box is checked, it means that the
value of the field will be determined by a formula and the field is
always read only. The details of how to specify a formula are speci-
fied on page 184.
TIP: Date field names should end with DA for easy identification later,
e.g., cstProjectedStartDateDA.

116 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Date and Time
A Date and Time field contains a value that is a combination of a date
and a time, such as 3:21 PM, January 21, 2006.
Figure 3-16 shows the properties of a Date and Time field. A Date and
Time field uses all the usual field properties discussed on page 40.
There are some additional properties:

Figure 3-16. Form to Edit Properties of a Date and Time Field

The Default Value property is used to specify a fixed or relative ini-

tial value for the field. To specify that the initial value of the field
should be relative to the current date and time, just select the radio
button marked Current Date & Time. When you select Current Date

© Copyright IBM Corporation 2011. Date and Time | 117

 & Time radio button, the Default Value property looks like
Figure 3-17.

Figure 3-17. Date and Time Default Value with Current Date & Time Selected

You can select the default value to be the specified number of days,
hours minutes or seconds before or after the current time. What
determines whether it is before or after the current time is whether
the value selected in the drop-down list is + or -.
To specify that the initial value should be a fixed date and time,
select the lower radio button and enter a date and time into the field
next to it.
The Formula Type property is visible only if the Formula check box is
checked. If the Formula check box is checked, it means that the
value of the field will be determined by a formula and the field is
always read only. The details of how to specify a formula are speci-
fied on page 184.
Date and TIme fields mapped into Date fields are truncated to mid-
night (00:00:00).
TIP: Date and Time field names should end with DT for easy identifi-
cation later, e.g., cstActualEndDT.

118 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Duration
A Duration field contains a value that is the length of a period of time
expressed in years, months, weeks, days, hours, minutes and seconds.
Figure 3-16 shows the properties of a Duration field. The form uses all
the usual field properties discussed on page 40. There are some addi-
tional properties:

Figure 3-18. Form to Edit Properties of a Duration Field

The Default Value property is used to specify an initial value for the
field. To enter an initial value, click the Enter hyperlink. A small form
that looks like Figure 3-19 pops up to allow you to enter a quantity of

© Copyright IBM Corporation 2011. Duration | 119

 years, months, weeks, days, hours, minutes, and seconds that will be
the field’s initial value.

Figure 3-19. Form to Enter Default Value for a Duration

The Formula Type is visible only when Formula is selected. It is

determined by a pair of radio buttons labeled Regular and Extended.
Selecting the Regular radio button brings the Formula Field property.
How to specify a regular formula is described on page 184. Selecting
the Extended radio button and then the Enter hyperlink brings the
Extended Formula panel. How to specify an extended formula is
described in the “Extended Formulas” chapter of the book Application
Building for the IBM TRIRIGA Application Platform 3: Calculations.
Duration is stored in the IBM TRIRIGA 10 database as a long value.
When saving duration values with a workflow or IBM TRIRIGA Connec-
tor for Business Applications, use the following format to ensure your
users see the correct value in a form. The formula is as follows:
(100000000000000 * ((years * 12) + months)) +
(weeks * 604800000) + (days * 86400000) + (hours
* 3600000) + (minutes * 60000) + (seconds * 1000)
+ milliseconds
TIP: Be careful when comparing duration fields in months or years in a
formula. A year is equal to 365 days in milliseconds. A month is equal
to 365 days in milliseconds divided by 12. When doing fencing compar-
isons, the length of a month is the same for any month, which can be
misleading if comparing against actual dates since there are several
months that do not have this exact number of days. The same is true
for years since a leap year has an extra day.
TIP: Duration field names should end with DU for easy identification
later, e.g., cstMeetingDurationDU.

120 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Financial Rollup
Financial Rollup fields are used to accumulate or summarize transac-
tion results.
The properties and use of a Financial Rollup field are fully described
in the “Financial Transactions and Rollups” chapter of the book Appli-
cation Building for the IBM TRIRIGA Application Platform 3: Calcula-
tions.
TIP: Financial Rollup field names should end with FR for easy identifi-
cation later.

© Copyright IBM Corporation 2011. Financial Rollup | 121

 Image
An Image field contains a value that is an image. Figure 3-20 shows
the properties of an Image field. An Image field has the usual field
properties discussed on page 40.

Figure 3-20. Form to Edit Properties of an Image Field

TIP: Image field names should end with IM for easy identification
later, e.g., cstPortraitIM.

122 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Label Only
A Label Only field does not contain any value. A Label Only field is
useful for adding labels to forms with no field associated with them.
Older versions of the platform required this field type to place a label
on the form. Since you now can add a label directly to the form with-
out storing it for each record, you should not use this field type.
TIP: Label Only field names should end with LA.

© Copyright IBM Corporation 2011. Label Only | 123

 List
A List field can have a value that is chosen from a list of values.
Classification is often a good or better alternative to List. There is a
comparison of the two types on page 164.
Figure 3-21 shows the properties of a List field. A List field uses all
the usual field properties discussed on page 40. There are some addi-
tional properties:

Figure 3-21. Form to Edit Properties of a List Field

If the Dependent check box is checked, it means the list of values

that may be selected for this field depends on the value selected for
another field from another list. For example, suppose that a business

124 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

object contains two List fields named Country and State. If the value
selected for Country is United States, then the list of values that should be
available for State should be a list of the U.S.A. states. If the value
selected for Country is Canada, then the list of values that should be
available for State should be a list of the Canadian provinces.
There is more discussion of what it means for the Dependent check
box to be checked in the next part of this chapter. What appears
under the Dependent check box changes if the check box is checked.
The following paragraphs assume that the Dependent check box is not
checked.
The Module and List properties are used to identify the list of values
that are available for this field. Lists of values are associated with a
module. We must identify the module that the list is associated with
before we can find the list. In Figure 3-21, we specified the module
named Common. We then selected the list named Country from the list
of lists in the Common module.
The Default Value property is used to specify what the initial value of
this field will be.
TIP: List field names should end with LI for easy identification later,
e.g., cstCategoryLI.
The properties that appear below the Dependent check box are dif-
ferent if the check box is checked. In the next section we describe
the process of defining a List field on a dependent list.

© Copyright IBM Corporation 2011. List | 125

 Dependent Lists
When the Dependent check box is checked, additional properties
become available on the bottom of the form.
Parent
The value of the Parent property is the name of the parent field
and the list that it uses. The choices in this drop-down list are the
names of only List fields that are already in the business object
and have dependent lists. If the parent you want to select is not
in this list, then check to see if it first needs to be added to the
business object.
List
The value of the List property is the name of the dependent list
that values for this field will be chosen from.
Each item in a dependent list is paired with an item from the par-
ent list. When a value for this field is chosen, it must be chosen
from items in the dependent list that are paired with the cur-
rently selected item in the parent list. For example, in the case of
the list named State or Province, the list is set up as dependent on a
list named Country.
The list named Country contains the names of countries including
United States and Canada. The items in the list named State or Province
include the U.S.A. states and the Canadian provinces. Each of the
U.S.A. state names is paired with the name United States. Each of
the Canadian province names is paired with the name Canada.
When it is time to use the State or Province list to select an item,
only those items that match the currently selected Country will be
offered as possible values.
If the current value of Country is United States, only the U.S.A. states
will be offered as possible values because they are paired with
United States. If the current value of Country is Canada, only the Cana-
dian provinces will be offered as possible values because they are
paired with Canada.

126 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Modifying Lists
To add, change or remove items in a list, use the IBM TRIRIGA Appli-
cation Platform List Manager. With the List Manager you can change
the contents of a list and create new lists.
To navigate to the List Manager, select Tools > Administration > Lists.
The List Manager appears. It looks like Figure 3-22.

Figure 3-22. List Manager

By clicking the drop-down box below the Manage By section bar you
can choose to view by Name or by Type.
To modify a list, begin by clicking the radio button next to the name
of the list in the Manage By section. After you click the radio button,

© Copyright IBM Corporation 2011. List | 127

 the list of items in the selected list appears in the right side of the
Filtering the List Manager.
List of Lists To add an item to a list, enter the text of the item in the field
In the upper left side of the labeled Value and click the Save Entries action.
List Manager is the list of Items are normally added to a list in alphabetical order. To change
lists. You must find the list
you want to modify in this
the sequence of the items in the list, click an arrow in the Order col-
list before you can modify umn. Clicking an upward pointing arrow moves the item up a row;
it. The list of lists is long. It clicking a downward pointing arrow moves the item down a row. To
may be inconvenient to find re-sort the list in alphabetical order click the Sort List action. To save
the list you are looking for. the new sequence, click the Save Sequence action.
In the lower left side of the
To delete an item from a list, check the check box next to the item
List Manager is a section
labeled Filter By. This sec-
and click Delete.
tion contains a list of mod- If a list is a dependent list, an additional field appears at the top of
ules with a check box next
the list section as shown in Figure 3-23.
to each one. If none of the
check boxes are checked,
the list of lists contains all
of the lists. If any of the
check boxes are checked,
the list of lists contains only
lists associated with the
modules whose check boxes
are checked.

Figure 3-23. List Manager Dependent List

We can select any item in the parent list to be the value of the
Parent List field. The columns below only contain items that are
paired with the specified item in the parent list. If we add an item to

128 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

a dependent list, the new item is paired with the specified item in the
parent list.

Creating New Lists

To create a new list, begin by clicking the List Manager’s New List
action. Clicking the New List action causes a form to pop up that
looks like Figure 3-24.

Figure 3-24. Form to Specify the Properties of a New List

Attention:
Be very careful about how you fill out this form. Once you
click the OK action and save what you enter, there is no way
to change the information you entered.
Text that people will see in a user interface to identify the list goes in
the Label field.
The unique name for the list that is used within the IBM TRIRIGA
Application Platform to identify the list goes in the Name field.
A description of the list goes in the Description field.
The Type field can be used to group related lists in the List Manager.
The List Manager can show the lists in order of their name or in order
of their type. For example, this is useful if we have a few different
lists that are related to training. In this situation we would specify
Training as the Type for training related lists. Then when we ask the

© Copyright IBM Corporation 2011. List | 129

 List Manager to show the lists ordered by type, the training lists will
show up together.
The System List check box should be unchecked. If it is checked, the
list cannot be deleted. Do not check this check box. Once you save a
list’s properties, you cannot change this check box.
The Language field is used for applications that need to function in
more than one language. The simplest way to set this field is to US
English or whatever language the application will be used in. A full
explanation of how to internationalize applications can be found in
the IBM TRIRIGA Application Platform 3 Localization User Guide.
The List Manager organizes lists by the module they are associated
with. We specify the module that the new list will be associated with
by selecting the name of the module in the Module field.
If the Dependent List check box is checked it means that the new list
will be a dependent list. Checking the Dependent List check box also
causes additional fields to appear at the bottom of the form. Creat-
ing dependent lists is discussed on page 133 under the heading “Cre-
ating Dependent Lists”.
The value of the Source Type field can be Manual or Dynamic. If the
Dependent List check box is checked, the value of Source Type is
forced to Manual.
If the value of Source Type is Manual, it means that the contents of
the list will be manually maintained through the List Manager, as dis-
cussed previously on page 127 under the heading “Modifying Lists”.
If the value of Source Type is Dynamic, it means that the contents of
the list will be dynamically generated from the contents of records. In
this case, the ordering will be alphabetical.

130 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

When the value of Source Type is Dynamic, additional fields appear at
the bottom of the form. It looks like Figure 3-25.

Figure 3-25. Form to Specify the Properties of a New Dynamic List

When the value of the Source Type field is Dynamic, the Dependent
List field is grayed out and cannot be checked. A list cannot be both
dynamic and dependent.
Together, the Source Module and Object Type fields identify a busi-
ness object. Use the Source Module field to select the name of the
module that contains the business object. Use the Object Type field
to select the business object.
Data from all records created from the specified business object is
used to populate the list. The rows of data to the right of the Fields
label identify the fields in the business object that have their Result
Column check box checked.
The text of the items in the list comes from the contents of the
selected fields in each record. In Figure 3-25, just the Name field is
selected. This means that the items of the list will consist of contents
of the Name field of every record that has been created from the
Country business object. For example, the contents of the list might
look like this:

© Copyright IBM Corporation 2011. List | 131

 Canada
Mexico
United States

If more than one field is selected, the contents of the selected fields
are assembled to form the text of each list item. The order in which
they are assembled is determined by the numbers in the Sequence
column. For example, suppose that both fields of Country are selected
and the sequence number for Name is 1 and the sequence number for
Short Name (ISO-A2) is 2. The contents of the list might look like this:
Canada CA
Mexico MX
United States US
If the value of a field used in a dynamic list changes, the dynamic list
does not update until the metadata cache is cleared. When a record
that is the source of a dynamic list is deleted, the value no longer
appears in the dynamic list.

Attention:
Deleting a list that is used in conjunction with other data may
produce unwanted or unexpected results.

132 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Creating Dependent Lists
When the Dependent List check box is checked, the form looks like
Figure 3-26. The Source Type field is forced to the value Manual and
grayed out. Two additional fields appear at the bottom to identify the
parent list.

Figure 3-26. Form to Specify the Properties of a New Dependent List

The Source Module and Master List fields jointly identify the parent
list. The Source Module field contains the name of the module that
the List Manager associates with the parent list. The Master List field
contains the name of the parent list.

© Copyright IBM Corporation 2011. List | 133

 Note
A Note field contains a formatted piece of text. There is no limit to
the length of the text.
Figure 3-27 shows the properties of a Note field. A Note field has the
usual field properties discussed on page 40.

Figure 3-27. Form to Edit Properties of a Note Field

An editable Note field displays to a user in a WYSIWYG editor with

basic formatting and basic editing features. Users also can insert/
update a table, embed an image, and view/edit the source HTML. Use
the Style Manager to configure settings for a Note field’s editor for-
mat options. (The Style Manager is discussed in the IBM TRIRIGA Appli-
cation Platform 3 User Experience User Guide.) A read-only Note field
displays the HTML defined in the field without editor controls.
The audit data store has a limit of 4000 characters for any audited
field. If an audited Note field’s data exceeds 4000 characters, its cor-
responding audit record will reflect only the first 4000 characters of
that Note field’s value.
NOTE: Use pure HTML reports when you are building HTML form
reports with Note data.

134 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

TIP: Note field names should end with NO for easy identification
later, e.g., cstCommentsNO.

Attention
A Note field cannot be used as any part of a record’s name.
Also, the IBM TRIRIGA Application Platform’s search facility
does not find text in a Note field and the Report Manager does
not allow reporting on this field. If these limitations are unac-
ceptable, consider using the Text data type.

© Copyright IBM Corporation 2011. Note | 135

 Number
A Number field contains a number.

Figure 3-28. Form to Edit Properties of a Number Field

136 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Figure 3-28 on page 136 shows the properties of a Number field. A
number field uses all the usual field properties discussed on page 40.
There are some additional Properties:
The Default Value property is used to specify an initial value for the
field. If blank, the user will be required to input a value.
The UOM List property indicates what sort of measurement the num-
ber in the field is for; e.g., area, length, quantity. It is possible for
you to customize the list of unit of measure types. This is described
on page 165 under the heading “Units of Measure”.
The Create Base Field property is visible only if the value of the UOM
List property is Currency. If the check box in the Create Base Field
property is checked, then when the properties for this field are saved,
a base currency field will be created for this field. Base currency
fields are discussed on page 180.
The name of the base currency field will be the name of this field fol-
lowed by Base. For example if the name of a field is CanadianCost, then
the name of its base field would be CanadianCostBase.
The Default UOM property specifies the default unit of measure to be
associated with values in this field. The values in the drop-down list
are the UOM Values for the UOM Type selected in the UOM List prop-
erty.
Use the Validation property to specify the validation that should be
applied to values entered for this field through a user interface. The
possibilities are:
• Accept Decimal
This means numbers that do or do not contain a decimal point will
be valid.
• Accept Only Number
This means that only numbers that do not contain a decimal point
will be valid.
When the UOM List property is blank, the Display Mask, Storage Preci-
sion, and Rounding Rule properties are visible.
Display Mask controls the formatting of the display of values for this
number field. See “Number Formats” on page 174 for a description of
the values to put in the Display Mask property. The formatting in a
Number field takes precedence over UOM formatting when displaying
Number fields in query reports or forms.

© Copyright IBM Corporation 2011. Number | 137

 Storage Precision defines how many decimal places the platform is to
use when computing and storing numbers entered in this number
field. Enter the number of digits to the right of the decimal point.
The maximum value is 12.
In Rounding Rule specify the rounding rule to be applied when round-
ing numbers entered in this number field to the number of decimal
places in the Storage Precision property. The default value is Half Up.
The options are as follows:
• Ceiling
Round the fractional digit so the value moves toward positive
infinity. For example, if Storage Precision is 2, 1.234 => 1.24, 1.12
=> 1.13, -1.234 => -1.23.
• Down
Round the fractional digit so the value moves toward zero. The
operation effectively truncates the value at the number of deci-
mal places in Storage Precision. For example, if Storage Precision
is 2, 1.2345 => 1.23, 1.328 => 1.32, -2.125 => -2.12.
• Floor
Round the fractional digit so the value moves toward negative
infinity. For example, if Storage Precision is 2, 1.234 => 1.23, 1.
236 => 1.23, 1.235 => 1.23, -1.234 => -1.24.
• Half Down
Round the fractional digit using the digit to the right to deter-
mine the direction of the round. If the digit to the right is 6 or
greater, round up. If the digit to the right is 5 or less, round
down. For example, if Storage Precision is 2, 1.234 => 1.23, 1.236
=> 1.24, 1.235 => 1.23, 1.23 => 1.23.
• Half Even
Round the fractional digit up or down as needed to make it even.
For example, if Storage Precision is 2, 1.234 => 1.23, 1.236 => 1.
24, 1.235 => 1.24, 1.245 => 1.24, 1.23 => 1.23.
• Half Up
Round the fractional digit using the digit to the right to deter-
mine the direction of the round. If the digit to the right is 5 or
greater, round up. If the digit to the right is 4 or less, round
down. For example, if Storage Precision is 2, 1.234 => 1.23, 1.236
=> 1.24, 1.235 => 1.24, 1.23 => 1.23.
• Up

138 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

 Round the fractional digit so the value moves away from zero. For
example, if Storage Precision is 2, 1.234 => 1.24, 1.23 => 1.23, -1.
234 => -1.24.
When the UOM List property is defined, the Use Custom Precision
and Mask property is visible. This property specifies whether or not
this number field will use the properties for Display Mask, Storage
Precision, and Rounding Rule as they are defined on the UOM.
When Use Custom Precision and Mask is not checked, the platform
uses the Display Mask, Storage Precision, and Rounding Rule as they
are defined on the UOM.
When the Use Custom Precision and Mask property is checked, the Dis-
play Mask, Storage Precision, and Rounding Rule properties are visi-
ble and initially set to the values defined on the UOM. Any change you
make only applies to this number field.
The UOM Source Attribute property contains a drop-down list that
allows you to specify the name of a field in the business object. If the
Formula check box is not checked, the drop-down list will contain
names of UOM fields only. The unit of measure for this field will be
determined by the value of the named UOM field.
If the Formula check box is checked, the drop-down list will contain
names of UOM and Number fields. The unit of measure associated
with the named field is the unit of measure of the formula’s result.
The value of the UOM Source Attribute property is the name of
another Number field in this business object. If the UOM Source
Attribute property has no value, then the unit of measure for the field
is defaulted to the value specified in the Default UOM property and
may be overridden by the user at runtime.
If you specify a value for the UOM Source Attribute property, the
named field’s unit of measure becomes the unit of measure for this
field. Also, this field’s Default UOM property is grayed out and set to
the value of the other field’s Default UOM property.
If you specify a value for the UOM Source Attribute property, the UOM
List property and the Default UOM property are grayed out and their
values ignored.
When there is a value in the Threshold Source Attribute property,
this number field is a scored number field, meaning it will be scored
(as described in “Comparison” on page 270). The score is displayed as
a red, yellow, or green image to the left of the number value.

© Copyright IBM Corporation 2011. Number | 139

 The value of the Threshold Source Attribute property must be a loca-
tor field that references the Threshold business object. This locator
field must be in either a General section or a one-to-one smart sec-
tion. For a number field that is in a smart section, the linked locator
field must reside on the referenced business object. The threshold
record defines the threshold ranges and contains a UOM value that is
used to convert the scored value.
Select the linked locator field in the Threshold Source Attribute drop-
down list. The list only shows locator fields in the same business
object that references the Threshold business object.
A scored number field can be used in a form section, non-table smart
section, table smart section, or vertical table section.
The score for the field is calculated during the rendering of the field
and is not stored. The platform compares the UOM of the number
field with that of the threshold record. If a conversion is needed, the
platform converts the number value before comparing it with the
threshold value to calculate the score.
During runtime, the system uses the threshold record that is cur-
rently selected by the linked locator fields. If the locator field does
not have a value, the number field displays without a score.
The score is updated when the tab is reloaded. This means that if the
value of the number field, or the threshold record, or the locator field
that links to the threshold record, is changed, the score will not
update (if needed) until the tab is reloaded.
If the check box in the Formula property is checked, it means that
the value of the field will be determined by a formula and will be
read only. This property is discussed in detail in “Formulas” on
page 184.
The Sum this Field check box is grayed out unless the field is part of
a smart section. If this check box is checked, it causes a summary
field to be generated in the business object that contains the smart
section. There is more detail about this on page 81 under the heading
“Computing Sums”.

Property Override Relationship

The ability to override the Display Mask and Storage Precision proper-
ties with the Use Custom Precision and Mask property provides clarity

140 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

in the display and storage precisions for number fields and UOM fields
and a higher level of granularity.
For example, suppose for efficiency or reporting reasons you want all
area measurement fields to have 2 decimal places and a storage pre-
cision of 6. You could set the corresponding UOM appropriately. Now
suppose you want some specific fields in a business object, for inter-
nal calculation for example, to have more decimal places and higher
precision. With IBM TRIRIGA, you can use the custom display mask
feature and not have to update all affected fields.
When a property is selected to be overridden, the initial values are
from the values defined in the next level, as illustrated in Figure 3-29.

Figure 3-29. Display Mask and Storage Precision Override Precedents

At the base definition level, should default values be employed, the

platform uses the default values shown in Figure 3-30 for each prop-
erty.
Property Default Value
Storage Precision 12
Display Mask #.####
Figure 3-30. Base Definition Default Values

© Copyright IBM Corporation 2011. Number | 141

 Property Default Value
Rounding Rule ROUND_HALF_UP
Figure 3-30. Base Definition Default Values

TIP: Number field names should end with NU for easy identification
later, e.g., cstCapacityNU.

142 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Password
A Password field contains text. Fields in user interfaces that allow
people to type a value for a Password field will not display the actual
value of the field or the text that is entered.
Figure 3-31 shows the properties of a Password field. A Password field
uses all the usual field properties discussed on page 40. There are two
additional properties.

Figure 3-31. Form to Edit a Password Field

The Validation property may have no value, in which case anything

entered in a user interface for the value of the Password field is
acceptable. The Validation property may contain the value Alpha Only
No Spaces, in which case what is entered in a user interface for a Pass-
word field must contain only letters to be acceptable. Anything

© Copyright IBM Corporation 2011. Password | 143

 entered that contains a number, spaces, or punctuation is not accept-
able.
The Reversible Encryption property defines how the platform will
store the password in the database. The three options are as follows:
Password • Do Not Encrypt
Validation This option stores the password as plain text in the database.
If you set the Validation • Encrypt - Reversible
for a Password field to This option encrypts the password using a reversible technique
Alpha Only No Spaces, it and stores that encrypted value in the database.
encourages people to
• Encrypt Non-Reversible
make the password a sin-
gle word that will be This option encrypts the password using a non-reversible tech-
easy for them to remem- nique and stores that encrypted value in the database.
ber. The drawback to
Once a Password field has been saved with the Reversible Encryp-
this is that passwords
that are regular words
tion property set to Encrypt Non-Reversible, the Reversible Encryption
are more easily guessed. property is disabled. If you wish to change the Reversible Encryption
property, you must delete the field and add it again.
Setting no Validation for
a password field by leav- A Password field can be mapped to a Text field, for example using a
ing the Validation prop- workflow. If the Reversible Encryption property is Do Not Encrypt or
erty blank allows the Encrypt - Reversible, a Text field mapped from a Password field can be
password to be multiple displayed as plain text. If the Reversible Encryption property is set
words that can contain to Encrypt Non-Reversible, a Text field mapped from a Password field can
numbers and punctua- be displayed but the output will be unreadable.
tion. Such passwords
may be harder to Password fields set to Encrypt Non-Reversible with identical content will
remember but also are not compare as equal in a workflow. Instead, try the following proce-
harder to guess. dure in a password change/verification scenario where the user enters
the password twice to make sure they entered it correctly: In the
temp record used to receive and compare the two fields containing
the new password, set the fields to Encrypt - Reversible. After the work-
flow validation is complete, have the workflow use one of the values
to set/update the password on the user’s profile in a different field
that is Encrypt Non-Reversible. Then discard the values of the Encrypt -
Reversible fields.

TIP: Password field names should end with PA for easy identification
later, e.g., cstPasswordPA.

144 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

System Read Only
A System Read Only field contains a value generated internally within
the IBM TRIRIGA Application Platform for the record that contains the
field. System Read Only fields are always read-only. Their value can-
not be directly changed from a user interface.
Figure 3-32 shows the properties of a System Read Only field. A Sys-
tem Read Only field uses all the usual field properties discussed on
page 40. There is an additional property.

Figure 3-32. Form to Edit Properties of a System Read Only Field

The value of the Sub Attribute Type property determines which of

the record’s internal information the IBM TRIRIGA Application Plat-
form places in the field. The Sub Attribute Type property is required
and its value cannot be changed after the field has been saved and
created. Reuse existing System Read Only fields instead of creating
new ones. Existing fields are noted in parentheses below. The values
for Sub Attribute Type follow:

© Copyright IBM Corporation 2011. System Read Only | 145

 BO Record Id
This is a string of text generated internally by the IBM TRIRIGA
Application Platform that uniquely identifies the record.
(triRecordIdSY)
BO Type Id
This is a string of text that uniquely identifies the business object
that was used to create the record.
(triBusinessObjectIdSY)
BO Type Name
This is the name of the business object that was used to create
the record.
(triBusinessObjectNameSY)
BO Label
This is the label of the business object that was used to create the
record.
(triBusinesObjectLabelSY)
Created DateTime
This is the date and time when this record was created.
(triCreatedSY)
Form Id
This is a string of text generated internally by the IBM TRIRIGA
Application Platform that uniquely identifies the form associated
with this record.
The form associated with a record is initially the form that was
used to create the record. If the record was created by a work-
flow task, the task specifies the form initially associated with the
record.
The form associated with a record can be changed by a workflow
using the Modify Metadata workflow task described on page 511.
(triFormIdSY)
Form Label
This is the label of the form associated with this record.
(triFormLabelSY)
Form Name
This is the name of the form associated with this record.
(triFormNameSY)
Modified DateTime
This is the date and time when this record was last modified,
stored as a string. Modified DateTime cannot be used as a DateTime
field in query filters.

146 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

 (triModifiedSY)
Object State
This is the name of the record’s current state from its state tran-
sitions. State transitions are discussed in Chapter 4.
(triRecordStateSY)
Parent Id
If the business object used to create this record is part of a hier-
archy module, then this is a string of text that uniquely identifies
the record’s parent in the hierarchy. Hierarchies are described in
the Chapter 9.
(triParentIdSY)
Path
If the business object used to create this record is part of a hier-
archy module, then this is the path from the root of the hierarchy
to this record.
(triPathSY)
Project Id
This is a string of text that uniquely identifies the project that the
record belongs to. Projects are discussed on page 675.
(triProjectIdSY)
Project Name
This is the name of the project that the record belongs to.
Projects are discussed on page 675.
(triProjectNameSY)
Record Name
The value used as this record’s unique name. This is explained on
page 48 under the heading “Determining a Unique Name for
Records”.
(triRecordNameSY)
Modified DateTime (Number)
This is the date and time when this record was last saved, stored
as a number. Modified DateTime (Number) can be used as a DateTime
field in query filters.
TIP: System Date fields may not display accurately on reports or
account for time zones for end users. In IBM TRIRIGA 10 applica-
tions, these fields are typically named triModifiedSY and triCreatedSY
and are stored as text strings in the server’s time zone. A field of
type Modified DateTime (Number) must be created and added to
objects on which you wish to report. This field type can be
retrieved through IBM TRIRIGA Connector for Business Applica-
tions. It can be used as a dynamic query filter through the API.

© Copyright IBM Corporation 2011. System Read Only | 147

 Created DateTime (Number)
This is the date and time when this record was created, stored as
a number. Created DateTime (Number) can be used as a DateTime field
in query filters.
TIP: System Date fields may not display accurately on reports or
account for time zones for end users. In IBM TRIRIGA 10 applica-
tions, these fields are typically named triModifiedSY and triCreatedSY
and are stored as text strings in the server’s time zone. A field of
type Created DateTime (Number) must be created and added to objects
on which you wish to report. This field type can be retrieved
through IBM TRIRIGA Connector for Business Applications. It can
be used as a dynamic query filter through the API.
TIP: System Read Only field names should end with SY for easy identi-
fication later.

148 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Text
A Text field contains text.
Figure 3-33 shows the properties of a Text field. A Text field uses all
the usual field properties discussed on page 40. There are additional
properties:

Figure 3-33. Form to Edit a Text Field

The Default Value property is used to specify an initial value for the
field.

© Copyright IBM Corporation 2011. Text | 149

 The Size property is used to specify the maximum number of charac-
ters which can be stored in this field.
The Validation property may have no value, in which case anything
entered in a user interface for the value of the Text field is accept-
able. These are the other possible values you can select for
Validation property:
Make Lower Case
If the value of this property is Make Lower Case, any value for this
field is acceptable. However, any upper case letters entered into
this field are converted to lower case.
Make Upper Case
If the value of this property is Make Upper Case, any value for this
field is acceptable. However, any lower case letters entered into
this field are converted to upper case.
Alpha Only No Spaces
If the value of this property is Alpha Only No Spaces, then whatever is
entered in a user interface as a value for this field may contain
only letters. Anything that contains numbers, spaces or punctua-
tion is not acceptable.
Only Numeric
If the value of this property is Only Numeric, then only digits may be
entered in a user interface as a value for this field.
The hyperlinks in the Formula property allow us to enter a formula
that determines the value of this field. The details of how to specify a
formula are specified on page 184.

Attention:
There is a 1000 character limit on the length of the text in a
Text field. If you need a field that can contain an unlimited
number of characters, consider using a Note field. Note fields
are discussed on page 134.

TIP: If you encounter instances of special characters in Text fields

saving as question marks, this can be caused by database encoding.
To check, run the following query on your database:
select value from NLS_DATABASE_PARAMETERS
where parameter='NLS_CHARACTERSET'

150 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

If the value returned is not a type UTF-8 or UTF-16 encoding, this may
be the cause of the issue. For example a common default encoding for
NLS_CHARACTERSET is WE8MSWIN1252, which is a 1 byte per charac-
ter encoding that cannot store as many character types as UTF-8.
Changing the character encoding for the database should resolve this
issue but also will result in slower performance.
TIP: Text field names should end with TX for easy identification later,
e.g., cstNameTX.

Locator Fields
If the Locator Field check box is checked, it means that this Text
field will function in a way similar to fields in a smart section. Like a
field in a smart section, if the Locator Field check box is checked, the
locator field can be populated with the value of a field from another
record and a reference and association (note, the reference and the
association are two separate things) to that record will be created
from the record containing the locator field.
This establishes the value of this field at the time it was populated
from the other record. However, should the value in the referenced
field be changed and saved, the value in the locator field is not
updated to the new value of the referenced field.
For example, the triProduct business object has a locator field called
triVendorCompanyLookupTX that is set to create a reference to an Organi-
zation and display the Organization's hierarchy path. If a triProduct
record's triVendorCompanyLookupTX field were populated with a vendor
whose hierarchy path value was Organizations\External Companies\AB&C, LLC,
the locator field's value would be Organizations\External Companies\AB&C,
LLC. If, after populating the locator field, the vendor's Name field
(which makes up the last part of the hierarchy path value) was
changed to ABC&D, Inc., the locator field's value in the triProduct record
would not be changed to the new value and would still have the value
Organizations\External Companies\AB&C, LLC. This is because a locator field
receives a copy of the referenced record's field value and not a link to
the value.
Locator fields are beneficial if a record containing a locator field
needs to retain the original value of the referenced record as it was
when the locator field was populated with the referenced record. If
your situation calls for a live link to the referenced record's most up-

© Copyright IBM Corporation 2011. Text | 151

 to-date value, you may want to use a smart section. Smart sections
are discussed on page 74.
When the Locator Field check box is checked, a property named
Locator Module appears below it. The next step is to specify which
field of which business object will populate this field. Begin by select-
ing the name of the module the field’s business object is defined in.
Select that module name as the value for the Locator Module prop-
erty.
When you select a module name as the value of the Locator Module
property, a form appears below the field properties to allow specify-
ing the business object and field that will be associated with this
field. Also use this form to specify the association that will be used to
connect the two business objects. The form looks like Figure 3-34.

Figure 3-34. Locator Field Details

Here are descriptions of the properties of the form:

Business Object Name
The value of this property is the name of the business object that
contains the field whose value will populate this field. Choose the
value of this field from a drop-down list of the business objects in
the module that was specified above for the value of the Locator
Module property.
The drop-down list also contains the value All. The meaning of All
is explained below.
Associated String
The value of this property is the name of an association that con-
nects this field’s business object to the business object whose
name is the value of the Business Object Name property. The
choices available in the drop-down list are the business object-
level association definitions that have been created from the
object that contains the locator field to the object that is speci-
fied in the Business Object Name property.

152 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

 If the value of the Business Object Name property is All, the value
of this property will be the name of an association between this
field’s business object and the base business object of the mod-
ule specified as the value of the Locator Module property. Such
an association allows records created from this field’s business
object to be associated with records created from any business
object in the module named by the Locator Module property.
Locator Field
This property’s value is the name of the field that this field will
be populated from in the business object named by the Business
Object Name property. The name is prefixed with the name of
the section that contains the field. If the field is not in a smart
section, the name General is used for the section name.
The drop-down list contains the names of fields in the business
object named by the value of the Business Object Name prop-
erty. If the value of the Business Object Name property is All, the
drop-down list contains the names of fields in the base business
object of the module specified as the Locator Module property’s
value.
After you finish specifying properties values for this form, click the
form’s Ok action. After you save the locator field properties, addi-
tional field properties named Locate Using and Locator String
appear.
Locate Using
The Locate Using property has two hyperlinks. The text of the
upper hyperlink contains the values specified for the Business
Object Name and Locator Field locator field properties. Clicking
the upper hyperlink causes the form used to specify these proper-
ties to reappear below the field properties.
The lower hyperlink in the Locate Using property has the text
Edit Mapping. Clicking this lower hyperlink causes a form to
appear in the List panel that allows you to specify that the value
of other fields in this business object should be taken from the
same record associated with this locator field. After you click the
lower hyperlink, the List panel looks like Figure 3-35 on page 154.
If you click the icon next to a field’s name, a list pops up that
allows you to specify which field of the record associated with
this locator field will be used to set the value of the field in this
business object whose icon you clicked.

© Copyright IBM Corporation 2011. Text | 153

 Figure 3-35. Locator Mapping

Locator String
The Locator String property is read-only. Its value is the value
you specified for the Associated String locator field property.
As mentioned at the beginning of this discussion about locator fields,
there is some similarity between smart sections and locator fields. For
example, setting the value of a locator field is done in the same way
as setting the value of a smart section, and this is different from set-
ting other field types. The way that a workflow sets the value of a
record’s contents is called Object Mapping and is discussed on
page 425.
When a locator field is initially created or is cleared, the objectID of
the referenced object is set to null.

Autocomplete
When a locator field is used in a form, the user sees the field’s label,
a text box, the search (locator picker) icon , and the clear icon .
Autocomplete’s goal is to reduce the user clicks needed to reach the
final search target.
Autocomplete functionality is available for all locator fields. Specify
whether or not your users will have this feature in the USE_AUTO_

154 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

COMPLETE_IN_LOCATOR_FIELD property in the TRIRIGAWEB.properties file, as
described in the IBM TRIRIGA Application Platform 3 Installation and
Implementation Guide. The default is for autocomplete to be
enabled.
The AUTO_COMPLETE_MIN_CHAR property in the TRIRIGAWEB.properties file sets
the minimum number of characters a user must type to trigger an
autocomplete search. The default is 3 characters. Another condition
for activating autocomplete is the user’s keystroke speed. The sys-
tem measures when to display the autocomplete list using a 400 milli-
second lag. A slow typist, after typing the minimum number of
characters, should see an indicator icon and, within a reasonable time
frame, the list. A fast typist may need to pause after typing the last
character in order to trigger the list.
Autocomplete is not case sensitive. As the autocomplete functional-
ity is triggered, a list appears under the text box, as shown in
Figure 3-36.

Figure 3-36. Locator Field with Autocomplete

The list shows suggested items. The first suggested item in the list is
highlighted. For each suggested item, if the locator field has defined
locator mapping fields, those field values display. The characters in
the main field value that match the user’s input are bold.
The user can perform the following actions at this stage:
• Accept the first suggested item by pressing the Tab key or Enter.
• Use the up/down arrow keys to select an item. Pressing Enter or
the Tab key completes the selection.
• Scroll and click an item. The selection completes automatically.
• Type in more characters to narrow the suggested items list.
• Delete characters, which may broaden the suggested items list.
• Key in a different set of characters.
• Press the Esc key to clear the field and hide the list.

© Copyright IBM Corporation 2011. Text | 155

 A user can take advantage of autocomplete and their familiarity with
their company’s data by entering one or two characters and pressing
the Tab key. The system performs a query and one of the following:
• If the query returns one record, that record completes the selec-
tion.
• If the query returns more than one record, the system presents
the records in a list, as shown in Figure 3-36 on page 155.
• If the query returns no records, the user sees a “no record match”
message and the cursor stays in the field waiting for the user’s
next action.
When the user completes the selection, the system populates all
related fields. The system also updates the field’s label to show the
anchor link. If the user clicks this hyperlink, the system displays the
selected record’s detail.
The list disappears when the user clicks within the text box, tabs out,
clicks outside the text box, presses Esc, or makes a selection.
If the user clicks a text box that has a value, presses a key to initiate
an autocomplete search, and then clicks outside the text box, the
original value in the text box is retained.
After selecting a record, the user can perform another search with-
out clearing the field with the clear icon .
Instead of using autocomplete, the user can click the field’s search
icon to popup the locator query full search window.
The autocomplete functionality also is available on single-record
smart section text fields, as described in “Autocomplete” on
page 272.

Overloading a Locator Field

One benefit of using locator fields to reference other records (as
opposed to smart sections) is that a locator field can be populated
with record types other than those they are defined to receive in the
Data Modeler. This ability, called overloading, is beneficial in a few
instances. First, the ability to overload a locator field is beneficial
when you need to populate a locator field with records from more
than one Business Object, or even from more than one Module. Simi-
larly, it also is beneficial when all of the types of records you may
need to populate into a locator field are not known at the time the
locator field definition is created.

156 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

For example, the triApproval business object is used in the IBM TRIRIGA
approval engine and has been set up to work with most kinds of busi-
ness objects. During the approval process, a triApproval record is cre-
ated and associated to the record being sent for approval. The
association is created by populating a locator field named triLinkedRe-
cordTX with the record being sent for approval via a workflow. By pop-
ulating the locator field, both a direct reference and an association
from the triApproval record to the record being sent for approval are
created. However, since triApproval records can potentially be created
for an almost unlimited number of types of records, the correspond-
ing number of types of values that may need to be referenced by the
single triLinkedRecordTX locator field is also virtually infinite, and hence,
the need to overload locator fields is sometimes necessary.
When overloading a locator field with a value it is not defined in the
Data Modeler to receive, certain steps need to be taken to ensure the
process works correctly:
First, since a locator field can only be defined to create an associa-
tion to one type of business object in the Data Modeler, when over-
loading a locator field the type of association that will be created
when overloading a locator field is still determined by the Association
String property defined in the locator field, although the association
type also should be specified by the workflow. This is done by setting
the Association Type property in the Object Mapping window of a Cre-
ate Record or Modify Records task in a workflow (this setting is
described in the Creating Workflows chapter on page 425). The Asso-
ciation Type property only shows those association types for which
business object-level association definitions have been defined, from
the perspective of the business object that contains the locator field
to be overloaded (e.g., the triApproval object in our scenario above) to
the Business Object whose records will be referenced by, and mapped
into, the locator field (for more information on creating association
definitions, see “Defining Associations” on page 61). Even though
using Source mapping to populate the locator field usually creates the
association as defined in the locator field in the Data Modeler, this
step ensures the association gets created in the event that the record
you are populating into the locator field is still in the null state (e.g.,
for a new record whose first state transition has yet to be invoked).
Note, that in this scenario, the workflow mapping results in the loca-
tor field not being populated and having a blank value, since there is
no Record Name or other field value yet for the record to map into
the locator field.

© Copyright IBM Corporation 2011. Text | 157

 The second requirement to overload locator fields is to make sure the
locator field is populated using the Source option in the Object Map-
ping window in the locator field. The process of populating locator
fields is described in the Object Mapping section of the Creating
Workflows chapter on page 425.

158 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Time
A Time field contains a value that is a time, such as 3:21 PM.
Figure 3-37 shows the properties of a Time field. A Time field uses all
the usual field properties discussed on page 40. There are some addi-
tional properties:

Figure 3-37. Form to Edit Properties of a Time Field

The Default Value property is used to specify a fixed initial value for
the field. The initial value is specified as an hour in the range 0-23, a
minute in the range 0-59 and a second in the range 0-59.
TIP: Time field names should end with TI for easy identification later,
e.g., cstStartTimeTI.

© Copyright IBM Corporation 2011. Time | 159

 Unit of Measure
A Unit of Measure field identifies a unit of measurement such as
pounds, feet or gallons. Unit of Measure fields are usually used with
Number fields. One Unit of Measure field can be used to specify the
unit of measure for any number of Number fields.
Though a Number field can be used to determine the unit of measure
of other number fields, it can be more natural for people to specify a
unit of measure for multiple number fields by using a field that is not
associated with any single Number field.
A Unit of Measure field can also be used to determine the kind of
measurement that a number is for, such as weight, length, or volume.
Figure 3-38. shows the properties of a Unit of Measure field. A Unit of
Measure field uses all the usual field properties discussed on page 40.
There are some additional properties:
The UOM List property is used to select the kind of unit that the field
will allow to be selected, such as weight, length or volume. The type
of unit that can be selected can be changed if the Edit UOM List
check box is checked.
The Default UOM property specifies the initial value of this field in
new records.
The Edit UOM List property specifies that at runtime the user can
change the type of units measured not just the unit value. For exam-
ple the user could change the UOM List from Length to Area which
would change the unit values available from feet and meters to
square-feet and square-meters.
TIP: Unit of Measure field names should end with UO for easy identifi-
cation later, e.g., cstAreaUO.

160 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Figure 3-38. Form to Edit Properties of a Unit of Measure Field

© Copyright IBM Corporation 2011. Unit of Measure | 161

 Url
A URL field contains string of text that should be a valid URL. Fields in
user interfaces that render a URL field also provide a way to open the
URL specified by the contents of the field.
Figure 3-39 shows the properties of a URL field. A URL field uses all
the usual field properties discussed on page 40. There are additional
properties.

Figure 3-39. Form to Edit a URL Field

The Default Value property can be used to specify the initial value of
this field in a new record. The system allows the following prefixes:
http://, https://, file://, and ftp://. If the protocol is not http://, https://,
file://, or ftp://, the system prefixes http://

TIP: Use the full URL when entering external URLs; e.g., http://www.
ibm.com.

162 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

TIP: Url field names should end with UR for easy identification later,
e.g., cstExternalInfoUR.

© Copyright IBM Corporation 2011. Url | 163

 List Versus Classification
The Classification and List data types are similar: both allow someone
to select a single item from multiple possibilities. To help you decide
which data type is the better choice for a particular field, we have
provided this description of the differences between the data types.
• Lists are usually a static set of choices. In general, the set of
choices presented by a list is determined in advance and is not
normally changed by an application. (The exception is a dynamic
list that is dynamically generated from the contents of records, as
described on page 130.) Classifications can be a dynamic set of
choices that reflect data the application can control.
• Lists are easier to set up and are a good choice to represent sin-
gle options that will never change. Classifications are harder to
set up but, being record data, support future changes better.
• Classifications make it easy to organize kinds of things into a hier-
archy. Some hierarchical organization is possible with dependent
lists. However, managing hierarchies with more than three levels
is not practical to do with dependent lists.
• Classifications may be used to identify live records. Lists are sim-
ply names.
• Classifications can have data associated with them that can be
used to influence the outcome of a computation. This relation-
ship between a selected classification and the outcome of a com-
putation can be indirect. Because a List is just a selection of text
strings, a choice of a list value can only have a direct relationship
to the outcome of a computation.
It is not possible to make a blanket statement that Classifications are
better than Lists or that Lists are better than Classifications. The bet-
ter choice depends on the application and the field. Be sure to con-
sider all of the pros and cons before deciding.

164 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Units of Measure
Number fields have a unit of measure associated with them. The unit
of measure is associated with a Number field as part of its definition.
The definition of a Number field is discussed on page 136.
A number’s unit may be displayed in a form or not. Figure 3-40 shows
an example of a form that displays some numbers with units of mea-
sure.

Figure 3-40. Example of Numbers Displayed with Unit of Measure

The units of measure are displayed as the selected item in a list. The
list contains other units of measure that are used to measure the
same kind of thing. In Figure 3-40, the kind of thing being measured is
length. Some of the other units of measure in the list are feet, yards,
meters and centimeters.
When a form is initially displayed, it shows numbers with the unit of
measure that they are stored with. Because the Width and Height
fields in Figure 3-40 initially display with inches selected, we know
that these numbers are stored as inches.
If we select a different unit of measure, the number is converted to
the selected unit of measure. For example if we change the unit
shown in Figure 3-40 for Width from inches to centimeters, the num-
ber changes from 7 to 17.78. You will need to save the record before
the conversion applies.
When someone enters a value for a number and selects its unit of
measure, that number and the selected unit of measure are stored in
the record’s field.

© Copyright IBM Corporation 2011. Units of Measure | 165

 Based on the IBM TRIRIGA Application Platform’s ability to handle dif-
ferent kinds of measurements, we see that it knows about different
kinds of measurement such as length, angles, and mass. It knows
about specific units used for each kind of measurement. For example
it knows that length is measured in units such as inches, feet, yards,
meters and kilometers. It knows that area is measured in units such as
acres and square yards. It is also clear that it knows how to convert
between different units that measure the same kind of thing.
The IBM TRIRIGA Application Platform uses two kinds of records to
represent its knowledge about units of measure:
• records are used to describe kinds of things that can be
UOM_Type
measured.
• UOM_Values records are used to describe actual units of measure
and how to convert between them.
The IBM TRIRIGA Application Platform comes with records that
describe most common kinds of measurements and most common
units of measure. If all the kinds of measurement and units of mea-
sure your application will need are already in the IBM TRIRIGA Appli-
cation Platform, feel free to skip ahead to “Number Formats” on
page 174.
If your application needs to use measurements that are not already in
the IBM TRIRIGA Application Platform environment, read the next sec-
tion, “Managing Units of Measure”.

166 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Managing Units of Measure
Both kinds of records used to represent knowledge about measure-
ments can be found by navigating to Tools > Administration > Unit of
Measure (UOM). Clicking Types brings up a list of existing UOM types,
as shown in Figure 3-41.

Figure 3-41. Managing UOM Types

We will explain how to add a new kind of measurement and units of

measure by working through an example. The kind of measurement
will be Digital Data. The units of measure will be byte, kilobyte,
megabyte, gigabyte, etc.
To add a new kind of measurement, click the Add action, which
causes a UOM_Type form to appear, as shown in Figure 3-42.

Figure 3-42. UOM_Type

© Copyright IBM Corporation 2011. Units of Measure | 167

 Put the name of the kind of measurement in the field labeled UOM
Type. This is the only field we need to fill in at this time.
UOM Type Code is a read-only field. It is used internally by the IBM
TRIRIGA Application Platform.
The Base UOM field will be filled in automatically when we create the
first unit of measure for Digital Data. The unit of measure whose name
appears in the Base UOM field is used to organize conversions
between different units of measure.
TIP: In the unlikely event that you have an invalid Base UOM for a
UOM Type, the system may not function properly. If the following SQL
returns any UOM Types, it is an indication that the UOM Type has an
invalid Base UOM and should be fixed:
SELECT * FROM uom_types a WHERE base_uom IS NOT
NULL AND base_uom != '' AND NOT EXISTS
(SELECT 'x' FROM uom_values b WHERE a.UOM_TYPE_
CODE = b.UOM_TYPE_CODE and a.base_uom = b.UOM_
VALUE)
One way to organize conversions between different units of measure
is as a matrix like the one in Figure 3-43. This organization supplies a
conversion factor to convert from every unit of measure to every
other unit of measure.
To
Bytes Kilobytes Megabytes Gigabytes
Bytes 1 0.0009765625 0.00000095367431640625 0.000000000931322574615
478515625
From Kilobytes 1024 1 0.0009765625 0.00000095367431640625
Megabytes 1048576 1024 1 0.0009765625
Gigabytes 1073741824 1048576 1024 1
Figure 3-43. Digital Data Unit Conversion Matrix

Using this matrix organization, to convert from one unit to another,

find the correct conversion factor and multiply by it. For example, to
convert from gigabytes to kilobytes, the table shown in Figure 3-43
tells us to multiply by 1048576.
The unfortunate thing about this organization is that it may require an
unreasonably large number of conversion factors. The example in
Figure 3-43 has 4 units of measure and requires 16 conversion fac-
tors. This is not so bad, but it gets worse with more units. For exam-

168 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

ple, 10 units require 100 conversion factors, whereas 25 units require
625 conversion factors!
To avoid needing so many conversion factors, the IBM TRIRIGA Appli-
cation Platform uses a different organization that requires only one
column of the matrix. The unit of measure that corresponds to the
matrix column we choose to use is called the base UOM.
Using this organization, conversion from one unit to another is done
by first converting from the original unit of measure to the base UOM.
Then the base UOM is converted to the target unit. The conversion
from the base unit to the target unit is done by dividing by the con-
version factor instead of multiplying. We will make this clearer by
working through an example.
Suppose we have decided that the base UOM for Digital Data will be
kilobytes and that we want to convert from gigabytes to megabytes.
We would first convert from gigabytes to kilobytes by multiplying by
1048576 and then convert from kilobytes to megabytes by dividing by
1024 like this:
1048576
------------------------ = 1024
1024
This works out the same as if we had set up the entire matrix, at the
expense of needing an extra division.

Be sure you understand the concept of a base UOM before you

define any units of measure for a new type of measurement.
The first unit of measure that you create for a type of mea-
surement will be its base UOM.
In theory, given a set of units used to measure the same kind of thing,
you could you pick any of the units to be the base UOM. Since every
unit can be converted to every other unit, it should work no matter
which unit you pick. However, it turns out that some units may be a
better choice for base UOM than others.
The reason that some units of measure may be a better choice for
base UOM than others has to do with the way the IBM TRIRIGA Appli-
cation Platform stores numbers. There is a limit to the size of num-
ber that it stores. The IBM TRIRIGA Application Platform can store a
number with up to 20 digits to the left of the decimal point and up to
12 digits to the right of the decimal point.

© Copyright IBM Corporation 2011. Units of Measure | 169

 Because of the limitation on the sizes of numbers that the IBM
TRIRIGA Application Platform can store, choose a base UOM that
allows all the conversion factors to be represented exactly. Looking at
the conversion matrix in Figure 3-43 on page 168, we see that con-
verting to megabytes or gigabytes involves conversion factors that
have more than 12 digits to the right of the decimal point. This means
that both megabytes and gigabytes would be bad choices for the base
UOM because the IBM TRIRIGA Application Platform would not be able
to store all the digits of some of the conversion factors. The results of
those conversions would not be correct.
The conversion factors for bytes and kilobytes do fit into what the IBM
TRIRIGA Application Platform can store. This makes either of them a
good choice for base UOM.
Returning to our example, we decide to make Kilobytes the base UOM
for Digital Data. To do this, create a new UOM_Values record. To create
a new UOM_Values record, navigate to Tools > Administration > Unit of
Measure (UOM) > Values. This looks like Figure 3-44.

Figure 3-44. Managing UOM Values

To create a new UOM_Values record, click the Add action. A form

appears that looks like Figure 3-45.
Set the value of the UOM Type field to Digital Data. The system com-
pletes the rest of the General section with information from the UOM_
Type selected.

170 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Figure 3-45. UOM_Values

Next, fill in fields of the UOM Details section, which describes infor-
mation about the unit of measure.
Enter the unit of measure’s name in the UOM field and put the unit of
measure’s abbreviation in the UOM ABBREVIATION field.
The default value for the Conversion Factor field is 1. The value of
Conversion Factor for a base UOM should be 1.
The rest of the fields are not relevant for Kilobytes, so we finish by
clicking the Create action. Kilobytes becomes the base UOM for Digital
Data because it is the first unit of measure defined for Digital Data.
To complete the example, create UOM_Values records to describe bytes,
megabytes, and gigabytes.
There are additional fields in the UOM_Values form that we did not
use to define kilobytes. The first of this is Conversion Offset. The
Conversion Offset field is used to specify a value that needs to be
added before multiplying by the value of the Conversion Factor field.
To see how the Conversion Offset field is used, look at the example of
degrees-fahrenheit. The base unit that the platform uses for temperature
is degrees-celsius. The formula to convert from Fahrenheit to Celsius is
C =  F – 32   5  9 . The record that describes degrees-fahrenheit is shown
in Figure 3-46.

© Copyright IBM Corporation 2011. Units of Measure | 171

 Figure 3-46. degrees-fahrenheit

The remaining fields are most often used with units of money (cur-
rency), but may be used for any kind of unit.
The value of the Display Mask field is used to determine how num-
bers with the unit of measure will be formatted when displayed. If no
value is supplied for the Display Mask field, default formatting is
used. The default formatting follows these rules:
• If a number is negative, it is formatted with a minus sign (-) at the
beginning.
• The number will be formatted with no leading zeros, unless the
magnitude of the number is less than 1. If the magnitude of the
number is less than 1, then there will be one leading zero.
• If the number has a fractional part, it will be formatted with a
decimal point followed by one or more digits.
• If a number has a fractional part, it will be formatted with only as
many digits after the decimal point as are needed. It will have no
trailing zeros.
• If a value has more digits to the right of the decimal place than
shown in the Display Mask property, the platform defaults to using
ROUND_HALF_UP to round the value in the display.

Here are examples of numbers with default formatting:

0 -2 34
-0.234 0.234 123.4565

172 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

See “Number Formats” on page 174 for a description of the values to
put in the Display Mask field to control the display formatting of num-
bers.
Storage Precision defines how many decimal places the platform is to
use when computing and storing numbers defined with this UOM.
Enter the number of digits to the right of the decimal point. The max-
imum value is 12.
In Rounding Rule specify the rounding rule to be applied when round-
ing numbers to the number of decimal places in Storage Precision.
The default value is ROUND_HALF_UP. The options are as follows:
• ROUND_CEILING
Round the fractional digit so the value moves toward positive
infinity. For example, if Storage Precision is 2, 1.234 => 1.24, 1.12
=> 1.13, -1.234 => -1.23.
• ROUND_DOWN
Round the fractional digit so the value moves toward zero. The
operation effectively truncates the value at the number of deci-
mal places in Storage Precision. For example, if Storage Precision
is 2, 1.2345 => 1.23, 1.328 => 1.32, -2.125 => -2.12.
• ROUND_FLOOR
Round the fractional digit so the value moves toward negative
infinity. For example, if Storage Precision is 2, 1.234 => 1.23, 1.
236 => 1.23, 1.235 => 1.23, -1.234 => -1.24.
• ROUND_HALF_DOWN
Round the fractional digit using the digit to the right to deter-
mine the direction of the round. If the digit to the right is 6 or
greater, round up. If the digit to the right is 5 or less, round
down. For example, if Storage Precision is 2, 1.234 => 1.23, 1.236
=> 1.24, 1.235 => 1.23, 1.23 => 1.23.
• ROUND_HALF_EVEN
Round the fractional digit up or down as needed to make it even.
For example, if Storage Precision is 2, 1.234 => 1.23, 1.236 => 1.
24, 1.235 => 1.24, 1.245 => 1.24, 1.23 => 1.23.
• ROUND_HALF_UP
Round the fractional digit using the digit to the right to deter-
mine the direction of the round. If the digit to the right is 5 or
greater, round up. If the digit to the right is 4 or less, round
down. For example, if Storage Precision is 2, 1.234 => 1.23, 1.236
=> 1.24, 1.235 => 1.24, 1.23 => 1.23.

© Copyright IBM Corporation 2011. Units of Measure | 173

 • ROUND _UP
Round the fractional digit so the value moves away from zero. For
example, if Storage Precision is 2, 1.234 => 1.24, 1.23 => 1.23, -1.
234 => -1.24.
The UOM Decimal field controls the formatting of numbers that con-
tain a decimal point. If no value is in the UOM Decimal field, a period
(.) will be used to indicate a decimal point. If a value is in the UOM
Decimal field, that value is used as the decimal point. This is useful
for formatting numbers for countries that use a comma (,) as a deci-
mal point.
The value of the Currency Symbol field is not used in the IBM TRIRIGA
Application Platform. If the value of the Display Mask field specifies
that numbers should be formatted with a currency symbol, it will
always use a dollar sign ($) for the currency symbol.
The value in the Display Mask field may indicate that the digits of a
number should be separated in to groups like this: 123,456,789. If no
value is specified in the UOM Delimiter field, the character used to
separate groups of digits is a comma (,). If a value is specified in the
UOM Delimiter field, that value is used instead of a comma to sepa-
rate groups of digits. This is useful for formatting numbers for coun-
tries that use a period (.) or a space to separate groups of digits.

Number Formats
The value supplied for the Display Mask field of the UOM_Values form
or the Number field form is used to determine the way that numbers
with the unit of measure are formatted when displayed. The format-
ting in a Number field takes precedence over UOM formatting when
displaying Number fields in query reports or forms. If a value has more
digits to the right of the decimal place than shown in the Display Mask
property, the platform uses Round Half Up to round the value in the
display.
The value supplied for the Display Mask field is treated as a sequence
of characters with each character having a particular meaning. Differ-
ent characters have different meanings in a format. The following
explains how formats work one character at a time.
The first character is 0 (zero). A zero is used to indicate a position
that contains a digit. If a number has a format that consists of a

174 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

sequence of zeros, it will be formatted to have at least that many dig-
its. This is shown in the example in Figure 3-47.
Value Format Formatted Value
0 000 000
3 000 003
45 000 045
678 000 678
12345 000 12345

Figure 3-47. Numbers Formatted with 000

Another character that has a special meaning in a number format is #

(known as hash mark, number sign or octothorp). A # is used to indi-
cate a position in a format that can contain a digit or a space. If a
position that corresponds to a # would contain a leading zero, then it
contains a space; otherwise it contains a digit. Figure 3-48 shows
some examples of numbers formatted with combinations of # and 0.
Value Format Formatted Value
0 ##0 0
0 #00 00
0 ###
3 ##0 3
45 ##0 45
678 ##0 678
12345 ##0 12345

Figure 3-48. Numbers Formatted with # and 0

A number format may contain one period to indicate a decimal point

in formatted numbers. Figure 3-49 shows some example formats with
a period.
Value Format Formatted Value
0 ##0.000 0.000
123.453 ##0 123
123.453 ##0. 123.
123.453 ##0.0 123.5
123.453 ##0.00 123.45
123.453 ##0.000 123.453
123.453 ##0.0000 123.4530

Figure 3-49. Numbers Formatted with a Decimal Point

© Copyright IBM Corporation 2011. Units of Measure | 175

 If a format does not allow enough digits after the decimal point to
express a number exactly, the number is rounded to fit within the for-
mat. If there are more zeros after the decimal point in the format
than are needed to represent a number exactly, the number is for-
matted with trailing zeros.
Use # after the decimal point to avoid trailing zeros. There are exam-
ples of this in Figure 3-50.
Value Format Formatted Value
0 ##0.0## 0.0
123 ##0.0## 123.0
123.4 ##0.0## 123.4
123.45 ##0.0## 123.45
123.453 ##0.0## 123.453
123.4538 ##0.0## 123.454

Figure 3-50. Numbers Formatted to Avoid Trailing Zeros

A comma (,) can be used to specify that the digits in a formatted

number should be divided into groups. Figure 3-51 has examples of
this.
Notice that if a number is longer than the format, the separation of
digits into groups continues with groups the same size. The size of the
groups can be three, four, or any other size that is desired. The last
example in Figure 3-51 shows digits formatted into groups of four.
Value Format Formatted Value
0 #,###,### 0
123 #,###,### 123
1234 #,###,### 1,234
123456 #,###,### 123,456
1234567 #,###,### 1,234,567
1234567890 #,###,### 1,234,567,890
1234567890 ####,#### 12,3456,7890

Figure 3-51. Numbers Formatted to Group Digits

Use an E to indicate numbers should be formatted using scientific

notation. Figure 3-52 shows some examples of this.
Do not use a comma (,) and an E in the same number format.

176 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

 Value Format Formatted Value
1234 0.###E0 1.234E3
0.00123 00.###E0 12.3E-4

Figure 3-52. Numbers Formatted to use Scientific Notation

Put a % (percent sign) or ‰ (per-mill sign) at the beginning or end of

number pattern. These characters are displayed as themselves. A %
has the affect of multiplying the formatted version of the number by
100. A ‰ has the affect of multiplying the formatted version of the
number by 1,000. Examples of these are shown in Figure 3-53.
Value Format Formatted Value
0.8432 0.#### 0.8432
0.8432 ##0.0#% 84.32%
0.8432 %##0.0# %84.32
0.8432 ##0.0#‰ 843.2 ‰
0.8432 %##0.0# ‰843.2

Figure 3-53. Numbers Formatted with Percent and Per-Mill

Do not use both a % (percent sign) and a ‰ (per-mill sign) in the same
number format.
Use a ¤ (currency sign) at the beginning or end of a number format to
indicate that a currency symbol should be in the formatted number.
This is always $ (dollar sign). Figure 3-54 shows some examples of
this.
Value Format Formatted Value
1234.5 ¤#,##0.00 $1,234.50
1234.5 #,##0.00¤ 1,234.50$

Figure 3-54. Numbers Formatted with Currency Symbol

Characters that have no special meaning in a number format can be at

the beginning or end of a number format. Such characters are just
copied into formatted numbers. This is shown in Figure 3-55.
Value Format Formatted Value
1234.5 **###0.00** **1234.50**

Figure 3-55. Numbers Formatted with Non-Special Characters

Number formats can specify how negative numbers are to be format-

ted. If a number format does not specify how negative numbers will

© Copyright IBM Corporation 2011. Units of Measure | 177

 be formatted, then a negative number is formatted the same as a pos-
itive number with a minus sign before it.
You can explicitly specify a how negative numbers are to be format-
ted by following the number format with a ; (semicolon) followed by
another number format that specifies formatting for negative num-
bers. This is shown in Figure 3-56.
Value Format Formatted Value
1234.5 #,##0.00 1,234.50
-1234.5 #,##0.00 -1,234.50
1234.5 #,##0.00;(#,##0.00) 1,234.50
-1234.5 #,##0.00;(#,##0.00) (1,234.50)

Figure 3-56. Numbers Formatted to with Semicolon

Use a ' (single quote) to indicate that the character following it should
not be treated with any special meaning, for example, for literal sym-
bols. Figure 3-57 shows some examples of this.
Value Format Formatted Value
12 '#0 #12
12 #0 o''clock 12 o'clock

Figure 3-57. Numbers Formatted with Single Quote

Money
Units that are used to measure things like length, volume, and tem-
perature have something in common. The conversion factors between
units used to measure each of these things do not change. Units that
are used to measure money are different.
The conversions between different currencies that countries use to
measure money change over time. Hence, IBM TRIRIGA treats curren-
cies differently from other kinds of measurements.
Evaluate your use of currencies during implementation and add or
remove currencies pertinent to your company needs prior to adding
data records. Failure to do so before creating records could cause
conversion issues or data loss on those records.
The IBM TRIRIGA Application Platform allows you to maintain conver-
sion rates between different currencies that apply only to a range of
time that you specify. To manage conversion rates for currencies, you
use the Currency Conversion Manager.

178 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

To access the Currency Conversion Manager, navigate to Tools >
Administration > Currency Conversions. The Currency Conversion Man-
ager looks like Figure 3-58.

Figure 3-58. Currency Conversion Manager

Each conversion rate is from one particular currency to another par-

ticular currency. Each conversion rate applies only to transactions
that occur between a specified start time and end time.
The conversion rates you enter into the Currency Conversion Manager
are used when the IBM TRIRIGA Application Platform generates finan-
cial transactions. Financial transactions are discussed in the book
Application Building for the IBM TRIRIGA Application Platform 3: Cal-
culations.
Conversion rates are also used when computing the value to automati-
cally put in a base currency field. Base currency fields are discussed
in the next part of this chapter.
Another use for conversion rates is with formulas. The conversion
rates that are used are determined by the mapping properties of the
business object that contains the field that the formula is for. Map-
ping properties for selecting conversion rates are discussed on
page 181. Formulas are discussed on page 184.
Manually entering conversion rates into the Currency Conversion Man-
ager may not be convenient. It is common to automate the process by
having another program feed conversion rates to the IBM TRIRIGA
Application Platform by using IBM TRIRIGA Connector for Business
Applications. For further information, see IBM TRIRIGA Connector for
Business Applications 3 Technical Specifications.

© Copyright IBM Corporation 2011. Units of Measure | 179

 Base Currency Fields
Some organizations need to track monetary amounts in different cur-
rencies. However, the organization’s accounting practices may
require that all monetary amounts be converted to a common cur-
rency that the organization uses internally for its accounting. This
common currency used for accounting purposes is usually called the
base currency.
The IBM TRIRIGA Application Platform has features to support the use
of a base currency. The support for a base currency is accomplished
using these features of the platform:
• Establish the currency that will be used as the base currency. Set
this from the platform’s administrative interface as one of its con-
figuration properties. The platform is shipped with this value set
to US Dollars.
The name of the property that controls the base currency is
BaseCurrency. It is in the TRIRIGAWEB.properties file. The details of
how to use the platform’s administrative interface to set the
value of configuration properties are described in the book IBM
TRIRIGA Application Platform 3 Administrator Console User Guide.
• For each number field whose UOM may be a different currency
from the base currency, create a corresponding base currency
field. The base currency field will contain the amount in the main
field converted to the base currency.
The details of how to create a base currency field are described in
the next part of this chapter.
• Edit the mapping properties of the business object that contains
the fields to be converted and their corresponding base currency
fields. The details of how to edit these mapping properties are
described on page 181.

Creating a Base Currency Field

To create a base currency field, begin by editing the properties of the
field to which the base currency field will correspond. Editing field
properties is discussed on page 36 under the heading “Specifying
Fields”.
You can create a base currency field for a Number field only if the
value of its UOM List property is Currency. When the value of a Num-
ber field’s UOM List property is Currency, a property that is otherwise

180 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

hidden appears under the UOM List property. The name of this prop-
erty is Create Base Field.
The Create Base Field property contains a check box. If the check
box in the Create Base Field property is checked, then when the
properties for the field are saved a base currency field will be cre-
ated for this field. The name of the base currency field will be the
name of the corresponding field followed by Base.
For example, suppose that the name of a field is CanadianCost and we
check its Create Base Field check box. When we save the field’s
properties, a base currency field named CanadianCostBase will be cre-
ated if it did not already exist.
When someone enters a value into the CanadianCost field, that value is
converted to the base currency. The converted value is stored in the
CanadianCostBase field.

It is common not to include base currency fields in forms (discussed in

Chapter 6) that are used to edit records. Usually the people entering
data in currencies other than the base currency do not need to see
the amount converted into the base currency and may find it confus-
ing.
If you do include a base currency field in a form, it should be read-
only. Allowing a base currency field to be set directly from a form
defeats the fundamental purpose of the base currency field.

Mapping Properties for Base Currency

The platform can perform automatic currency conversions for base
currency fields and for the results of a formula. To convert curren-
cies, the platform must use a conversion rate in the Currency Conver-
sion Manager (described on page 178 under the heading “Money”).
To select a conversion rate, the platform needs to know more than
just the currencies it is converting to and from. It also needs the
name of a conversion group and a date. You provide the platform with
this information through the mapping properties of the business
object that contains the field that is the destination of the converted
amount.
To access a business object’s mapping properties, navigate to the
Data Modeler. Select the business object. Go to the Data Modeler’s
Tools menu and click its BO Mapping menu item. Clicking the BO
Mapping menu item causes the business object’s mapping properties

© Copyright IBM Corporation 2011. Units of Measure | 181

 to appear in the Data Modeler’s Property panel. When a business
object’s mapping properties appear they look like Figure 3-59.

Figure 3-59. Initial Mapping Properties

There are two mapping properties related to currency conversion. The

value of the Conversion Group property is used to determine the con-
version group that the conversion rate should be found in. This is done
indirectly.
The value of the Conversion Group property is the name of a List
field in the business object. The drop-down list in the Conversion
Group property contains the names of the List fields in the business
object. The value of the list field named by the Conversion Group
property is treated as the name of the conversion group that the con-
version rate must belong to.
To make this work, you will need to add a list to the List Manager that
contains the names of the conversion groups that may be used for this
purpose. The List Manager is described on page 127.
The other mapping property that is related to currency conversion is
the Exchange Date property. The value of the Exchange Date prop-
erty is used to determined the date for the conversion rate.
The value of the Exchange Date property is the name of a Date and
Time field or the name of a Date field. The drop-down list in the

182 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

Exchange Date property contains the names of the Date fields and
Date and Time fields in the business object. The value of the field
named by the Exchange Date property is the date that is used to
select the conversion rate.
If these properties are not specified the platform will use the
“Default” Conversion Group and the date/time that the record is
saved as the Exchanged Date.

© Copyright IBM Corporation 2011. Units of Measure | 183

 Formulas
Some kinds of fields can have their value determined by a simple for-
mula. The simple formula mechanism works about the same way for
each data type it can be used with.
There also is an extended formula mechanism. Extended formulas are
more powerful and complicated than simple formulas. Extended for-
mulas are described in the book Application Building for the IBM
TRIRIGA Application Platform 3: Calculations. The following para-
graphs describe simple formulas.
A simple formula determines the value of a field from the values of
other fields in the same record. For example, we may want to have a
formula determine when a training session will end based on the time
that it starts and its duration.
Some formulas may involve the use of a constant. For example, you
may want the amount of money you budget for a certain kind of
project to be 10% greater than the estimated amount. To do this, we
need to multiply by 1.1. Simple formulas work with fields, not con-
stants, so we cannot put 1.1 directly in a simple formula.
What you can do is add to the business object a read-only field that
has a default value of 1.1. You would not normally include such a
field in a user interface. Generally, creating fields that are constants
is not a good idea since the system will have to store the value for
each record that is created.
Now that you know what simple formulas can do, we are ready to look
at the mechanics of specifying a simple formula. Though some details
vary from one data type to another, the idea is that you select a field
and then an operator and then a field until you have entered the
entire formula. To make this clearer, we will work through the exam-
ple of defining a field to contain a budget amount that is 10% more
than an estimated amount.
Let us suppose a business object named RepairProject already has a field
named EstimatedCost to contain the estimated cost of a repair. Also sup-
pose that the business object has a read-only field named ErrorMargin
whose value is 1.1. We want to define a field named BudgetCost that
will contain the budget amount. Check the Formula check box and
selected the Regular Formula Type.

184 | Chapter 3: Data Types © Copyright IBM Corporation 2011.

To enter the formula, click the first Find hyperlink. Clicking the Find
hyperlink causes a form to appear under the field’s properties that
allows us to select a field.
To select a field, first select the section that contains the field. If the
field is not in a section, select the name General. Next, select the
field. Following this procedure, we select the General section and then
the Error Margin field. Finish by clicking the Accept action.
Operators are selected from the drop-down list to the right of the
field we just found. Select * (indicating multiplication) from the drop-
down list.
Repeat the process of selecting a field to select the EstimatedCost field.
When the value of a field is computed by a formula, you may want the
field’s unit of measure to be determined by the one of the fields that
the formula uses. In this case, we want this field to have the same
unit of measure as the EstimatedCost field; set the value of the UOM
Source Attribute property to Estimated Cost.

© Copyright IBM Corporation 2011. Formulas | 185

186 | Chapter 3: Data Types © Copyright IBM Corporation 2011.
Chapter 1
In this chapter: CHAPTER 4
• How the life cycle of a
record is managed.
• The relationship between a
record’s life cycle and its
Life Cycles
behavior.

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:

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

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

Published The book has been published.

Abandoned Publication of the book has been abandoned.

Out of Print The book was published but is no longer being published.

The state of a record changes in response to an action. We will illus-

trate 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

© Copyright IBM Corporation 2011. 187

 is in prepublication, its release may be delayed for marketing pur-
poses. 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 aban-
doned 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 relation-
ships are usually much easier to understand when they appear in a
diagram. Figure 4-1 shows a type of diagram called a life cycle dia-
gram that illustrates the relationship between the states and events
discussed in the preceding paragraph.

Figure 4-1. Sample Life Cycle Diagram

The boxes in Figure 4-1 represent the states of the record. The verti-
cal 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 this 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

188 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

fields. Read more about workflows in Chapter 5, “Overview of Work-
flows”.

Life Cycle Transitions

Every state in a life cycle has a set of state transition actions associ-
ated with it. When a record is being edited by a form, the state tran-
sition 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 Condi-
tions” on page 208 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 vs. Asyn-
chronous Workflows” on page 207 for a discussion.
The same state transition action name may have a different meaning
depending on a record’s state. In Figure 4-1, 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 Aban-
doned. 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.

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 Figure 4-2 on page 190.
We will explain how to use the State Transitions panel by working
through an example. The example is the creation of a state transition

© Copyright IBM Corporation 2011. Specifying State Transition Actions | 189

 Figure 4-2. Initial State Transition Window

family for a cstBook business object that will model the life cycle
shown in Figure 4-1 on page 188.
As you can see in Figure 4-2, when you start from nothing*, a new
business object’s state transition family is created with a single state
named null.

The 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 indi-
cate 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 transi-
tion 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.

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
Figure 4-3.

* The alternatives to starting from nothing are described on page 196 under the heading
“Reusing Existing Transition Families”.

190 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

Figure 4-3. State Transitions Panel with Second State

The new state has no name. When new states are added, they auto-
matically 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

© Copyright IBM Corporation 2011. Specifying State Transition Actions | 191

 cstWorkInProgress state. The State Transitions panel now looks like
Figure 4-4.

Figure 4-4. 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.
Actions of the same name will trigger the same event. If you want
the same labeled action to trigger different asynchronous work-
flows, use a different Action name in this field.
Use the naming conventions in “Naming Conventions” on page 13.
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 differ-
ent labels.

192 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

Class or Ejb Name
This field is used to integrate a state transition action with a
piece of the IBM TRIRIGA Application Platform’s internal logic.
You should not put a value in this field unless specifically told to
do so by this book.
Method Name
This field is used to integrate a state transition action with a
piece of the IBM TRIRIGA Application Platform’s internal logic.
You should not put a value in this field unless specifically told to
do so by IBM TRIRIGA’s support personnel or this book.
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 on page 198, 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 discus-
sion at “Default Display” on page 374. 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 page 375
for more details on the effect of this property.

© Copyright IBM Corporation 2011. Specifying State Transition Actions | 193

 Fill in the fields shown in Figure 4-4 on page 192, 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 Figure 4-5.

Figure 4-5. 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 Figure 4-6.

Figure 4-6. Life Cycle Diagram with Abandoned State Added

Build the rest of the state transition family. The completed life cycle
diagram looks like Figure 4-1 on page 188.
When you are finished entering the states and state transition actions,
click Save to save the diagram. Click Cancel to close the state transi-
tion diagram.
The following reviews the remaining actions in the upper right hand
corner:
Print
This action allows you to print the contents of the state transition
diagram.

194 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

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 opti-
mal readability. Starting in IBM TRIRIGA Application Platform 3.0,
the states retain their ordering when you click Save, and the pre-
vious 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 on page 196. Note that, unlike Autosort, the sys-
tem saves the results of this action to the database.

Scrolling the Life Cycle Diagram

A life cycle diagram can grow wider and/or taller than the Data Mod-
eler 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 dia-
gram.

Important State Family 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 transi-
tion actions, sub actions, and the like.
The editor will not allow you to create a technically invalid state fam-
ily. 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:
• There are two actions that save the state of the diagram. The
Apply on the left side saves individual states and state transition

© Copyright IBM Corporation 2011. Important State Family Tips | 195

 actions. The Save on the upper right saves the whole state transi-
tion family.
• 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.
• A valid state family consists of the following:
• At least two states, the first of which is named null. Remem-
ber 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 spe-
cial characters in the names).
• No “island” states, except in state family templates.
• 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.

Reusing Existing Transition Families

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 fam-
ily. There are three ways to begin with an existing state transition
family:
• 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.
• If you want to start out with a copy of a different business
Figure 4-7. Import from Business
object’s state transition family, click the State Transition panel’s
Object
Import action and select the Import from Business Object menu
item. The Import menu looks like Figure 4-7.
• 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.

196 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

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 busi-
ness 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 Figure 4-8.

Figure 4-8. 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 that looks
like Figure 4-9.

Figure 4-9. Window to Add Business Object Information to a Transition

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

© Copyright IBM Corporation 2011. Sub Actions | 197

 text will be used instead of the label specified for the state tran-
sition 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.
NOTE: If you plan on having only one sub action associated to a
state transition that the labels on both be the same.
If a workflow triggers a state transition action, and that action
has multiple sub actions, only the first sub action will be exe-
cuted, 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.
Workflow Select
Use this field to associate a synchronous workflow with this state
transition action. Workflows are discussed in Chapter 5 and Chap-
ter 7. The specified workflow is launched when the state transi-
tion action is triggered.
Log
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 work-
ing 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. It looks like Figure 4-10 on page 199. After the initial business
object-specific information has been saved, the SubAction Label win-
dow 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.

198 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

 Figure 4-10. Window to Edit Business Object Information for a Transition
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 Exclu-
sion 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 dis-
played.
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 exclu-
sions on the sub action.

© Copyright IBM Corporation 2011. Sub Actions | 199

 For example, the state transition family for triContractLineItem in triCos-
tItem, shown in Figure 4-11 on page 200, reflects a standard pattern
used in the platform. In this Edit Hidden example, the ability to edit a

Figure 4-11. State Transitions Panel for Hidden Sub Action

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

200 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

Hidden actions cannot be initiated from a menu. However, a hidden
action can be initiated from a workflow. Actions in general are dis-
cussed in more detail in “Actions” on page 339.
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 trig-
gered. 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.
You can see the initial appearance of this section in Figure 4-10 on
page 199. 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 looks like Figure 4-12.

Figure 4-12. State Transition Attribute Window

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

© Copyright IBM Corporation 2011. Sub Actions | 201

 field(s) appear in the State Transition Attribute section of the SubAc-
tion Label Details window, as shown in Figure 4-13.

Figure 4-13. SubAction Label 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.
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. It looks like Figure 4-14. State transition

202 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.

actions that have business object-specific information associated with
them are a different shade of gray.

Figure 4-14. State Transition with Business Object-Specific Information

© Copyright IBM Corporation 2011. Sub Actions | 203

204 | Chapter 4: Life Cycles © Copyright IBM Corporation 2011.
Chapter 1
In this chapter: CHAPTER 5
• Concepts important for
understanding workflows.
Overview of Workflows

The IBM TRIRIGA Application Platform allows you to add your business
logic to your applications by creating a workflow. Workflows can be
created to define any business process associated with the system or
the business objects created in the system. A number of pre-defined
workflows are delivered with the IBM TRIRIGA applications. This chap-
ter is an overview of major concepts involved in creating workflows.
There is some discussion of how to connect workflows to other parts
of an application. Most other details about workflows are in Chapter
7.
This chapter covers the following topics:
• The sorts of things that workflows are commonly used for, begin-
ning on page 206.
• “Synchronous vs. Asynchronous Workflows” describes how work-
flows can be made to run while a person waits or in the back-
ground without making anyone wait for the workflow to finish and
begins on page 207.
• “Launch Conditions” begins on page 208 and describes various
things that can cause a workflow to run.
• “Organizing a Workflow into Tasks” describes how workflows are
organized into simple steps and begins on page 210.
• How workflows use data values in records in the database and
data values input by a person editing the fields of a form can be
found in “Temporary vs. Permanent Data” beginning on page 211.
• “System Events” on page 212 describes a system event and the
circumstances under which a system event causes a workflow to
be launched.

© Copyright IBM Corporation 2011. 205

 • “Transaction Scope and Processing” defines a Transaction and
how it can be used in a workflow. See page 214.
• Workflows can define and use workflow variables and pass values
to and return values from a called workflow, as described in
“Variables, Parameters, and Return Values” starting on page 216.
• Asynchronous workflows can use the Integration property to
migrate data from staging tables into IBM TRIRIGA records. This is
used extensively in IBM TRIRIGA DataConnect. See “Integration”
starting on page 399.

Identifying Needs for Workflows

The first thing you should understand about workflows is what they
are used for. It is not possible to present you with a complete list,
because there is an almost limitless range of things that can be done.
Here are some common uses for workflows:
• A workflow can be used to set the values in the fields of a new
record. Formulas (discussed in Chapter 4) are a simpler and eas-
ier way to initialize the values of fields, but there are computa-
tions a workflow can do that a formula cannot.
There is no guarantee of the order in which formulas are com-
puted. If you need initial values for fields computed in a certain
order, you must use a workflow.
• You can use workflows to vary the appearance of a form based on
the contents of underlying records or a user’s actions.
• You can use workflows to validate the contents of a form before
saving its contents.
• You can use workflows to perform computations to set the values
of fields in a record. You can also use workflows to perform com-
putations that affect just the fields in a form.
• You can use workflows to create or manipulate records without
requiring any interaction with a person.
• You can use workflows to route work to people. This can be done
entirely within the IBM TRIRIGA Application Platform by having
workflows put action items in a person’s portal (portals are
described in IBM TRIRIGA Application Platform 3 User Experience
User Guide).
Workflows can also route work to people working outside the plat-
form by copying data from records into a spreadsheet and e-mail-
ing it to someone. A workflow can then receive an e-mailed

206 | Chapter 5: Overview of Workflows © Copyright IBM Corporation 2011.

 spreadsheet that a person has worked on and copy its data into
records.

Synchronous vs. Asynchronous

Workflows
One of the key properties of a workflow is whether it is synchronous
or asynchronous. If a workflow is synchronous, it means that if the
workflow is launched in response to something that a user did in the
user interface, the workflow will begin executing immediately; the
user has to wait for the workflow to finish before doing anything else.
If a workflow is asynchronous, it means that the workflow is launched
in response to an event that has occurred in the system. When it
launches depends on its position in the workflow queue. For exam-
ple, if the workflow is launched in response to an event that a user
triggered in the user interface, the workflow may not start executing
immediately; the user can do something else immediately without
waiting for the workflow to finish.
Whether a workflow is synchronous or asynchronous is determined by
the value of its Concurrence property (described on page 395). In
addition to synchronous and asynchronous, the Concurrence property
includes a value named subflow. A subflow workflow is a special type
of synchronous workflow that allows required parameters. A subflow
is special because the only way it can be used is from a Call Workflow
task.
Although workflows marked asynchronous are executed asynchro-
nously (from the event that triggered it), workflows that are marked
synchronous can be executed a number of ways. Synchronous work-
flows are executed in-line with whatever caused it to be executed,
and the process causing it will wait until the workflow has finished
before it continues. In the case of a form action causing the workflow
to run, it means that control will not be returned to the user until the
workflow completes.
A workflow that is marked synchronous can also be called. If it is
called from an asynchronous workflow, it will be executed as part of
that asynchronous process. So workflows that are marked asynchro-
nous are pretty clear, but synchronous really means “executed in-line
with the process invoking it”.

© Copyright IBM Corporation 2011. Synchronous vs. Asynchronous Workflows | 207

 Launch Conditions
There are a number of ways a workflow can be launched. The ways
that a workflow can be launched are determined by whether it is syn-
chronous, subflow, or asynchronous. The distinction between synchro-
nous and asynchronous is explained on page 207 in the preceding part
Launching More of this chapter. Subflow workflows are described in detail in the
Than One Way description of the Start task on page 394.
The IBM TRIRIGA Application Asynchronous workflows are launched in response to an event occur-
Platform allows each work-
ring on a business object. A workflow is registered for a given event/
flow to be launched only in
one way. If you want a work-
business object combination using the Event property in the workflow
flow to be launched in more Start task. There are two types of events: events generated by state
than one way, there is a transition actions, and system events, such as user sign in, scheduled
workaround to this limita- event start, or a DataConnect Job being executed.
tion.
The workflow Event property is discussed on page 394. The Start task
If you want to launch a is described on page 394. State transition actions are discussed in
workflow in two different Chapter 4. DataConnect is discussed in the DataConnect chapter in
ways, write two other work- Application Building for the IBM TRIRIGA Application Platform 3: Data
flows that will be launched Management.
in each of the ways that you
want the real workflow to Asynchronous workflows are not directly connected to a state transi-
be launched. All that these tion action. Instead, they may be connected to events that corre-
other workflows need to do spond to the name of the state transition actions. When a state
is call the desired workflow. transition action is triggered on a record an event of the same name is
registered in the system event queue for that record. If an asynchro-
nous workflow exists that corresponds to the business object of the
record and event in the queue, the system launches the workflow.
The diagram in Figure 5-1 on page 209 illustrates the order in which
things occur when state transition actions that invoke workflows are
triggered.
An asynchronous workflow also can be launched by a system event.
System events are things that happen to records that may not be the
direct result of an action by a user. For example, when a record
becomes de-associated from another record there is a system event.
System events are discussed more fully on page 212.
These are the ways a synchronous workflow can be launched:
• A synchronous workflow can be launched from a sub action
attached to a state transition action. Sub actions are discussed on
page 197.

208 | Chapter 5: Overview of Workflows © Copyright IBM Corporation 2011.

Figure 5-1. When State Transitions that Invoke Workflows Are Triggered

• A synchronous workflow can be launched from an action a user

performed on a part of a form. Form actions include actions that
appear at the top of a section, actions that are triggered when a
button is pressed, and actions that are triggered when the value
of a field changes. Form actions are discussed in Chapter 6.
• A synchronous workflow can be launched when a record is cre-
ated. The way to specify that a workflow should be launched in
this way is by the business object’s Pre-Create Workflow prop-
erty, which is described on page 34.
• A synchronous workflow can be launched prior to popping up a
form to edit a record. The way to specify that a workflow should
be launched in this way is described on page 231 under the head-
ing “Pre-Load Workflow”.
• A synchronous workflow can be launched from another workflow
by using a Call Workflow task. Call Workflow tasks are described
on page 543.

© Copyright IBM Corporation 2011. Launch Conditions | 209

 • A synchronous workflow can be launched from certain navigation
items. See the IBM TRIRIGA Application Platform 3 User Experi-
ence User Guide.
• A synchronous workflow can be launched from a report or query.
Configuring actions to be launched from a report or query is dis-
cussed in the IBM TRIRIGA Application Platform 3 Reporting User
Guide.
You can make the launch of a workflow conditional on such things as
the contents of its record, the state of the record, or the current
time. These conditions that you can impose on the launch of a work-
flow are called the workflow’s start conditions. The details of how to
do this are discussed on page 401.

Organizing a Workflow into Tasks

Workflows are organized into simple pieces called tasks. There are
different kinds of workflow tasks. Each kind of workflow task does
something different. For example, there are workflow tasks to create
a record, change the contents of a record and create associations
between records.
Workflow tasks are described in Chapter 7. You can find a complete
list of workflow tasks on page 393.
By arranging different types of workflow tasks into a suitable order
and specifying the correct properties for each task, you can create a
workflow that is capable of performing whatever business logic is
needed.
Each kind of workflow task has a properties form associated with it
that allows you to specify details of what the task will do. These
properties typically include as how to find the record(s) that the task
will work with, computations it should perform with the found
record(s), or how it should modify the contents of the record(s).
There are a few fundamental techniques for arranging the order of
workflow tasks. The most basic technique is to organize tasks into a
simple sequence where after each task there is one other task that
will be the next task performed.
Sometimes you want more than one task that can immediately follow
a particular task. There are two kinds of workflow tasks you can use
this way.

210 | Chapter 5: Overview of Workflows © Copyright IBM Corporation 2011.

 • A Switch workflow task causes one of two sequences of tasks to be
performed, based on whether a condition is true or false. Switch
workflow tasks are described on page 519.
• A Fork workflow task defines two or more sequences that can be
performed at the same time. Fork workflow tasks are described
on page 530.
Sometimes you will want a sequence of tasks to be performed multi-
ple times. There are three kinds of workflow tasks you can use to
cause a sequence of tasks to be repeated multiple times.
• The Loop task is a general purpose task for repeating a sequence
of tasks for any reason. Loop tasks are described on page 533.
• The Iterator task is a simpler and more specialized kind of loop. It
is used to repeat a sequence of tasks once for each record associ-
ated with a preceding task. Iterator tasks are described on
page 540.
• A DataConnect workflow task gets a set of records from the desig-
nated staging table and acts as an iterator to create or update a
record for each row in the staging table and to run the body of
the task for each row. DataConnect workflow tasks are described
on page 561.
Sometimes you want to reuse some business logic or have some busi-
ness logic be shared by workflows. You can organize workflows to do
these things by having one workflow call another workflow. There are
two kinds of workflow tasks available for this purpose:
• Workflows can use the Call Workflow task to launch synchronous
workflows. The Call Workflow task is discussed on page 543.
• The Trigger Action workflow task triggers actions which in turn
cause events that can cause asynchronous workflows to be
launched. The Trigger Action workflow task is discussed on
page 473.

Temporary vs. Permanent Data

The data that workflows normally deal with is considered to be per-
manent data. Permanent data is the values in records that are kept in
the database indefinitely. While a record is being edited with a form,
a temporary version of a record’s permanent data is used. As a per-
son edits the fields of a form, the temporary data is updated. The
permanent data is not affected by the edits until the edits are saved.

© Copyright IBM Corporation 2011. Temporary vs. Permanent Data | 211

 A workflow can access a record’s temporary data if the workflow is
synchronous and the value of the workflow’s Temporary Data prop-
Start Conditions erty is Temporary. A workflow can use a Get Temp Record task to
access a record’s temporary data. The Get Temp Record task is
Temporary Data described on page 575.
and Workflows
Once a workflow has access to a record’s temporary data, it can mod-
Sometimes you will have a ify the temporary data. Some other possibilities are for the workflow
synchronous workflow that is
to perform calculations based on the temporary data or to change the
launched from an action or
button on a form whose job it appearance of the form based on the values in the temporary data.
is to save temporary data to A workflow uses a Modify Metadata task to modify the appearance of
permanent. Such buttons or
a form. The Modify Metadata task is described on page 511.
actions typically have a label
such as Save or Ok. A workflow can use its ability to change the appearance of a form to
When people click an action tell a person about any problems with data entered into the form.
with such a label, they Also, if there are no problems with data, the workflow can save the
expect that the data will be temporary data. A Save Permanent task updates the contents of a
saved. There may be legiti- record with the values in its temporary data. The Save Permanent
mate reasons for the work- task is described on page 578.
flow not to save the data. For
example, some fields may
have inconsistent values. If
such a workflow decides not
System Events
to save data, it should do As mentioned earlier, one of the ways that an asynchronous workflow
something to inform the user
can be launched is for a system event to happen to a record. When a
that the data was not saved.
It should never be a surprise
system event happens to a record, if there are any workflows associ-
that the data was not saved. ated with the system event and the business object that was used to
create the record, then those workflows are launched.
For these reasons, putting
start conditions on this sort Here is a list of the different kinds of system events and an explana-
of workflow is a bad thing to tion of what they mean:
do in this situation. If the
Associate
workflow does not run
because its start conditions An Associate system event happens to a record when it becomes
are not satisfied, a user will associated with another record. When a workflow is launched as a
have no way of knowing. result of an Associate system event, the other record that the
To handle this, let the work-
record is becoming associated with is accessible from the work-
flow run, have it detect a flow’s tasks as the Secondary BO of the workflow’s Start task.
reason it should not save the De-Associate
data and then set a visible A De-Associate
system event happens to a record when its associa-
status indicator so that the tion with a record is removed. When a workflow is launched as a
user will be aware of the
result of a De-Associate system event happening to a record, the
problem and that the data
was not saved. record that was on the other end of the association is accessible
from the workflow’s tasks as the Secondary BO of the workflow’s
Start task.

212 | Chapter 5: Overview of Workflows © Copyright IBM Corporation 2011.

 There are two other situations in which a De-Associate system event
happens to a record:
• If a record is removed from a smart section, that triggers a De-
Associate system event even though its association with the
record that contains the section still exists.
• An association may indicate that a record’s existence is
dependant on another record. If a record is deleted because a
record it depends on deleted, a De-Associate system event hap-
pens to the dependant record.
SCHEVENTCREATE
A SCHEVENTCREATE system event happens to a record when a time-
based event is scheduled to happen to the record. Time-based
events are discussed in Chapter 10.
SCHEVENTEND
A SCHEVENTEND system event happens to a record at the end of a
time based event that happens to a record. Time-based events
are discussed in Chapter 10.
SCHEVENTSTART
A SCHEVENTSTART system event happens to a record at the start of a
time-based event that happens to a record. Time-based events
are discussed in Chapter 10.
SYSTEM DC PROCESS JOB
This event is used by the DataConnect Agent when a DataConnect
Job is ready to execute. The agent triggers the workflow associ-
ated to the corresponding DataConnect Job record and the SYSTEM
DC PROCESS JOB event.
WF Q Accept
A WF Q Acceptsystem event happens to a record when a recipient
accepts an action item associated with the record.
WF DELETE FROM MGR
A DELETE FROM MGR system event happens to a record when it is
deleted using a system delete from a navigation item or a report
action. Navigation items are discussed in the IBM TRIRIGA Applica-
tion Platform 3 User Experience User Guide. Reports are dis-
cussed in the IBM TRIRIGA Application Platform 3 Reporting User
Guide.
WF USER LOGIN
For every login ID in the IBM TRIRIGA Application Platform, there
is a corresponding My Profile record to describe the login ID. When a
person signs in, a WF USER LOGIN system event happens to the
person’s My Profile record.

© Copyright IBM Corporation 2011. System Events | 213

 WF USER LOGOUT
For every login ID in the IBM TRIRIGA Application Platform, there
is a corresponding My Profile record to describe the login ID. When a
person signs out, a WF USER LOGOUT system event happens to the
person’s My Profile record.
WF WIZARD CANCEL
A WF WIZARD CANCEL system event happens to a record when a user
editing the record closes the form.

Transaction Scope and Processing

In a workflow, most task steps are processed in their own scope. If
there are no problems affecting successful processing, a task step per-
forms its database operations and the workflow’s processing moves to
the next task step and that task step processes as a unit. This contin-
ues through the entire workflow and provides data integrity within
the task step, but it does not allow transactions that span task steps.
Note that for Iterator and Loop tasks there are no transactions that
span any or all of the iterations of the tasks within a given Iterator or
Loop. Also, for tasks such as Associate Records or a task that works on
a set of records and causes changes, where there may be more than
one record modified by a single task step, each record that is modi-
fied is processed individually within its own transaction.
The DataConnect, Create Record, and Modify Records tasks can be
configured to use transactions during the processing of the task. The
DataConnect task includes a Transaction parameter that is used to
enable transactions. Within a DataConnect task, the Transaction
parameter determines how the business object record is committed.
The Transaction parameter values are part of the description of the
DataConnect workflow task that starts on page 561.
When nested DataConnect tasks exist, the outermost task is in con-
trol of the transaction for that task and all nested tasks, regardless of
how the nested tasks are configured. That outermost task is known as
the Controlling Block. Transaction setting is valid only on the outer-
most DataConnect task with a Transaction setting (All Iterations, Per X
Iterations). If the Transaction parameter is set to None, the DataCon-
nect task processes the same as other workflow tasks.
The Create Record and Modify Records workflow tasks, like the Data-
Connect task, have Transaction properties available that can be used
to enable transactions. Within a Create Record task or Modify Records

214 | Chapter 5: Overview of Workflows © Copyright IBM Corporation 2011.

task, the Transaction parameter determines how the business object
record is created. The Transaction parameter values are part of the
description of the Create Record task that starts on page 416 and of
the Modify Records task that starts on page 432
When the Transaction parameter is set to None, the DataConnect, Cre-
ate Record, or Modify Records task processes the same as other work-
flow tasks. It is only when the Transaction parameter has another
value that a transaction is used across multiple tasks (DataConnect) or
multiple records (Create Record and Modify Records).
A transaction is committed if everything processes correctly within
the controlling block and is rolled back if an error that would compro-
mise data integrity is encountered.
There are two ways a transaction can be committed:
• The controlling block is exited successfully.
• A looping type controlling block successfully reaches the end of an
iteration that meets the transaction criteria (number of itera-
tions) configured for the transaction block.
A block is successfully exited if it:
• Meets the exit criteria without encountering a fatal error or a pro-
cessing condition (task) that rolls back the transaction.
• Encounters an End task within the block before encountering a
condition causes a rollback.
• Breaks out of a controlling block with a state of Success.
A transaction is rolled back if the controlling block does not complete
successfully. The following cause unsuccessful completion of a block:
• Encountering a non-recoverable error within the block (this
includes non-recoverable errors anywhere within the block or any-
where within nested blocks).
• Encountering a Stop task within the block (this includes Stop tasks
within nested blocks).
• Breaking out of, or Continuing, a controlling block with state of
Error.

© Copyright IBM Corporation 2011. Transaction Scope and Processing | 215

 Variables, Parameters, and Return
Values
Task steps within a workflow can refer to other task steps for data
values to be used in processing. Workflow variables provide another
way to access these data values. Once a workflow variable is assigned
a value from a task step another task step can reference the variable
and use the data just as it would have referenced the task step.
Referring to a variable rather than directly to a task step can some-
times allow for better workflow structure and a reduction in repeated
logic.

216 | Chapter 5: Overview of Workflows © Copyright IBM Corporation 2011.

Figure 5-2 shows a simplistic example of using a variable.

Figure 5-2. Simple Example Using A Variable

In this example, before the condition step, a workflow variable VAR1

is defined. After STEP-A and STEP-B, variable VAR1 is set to be a copy
of their result. STEP-C is defined to reference variable VAR1 rather
than the actual task step, allowing STEP-C to exist a single time
within the workflow while being able to use the result of either STEP-
A or STEP-B depending on which was executed.
In many business processes there is logic that is the same or very simi-
lar. To avoid duplicating the steps needed to perform the logic in
each of the workflows that make up the process, those common steps
can be broken out into a shared workflow that each of the others can

© Copyright IBM Corporation 2011. Variables, Parameters, and Return Values | 217
 call. Duplicating common logic makes it harder to maintain the pro-
cessing logic and can lead to subtle differences in the way two simi-
lar business processes behave.
To allow these workflows to have access to all of the information
needed they can be defined to accept one or more parameters (as
workflow variables). They can also be defined to return one or more
results to the calling workflow (as workflow variables). This makes it
possible to break out common business logic into a shared workflow
that can be called with a set of workflow variable parameters that
have been set within the calling workflow. Upon return from the
called workflow, a set of workflow variables can be set containing the
return information. The calling workflow can then access the returned
values as variables.
Workflow parameters and return values are one or more workflow
variables that can be selected in the Start task to identify them as
being parameters and/or return values. Asynchronous workflows can-
not use parameters and return values. Synchronous workflows allow
optional parameters while Subflow workflows allow either optional or
required parameters.
More information can be found in the descriptions of the Start task
(page 394), Call Workflow task (page 543), Variable Definition task
(page 568), and Variable Assignment task (page 570) in “Creating
Workflows,” Chapter 7.

218 | Chapter 5: Overview of Workflows © Copyright IBM Corporation 2011.

Chapter 1\
In this chapter: CHAPTER 6
• How to define and lay out
forms.
• Defining and managing
business processes.
Building User
Interfaces

The IBM TRIRIGA Application Platform provides a tool named Form

Builder for defining forms to create, view, and edit the contents of
records. To get to the Form Builder, navigate to Tools > Builder Tools
> Form Builder, as shown in Figure 6-1.

Figure 6-1. Form Builder

Each form is associated with a business object. The Form Builder

organizes forms by the module that contains their associated business
object. The left side of the Form Builder is a list of modules with a
radio button next to each module. Selecting a radio button selects the
corresponding module. The right side of the Form Builder lists the
forms associated with the selected module.

© Copyright IBM Corporation 2011. 219

 The list of forms on the right side of the Form Builder is organized
into these columns:
Name
This is the name that is used in workflows to uniquely identify the
form. This name is unique within a module.
Label
This is the string that identifies the form in the user interface.
Business Object
The name of the business object the form is associated with.
Status
This is the status of the form. For an explanation, see page 9
under the heading “Create-Publish-Revise Cycle”.
The actions that appear at the top of the Form Builder when it first
appears are always displayed at the top of the Form Builder:
Style Sheet Editor
Clicking this action pops up the Style Sheet Editor, which is a tool
for editing style attributes that may be common to many forms.
The Style Sheet Editor is described in “Style Sheets” in the “Brand
with Colors and Logos” chapter of the IBM TRIRIGA Application
Platform 3 User Experience User Guide.
Where Used
If you select the radio button for a form and then click this
action, a window pops up showing what references or uses the
selected form. The fields displayed are: Name, Type (e.g., Query,
Workflow, Nav Item), Module, Object, Form, Action, and Addi-
tional Information.
If you want to export the information in the Where Used window,
click the Export Usage action at the top of the window. You will
be offered the choice of saving or opening a csv file.
Refer to page 46 for a list of references reported by Where Used.
New
Clicking this action pops up a window that allows you to specify
the properties of a new form. The new form will be associated
with the currently selected module.
Open
If you select the radio button for a form and then click this
action, a window pops up to allow you to edit the properties of
the selected form.

220 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 It is usually easier just to click the name of the form, which
causes the same window to pop up.
Copy
If you select the radio button for a form and then click this
action, a copy of the selected form is created.
Delete
If you select the radio button for a form and then click this
action, the selected form is deleted.
Data Modeler
Clicking this action is a convenient way to navigate to the Data
Modeler tool from the Form Builder. The Data Modeler is
described in Chapter 2.
Additional actions appear at the top of the Form Builder when you
select the radio button to the left of a form’s name. Which additional
actions appear depend on the form’s status.
If you select the radio button for a form in Created or Revision In
Progress status, one additional action appears to the right of the
Delete action, as shown in Figure 6-2. The label of this action is
Publish. Clicking the Publish action causes the selected form to be
published. Publishing is explained on page 9 under the heading
“Create-Publish-Revise Cycle”.

Figure 6-2. Actions for Created and Revision In Progress Forms

If you select the radio button to the left of a form whose status is
Published, the actions at the top of the Form Builder will look like
Figure 6-3.

Figure 6-3. Actions for Published Forms

These additional actions appear at the top of the Form Builder:

Report Header
This action is used to create a raw template for a form report.
Form reports and this action are described in the IBM TRIRIGA
Application Platform 3 Reporting User Guide.

© Copyright IBM Corporation 2011. Building User Interfaces | 221

 ADO XML v2
This action is used for the integration between the IBM TRIRIGA
Application Platform and Crystal Reports to help configure Crystal
Reports to produce a form report. This is explained in the IBM
TRIRIGA Application Platform 3 IBM TRIRIGA Connector for SAP
BusinessObjects User Guide.
ADO XMLv1
This action is used for the integration between the IBM TRIRIGA
Application Platform and Crystal Reports to help configure Crystal
Reports to produce a form report. This is explained in the IBM
TRIRIGA Application Platform 3 IBM TRIRIGA Connector for SAP
BusinessObjects User Guide.
Revise
This action appears to the right of the Delete action.
Clicking this action changes the state of the selected form to
Revision in Progress and pops up a window that allows you to edit
the properties of the selected form. Revision is explained on
page 9 under the heading “Create-Publish-Revise Cycle”.
The rest of this chapter is about how to configure a form. Most of the
discussion assumes that you are creating a new form. Differences will
be noted in those few places where editing an existing form is differ-
ent from creating a new one.

222 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Structure of Forms
A form is organized in a hierarchy. Each part of the hierarchy has its
own properties. When you create a form, you generally specify the
structure and properties of its hierarchy starting at the top and work-
ing down to the lowest details.
These are the types of components that appear in the structure of a
form:
Form
The form contains one or more tabs. Forms and their properties
are described in greater detail on page 224 under the heading
“Form”.
Tab
Top-level tabs are directly contained by a form. Other tabs can be
contained by a multi tab section (described on page 324). More
than one tab can be under the same form or section. However,
the contents of only one tab under the same form or section is
visible at one time. When you select a tab, its contents become
visible and the contents of other tabs under the same form or sec-
tion are not visible.
A tab contains one or more sections.
Tabs are described in greater detail on page 233.
Section
A tab contains one or more sections. Each section in a tab usually
displays different information, though this is not required. The
sections of a tab are different in their purpose than sections in a
record. The basic purpose of sections in a record is to contain
data. The basic purpose of sections in a tab is the presentation of
data, even though it is possible to use the sections of a tab as
containers for temporary data. Temporary data is described in
Chapter 8.
Different kinds of sections are used to display different kinds of
information in different ways. A summary of the different types of
sections appears on page 238 under the heading “Overview of Sec-
tions”.
Field and Buttons
Some types of sections can contain fields or buttons. Fields and
buttons are at the bottom of the hierarchy. A field contains an
individual piece of information. A button does not contain any
information but can trigger an action when clicked.

© Copyright IBM Corporation 2011. Structure of Forms | 223

 Fields are described on page 247. Buttons are described on
page 262.
The structure described in the preceding paragraphs is the internal
presentation structure of the form. For forms that are used to present
records that are part of a hierarchy, there is also an external presen-
tation structure used to determine what forms will be used to look at
other records in the hierarchy. This external presentation structure is
discussed on page 368 under the heading “Includes/Forms”.

Form
When you create a new form, the window to configure its properties
pops up. This window is called a Form Wizard. It looks like Figure 6-4.
Initially, three tabs are visible:
• The Layout tab is used to specify the internal presentation struc-
ture of the form.
• The Includes/Forms tab is used for two separate purposes. It is
used to describe the external presentation structure of forms for
records that are part of a hierarchy, for example Classifications.
This use of the Includes/Forms tab is described on page 368 under
the heading “Includes/Forms”.
The Includes/Forms tab is also used to specify which form reports
may be used in a Reports tab in the form. Form reports are
described in the IBM TRIRIGA Application Platform 3 Reporting
User Guide. Reports tabs are described on page 232 under the
heading “Show Reports”.
• The State Transition tab is used to manage the state-based
actions. This is described on page 370.
The following additional actions appear at the top of the Layout tab:
Reset
Changes the form back to what it looked like the last time it was
saved, including window size.
View
Presents a drop-down list of Form Builder sections. Click one to
add it to the Form Builder display.
Preview
Renders the form in its current state.

224 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Figure 6-4. Form Wizard for Editing a New Form

Validate
When selected, the platform checks the section for the following
and displays any errors.
• Duplicate fields on a tab.
• Duplicate sections on a tab.
If it is a Group By section, the platform also checks the following:
• Group By field set on the section.
• Only one Group By field set on the section.

© Copyright IBM Corporation 2011. Form | 225

 • Only one Group By order field set on the section.
• Group By field is visible in the form.
• Group By field is either a text field or a locator field.
• Group By section has a query defined.
• Group By section query has a primary business object set.
• Group By section fields are all Display Columns in the query.
(WARNING)
• Group By section columns are the same fields in the same
order as the query’s Order By.
• Query used by Group By section does not have Group By col-
umns set. (WARNING)
• If Group By field is a locator, the referenced business object
has the Group By Columns on it. (ERROR)
• If the Group By Columns Start Columns are equally dispersed.
(WARNING)
• If there are no Group By Columns.
The following sections of this chapter describe how to specify the
internal presentation structure of a form. This is followed by a discus-
sion of how to specify the external presentation structure and then
state-based actions.

226 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Laying Out a Form’s Structure
The Layout tab is used to specify the internal presentation structure
of the form. Its Navigation panel shows the organization of the form’s
internal presentation structure. When a form is first being created, all
that is in the Navigation panel is an icon that represents the root of
the hierarchy that is the internal structure.
A sample Navigation panel is shown in Figure 6-5. The operation of
the Navigation panel is similar to panels in other platform tools that
display a tree. Each part of the tree or node is displayed with a name
on the right and an icon on the left. If a node has other nodes under
it, clicking the node’s icon will alternately expose and hide the nodes
under it. Clicking the name of the node will select it so you can work
with its properties or other aspects. Figure 6-5. Navigation Panel
The label displayed next to the root icon is initially Form. The label
Form is just a placeholder that is used until you specify what the
name of the form will be. After you specify that, the name of the
form replaces the label Form.
The Layout panel displays a mock-up of the form being specified. It
will help you see how the internal structure you specify lays out on
the screen.
When you are just beginning to create a form, the Layout panel is
blank. As you fill in the structure of the form, you will see the Layout
panel filled in.
The Layout panel shows a mock-up of the form based solely on its
internal presentation structure. Some aspects of a form’s appearance
are not based on its internal structure, such as the presence of an
Associations tab. Clicking the Preview action at the top of the win-
dow causes a preview window to pop up that presents a mock-up of
the form that includes things like the Associations tab that are not
part of the form’s internal presentation structure. In preview mode,
the system does not render a report in a report section; instead it dis-
plays “Report Section”.
The Properties panel shows the properties of whatever component of
the form’s internal structure is selected in the Navigation panel. Ini-
tially the form is the selected component, so initially the Properties
panel shows the properties of the form.
The Components panel displays a list of fields or sections from busi-
ness objects that is available for inclusion in a section.

© Copyright IBM Corporation 2011. Laying Out a Form’s Structure | 227

 When you create a new form, first specify the properties for the
form. You will not be able to save a new form until you have speci-
fied values for its Business Object and Name properties.
After you have saved the form for the first time, it will have a Publish
action at the top of the Layout tab. Clicking the Publish action will
publish the form. While the state of the form is published, the top of
the Layout tab will not have a Publish action, but it will have a
Revise action that you will be able to click to revise the form. Publi-
cation and revision are described on page 9 under the heading
“Create-Publish-Revise Cycle”.

228 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Form Properties
When you select the form in the Form Wizard’s Navigation panel, the
Properties panel looks like Figure 6-6.

Figure 6-6. Form Properties

Here are descriptions of the properties for a form:

Business Object
The value of this property is the name of the business object that
the form is associated with.
When you are creating a new form, this property has no value.
Select its value from a drop-down list of the business objects in
the module with which the new form is associated.

© Copyright IBM Corporation 2011. Form Properties | 229

 You cannot save a new form without first specifying the value of
this property. After the first time the new form is saved, this
property is grayed out and you cannot change it.
Name
The value of this property is the name that uniquely identifies the
form. People using applications do not see this name.
When you are creating a new form this property has no value. You
must enter a name.
You cannot save a new form without first specifying the value of
this property.
Label
The value of this property is the text displayed to identify this
form to people using applications.
Description
Enter a description of the form.
Default Form
Since multiple forms can be associated with the same business
object, it is convenient to identify one form as the default for a
business object. Checking the check box for this property identi-
fies this form as the default for its associated business object.
This check box has some special behavior. If this check box is
checked when you save the form properties, it becomes grayed
out. You cannot uncheck it in the usual way. The way to uncheck
this check box is to make a different form associated with the
same business object the default form.
Single Tab
If this check box is not checked and the form has multiple top-
level tabs, a portion of the window that the form is displayed in
will be used to display things a person can click to navigate from
one tab to another.
If this check box is checked, nothing is displayed to allow a per-
son to explicitly navigate from one tab to another. It is up to you,
the person who is specifying the internal presentation structure of
the form, to insure that appropriate actions are available in each
tab to navigate to other tabs in the form.
When you save a form with the Single Tab property checked and
then view the form state transition diagram, there will be an
additional attribute, Show Tab. This allows an application builder
to define multiple tabs on the form and use specific state transi-
tions to determine which tab will be visible to the user.

230 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 This check box will not be visible if the specified business object
was specified with its Show Single Tab check box not checked. A
business object’s Show Single Tab check box is described on
page 31.
Pre-Load Workflow
If this property has a value, it is the name of a synchronous work-
flow. The synchronous workflow named by this property is
launched just before a form described by this form becomes visi-
ble, unless the record is being created for the very first time. Such
workflows are used to do any last minute bookkeeping or fix-ups
of records the form will display.
Synchronous workflows are discussed on page 207 under the head-
ing “Synchronous vs. Asynchronous Workflows”.
Allow to Bookmark to create record
If this check box is checked, this form will be bookmarkable. See
the “Bookmarking in Forms” on page 233 for more details on this
property.
Allow to Bookmark to specific record
If this check box is checked, specific records created from this
form will be bookmarkable. See the “Bookmarking in Forms” on
page 233 for more details on this property. Note that in order to
have records from this form show up in a Last Visited portal sec-
tion, this property must be checked.
Calculate Excel
If this check box is not checked, then if this form contains any
Excel sections (described on page 291), the calculations in each
Excel section will be performed only if someone clicks the action
at the top of the Excel section.
If this check box is checked, clicking any state transition action in
the form that saves data will cause the Excel calculations to be
done first.
Show Association
If this check box is checked, the form will include an Associations
tab. An Associations tab graphically shows a record’s associations
with other records. It also allows people to create and remove
associations between records.
The Associations tab will be present at runtime but will not be
part of the form’s internal presentation structure. It will not be
visible in the Navigation panel, but it will be visible in the pre-

© Copyright IBM Corporation 2011. Form Properties | 231

 view window that pops up when you click the Preview action at
the top of the Form Wizard’s Layout tab.
Show Workflow Instance
If this check box is checked, the form will include a Work Flow
Instance tab. A Work Flow Instance tab shows workflow instances
that are associated with a record. Work Flow Instance tabs are
discussed in greater detail on page 695 under the heading “Work-
flow Instances”.
The Work Flow Instance tab will be present at runtime but will
not be part of the form’s internal presentation structure. It will
not be visible in the Navigation panel, but it will be visible in the
preview window that pops up when you click the Preview action
above the Properties panel.
Show Reports
If this check box is checked, the form will include a Reports tab.
A Reports tab allows users to view the content of a record as a
form report. A form report can be in any format that can be cre-
ated using Microsoft Word or Excel or an external report. Form
reports are discussed in the IBM TRIRIGA Application Platform 3
Reporting User Guide.
The Reports tab will be present at runtime but will not be part of
the form’s internal presentation structure. It will not be visible in
the Navigation panel, but it will be visible in the preview window
that pops up when you click the Preview action above the
Properties panel.
Show Audit
This property is visible only if the business object associated with
the form has the check box checked in its Audit Access or Audit
Data Changes property.
If the check box in this property is checked, the form will have an
automatically generated Audit tab. Auditing records and the
Audit tab are discussed on page 686 under the heading “Audit
Trail”.
Show Audit Actions
This property is visible only if the business object associated with
the form has the check box checked in its Audit Actions property.
If the check box in this property is checked, the form will have an
automatically generated Audit Actions tab. Auditing records and
the Audit Actions tab are discussed on page 686 under the head-
ing “Audit Trail”.

232 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Bookmarking in Forms
The properties for Allow to Bookmark to create record and Allow to
Bookmark to specific record in a particular form allow you to con-
trol whether or not it makes sense to allow bookmarks for these sce-
narios. For example, Figure 6-7 shows an Employee form with both
options checked.

Figure 6-7. Employee Form with Both Bookmark Options Checked

Note that the Bookmark this record option corresponds to the spe-
cific record scenario, and allows the user to bookmark the Andrew
Admin employee record. The Bookmark this form option, on the
other hand, allows the user to bookmark the form itself. In other
words, selecting the form to bookmark means that the user can cre-
ate a new employee through a bookmark link in their My Bookmarks,
as shown in Figure 6-8 on page 234.
Keep in mind that the user would need to have the capability to book-
mark in the first place for these options to be available. See the IBM
TRIRIGA 10 Getting Started User Guide for more information about
bookmarks.

Tabs
A tab is a part of a form. A form contains one or more top-level tabs.
Top-level tabs take up all the available area in the window. Each tab
contains one or more sections. One kind of section a tab can contain
is a multi tab section (described on page 324). A multi tab section

© Copyright IBM Corporation 2011. Form Properties | 233

 Figure 6-8. Bookmark to Form to Create New Employee

contains one or more tabs. Tabs in multi tab sections contain exactly
one section.
More than one tab can be in the same form or section. However, the
contents of only one tab in the same form or section are visible at one
time. When you select a tab, its contents become visible and the con-
tents of other tabs under the same form or section are not visible.
Top-level tabs have their own properties. Tabs in a multi tab section
do not have their own properties; they are controlled by the proper-
ties of the multi tab section that contains them. For a description of
multi tab sections see page 324.
To add a top-level tab to a form, first select the form in the
Navigation panel and then click the Add Tab action that appears at
the top of the Form Wizard’s Layout tab. To delete a top-level tab,
first select the tab in the Navigation panel and then click the Delete
action at the top of the Form Wizard’s Layout tab.
While a top-level tab is selected in the Navigation panel, its proper-
ties appear in the Properties panel. The Properties panel displaying
the properties of a top-level tab is shown in Figure 6-9.

234 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Figure 6-9. Tab Properties

Here are descriptions of a top-level tab’s properties:

Name
The value of this property is the name used by workflows to iden-
tify the tab. This name must be unique within the form.
You cannot save the properties of a new tab until you set its
name. Once you have saved a tab, its Name property becomes
read-only and its value is grayed out.
Label
The value of this property appears as the tab’s label.
Tab Information
The value of this property appears as bold text in parentheses in
the area under the tab followed by a colon. Common values for
this field are Required, Optional, or Summary.
Instruction
This property’s value appears in the area under the tab after the
colon. It should briefly explain the tab’s intended use.
Visible
If this check box is checked, this tab will be visible in the form. If
the check box is not checked, this tab will be hidden. The default
for this property is for the check box to be checked.
Workflows can change the value of this property at runtime, mak-
ing the tab visible or hidden as appropriate.
Access Key
The value of this property identifies a way to navigate directly to
this tab from the keyboard. The value of this property should be a

© Copyright IBM Corporation 2011. Form Properties | 235

 single character. Pressing the ALT key and the specified character
in this form will navigate the user directly to this tab.
Style Class
If you do not specify a value for this property, the appearance of
this tab will be determined by default settings in the Style Man-
ager.
If you do specify a value for this property, it will be the name of a
tab style sheet defined by the Style Sheet Editor. The style sheet
determines the appearance of the label. The Style Sheet Editor is
described in “Style Sheets” in the “Brand with Colors and Logos”
chapter of the IBM TRIRIGA Application Platform 3 User Experi-
ence User Guide.
Custom
If this check box is checked, the IBM TRIRIGA Application Plat-
form will not generate the contents of this tab in the normal way.
Instead, the tab’s contents will be taken from the URL that is the
value of the URL property.
URL
This property is visible only if the check box in the Custom prop-
erty is checked. If the check box in the Custom property is
checked, the contents of the tab will be taken from the URL that
is the value of this property.
In addition to wanting each tab to have appropriate values for its
properties, you will want each tab to contain the appropriate sec-
tions laid out in an appropriate way. Sections are discussed in the fol-
lowing parts of this chapter.

Copy A Tab
You can copy a tab from the current form to another place in the cur-
rent form, to another form in the same business object, or to another
form in a different business object in the same module. Begin by
selecting the tab in the Navigation panel. While the tab is selected,
there is an action labeled Copy Tab at the top of the Form Wizard’s
Layout tab. The purpose of the Copy Tab action is to allow you to
copy the tab and paste it.
When you click the Copy Tab action, the Properties panel changes to
allow you to specify the properties of the tab when it is pasted. The
Properties panel looks like Figure 6-10.
The properties are as follows:

236 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Figure 6-10. Copy Tab Properties

Name
This is the name of the tab in the target form. The default is the
name of the source tab. You cannot use the same name unless you
are copying the tab to a different form. The name must be unique
in the target form.
Target Business Object
This is the business object of the target form. The default is the
business object of the current form. You can copy a tab to a form
in the same business object or in a different business object in the
same module. Select the Target Business Object from the drop-
down list. The list shows all business objects in the same module
as the current form.
Target Form
This is the form into which the tab will be copied. The default is
the current form. You can copy a tab into any form in the
selected Target Business Object. Select the target form from the
drop-down list. The list shows all forms in the target business
object.
Click the Apply action in the Properties panel. The system revises the
target form if necessary and pastes the copied tab as the last tab in
the target form. Be sure to publish the target form.
If the target business object is not the same as the source business
object, the system removes fields, smart section fields, and smart
sections that are not valid in the target business object.
You will see an error message if the tab is not uniquely named within
the target form.

Sort the Tabs

To specify the order in which top-level tabs appear in a form, begin
by selecting the form in the Navigation panel. While the form is
selected, there is an action labeled Sort Tab at the top of the form

© Copyright IBM Corporation 2011. Form Properties | 237

 Wizard’s Layout tab. The purpose of the Sort Tab action is to allow
you to rearrange the order of top-level tabs.
When you click the Sort Tab action, a list of the form’s top-level tabs
appears in the Properties panel. This list looks like Figure 6-11.

The Same Field in

Multiple Tabs
It is sometimes convenient
to include the same record
field in more than one tab.
The Form Builder allows
you to include the same
field in multiple tabs; how-
ever, it will not allow you Figure 6-11. Tab Sort
to have the same field on
the same tab. If that The top-level tabs in the list appear in the same order they will
occurs, you will not be able appear in the form. Click the arrow heads in the first column to move
to publish the form. The
the tabs up or down in the list.
Validate action can help
you find duplicate fields. Remember to save the form before you move on to something else,
otherwise the modified tab order will be lost. Also remember to see
what your tabs look like in the window that pops up when you click
the Preview action. The preview window is a more accurate indica-
tion of what tabs will look like at runtime.

Overview of Sections
You can add a section to a tab by clicking the tab’s name in the
Navigation panel and then clicking the Add Section action.
Sections of a form are used to present information of some sort.
These kinds of sections are used to present different kinds of informa-
tion:
Form Section
A form section can contain fields and buttons. Each field may be
explicitly based on a field in the business object associated with
this form.
Form sections are discussed in greater detail on page 247.

238 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Smart Section
A smart section is connected with a smart section in the business
object associated with the form. A smart section can contain
fields explicitly connected with fields in the business object’s
smart section.
Smart sections are discussed in greater detail on page 268.
Multi Tab Section
A multi tab section cannot directly contain any fields. It can only
contain other sections. A tab is created for each section in a multi
tab section.
Multi tab sections are discussed in greater detail on page 275.
Query Section
A query section displays the results of a query. The query may be
produced by the IBM TRIRIGA Application Platform’s internal
report generator or by an external report generator. See the IBM
TRIRIGA Application Platform 3 Reporting User Guide for details
about building queries.
Query sections are discussed in greater detail on page 277.
Report Section
A report section displays the results of a form report.
Report sections are discussed in greater detail on page 283.
Graphics Section
Graphics sections exist to display a graphic image that is associ-
ated with an organization, geography or location.
Excel Section
Excel sections are used to display an Excel spreadsheet and use
the calculations of the spreadsheet to update fields in other sec-
tions.
Excel sections are discussed in greater detail on page 291.
Gantt Section
Gantt sections are used to display Gantt charts.
Gantt sections are discussed in greater detail on page 297.
Availability Section
Availability sections are used to display the availability of
resources.
Availability sections are discussed in greater detail on page 297.

© Copyright IBM Corporation 2011. Form Properties | 239

 Stacking Section
Stacking sections are used to view current or planned assign-
ments of demand to supply and allow the user to make changes by
moving some of the demand from one location to another.
Stacking sections are discussed in greater detail on page 324.
Group By Section
Group By sections show data in a tabular grid-like format grouped
by the values of a specified field. The data in a Group By section
is sourced from a query.
Group By sections are discussed in greater detail on page 328.
When you create a new section, the first thing you need to do is spec-
ify the type of section it will be. After you click the Add Section
action, the Properties panel looks like Figure 6-12.

Figure 6-12. Properties of a New Section

After you set the value of the Type property, the set of properties
visible below the Type property changes to properties that are appro-
priate for the selected type of section.

240 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

After the first time you save a section’s properties, the Type prop-
erty becomes grayed out and you are no longer able to change its
value.
If the type of section you want to create is a smart section, there is a
shortcut that can save you a few steps. While you are editing the
properties of a tab, the Components panel contains a list of smart
sections in the form’s associated business object. This list of smart
sections looks like Figure 6-13.

Figure 6-13. LIst of Sections in Components Panel

To create smart sections in the currently selected tab that corre-
spond to sections in the associated business object, check the check
box next to each section’s name, then click the Add action. A smart
section will be added to the currently selected tab for each section
selected in the Components panel.
A word about single-record smart sections: To specify that a user can
click a hyperlink to the linked record in a single-record smart section,
check the smart section’s Show Embedded Link check box.

Copy A Section
You can copy a section from the current tab to another place in the
current form. Begin by selecting the section in the Navigation panel.
While the section is selected, there is an action labeled Copy Section
at the top of the Form Wizard’s Layout tab. The purpose of the Copy
Section action is to allow you to copy a section and paste it.
When you click the Copy Section action, the Properties panel
changes to allow you to specify the properties of the section when it
is pasted. The Properties panel looks like Figure 6-14.

© Copyright IBM Corporation 2011. Form Properties | 241

 Figure 6-14. Copy Section Properties

The properties are as follows:

Name
This is the name of the section in the target tab. The default is
the name of the source section. You cannot use the same name
unless you are copying the section to a different tab. The name
must be unique in the target tab.
Target Tab
This is the tab into which the section will be copied. The default
is the current tab. You can copy a section into any tab in the cur-
rent form. Select the target tab from the drop-down list. The list
shows all tabs in the current form.
Click the Apply action in the Properties panel. The system pastes the
copied section as the last section in the target tab. You will see an
error message if the section is not uniquely named within the target
tab.
The Target MultiTab property appears if the source section is not a
multi tab section and the target tab you picked has a multi tab sec-
tion. The Target MultiTab property allows you to place a section into
a multi tab section. You can copy a section from a multi tab section,
copy a section into a multi tab section, or copy an entire multi tab-
section. However, you cannot copy a multi tab section into a multi
tab section.
The system displays an error message if you try to publish a form that
has form fields or form smart sections duplicated on a given tab. Use
the Validate action to help work through fixing those issues.
TIP: To move a section, use a Copy Section and then a Delete.
TIP: To copy a section to another form, use the Copy Tab action to
copy the tab containing the section to the other form and proceed
from there.

242 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Insert A Row
You can insert a row before a section or a field. This provides an easy
way to insert fields/tabs into the middle of an existing layout. Begin
by selecting the section or field in the Navigation panel. While the
section or field is selected, there is an action labeled Insert Row at
the top of the Form Wizard’s Layout tab.
When you select a section and click the Insert Row action, the sys-
tem increments the Start Row property on all sections in the tab from
that section on and refreshes the selection.
When you select a field and click the Insert Row action, the system
increments the Start Row property on all fields in the section from
that field on and refreshes the selection.

Common Section Properties

Many of the properties of a section are the same regardless of the
form type. This section discusses these common properties. The infor-
mation is not repeated in other parts of this user guide except to
highlight a difference from the common property or to add additional
information.
Type
The type of section this will be. Select the value from the drop-
down list: Form Section, Smart Section, Multi Tab Section, Query
Section, Report Section, Graphics Section, Excel Section, Gantt
Section, Availability Section, Stacking Section, or Group By Sec-
tion.
Name
The value of this property is the name that workflows use to iden-
tify the section. It must be unique within the tab that contains it.
Label
The value of this property is the text that will appear in the title
bar at the top of the section.
Height
The number that is the value of this property determines the
height of the area used to display the section. The height is mea-
sured in lines of text. This sets the boundary in which an overflow
of data causes scroll bars to appear.
The default value is 0 (zero), which translates to an initial display
of 10 rows of data with a height of 23 pixels for each row.

© Copyright IBM Corporation 2011. Form Properties | 243

 Title Bar Color
This property usually does not have a value. If this property does
not have a value, the background color of the title bar for this
section will be the default color specified in the Style Manager.
To specify a color, click the icon. A palette of colors will pop
up. After you have selected a color by clicking it, the color pal-
ette disappears and a rectangle of the selected color appears to
the left of the icon. The Advanced color picker also is avail-
able. See “Color” on page 111 for its usage.
Clicking the icon causes the color selection to be cleared, so
that the default color will be used for the title bar.
Visible
If this property’s check box is checked, this section will be visi-
ble. If the check box is not checked, this section will be hidden.
The default for this property is for the check box to be checked.
Workflows can change the value of this property at runtime, mak-
ing the section visible or hidden as appropriate.
Expand Section
This is checked by default. If this check box is checked, the first
time a user uses this form, this section will be expanded by
default. If not checked, the section will be collapsed by default.
Note that for subsequent use of this form, IBM TRIRIGA remem-
bers the state of each section for each user.
Read Only
If this check box is checked, all fields in this section will be read-
only. People will not be allowed to modify the contents of the
fields using the form.
Show Title Bar
This check box is usually checked. If this check box is checked, a
title bar will be displayed above the section. If the check box is
not checked, no title bar will be displayed.
A common reason to leave this check box unchecked is so that
what is internally organized as two sections appears to be one
section.
Border Size
The number that is the value of this property determines the
width of the border around this section.
Border Color
If this property does not have a value, the border around this sec-
tion is the default color specified in the Style Manager.

244 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 To specify a color, click the icon. A palette of colors will pop
up. After you have selected a color by clicking it, the color pal-
ette disappears and a rectangle of the selected color appears to
the left of the icon. The Advanced color picker also is avail-
able. See “Color” on page 111 for its usage.
Clicking the icon causes the color selection to be cleared, so
that the default color will be used for the title bar.
Style Class
If you do not specify a value for this property, the appearance of
this section will be determined by default settings in the Style
Manager.
If you do specify a value for this property, it will be the name of a
section style sheet defined by the Style Sheet Editor. The style
sheet determines the appearance of the label. The Style Sheet
Editor is described in “Style Sheets” in the “Brand with Colors and
Logos” chapter of the IBM TRIRIGA Application Platform 3 User
Experience User Guide.
Start Row
The value of the Start Row property specifies in which of the
tab’s rows this section will appear. The rows in tabs are counted
from the top to the bottom, so row 1 is above row 2. If a section
is more than one row tall, this property specifies in which row of
the tab the top of the section will appear.
The platform uses the absolute value of the number entered.
Row Span
This property specifies the height of the section in rows. For most
sections, the Row Span value is 1.
The Start Column and Col Span properties determine a section’s hori-
zontal position and width within its tab. A tab is laid out in twelve
columns. Most tabs do not look like they are laid out in twelve col-
umns because they do not use all twelve columns. If a tab has no sec-
tions in a column, the column has no width and it looks like the

© Copyright IBM Corporation 2011. Form Properties | 245

 column is not there. Figure 6-15 is a visual explanation of how the val-
ues of the Start Row, Row Span, Start Column and Col Span proper-
ties combine to determine a section’s size and position within a tab.

Start Row = 1, Row Span = 1

Start Column = 1, Column Span = 1
Start Row = 1, Row Span = 2
Start Column = 2, Column Span = 1
Start Row = 2, Row Span = 1
Start Column= 1, Column Span = 1

Start Row = 3, Row Span = 1, Start Column = 1, Column Span = 2

Figure 6-15. Start Row, Row Span, Start Column, Column Span Combinations

246 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Form Sections
A Form section can contain fields and buttons. Each field may be
explicitly based on a field in the associated business object.
If you want fields in the form that are connected to fields in the asso-
ciated business object that are part of a smart section, you must put
those fields in a smart section. Smart sections are discussed on
page 268.
When you are editing a Form section, there are two aspects of the
section you may be concerned with. As with all components, a Form
section has properties you will want to give appropriate values. You
also will want a Form section to contain the appropriate fields and
buttons laid out in the appropriate way.
The properties of a Form section are shown in Figure 6-16 on page
248.
Fields are discussed on page 247. Buttons are discussed on page 265.
“Common Section Properties” on page 243 includes information about
the following properties in a Form section: Type, Name, Label, Title
Bar Color, Visible, Expand Section, Read Only, Show Title Bar, Style
Class, Start Row, Row Span, Start Column, and Col Span.
Once you have set a Form section’s properties to appropriate values,
the usual next step is to add fields to the section and give them an
appropriate layout. Adding fields is discussed in the next part of this
chapter.
Once this section’s fields are set up, you may want to specify what
actions will be available in the section. Actions for sections are dis-
cussed on page 340.

Fields
There are two ways you can edit the properties of a field: You can
click the name of the field in the Navigator panel or add a new field
to a section.
To add a field to a form section or smart section, first click the sec-
tion’s name in the Navigator panel so its properties appear in the
Properties panel. Then click the Add Field action at the top of the
Layout tab.

© Copyright IBM Corporation 2011. Form Properties | 247

 Figure 6-16. Properties of a Form Section
There are three kinds of fields you can add to a section:
• A Data field is a field that is explicitly connected to a field in the
business object with which the form is associated.
• A Form Field is a field that is not explicitly connected to any field
in a business object.
• A Form Action is not really a field. It is a button. It is something
you can put in a section that does not contain data. You can
arrange for a workflow to run when someone clicks a button. But-
tons are described in greater detail on page 265.
If the kind of field you want to add to a section is a Data field, there
is a shortcut that may be less work than clicking the Add Field action.
If you are looking at properties of a section you can add a field to, the
Components panel contains a list of the fields in the form’s associ-

248 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

ated business object that you can use to create a Data field. This list
in the Components panel looks like Figure 6-17. If you check some

Figure 6-17. List of Fields in Components Panel

check boxes in the list and then click the Components panel’s Add
action, Data fields that correspond to record fields whose check box
you checked will be added to the currently selected section in the
form.
When you are editing the properties of a field, the field’s properties
will appear in the Properties panel and look like Figure 6-18 on page
250.
Figure 6-18 shows the properties of a new field, just after someone
has clicked the Add Field action. Additional properties may become
visible as you select values of some of the initially shown properties.
Here are descriptions of the properties:
Type
A field has two properties named Type. This is a description of
the first.
The value of this property determines whether the field is a form
field, a data field, or a button. The value for this field is chosen
from a drop-down list. The possible values are:
Data
If the value of the Field Type property is Data, the field will
be a data field connected to the business object’s field speci-
fied by the Data Field and Data Section properties. All prop-
erties shown in Figure 6-18 will apply to the field.

© Copyright IBM Corporation 2011. Form Properties | 249

 Figure 6-18. Data Field Properties

250 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Form Field
If the value of the Field Type property is Form Field, the field
will be a form field not connected to any business object
field. This is the equivalent of a label and does not let the
user input data.
Form fields are usually used to present instructions or mes-
sages.
Form Action
If the value of the Field Type property is Form Action, the field
will be a button. It will have a different set of properties than
shown in Figure 6-18. Buttons are described on page 262.
After a new field is saved for the first time, the Type property
becomes read-only and is not displayed in the Properties panel.
Data Field
This property is visible only if the value of the Type property is
Data. Otherwise, this property is hidden and does not appear in the
Properties panel.
The value of this property is the name of the business object field
that this data field is connected to. The names of available busi-
ness object fields appear in a drop-down list.
When you select a field from this list, the name of the smart sec-
tion it appears in becomes the value of this field’s Data Section
property. If the business object field is not part of a section, the
value of this field’s Data Section property is set to General.
After a new field is saved for the first time, this property becomes
read-only and its value is grayed out.
Data Section
This property is visible only if the value of the Type property is
Data. Otherwise, this property is hidden and does not appear in the
Properties panel.
The value of this property cannot be set directly, rather it is set
when you select a value for the Data Field property. When you
select a value for the Data Field property, the value of this prop-
erty is set to the name of the smart section that contains the
business object field that is named by the value of the Data Field
property. If the business object field that is named by the value
of the Data Field property is not part of a smart section, the value
of this field is set to General.
After a new field is saved for the first time, this property becomes
read-only and its value is grayed out.

© Copyright IBM Corporation 2011. Form Properties | 251

 Name
The value of this property is the name that workflows can use to
refer to this field. The name must be unique within the section
that contains this field.
After a new field is saved for the first time, this property becomes
read-only and its value is grayed out.
Label
The text that is the value of this property is used as the field’s
label. The property whose value determines the appearance of
the label is the Label Style Class property.
Type
A field has two properties named Type. This is a description of the
second.
If this field is a Data field, this property is read-only and the value
of this property is the data type of the business object field that
this field is connected to.
If this field is a Form Field, the value of this property is always
Label.
If this field is a Form Action, the value of this property is always
Form Action. Refer to the Buttons section on page 265 for informa-
tion about the properties of a Form Action field.
Root Classification
This property is visible only if the value of the second Type field is
Classification. Click the Search icon to select the value.
Lookup Query
This property is visible only if the value of the second Type field is
Classification.
When blank, at runtime the system uses the hierarchy tree to
determine the value.
If a query is present, at runtime the system runs the specified
query to select a value. For the tabout functionality to work, the
query must contain the field triNameTX in TRIRIGA 9.x or IBM
TRIRIGA 10.x or ClassName in TRIRIGA 8x.

252 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Display Type
This property is visible only if the value of the Data Type prop-
erty is Binary. The value of this property can be chosen from two
values in a drop-down list:
Content
If the value of this property is Content, the scrollable area this
field takes up will be used to display whatever rendering of
the binary data the browser is configured to use for the type
of binary data this field has for its value.
Link
If the value of this property is Link, this field will be rendered
as a hyperlink. Clicking the hyperlink will cause the browser
to pop up a separate window to display whatever rendering of
the binary data the browser is configured to use for the type
of binary data this field has for its value.
Icon Position
This property is visible only if the value of the Data Type prop-
erty is a type of field that has icons next to its data area that can
be clicked to set the field’s value, such as Business Object or
Classification. This field may be narrower than the width of the col-
umn it is in. In addition to this field’s label and data areas, it also
has an icon a person can click to set the field’s value.
The value of this property can be chosen from two values in a
drop-down list:
Next to Field
If this property’s value is Next to Field, the icon will be posi-
tioned next to the right side of the field’s data area.
Right Align
If this property’s value is Right Align, the icon will be posi-
tioned next to the right side of the column.
Minimum Size
The value of this property determines the minimum number of
characters that must be entered into this field for the value in the
field to be considered valid.
Maximum Size
The value of this property determines the maximum number of
characters that may be entered into this field for the value in the
field to be considered valid. If the value of this property is 0,
there is no maximum allowed number of characters. Note, the

© Copyright IBM Corporation 2011. Form Properties | 253

 Size property of the field from the Data Modeler will override this
value if it is less then the Maximum Size.
Score Type
This property is visible only if the value of the Type field is Num-
ber, Financial Rollup, or Classification Rollup and the field is defined in
the Data Modeler as a scored number field (as described on
page 139). The value of this property can be chosen from a drop-
down list containing the following:
• Number Value Only
Display the number value of the field only and not the score
image.
• Score Image Only
Display the score image only and not the number value of the
field.
• Both
Display both the score image and the number value of the
field.
Delta Type
This property is visible only if the value of the second Type field is
Number, Financial Rollup, or Classification Rollup and the field belongs to
an enabled vertical comparison section (as described on
page 270).
The delta value is the difference between this field’s value in this
record and its value in the compare to record. This value is not
stored; it is only a runtime calculation for viewing the data.
The values of the Delta Type property are as follows:
• No Delta
The delta value is not displayed in the vertical comparison
section.
• Numeric Delta
The delta value displayed will be numeric and is calculated by
subtracting the value of the record being compared from the
compare to record’s value.
• Percent Delta
The delta value displayed will be numeric and is calculated by
subtracting the compare to record’s value from the value of
the record being compared and dividing the result by the com-
pare to record’s value.

254 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Delta Precision
This property is visible only if the value of the Type field is Num-
ber, Financial Rollup, or Classification Rollup and the field belongs to an
enabled vertical comparison section (as described on page 270).
The Delta Precision property defines how many decimal places
the platform is to use when computing and displaying the delta
value for this field. Enter the number of digits to the right of the
decimal point. The maximum value is 5.
Use Custom Display Mask
This property specifies whether or not this field’s display mask
uses the Display Mask property defined for the business object or
the UOM.
When Use Custom Display Mask is not checked, the platform uses
the display mask defined on the business object or UOM.
When the Use Custom Display Mask property is checked, the Dis-
play Mask property is visible and set to the value defined on the
business object or UOM. Changing the Display Mask property only
affects this field. See the definition of Display Mask on page 137.
The chart on page 140 describes the Display Mask property over-
ride relationship.
If a value has more digits to the right of the decimal place than
shown in the Display Mask property, the platform uses Round Half
Up to round the value in the display.
Input Width
The value of this property determines whether this field will be
displayed with its natural width or the full width of the column it
occupies.
A text field with its Maximum Size property set to 0 has no natu-
ral width. However, many fields do have a natural width. For
example, a text field with its Maximum Size property set to 15 has
a natural width wide enough to hold 15 characters. Some fields
have a natural width based on the type of data they contain. A
field that contains a date will have a natural width based on the
date format that is in the user’s My Profile record.
Each column of a section is at least as wide as the widest combi-
nation of field and label the column contains. A column may be
noticeably wider than the natural width of some of the fields it
contains.
This property has two possible values that can be chosen from a
drop-down list. These are the possible values:

© Copyright IBM Corporation 2011. Form Properties | 255

 Default
If the value of this property is Default, then the field will be
displayed only as wide as its natural width.
Full Column
If the value of this property is Full Column, then the field will be
displayed as wide as the width of the column that contains it.
Label Style Class
If you do not specify a value for this property, the appearance of
this field’s label will be determined by default settings in the
Style Manager.
If you do specify a value for this property, it will be the name of a
field style sheet defined by the Style Sheet Editor. The style sheet
determines the appearance of the label. The Style Sheet Editor is
described in “Style Sheets” in the “Brand with Colors and Logos”
chapter of the IBM TRIRIGA Application Platform 3 User Experi-
ence User Guide.
Data Style Class
If you specify a value for this field, it will be the name of a data
style defined by the IBM TRIRIGA Application Platform’s Style Man-
ager tool. The named style is used to specify the appearance of
the field’s data instead of the default.
If you do not specify a value for this property, then the appear-
ance of this field’s data will be governed entirely by the default
specified in the IBM TRIRIGA Application Platform’s Style Manager
tool. This tool is described in “Style Sheets” in the “Brand with
Colors and Logos” chapter of the IBM TRIRIGA Application Plat-
form 3 User Experience User Guide.
Data Alignment
The value of this property determines the alignment of data in
this field when it is displayed. The possible values for this prop-
erty are:
• Left
• Center
• Right
Hierarchical Parent
This property is visible only for fields in smart sections with the
Hierarchical Fields property selected. Such sections are backed by
a Vertical Table business object section. Vertical sections are
described page 77.

256 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 To indicate that this field should be displayed in a Vertical sec-
tion as the child of another field, select the parent field in the
drop-down list.
If this property is blank, this field does not have a parent.
If a field is set to be not visible, it and its child records will not be
visible.
Hierarchical State
This property is visible only for fields in smart sections with the
Hierarchical Fields property selected and when a value is not
selected in the Hierarchical Parent property.
If this field turns out to have child fields, this property deter-
mines whether the parent / child relationship is initially rendered
as expanded or collapsed.
Start Row
The following description of this property does not apply if the
field is in a smart section that is connected to a multiple-record
smart section. The interpretation of this property in a smart sec-
tion that is connected to a multiple-record smart section is dis-
cussed on page 272 under the heading “Laying Out Multiple-
Record Smart Sections”.
The Start Row property specifies in which of the section’s rows
the field will appear. The rows in sections are counted from the
top to the bottom, so row 1 is above row 2. If a field is more than
one row tall, this property specifies which row of the section the
top of the field will appear in.
See Figure 6-15 on page 246 for a visual description of this prop-
erty.
Row Span
The following description of this property does not apply if the
field is in a smart section that is connected to a multiple-record
smart section. The interpretation of this property in a smart sec-
tion that is connected to a multiple-record smart section is dis-
cussed on page 272 under the heading “Laying Out Multiple-
Record Smart Sections”.
The value of this property specifies the height of the field in rows
of a section. For most fields, the value of this property is 1.
Descriptions and other lengthy text fields usually take up multi-
ple lines, so the value of their Row Span property is usually at
least 3.

© Copyright IBM Corporation 2011. Form Properties | 257

 See Figure 6-15 on page 246 for a visual description of this prop-
erty.
Start Column
The following description of this property does not apply if the
field is in a smart section that is connected to a multiple-record
smart section. The interpretation of this property in a smart sec-
tion that is connected to a multiple-record smart section is dis-
cussed on page 272 under the heading “Laying Out Multiple-
Record Smart Sections”.
The value of the Start Column property determines the field’s
horizontal position. The value of this property specifies in which
of the section’s columns this field will appear. If the field occu-
pies more than one column, the value of this property is the left-
most column that this field occupies.
A section is laid out in twelve columns. Most sections do not look
like they are laid out in twelve columns because they do not use
all twelve columns. If a section has nothing in a column, the col-
umn has no width and it looks like the column is not there.
You can choose a value from 1 to 12 for this property in a drop-
down list.
See Figure 6-15 on page 246 for a visual description of this prop-
erty.
Col Span
The following description of this property does not apply if the
field is in a smart section that is connected to a multiple-record
smart section. The interpretation of this property in a smart sec-
tion that is connected to a multiple-record smart section is dis-
cussed on page 272 under the heading “Laying Out Multiple-
Record Smart Sections”.
The value of the Col Span property specifies the width of the field
in columns of a section. For most fields, the value of this prop-
erty is 1. Descriptions and other lengthy text fields usually have a
value for Col Span of at least 2.
See Figure 6-15 on page 246 for a visual description of this prop-
erty.
Group Seq
It is possible to have more than one field in the same rectangle
that is specified by the Start Row, Row Span, Start Column and
Col Span properties. If more than one field in a section is speci-
fied with these properties having the same value, all the fields

258 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 with the same values for these properties will appear in the same
rectangle. The order in which the fields appear in the rectangle is
determined by the value of this property.
Prefix
If the Group Seq property is greater then zero, the Prefix prop-
erty will be displayed. The value of this property defines the text
that will be displayed between grouped fields. This text will be
displayed instead of the Label.
Tab Order
A person using this section can navigate between its fields and
buttons by pressing the tab key. The order in which the tab key
navigates to the fields and buttons in a section is determined by
their Tab Order property. The tab key will navigate to fields and
buttons in a section in the same order as the relative magnitude
of the value of their Tab Order property. If the value of this prop-
erty is 0 for all fields in the section, the tab order is left to right,
top to bottom of the fields in the section.
Do not use this feature. Custom tab ordering can lead to confu-
sion for screen readers and can break accessibility rules. For
applications with custom tab ordering, the tabbing traverses the
fields with custom ordering first, then continues with the remain-
ing objects starting with the top-most tab-enabled object.
Required
If this property’s check box is checked, a user will not be able to
save the record until he or she enters a value into this field. If the
business object’s field is set as required in the Form Builder, the
Form Field required flag will be set and the check box is read only
and cannot be changed.
Show UOM
This property is visible only if the value of the Data Type prop-
erty is Number. If the property’s check box is checked, the unit of
measure (UOM) associated with the field will be displayed. If the
field is not read-only and there is no Source UOM for the field, a
user will be able to select a different UOM.
Units of measure are discussed on page 165.
Hide Label
If the check box for this property is checked, this field is dis-
played without a label.

© Copyright IBM Corporation 2011. Form Properties | 259

 Position
The value of this property is normally Both. A value of Both means
that both the label and data portions of the column will be used
to display the field.
There are two other possible values for this property that you can
select from a drop-down list. The other values for this property
are primarily intended to be used when the check box for the
Hide Label property is checked.
If the value of this property is Label, only the label portion of the
column will be used to display this field.
If the value of this property is Data, only the data portion of the
column will be used to display this field.
If the value of this field’s Col Span property is greater than 1, the
width of the multiple columns this field spans is first broken up
into label and data areas. The field is positioned into one area,
the other area, or both areas, depending on the value of this
property.
Visible
If this check box is checked, this field will be visible. If the check
box is not checked, this field will be hidden. The default is for the
check box to be checked.
Workflows can change the value of this property at runtime, mak-
ing the field visible or hidden as appropriate.
Read Only
If the check box for this property is checked, it will not be possi-
ble for a user to interactively change the value of this field by
directly editing the field.
If a field is read-only, it does not have a border. If a field is edit-
able (not read only), it has a border.
The next three fields are intended for situations in which you want a
field of records created from the same business object to contain dif-
ferent kinds of data. An example of when this is useful is a survey for
which the answers to different kinds questions may be different kinds
of data. You want to use one kind of record to contain responses to
questions. Define the field that will contain the answers as a text
field. Then set the following three properties so that the field will be
presented by the form as text, a number, a list, a check box, or what-
ever is appropriate for the specific question. The idea is that other
fields in the same record will control the presentation of the field
that contains the answers.

260 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Type Field
This property is visible only if the value of the Data Type prop-
erty is Text. Even though the value of a text field is always stored
as text, it is possible for the field’s value to be presented in forms
and reports as if it were a date, number, duration, or some other
type of data. The way that this field’s data is presented can vary
by record and over time. The purpose of this property is to con-
trol the presentation of this field as if it contained a different
data type.
If this property has no value, this field will be presented as a nor-
mal text field.
If this property does have a value, even though this field’s value
will be stored as text, the field will be presented by the form and
in reports as whatever type is named by the field whose name is
the value of this property.
This property’s value is chosen from a drop-down list of other text
fields in the same section. Though it is not required, the field
named by this property will usually have its Visible check box
unchecked.
The field you select to drive this property should be a list field, so
users can only select a valid data type. There is a list in the List
Manager named triDynamicFieldType that has all valid field types
defined.
Content Field
This property is visible only if the value of the Data Type prop-
erty is Text.
If the Type Field property has a value that is the name of another
field in this section and the text value of the named field is
“List”, the value of the field named by this property will be used
as the name of the list of values to be presented by the field.
Lists of values are managed by the List Manager, which is dis-
cussed on page 127 under the heading “Modifying Lists”.
The value of this property is chosen from a drop-down list of other
text fields in the same section. Though it is not required, the field
named by this property will usually have its Visible check box
unchecked.
Required Field
This property is visible only if the value of the Data Type prop-
erty is Text.

© Copyright IBM Corporation 2011. Form Properties | 261

 If this property has a value, this field’s Required property will be
ignored. Instead, the value of the field whose name is the value of
this property will determine whether this field is required or not.
The value of this property is chosen from a drop-down list of other
text fields in the same section. Though it is not required, the field
named by this property will usually have its Visible check box
unchecked.
If the text value of the named field is “true” or “yes”, this field
will be required. If the text value of the named field is “false” or
“no”, this field will not be required.
Do not use this property. Similar functionality can be achieved
using a workflow to change the required metadata property. See
“Modify Metadata Task” on page 511 for more details on how to
do this.
After you have finished setting up the properties of a section, you
may want to set up actions that can be performed within the section.
Section actions are described on page 340.

Field Properties Tutorial

In order to illustrate the use of these three properties, we will now go
through a simple tutorial.
In the Data Modeler, create/revise a business object and add the fol-
lowing fields:
• Create a new text field cstComboTX
• Create a new text field cstListNameTX
• Create a new list field cstFieldTypeLI. For the Module, select System,
and for the List, select triDynamicFieldType
• Create a new text field cstRequiredTX.

Publish the business object (create a Publish Name and a data-revise

state transition diagram if necessary).
In the Form Builder, create a new form for this business object. Add
each of the fields to the form. For the cstComboTX field, set the Type
Field to cstFieldTypeTX, the Content Field to cstListNameTX, and the
Required Field to cstRequiredTX, as shown in Figure 6-19.
Now, create a new form of this type (you may need to create a navi-
gation item for this new form first, see IBM TRIRIGA Application Plat-
form 3 User Experience User Guide for details on how to do this).

262 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Figure 6-19. Tutorial - Form Builder

To demonstrate the Required Field property, assume the Combo field

was originally set to not required in the Form Builder. Now type true or
yes in the Required? field and save the record. Notice the Combo field
is now required. Similarly, if the Combo field was set to required in
the Form Builder, you can override it by typing in false or no in the
Required? field.
To demonstrate the Type Field property, open the record for this
form. Change the Field Type to Color and save. Notice the Combo field
literally becomes a color field, as shown in Figure 6-20. Similarly you
can change the Field type to other values and the type of the Combo
field changes accordingly. Note that the underlying representation of
the field is saved as text.

Figure 6-20. Tutorial - Field Type = Color

To demonstrate the Content Field property, first set the correspond-

ing Type Field property, Field Type, to List (alternatively you could
have used a hidden, read-only text field set to List). Now set the Con-
tent Field, List Name, to the name of a list in the system. For exam-
ple, type in Language and save. Now the Combo field has a list drop
down of the Languages in the system, as shown in Figure 6-21. Simi-
larly, if you change the List Name to Year, the Combo field will have a

© Copyright IBM Corporation 2011. Form Properties | 263

 list drop down of years, and so forth. Note that if the List Name field
does not contain a valid list, the drop down will have an empty list. In
addition, if the Field Type is not List, the List Name field will be
ignored.

Figure 6-21. Tutorial - Field Type = List

Despite the flexibility these properties provide, this comes at the cost
of difficulty--it is very easy to configure these properties improperly,
so you should explore other options, e.g., using workflows and swap-
ping in hidden fields, if doing so can accomplish the same thing.
Needless to say, target fields like List Name should be hidden to pre-
vent the casual user from being able to search for sensitive list data
values with this setup.

264 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Buttons
The way you edit a button or add a button to a smart section or form
section is the same as the way you edit a field. This is because the
Form Wizard treats buttons as a kind of field. Fields are described on
page 247.
Buttons have a fundamentally different purpose than fields. The pur-
pose of a field is to allow someone to view or edit a piece of data.
The purpose of a button is to trigger an action when someone clicks
it. Actions are discussed on page 339.
Buttons have some of the same properties as fields and some addi-
tional properties. Buttons always have property Type of Form Action.
The properties for a new button are shown in Figure 6-22.
Button’s properties that were not discussed for Fields (starting on
page 247) are described below:
Display Type
The value of this property determines what sort of button this will
be displayed as. These are the choices:
Button
If the value of this property is Button, this button will be dis-
played as a push button. A push button typically looks like
Figure 6-23. 
Figure 6-23.
Push Button
Image Only
If the value of this property is Image Only, this button will be
displayed as a hyperlink just using the images specified by the
Display Image and Press Image properties. No label text is
displayed.
Image and Text
If the value of this property is Image and Text, this button will
be displayed as a hyperlink using the label text specified by
the Label property and the images specified by the Display
Image and Press Image properties.
Text Only
If the value of this property is Text Only, then this button will
be displayed as a hyperlink using just the label text specified
by the Label property.
Display Image
If the value of the Display Type property is Image Only or Image and
Text, the image that is the value of this property will be the image
that is normally displayed for this button.

© Copyright IBM Corporation 2011. Form Properties | 265

 Figure 6-22. Button Properties

To specify an image to be the value of this property, click the

icon. A panel will pop up that looks like Figure 6-24. Click the
Browse button and a File Chooser window will pop up so you can
select the file that contains the image you want.

266 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Figure 6-24. Image Picker Panel

After you have selected the file with the image that you want,
click the panel’s Ok action. The panel will disappear and a small
version of the image appears to the left of the icon.
Clicking the icon causes the image selection to be cleared, so
that there will be no image to display for the button.
If the value of the Display Type property is Button or Text Only, the
value of this property is irrelevant and this property is ignored.
Image Tooltip
If the value of the Display Type property is Image Only or Image and
Text, the Image Tooltip field appears. Enter the text of the tooltip
you wish to appear when a user moves their mouse over the
image.
Press Image
If the value of the Display Type property is Image Only or Image and
Text, the image that is the value of the Display Image property will
be the image that is normally displayed for this button. When the
mouse pointer is over this button and the mouse button is
pressed, you may want an alternate image to be displayed for this
button to give the appearance that the button is being pressed. If
the Press Image property has a value that is an image, the image
that is the value of this property is the alternate image.
To specify an image to be the value of this property, click the
icon. A panel pops up that looks like Figure 6-24. Click the Browse
button and a File Chooser window pops up so you can select the
file that contains the image you want.
After you have selected the file with the image that you want,
click the panel’s Ok action. The panel will disappear and a small
version of the image appears to the left of the icon.
Clicking the icon causes the image selection to be cleared, so
that there will be no image to display for the button.
If the value of the Display Type property is Button or Text Only, the
value of this property is irrelevant and this property is ignored.

© Copyright IBM Corporation 2011. Form Properties | 267

 Active
If this check box is checked, this button has its normal appear-
ance and clicking this button will cause an action to be triggered.
If this check box is not checked, this button will appear to be
grayed out and clicking it will have no effect.

Smart Sections
Smart sections are similar to form sections in that they both contain
fields. Smart sections are different from form sections because they
are connected to a specific smart section of the associated business
object. A smart section can have actions a person can click to control
what records are referenced by the connected smart section.
The specific actions that a smart section can offer and the way it dis-
plays the contents of the smart section depends on whether it is a sin-
gle-record smart section or a multiple-record smart section. The basic
setup and properties for smart sections are the same whether they
are connected to a single-record smart section or a multiple-record
smart section. The aspects of smart sections that are independent of
the kind of connected record smart section are discussed in the fol-
lowing paragraphs. The details of laying out fields in a single-record
smart section are discussed on page 247 under the heading “Fields”.
The details of laying out fields in a multiple-record smart section are
discussed on page 272 under the heading “Laying Out Multiple-Record
Smart Sections”.
Like other kinds of sections, you can create a smart section by select-
ing the tab that will contain the section and clicking the Add Section
action. You then set the value of the Type property to Smart Section. At
this point, the Properties panel looks like Figure 6-25 on page 269.
The next thing to do is select the smart section you want connected
to this section. The names of smart sections in the associated busi-
ness object appear in the drop-down list for the Data Section prop-
erty. When you select the value for the Data Section property, the
value of the Name and Label properties are set to the name of the
smart section.
There is a shortcut that can get you to this point in the creation of a
smart section in fewer steps. When you select a tab in the Navigation
panel, the Components panel contains a list of the smart sections in
the business object that have not been connected to a smart section

268 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Figure 6-25. Properties of a Smart Section Before Saved

in this form. This list of smart sections looks like Figure 6-26 on page
270.
You can use the list of smart sections in the Components panel to
create all the smart sections you want in a single step. Check the
check box of each smart section you want to use to create a smart
section, then click the Add action at the top of the Components
panel. That’s all there is to it.
When you create a smart section you may not need to add any fields
to it. A smart section starts out with a data field for each of the fields
in the smart section it is connected to. You can delete any of these
fields. If you change your mind, you can add them back in.
“Common Section Properties” on page 243 includes information about
the following properties in a smart section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show

© Copyright IBM Corporation 2011. Form Properties | 269

 Figure 6-26. Component Panel Showing Smart Sections

Title Bar, Style Class, Start Row, Row Span, Start Column, and Col
Span. The properties in a smart section that are not described in
“Common Section Properties” on page 243 follow:
Fixed Data Cols
If you would like some of the left hand columns in the display to
be fixed and not move as the display is scrolled horizontally,
enter the number of columns in Fixed Data Cols. You can identify
the fixed columns because they are to the left of a thicker grey
demarcation line. The default value is 0 (zero). Performance
degrades as the number of fixed columns increases. Set Fixed
Data Cols to no more than 5.
Hierarchical Fields
This property is visible only for smart sections that are backed by
a Vertical Table business object section. Vertical sections are
described page 77.
When selected, fields in vertical table sections have and
icons that allow the user to expand parent fields to show child
fields below or to collapse the display. A field has a parent when
its Hierarchical Parent property identifies a field, as described on
page 256.
Comparison
This property is visible only for smart sections that are backed by
a Vertical Table business object section. Vertical sections are
described page 77.
When selected, the Comparison property indicates that the sec-
tion will compare numeric field values of the records in the sec-
tion to the same field in a compare to record. The number type

270 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 fields that have the compare ability are Number, Financial Rollup, and
Classification Rollup fields. The compare to record also must be a
record in the section and is designated by an association in the
Comparison Association property.
A comparison vertical section displays all records that are com-
pared to the compare to record with a delta value next to the
actual value of the field. The delta value is configured in the
Delta Type property as either a numeric difference, a percent dif-
ference, or as not displayed. If the compare to value has a differ-
ent UOM than the compare from value and a conversion is
available between the two UOMs, the compare from value is con-
verted first.
If there are fewer than two records in the section, the platform
displays the section without the comparison functionality.
The user will be able to change the compare to record during
runtime. When the user changes the compare to record, the plat-
form refreshes the comparison vertical section showing updated
delta values and updates the association. The order of the records
in the section does not change.
The compare to record can be changed during workflow by remov-
ing the previous association and associating a new compare to
record.
Comparison Association
This property is visible only when the Comparison property is
selected. The association designates the compare to record in a
comparison vertical section. This association is a temporary asso-
ciation.
The drop-down list contains all associations that associate to the
same business object that is referenced by the section and that
are defined on the business object of the form. The list does not
include the association that the section uses.
The compare to record must be in the smart section and there
should be at most one associated record at a time.
If no association is found, the platform uses the first record in the
section as the compare to record. If more than one record is asso-
ciated with the Comparison Association, the platform sorts the
records alphabetically by their names and uses the first record
from the sorted list.

© Copyright IBM Corporation 2011. Form Properties | 271

 Print Preview Link
This property is visible only on vertical table sections. When
selected, a Print Preview link shows on the vertical table section
bar.
At runtime, when a user selects the Print Preview link, the plat-
form displays the vertical table section in a new window. The dis-
play is read-only and retains the expand/collapse state of the
fields in the original section.
After you have finished setting up the properties of a section, you
may want to set up actions that can be performed within the section.
Section actions are described on page 340.

Source Details
Below a smart section’s real properties is what looks like a property
with no value and the label Source Details… This label is a hyperlink.
Clicking this hyperlink causes a window to pop up that displays infor-
mation about the underlying smart section.

Autocomplete
Autocomplete functionality is available for all single-record smart sec-
tion text fields. Specify whether or not your users will have this fea-
ture in the USE_AUTO_COMPLETE_IN_SMART_SECTION property in the
TRIRIGAWEB.properties file, as described in the IBM TRIRIGA Application
Platform 3 Installation and Implementation Guide. The default is for
autocomplete to be enabled. Read more in “Autocomplete” on
page 154.
The autocomplete functionality also is available on Locator fields, as
described in “Autocomplete” on page 154.

Laying Out Multiple-Record Smart Sections

Laying out the fields in a smart section connected to a multiple-
record smart section is different from laying out a single-record smart
section. Instead of laying out individual fields you lay out columns of
fields.* Figure 6-27 shows an example of what the Layout panel looks

* In the properties of the connected business object, if the check box for the Vertical
Section property is checked, you will be laying out rows of fields instead of columns. The
Vertical Section property of a business object is discussed on page 77.

272 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

like when you are laying out a smart section connected to a multiple-
record smart section.

Figure 6-27. Layout of a Form With a Multiple-Record Smart Section

Laying out a multiple-record smart section is simpler than laying out a

single-record smart section because you do not have to specify the
position of each field. All you have to do is specify the order in which
the columns will appear. The order in which the columns appear is
determined by the value of each field’s Start Row property. The val-
ues of the Row Span, Start Column and Col Span properties are
ignored.
One other difference between a single-record smart section and a
multiple-record smart section is that you cannot add form fields to a
multiple-record smart section. A multiple-record smart section can
only contain data fields.

© Copyright IBM Corporation 2011. Form Properties | 273

 In a multiple-record smart section, the properties of fields not related
to their layout are interpreted the same as in other kinds of sections.
For descriptions of these properties, see page 247 under the heading
“Fields”.

274 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Multi Tab Sections
Multi Tab sections contain tabs. The tabs in a Multi Tab section are
different from top-level tabs in that they contain exactly one section.
Like other kinds of sections, you can create a Multi Tab section by
selecting the tab that will contain the section and clicking the Add
Section action. You then set the value of the Type property to Multi
Tab Section. At this point, the Properties panel should look like
Figure 6-28.

Figure 6-28. Properties for a Multi Tab Section

“Common Section Properties” on page 243 includes information about

the following properties in a Multi Tab section: Type, Name, Label,
Title Bar Color, Visible, Expand Section, Read Only, Style Class, Start
Row, Row Span, Start Column, and Col Span.
Once you have saved a Multi Tab section for the first time, you will
see an Add Section action. The way that you add a tab to a Multi Tab
section is to add a section. When you add a section to a Multi Tab sec-
tion, it shows up in its own tab that has the same label as the section.
Most of the properties in Figure 6-28 have no effect. Since you can
add any section to a Multi Tab section (except for another Multi Tab
section), the properties of the section that is displayed override the

© Copyright IBM Corporation 2011. Form Properties | 275

 Multi Tab section's properties. The only exception is the Visible prop-
erty. If the Visible property of a Multi Tab section is unchecked, the
entire Multi Tab section will be hidden.

276 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Query Sections
A Query section looks similar to a multiple-record smart section. A
query section contains the records found by a query. A query section
has no direct connection with a business object. Queries are dis-
cussed in the IBM TRIRIGA Application Platform 3 Reporting User
Guide.
Like other kinds of sections, you can create a query section by select-
ing the tab that will contain the section and clicking the Add Section
action. You then set the value of the Type property to Query Section. At
this point, the Properties panel should look like Figure 6-29 on page
278.
After you have set the value of the Type, Name, and Label proper-
ties, the next property you will probably want to set the value of is
the Query property. The value of the Query property is used to deter-
mine which query will be run to generate the contents of this Query
section. What is run to generate the contents of this section does not
actually have to be a query. It can be any type of report managed by
the Report Manager (discussed in the IBM TRIRIGA Application Plat-
form 3 Reporting User Guide).
To select a query, click the Search icon in the Query property.
Clicking the icon causes a Select Item(s) panel to pop up over the
Properties panel.
A query section is always viewed within a parent record. If the record
is a capital project, the active project for that query section is the
record itself. If the record is not a capital project, the active project
for the query section is the project that the parent record is in.
Whether or not the active project is used in the query section results
is dictated by the data scope on the query definition. If the data
scope of the query definition is Active Project, the records returned
by the query are restricted to the active project.
Within the Form Builder, queries attached to query sections are not
executed. Instead they are displayed with an empty result set. This
improves design time performance.
When a graphics section is associated to a query section, the only
items that can be selected from the graphics section are those associ-
ated items that are derived from the query results.
Query sections are resized when the number of rows returned by the
query is greater than the height defined. The platform produces scroll
bars so the user can scroll the results. For hierarchical queries, the

© Copyright IBM Corporation 2011. Form Properties | 277

 Figure 6-29. Properties of a Query Section

number of rows refers to the top-level (check box) rows, and expand-
ing the top level causes the query section height to expand accord-
ingly. For queries with Group By or Sum, the number of rows refers to
data (check box) rows, not the sum rows. A query section with Height

278 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

= 0 defaults to Height = 10. A query section with Height = -1 defaults
to Height = 10.

Selecting a Query
Initially, no queries appear in the Select Item(s) panel because no
module is selected. Select the module of the query you want from the
drop-down list to the right of the Module label. Once the module is
selected, the system displays all queries for that module from the
Report Manager. If what you are looking for is a query, you will see it
in a list.
If what you are looking for is not a query but some other kind of
report, you will not see what you are looking for because the list ini-
tially includes only queries. You will need to select the type of report
you want to see.
To select the type of report you want to see, click the Filter icon
to the right of the Reports List label. A menu will pop up that looks
like Figure 6-30. From this menu, you can choose the type of report
you want to see a list of or you can choose All to see a list that con-
tains every kind of report.

Figure 6-30. Report Type Menu

The query or report you use in a query section should have an associa-
tion filter that uses $$RECORDID$$ or $$PARENTID$$ (discussed in the IBM
TRIRIGA Application Platform 3 Reporting User Guide) so that its
results only include records associated with the record that contains
the Query section.

© Copyright IBM Corporation 2011. Form Properties | 279

 “Common Section Properties” on page 243 includes information about
the following properties in a query section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show
Title Bar, Border Size, Border Color, Style Class, Start Row, Row Span,
Start Column, and Col Span. The properties in a query section that are
not described in “Common Section Properties” on page 243 follow:
Query
See the explanation of this property on the preceding pages.
Threshold Record Field
This property is visible only when the query specified in the Query
property is a metric query. Use this property to provide context
sensitive behavior for a metric query displayed in a form.
The Threshold Record Field drop-down list contains locator fields
anchored to the Threshold business object. At runtime, the plat-
form uses the threshold record from this locator instead of the
threshold record specified in the query within the Report Man-
ager. If the locator does not specify a threshold record, the plat-
form uses the threshold record specified in the query.
Auto Refresh
If you wish the query section to refresh automatically, select the
Auto Refresh property.
Refresh Time in secs.
This property is visible only when the Auto Refresh property is
selected. Enter the number of seconds the platform should wait
between automatic refreshes of the query section.
Workflow
The workflow specified by the value of this property is run when,
as a result of a Find action, a person selects records to be associ-
ated with the record that contains the Query section. Find actions
are discussed in greater detail on page 356 under the heading
“Query Section Actions”.
This workflow is typically used to update totals or other statistics
about associated records in the record that contains the query
section.
If this property has no value, no workflow will be run when a find
action is used to associate additional records with the record that
contains the query section.
To specify the value of this property, click the icon. Clicking
the icon causes a list of synchronous workflows to appear. The
synchronous workflows in the list will be workflows launched from

280 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 records created from the business object associated with the form
that the query section is part of. If you select one of the work-
flows in the list and click the OK action at the top of the list, the
workflow you selected becomes the value of this property.
If you want to clear the value of this property so that it has no
value, click the icon.
Association Type
The value of this property is the name of the association this sec-
tion will be based on. If you use the Find or Add action that the
IBM TRIRIGA Application Platform may provide for this query sec-
tion, the found records or newly created record will become asso-
ciated with the record that contains this section using the
specified association name.
These platform-provided actions are described on page 356 under
the heading “Query Section Actions”.
Select Association Type
Workflows may be run as a result of someone clicking a form state
transition action (described on page 370 under the heading
“State-Based Actions”). It may be helpful for the workflow to be
able to recognize if the person who clicked the action that trig-
gered the workflow first selected some records displayed in the
query section by checking the check box to the left of the record.
If an association name is selected for the value of this property
and someone clicks an action you defined that triggers a work-
flow, the platform will create an association from the record asso-
ciated with the form to the any records shown in this section that
have their check box checked.
There is a different mechanism that allows a workflow run from
an action in a query section to navigate to selected records. This
is discussed on page 356 under the heading “Query Section
Actions”.
Having the same Select Association Type on multiple query sec-
tions in the same form may result in undesired select behavior as
those sections are sharing the same select associated records. Use
a different Select Association Type for each query section to prop-
erly maintain each select association.
Temp Select Association
When selected, the query section association is temporary. When
not selected, the query section association is permanent.

© Copyright IBM Corporation 2011. Form Properties | 281

 Single Select
If this property’s check box is not checked, it means that a user
may select the check box for any or all of the records in the Query
section.
If this property’s check box is checked, it means that a user may
select only one of the records in the query section.
Select Workflow
This property is only displayed if the Single Select property is
checked. The workflow specified by the value of this property is
run when a user selects the radio button of a record contained in
the query section.
If this property has no value, then no workflow will be run when a
radio button is clicked.
To specify the value of this property, click the icon. Clicking
the icon causes a list of synchronous workflows to appear. The
synchronous workflows in the list will be workflows launched from
records created from the business object associated with the form
that the query section is part of. If you select one of the work-
flows in the list and click the OK action at the top of the list, the
workflow you selected becomes the value of this property.
If you want to clear the value of this property so that it has no
value, click the icon.
Note that the Select association created when the user clicked
the radio button will be deleted after the workflow(s) complete.
Show Add
If this property’s check box is checked, then there will be an Add
action for people to click at the top of this query section. The
Add action is described on page 356 under the heading “Query
Section Actions”.
Show Query Header
If this property’s check box is checked, then column headings for
the query results will be displayed in the query section. This
check box is usually checked. If this check box is not checked then
no column headings will be displayed in this query section.

282 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Report Sections
A Report section allows a form report to be presented as a section in
a form. Form reports are discussed in the IBM TRIRIGA Application
Platform 3 Reporting User Guide.
Like other kinds of sections, you can create a Report section by
selecting the tab that will contain the section and clicking the Add
Section action. You then set the value of the Type property to Report
Section. At this point, the Properties panel should look like
Figure 6-31.

Figure 6-31. Form for Specifying a Report Section

After you have set the value of the Type property, the next property
you will probably want to set the value of is the Document property.
The value of the Document property is used to determine which form

© Copyright IBM Corporation 2011. Form Properties | 283

 report template will be used to generate the contents of this report
section.
To select a form report template, click the icon in the Document
property. Clicking the icon causes a Select Item(s) panel to pop up
over the Properties panel containing a list of the documents in the
Document Manager.
To specify which document to use as the form report template, select
the document’s radio button and then click the OK action at the top
of the list.
After you have set the value of the Document property, you may
want to set the value of some of the other properties. Here are
descriptions of the properties of a report section:
“Common Section Properties” on page 243 includes information about
the following properties in a Report section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show
Title Bar, Style Class, Start Row, Row Span, Start Column, and Col
Span. The properties in a Report section that are not described in
“Common Section Properties” on page 243 follow:
Document
See the explanation of this property on the preceding pages.
Financial Report
If the values in this report are or depend on Financial Rollup
tokens, you should check this property’s check box. Financial Rol-
lup tokens are discussed in the “Financial Transactions and Rol-
lups” chapter of the book Application Building for the IBM TRIRIGA
Application Platform 3: Calculations.

284 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Graphics Sections
Graphics sections are a specialized kind of section used to support
CAD-related and other graphics for IBM TRIRIGA’s applications. The
details of how to put content in a graphics section are not described
in this book; however, the following paragraphs explain how to cre-
ate a graphics section.
Like other kinds of sections, to create a graphics section, select the
tab that will contain the section and click the Add Section action.
Then set the value of the Type property to Graphics Section. At this
point, the Properties panel should look like Figure 6-32.

Figure 6-32. Form for Specifying a Graphics Section

© Copyright IBM Corporation 2011. Form Properties | 285

 “Common Section Properties” on page 243 includes information about
the following properties in a graphics section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show
Title Bar, Style Class, Start Row, Row Span, Start Column, and Col
Span. The properties in a graphics section that are not described in
“Common Section Properties” on page 243 follow:
Module
For the value of this property you may select either Geography,
Location or Organization. This determines which one of these hierar-
chies the images will be connected to.
Association Type
The value of this property is the name of the association that con-
nects the record this form is editing to the record the graphic is
associated with.
Default Theme
Every graphics section must have a theme. The Default Theme
determines which theme is used when a graphics section is ren-
dered for the first time in a form. If this property does not have a
value, IBM TRIRIGA will use the Global Default Theme as the
theme of this section when the section is rendered initially. The
Global Default Theme is defined in Tools > Administration >
Graphics > Theme, as shown in Figure 6-33.

Figure 6-33. Global Default Theme

You may set this property to specify a different Default Theme for
this section. To specify a Default Theme, click the icon. A list

286 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 of existing themes is shown. Select a theme and click Ok. A
hyperlink for that theme appears next to this property, and this
will be the theme used when the section is rendered initially.
Clicking the icon causes the theme to disappear, and the Glo-
bal Default Theme will be used for the Default Theme. Please
refer to the IBM TRIRIGA Application Platform 3 Graphics User
Guide more information on themes.
Expand Section
TIP: Graphics sections do not load if the section is collapsed,
which can have a significant positive impact on the time to load
the section.
When a graphics section is associated to a query section, the only
items that can be selected from the graphics section are those
assigned items that are derived from the query results.
After filling in these properties, click the Apply action at the top of
the Layout tab. Additional properties are now available, as shown in
Figure 6-34 on page 288. Also “Common Section Properties” on
page 243 includes information about the following properties in a
graphics section: Border Size and Border Color.
Display
This property indicates the source of the data displayed in the
graphics section. The values in the drop-down list are as follows:
• Self means that the data is from the business object of this
form.
• By Association means that the source is by association. The Asso-
ciation Type and the Associated Query Section properties
define the association.
Associated Query Section
This property is used to link a query section to the graphics sec-
tion (see below). Select the query section from the drop-down
list. One of the choices is -None-.
Actions Section
Graphics sections can have section actions. Read about section
actions in “Actions” on page 339.

Linking a Query Section to a Graphics Section

IBM TRIRIGA provides a way for you to link a query section to a graph-
ics section. In order to do this, you will need to first add a query sec-

© Copyright IBM Corporation 2011. Form Properties | 287

 Figure 6-34. Graphics Section after Apply Action

tion to the form. Once this is done, this query section will be
available in the Associated Query Section property.

288 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

The primary use of this feature is to associate a floor plan to a query
that returns spaces. IBM TRIRIGA will highlight the spaces on the floor
plan that are also in the linked query section, as shown in Figure 6-35.

Figure 6-35. Graphics Section with Linked Query Section

In this diagram, the List View section is the linked query section, and
all Vacant Spaces are highlighted. In addition, the entities in the floor

© Copyright IBM Corporation 2011. Form Properties | 289

 plan can be selected only if they are part of the linked query result.
In the diagram, Space 204-01 is currently selected, and any of the
highlighted spaces are selectable. Space 205, however, is not select-
able.
Using this feature requires defining the context of the query results,
which is used to determine the floor plan(s) associated with the query
results. In order to define the context, you will need to set the Dis-
play property to By Association, and set the Module and Association Type
properties appropriately in the graphics section. Since we want the
floor plan from the Parent Floor of the spaces in the query results, we
set the Module to Location and Association Type to Parent Floor. Note
that this association determines which floors appear in the drop-down
menu in Figure 6-35. If we had a query that had results of spaces from
10 different floors, then all 10 floors would appear in the context
menu.
Tip: The primary business object of the query determines the record
type of the results. In this example, we used Spaces, but potentially
any attached entity (e.g., Assets, People, Organizations) that corre-
sponds to the query results could be used in a linked query. In order
to define the context, an association will need to be available from
that record to a record with a floor plan, i.e., Floor.
Tip: When running a graphic report on a graphics section that is linked
to a query section, that report only applies colors to the linked query
results. Only entities that are in both the linked query results and the
graphic report results will be selectable. See the IBM TRIRIGA Applica-
tion Platform 3 Graphics User Guide for more information on graphic
reports.

290 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Excel Sections
An Excel section is like a report section in that it displays values from
a record using the formatting and context of a Microsoft Excel spread-
sheet. It is different from a report section in that you can use it to
perform calculations. Values computed by the spreadsheet can be
used to update fields in the record associated with the form. Excel
sections can also update fields in records that are directly or indi-
rectly associated with the underlying record.
The main use for an Excel section is to perform computations that are
not easily done within the platform. However, there is a major
restriction.
Values computed by the spreadsheet can only be used to update the
underlying record when a record’s form is being used interactively by
a person. Changes to a record that happen outside the interactive
environment will not be processed by the Excel spreadsheet. In par-
ticular, the spreadsheet is not used to update fields when a workflow
creates or modifies a record. Similarly, when records are created or
modified by an application that runs outside the IBM TRIRIGA Applica-
tion Platform, the Excel spreadsheet is not run to compute values.
The values used and updated by an Excel section come from the per-
manent data in records, not the temporary data in a form. So, when a
user clicks the Calculate on an Excel section, the platform perma-
nently saves the data and when it is calculated based on a state tran-
sition action, it only does so after the data is permanently saved. See
Chapter 8 for an explanation of the distinction between temporary
and permanent data.
NOTE: According to Microsoft’s website on http://technet.microsoft.com/
en-us/library/cc178954.aspx, the OWC library that IBM TRIRIGA uses for
Excel sections is not available in Office 2007. That article has a link to
where you can download the OWC library and install it as a separate
component. If you upgrade Office 2003 or Office 2000 to Office 2007,
the OWC library is available. If you have a clean install of Office 2007,
the library is missing.

First Create an Excel Form Template

Before you create an Excel section, you must already have created an
Excel Form Template like those used for form reports. Form reports
are discussed in the IBM TRIRIGA Application Platform 3 Reporting
User Guide.

© Copyright IBM Corporation 2011. Form Properties | 291

 There are some requirements for the form report template you cre-
ate:
• The form report template must be created using Excel.
• The form report template must have cells that contain formulas
to make whatever computations are needed.
• You must have Excel save the form report template as HTML with
interactivity enabled. Check the Add Interactivity check box is
checked. If you do not check this, no computations will be per-
formed by the Excel section.

Creating Excel Sections

Like other kinds of sections, you can create an Excel section by
selecting the tab that will contain the section and clicking the Add
Section action. You then set the value of the Type property to Excel

292 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Section. At this point, the Properties panel should look like
Figure 6-36.

Figure 6-36. Form for Specifying an Excel Section

After you have set the value of the Type property, the next property
you will probably want to set the value of is the Excel(.htm)
Document property. The value of the Excel(.htm) Document prop-
erty is used to determine which form report template will be used to
generate the contents of this Excel section.
To select a form report template, click the icon in the Excel(.htm)
Document property. Clicking the icon causes a panel to pop up
over the Properties panel containing a list of the documents in the
Document Manager.
To specify which document to use as the form report template, select
the document’s radio button and then click the OK action at the top
of the list.

© Copyright IBM Corporation 2011. Form Properties | 293

 After you have set the value of the Excel(.htm) Document property,
you may want to set the value of some of the other properties.
“Common Section Properties” on page 243 includes information about
the following properties in an Excel section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show
Title Bar, Style Class, Start Row, Row Span, Start Column, and Col
Span.
After you have saved an Excel section for the first time, under the
properties is a form section that contains a spreadsheet. Initially the
spreadsheet is blank. After you have specified the Excel(.htm)
Document, the spreadsheet you are using as a template should
appear in place of the blank spreadsheet.

Linking Spreadsheet Results Back to Fields

After you have specified the Excel section’s properties and clicked the
Apply action to save the properties, the Excel section exists. How-
ever, the Excel section is not yet finished. One major step still
remains.
All that we have done so far is to arrange for values in a record’s
fields to be presented in a spreadsheet. We still need to arrange for
computed result values in the spreadsheet to be copied to fields in
the record being edited by the form.
Below the properties and above the spreadsheet is an action labeled
Link Cell. It is used to link spreadsheet cells to fields. If a spread-
sheet cell is linked to a field, it means that the value in the spread-
sheet cell will be copied to the field(s) it is linked to. If a spreadsheet
cell is linked to more than one field, then the value in the spread-
sheet cell is copied to all the fields that the spreadsheet cell is linked
to. The field must be present in the form for it to be updated.
The way we link a spreadsheet cell to fields is to first click the
spreadsheet cell we want to link. When we click a spreadsheet cell,
the spreadsheet cell becomes highlighted.
After we have highlighted a spreadsheet cell, we click the Link Cell
action to link the spreadsheet cell to field(s). Clicking the Link Cell
action causes an Excel Field List window to pop up.
Initially the spreadsheet cell is not linked to any fields, so the Excel
Field List window is empty. We can add a link to a field by clicking
the Add action. Clicking the Excel Field List window’s Add action
brings up a Formula Tree window that allows you to select a field in

294 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

the business object that contains the Excel section. The Formula Tree
window can also be used to select fields in business objects that are
associated, directly or indirectly, with the business object that con-
tains the Excel section. Formula trees are discussed in the book Appli-
cation Building for the IBM TRIRIGA Application Platform 3:
Calculations.
The record number field defaults to 1, which is always the correct
value unless the field is in a multiple-record smart section. If the field
is in a multiple-record smart section, the Record Number value is
used to determine which record in the multiple-record smart section
contains the field that will be updated. The value 1 indicates the first
record.
Be careful when linking a spreadsheet cell to a field on an associated
business object, as shown in Figure 6-37. When someone is using the
spreadsheet to update data, the IBM TRIRIGA Application Platform will
follow all specified associations to find the record that contains the
field a spreadsheet cell is linked to. If it finds multiple records

© Copyright IBM Corporation 2011. Form Properties | 295

 through the association, then it will update the field in all of the
records it finds with the spreadsheet cell value.

Figure 6-37. Result when Cell Linked to Assoc. Business Object Field

296 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Gantt Sections
A Gantt section is used to display a Gantt chart. Gantt sections have a
scheduling engine that can be used to set scheduling information in
records that represent tasks. This scheduling information includes
earliest start dates, latest start dates, percentage complete, critical
path, baseline information, associated resources, container or
umbrella tasks, and dependent tasks.
The dates in the Gantt display using the value in the Date Time For-
mat field from the user’s My Profile record. The time scale in the
hourly view displays using the value in the Date Format field of the
user’s My Profile record.
A user can choose which type of Gantt section display they would like
to see by expanding the Gantt section or clicking the Open Gantt In
New Window section action. Expanding the Gantt section displays the
Gantt chart in a Java Applet display inside the tab that the section
belongs to. Clicking Open Gantt In New Window results in a Java Web
Start display in a separate window; this action is intended for larger
projects. The Gantt displayed in either case is the same.
Figure 6-38 shows an example of a Gantt chart.
The left panel of the Gantt section shows specified fields in records
that represent the tasks displayed by the Gantt chart. The fields that
display are defined by the query that is specified for the Gantt sec-
tion. The right panel of the Gantt section displays a Calendar view of
the records. If the Gantt section is not read only, you can use the
Gantt section to interactively edit and create records that represent
tasks in a project.
The Form Builder will allow you to put a Gantt section in any form.
However, for the Gantt section to work properly, the business object
associated with the form must contain these fields in its General sec-
tion:
triProjectPlanStartDA
This is the project’s planned start date.
triProjectPlanEndDA
This is the project’s planned end date.
triProjectCalcStartDA
This is the project’s calculated start date. This should be a read
only field because the scheduling engine calculates the value.

© Copyright IBM Corporation 2011. Form Properties | 297

 Figure 6-38. Example Gantt Chart

triProjectCalcEndDA
This is the project’s calculated end date. This should be a read
only field because the scheduling engine calculates the value.
triTimeZonesCL
This is the time zone of the project.
triProjectCalcFromLI
This establishes scheduling engine calculation settings. The val-
ues in the drop-down list are Start, End, and Both.
TIP: Prior to opening the Gantt chart, any unsaved changes to the fol-
lowing fields should be saved so that the project can be scheduled
correctly: Plan Start, Plan End, and Calculate Project From. This does
not apply to forms that include a Gantt Project section but do not
include a Form section containing the fields listed.
In addition to needing a business object that contains these fields, a
Gantt section also needs a query that determines which records and
which of their fields will be displayed in the Gantt section. Though
the Form Builder allows you to use any query with a Gantt section, at
the time of this writing, Gantt sections can display only records cre-

298 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

ated from business objects that are part of the triTask module.* Those
are asset reservation tasks, contract review tasks, facility assessment
work tasks, follow up tasks, inspection tasks, inventory count work
tasks, inventory pick work tasks, key work tasks, location reservation
tasks, material order tasks, offline tasks, punchlist tasks, reserve
work tasks, schedule tasks, submittal tasks, vehicle reservation tasks,
and work tasks.
One last thing needed to set up a Gantt section is an association name
to use for records that are interactively created through the Gantt
section.
The properties for a Gantt section look like Figure 6-39 on page 300.
“Common Section Properties” on page 243 includes information about
the following properties in a Gantt section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show
Title Bar, Border Size, Border Color, Style Class, Start Row, Row Span,
Start Column, and Col Span. The properties in a Gantt section that are
not described in “Common Section Properties” on page 243 follow:
Query
The value of this property is the query used by this section to
determine which records and which of their fields to display. This
also determines which forms can be selected while creating tasks
from within the Gantt section.
The details of how to specify the query that will be the value of
this property are described on page 277.
TIP: Once tasks are added to a Query section and loaded in the
Gantt, the Gantt scheduling engine schedules (or arranges) the
tasks. After the tasks have been scheduled, the start and end
dates on the Gantt may be different from those on the Query sec-
tion. These dates will coincide once the user either clicks the
Save button on the Gantt or saves the record. The save causes the
dates from the Gantt section to be propagated to the Query sec-
tion. The start and end dates on the Gantt should be the Calcu-
lated Start and the Calculated End.

* The limitation that Gantt sections will only display records that were created from busi-
ness objects that are part of the triTask module should not be relied upon to filter query
results.

© Copyright IBM Corporation 2011. Form Properties | 299

 Figure 6-39. Properties for a Gantt Section

300 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Workflow
The workflow specified by the value of this property is run when a
person selects records to be associated with the record that con-
tains the Gantt section.
If this property has no value, no workflow will be run.
To specify the value of this property, click the icon. Clicking
the icon causes a list of synchronous workflows to appear. The
synchronous workflows in the list will be workflows launched from
records created from the business object associated with the form
that the Query section is part of. If you select one of the work-
flows in the list and click the OK action at the top of the list, the
workflow you selected becomes the value of this property.
If you want to clear the value of this property so that it has no
value, click the icon.
Association Type
When this section is used to interactively create records, an asso-
ciation is created from the record being edited by the form to the
new record. The value of this property is the name that is used
for the association.
Select Association Type
Workflows may be run as a result of someone clicking a form state
transition action (described on page 370 under the heading
“State-Based Actions”). It may be helpful for the workflow to be
able to recognize if the person who clicked the action that trig-
gered the workflow first selected some records displayed in the
Gantt section.
If an association name is selected for the value of this property
and someone clicks an action you defined that triggers a work-
flow, the platform will create an association from the record asso-
ciated with the form to the any records shown in this section.
The Actions section shows the Open Gantt In New Window action
that enables a user to open the Gantt in a new window using Java
Web Start. The system adds this action automatically when you save a
new Gantt section for the first time. All Gantt sections have this
action by default.
This action is present even if the section is read only, in which case a
user can view the Gantt, but the Gantt nodes cannot be modified,
created, deleted, promoted, or demoted. The Open Gantt in New
Window has a visible property that you can uncheck if you do not
want this to be available on the Gantt section.

© Copyright IBM Corporation 2011. Form Properties | 301

 Single Select Gantt Section
IBM TRIRIGA treats single select Gantt sections differently from other
Gantt sections. Checking the Single Select check box makes some
additional properties relevant, as shown in Figure 6-40.

Figure 6-40. Additional Properties in SIngle Select Gantt Section

The primary purpose of these properties is to support putting a par-

ent Gantt section and a child Gantt section on the same form, and
have the parent Gantt chart drive what is displayed in the child Gantt
chart. By having a single select Gantt chart be able to run workflows,
you can make whatever modifications to the form are needed to
enable the child Gantt section to display the appropriate data.
Single Select
If this property’s check box is checked, it means that a user may
select only one of the rows in the Gantt section. When this prop-
erty is checked, the form will refresh automatically when the user
selects a row.
If this property’s check box is not checked, it means that a user
may select any or all of the rows in the Gantt section.

302 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Single Select Always Available
This property only displays if the Single Select property is
checked.
If this property’s check box is checked, it means that a user may
select rows in the Gantt section even when the form is read-only.
If this property’s check box is not checked, it means that a user
may not select rows when the form is read-only.
Select Workflow
This property only displays if the Single Select property is
checked. The workflow specified by the value of this property is
run when a user selects a row in the Gantt section.
If this property has no value, no workflow will be run when the
user selects a row in the Gantt section.
To specify the value of this property, click the icon. Clicking
the icon causes a list of synchronous workflows to appear. The
synchronous workflows in the list will be workflows launched from
records created from the business object associated with the form
that the Gantt section is part of. If you select one of the work-
flows in the list and click the OK action at the top of the list, the
workflow you selected becomes the value of this property.
If you want to clear the value of this property so that it has no
value, click the icon.
Note that the system deletes the association created when the
user clicked the radio button after the workflow(s) complete.
Select Association Type
With Single Select, you can specify a workflow to run when a user
selects a row in the Gantt section. If an association name is
selected for the value of this property and someone selects a row
in the Gantt chart, the platform will create an association
between the form containing the Gantt section and the record
associated with the selected row in the Gantt. This association
will be available to the select workflow when it runs.

Requirements for Records in a Gantt Section

The types of tasks that may be created in a Gantt section are deter-
mined by the query specified for the Gantt section. Only forms that
are allowed for the query can be used to create records in a Gantt
section.

© Copyright IBM Corporation 2011. Form Properties | 303

 The forms that can be used with a query are determined by the value
of a field named Form on the Description tab of its specification, as
described in the IBM TRIRIGA Application Platform 3 Reporting User
Guide.
In order to work properly with the Gantt section and its scheduling
engine, certain requirements must be satisfied by records used to rep-
resent project tasks.
All records that represent project tasks must have these fields:
triTaskNameTX
The name of the task.
triPlannedStartDT
The planned start date and time of the task.
triPlannedEndDT
The planned end date and time of the task.
triPlannedEarlyStartDT
The planned earliest start date and time of the task. This is calcu-
lated by the scheduling engine.
triPlannedEarlyFinishDT
The planned earliest end date and time of the task. This is calcu-
lated by the scheduling engine.
triPlannedLateStartDT
The planned latest start date and time of the task. This is calcu-
lated by the scheduling engine.
triPlannedLateFinishDT
The planned latest end date and time of the task. This is calcu-
lated by the scheduling engine.
triBaselineStartDT
The baseline start date and time of the task.
triBaselineFinishDT
Planned early end date and time of the task.
triActualStartDT
The actual start date and time of task.
triActualEndDT
The actual end date of the task.
triActualPercentCompleteNU
The task’s actual percent complete.
triIdTX
The task’s work breakdown structure (WBS) code. This is used for
sorting the tasks in the Gantt section.

304 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

triFreeFloatDU
The free float duration of the task. This is calculated by the
scheduling engine.
triTotalFloatDU
The total float duration of the task. This is calculated by the
scheduling engine.
triPlannedWorkingInputHrsNU
The planned number of hours of the task.
triPlannedWorkingInputDaysNU
The planned number of days of the task.
triHoursPerDayNU
The number of hours in a work day of the task. The number of
working hours in a day is given by the calendar. If the task has a
calendar, the Calendar record has a field named triHoursPerDayNU
that gives the number of working hours per day. If the task does
not have a calendar, the value defaults to 24 working hours in a
day.
TIP: As mentioned on page 297, the left panel of the Gantt section
has fields that correspond to the query set in the Gantt section. Most
fields that appear here will be read only. However, the following
fields will be directly editable on the Gantt chart if included in the
query: triNameTX, triIdTX, triPlannedWorkingDaysNU, triPlannedWorkingHoursNU,
triPlannedWorkingInputDaysNU, triPlannedWorkingInputHrsNU.

TIP: If you are experiencing issues with date and time fields display-
ing the time incorrectly, the following steps may help resolve them:
1. Make sure your operating system is updated and includes the
most current time zone patches.
2. Upgrade the Application Server’s Java with the appropriate
time zone patches.
3. When applicable, make sure the TZ environment variable has
DST set.

Container Tasks
Some project tasks are what are called container tasks or umbrella
tasks. This means that they are composed of one or more tasks. The
tasks inside a container task can execute in series or in parallel (be
overlaying). A container task is used to break a project into major
phases; each container task contains a group of tasks or activities.

© Copyright IBM Corporation 2011. Form Properties | 305

 The Gantt section shown in Figure 6-38 on page 298 has an example of
a container task.
The name of the container task in the example is Design. It is broken
down into two smaller tasks named Design Review and Complete Working
Drawings.

If you want a record to represent a container task, create an associa-

tion between the record that represents the container task and the
records that represent the smaller tasks that are in the container
task. On the container task side of the association, the name must be
Includes. On the other side of the association, the name must be Included
In.

It is possible to interac-
tively make some tasks
container tasks by using
the Gantt section’s pro-
mote and demote fea-
tures. You use these by
right clicking the task in
the Gantt chart and then
clicking the Promote or
Demote menu item of the
menu that pops up. This
pop-up menu is shown in
Figure 6-41.
For this feature of the
Figure 6-41. Gantt Chart Pop-Up Menu Gantt section to work
properly, there must be
workflow called triTask - Synchronous - Promote Task that creates the Includes
/ Included In association.
Another way to create the parent child relationship for the container
task is to use the Rolls up To section from the task form. Populate this
section with the ID of the task that is the parent of the current task.

Calendars
When scheduling a task, the scheduling engine takes into account the
Calendar of the task. The calendar includes information on Working
Hours and non-Working Events. Calendars such as these are repre-
sented using records created from the business object named
triCalendar in the triSetup module.

306 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

The triCalendar record must also have an association with the record
that describes the underlying calendar. The association on the side of
the underlying calendar must have the name Calendar For. On the task
side of the association, the name must be Has Calendar.

Dependent Tasks
It is common for there to be dependencies between tasks. Some com-
mon dependencies are that one task must start after another finishes
or that two tasks must start at the same time. Dependencies such as
these are represented using records created from the business object
named triDependency in the triIntermediate module.
Two associations from a triDependency record to records that represent
tasks are used to identify the tasks involved in a dependency relation-
ship. One of the tasks involved in the dependency relationship is con-
sidered to be the predecessor task; the other task is considered to be
the dependent task.
The predecessor task must have an association with the triDependency
record. The name of the association on the predecessor task side must
be Is Predecessor. On the triDependency side, the name of the association
must be Has Predecessor.
The dependent task must have an association with the triDependency
record. The name of the association on the dependent task side must
be Has Dependency. On the triDependency side, the name of the associa-
tion must be Defines Dependency.
Some fields of the triDependency record must be set to describe the
dependency. The required fields are:
triDependencyRelationshipLI
The value of this field determines the type of dependency that
this record represents. The choices available are:
Finish-to-Finish
This value means that the finish time of the dependent task
depends on the finish time of the predecessor task.
Finish-to-Start
This value means that the start time of the dependent task
depends on the finish time of the predecessor task. This is the
most common type of dependency.
Start-to-Finish
This value means that the finish time of the dependent task
depends on the start time of the predecessor task.

© Copyright IBM Corporation 2011. Form Properties | 307

 Start-to-Start
This value means that the start time of the dependent task
depends or the start time of the predecessor task.
triLagInputDaysNU
If the value of this field is negative, it is a lead, which means that
the successor task can start sooner. If the value is positive, it is a
lag, which means the successor task has to start later. Whether
this is measured from the start or finish of the predecessor task to
the start or finish of the dependent task is determined by the
value of the triDependencyRelationshipLI field.
triLagInputHoursNU
If the value of this field is negative, it is a lead, which means that
the successor task can start sooner. If the value is positive, it is a
lag, which means the successor task has to start later. Whether
this is measured from the start or finish of the predecessor task to
the start or finish of the dependent task is determined by the
value of the triDependencyRelationshipLI field.
triLagWorkingHoursNU
If the value of this field is negative, it is a lead, which means that
the successor task can start sooner. If the value is positive, it is a
lag, which means the successor task has to start later. Whether
this is measured from the start or finish of the predecessor task to
the start or finish of the dependent task is determined by the
value of the triDependencyRelationshipLI field.
Dependencies can be created from within the Gantt section by drag-
ging a line between two tasks, provided there is workflow called
triTask - Synchronous - Create Dependancy from Selected Task that creates a
triDependency record with the necessary associations.

Resources
It is often the case that you want to associate resources with tasks.
Resources that can be associated with tasks are represented by
records created from the triResource business object in the triIntermediate
module. A triResource record has a number of fields that can be used to
describe the resource it represents. It also has a number of sections
that can be used to reference other records that describe the
resource being represented. Applications and people have a great
deal of leeway in how they use these fields and sections, since nei-
ther the Gantt section nor the scheduling engine rely on them.

308 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

triResource records have one field that must be filled in. The value of
the triNameTX field is used as the name of the resource. Resource
names appear in the Gantt chart as shown in Figure 6-42.

Figure 6-42. Gantt Chart Showing Resources Assigned to a Task

To indicate that a resource is needed by a task, a triResource record

must have an association with the task record. The name of the asso-
ciation on the task side of the association must be Assigned. The name
of the association on the triResource side of the association must be
Assigned To.

The triResource record also must have an association with the record
that describes the underlying resource. The association on the side of
the underlying resource must have the name Is Resource For. On the task
side of the association, the name must be Has Resource.

Using Gantt Date/Time Adjust Features via Workflow

Some of the features employed by the Gantt scheduling system also
can be accessed via workflow. For example, there are places in the
IBM TRIRIGA applications (tasks, for example) where the ability to
adjust dates based on calendar availability is desired. The same logic
employed by the Gantt scheduling system can be made available to
workflows via Custom tasks.
The following section describes the available classes used by the
Gantt scheduling system that also can be called using Custom tasks in
a workflow to adjust dates, hours, and durations based on calendar
availability for virtually any type of object. In order for these classes
to work, a calendar needs to be appropriately associated to the
record(s) that will be processed by the workflow that uses these
classes. For more information on using calendars see Chapter 10. For
more information on using Custom tasks see “Custom Task” on
page 554. For examples of how these classes have been used by the

© Copyright IBM Corporation 2011. Form Properties | 309

 IBM TRIRIGA applications you may refer to many of the Synchronous
On Change workflows in the triTask module that are used to adjust task
dates, hours, and durations using the Gantt classes defined below.
The names of the Custom task workflow calls for Gantt sections all
start with com.tririga.architecture.web.process.gantt.workflow. The following
table lists each Custom workflow call, gives a description of the call,
and shows each field and whether it is input or output. A value of Input
in a cell means that for that particular custom task, that particular
field is used to calculate other fields, labeled Output.
It is important to note that the field names listed below need to be
named exactly as listed in the business object that you are using the
classes for or the classes will not work correctly. Ignore any hyphens
you see in a class name or a field name; the class names and field
names in the system do not contain hyphens. Also, remember that a
field that is used as an input for one class may be used as an output
for another.

CalcActualDuration Fields
Calculates actual duration, triActualStartDT Input
working days and hours, total triActualEndDT Input
working hours based on actual
start and actual end date. triActualDU Output
triActualWorking- Output
HoursNU
triActualWorkingIn- Output
putHrsNU
triActualWorkingIn- Output
putDaysNU

CalcActualEndDateFromDuration Fields
Calculates actual end date, triActualStartDT Input
working hours and days, total triActualEndDT Output
working hours based on actual
start date and actual duration. triActualDU Input
triActualWorking- Output
HoursNU
triActualWorkingIn- Output
putHrsNU
triActualWorkingIn- Output
putDaysNU
Table 6-1.

310 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 CalcActualEndDateFromWkgdays Fields
Calculates actual end date, triActualStartDT Input
actual duration, actual total triActualEndDT Output
working hours based on actual
start date and actual working triActualDU Output
days and hours. triActualWorking- Output
HoursNU
triActualWorkingIn- Input
putHrsNU
triActualWorkingIn- Input
putDaysNU

CalcActualEndDateFromWkghrs Fields
Calculates actual duration, triActualStartDT Input
actual end date, actual working triActualEndDT Output
days and hours based on actual
start date and actual total work- triActualDU Output
ing hours. triActualWorking- Input
HoursNU
triActualWorkingIn- Output
putHrsNU
triActualWorkingIn- Output
putDaysNU
CalcActualStartDateFromDura-
tion Fields
Calculates actual start date, triActualStartDT Output
actual working days and hours, triActualEndDT Input
actual total working hours based
on actual end date and actual triActualDU Input
duration. triActualWorking- Output
HoursNU
triActualWorkingIn- Output
putHrsNU
triActualWorkingIn- Output
putDaysNU
CalcActualStartDateFromWkg-
days Fields
Table 6-1.

© Copyright IBM Corporation 2011. Form Properties | 311

 Calculates actual total working triActualStartDT Output
hours, actual start date, actual triActualEndDT Input
duration based on actual work-
ing days and hours and actual triActualDU Output
end date. triActualWorking- Output
HoursNU
triActualWorkingIn- Input
putHrsNU
triActualWorkingIn- Input
putDaysNU

CalcActualStartDateFromWkghrs Fields
Calculates actual start date, triActualStartDT Output
actual working days and hours triActualEndDT Input
based on actual end date and
actual total working hours. triActualDU Output
triActualWorking- Input
HoursNU
triActualWorkingIn- Output
putHrsNU
triActualWorkingIn- Output
putDaysNU

CalcBaselineDuration Fields
Calculates baseline duration, triBaselineStartDT Input
baseline working days and hours, triBaselineEndDT Input
baseline total working hours
based on baseline start and triBaselineDU Output
baseline end date. triBaselineWorking- Output
HoursNU
triBaselineWorking- Output
InputHrsNU
triBaselineWorking- Output
InputDaysNU
CalcBaselineEndDateFromDura-
tion Fields
Table 6-1.

312 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Calculates baseline end date, triBaselineStartDT Input
baseline working hours and days, triBaselineEndDT Output
baseline total working hours
based on baseline start date and triBaselineDU Input
baseline duration. triBaselineWorking- Output
HoursNU
triBaselineWorking- Output
InputHrsNU
triBaselineWorking- Output
InputDaysNU
CalcBaselineEndDateFromWkg-
days Fields
Calculates baseline duration, triBaselineStartDT Input
baseline working days and hours, triBaselineEndDT Output
baseline total working hours
based on baseline start and triBaselineDU Output
baseline end date. triBaselineWorking- Output
HoursNU
triBaselineWorking- Input
InputHrsNU
triBaselineWorking- Input
InputDaysNU
CalcBaselineEndDateFrom-
Wkghrs Fields
Calculates baseline duration, triBaselineStartDT Input
baseline end date, baseline triBaselineEndDT Output
working days and hours based on
baseline start date and baseline triBaselineDU Output
total working hours. triBaselineWorking- Input
HoursNU
triBaselineWorking- Output
InputHrsNU
triBaselineWorking- Output
InputDaysNU
CalcBaselineStartDateFromDura-
tion Fields
Table 6-1.

© Copyright IBM Corporation 2011. Form Properties | 313

 Calculates baseline start date, triBaselineStartDT Output
baseline working days and hours, triBaselineEndDT Input
baseline total working hours
based on baseline end date and triBaselineDU Input
baseline duration. triBaselineWorking- Output
HoursNU
triBaselineWorking- Output
InputHrsNU
triBaselineWorking- Output
InputDaysNU
CalcBaselineStartDateFromWkg-
days Fields
Calculates baseline total work- triBaselineStartDT Output
ing hours, baseline start date, triBaselineEndDT Input
baseline duration based on base-
line working days and hours and triBaselineDU Output
baseline end date. triBaselineWorking- Output
HoursNU
triBaselineWorking- Input
InputHrsNU
triBaselineWorking- Input
InputDaysNU
CalcBaselineStartDateFrom-
Wkghrs Fields
Calculates baseline start date, triBaselineStartDT Output
baseline working days and hours triBaselineEndDT Input
based on baseline end date and
baseline total working hours. triBaselineDU Output
triBaselineWorking- Input
HoursNU
triBaselineWorking- Output
InputHrsNU
triBaselineWorking- Output
InputDaysNU
CalcLagInputDaysHoursFrom-
WorkingHours Fields
Calculates the lag working input triLagWorking- Input
hours and lag working input days HoursNU
based on the total lag working triLagInputDaysNU Output
hours.
triLagInputHoursNU Output
Table 6-1.

314 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 CalcLagWorkingHoursFromInput-
DaysHours Fields
Calculates the total lag working triLagWorking- Output
hours based on the lag working HoursNU
input hours and lag working triLagInputDaysNU Input
input days.
triLagInputHoursNU Input

CalcPlannedDuration Fields
Calculates planned duration, triPlannedStartDT Input
planned working days and hours, triPlannedEndDT Input
planned total working hours
based on planned start and triPlannedDU Output
planned end date. triPlannedWorking- Output
HoursNU
triPlannedWorking- Output
InputHrsNU
triPlannedWorking- Output
InputDaysNU
CalcPlannedEndDateFromDura-
tion Fields
Calculates planned end date, triPlannedStartDT Input
planned working hours and days, triPlannedEndDT Output
planned total working hours
based on planned start date and triPlannedDU Input
planned duration. triPlannedWorking- Output
HoursNU
triPlannedWorking- Output
InputHrsNU
triPlannedWorking- Output
InputDaysNU
CalcPlannedEndDateFromWkg-
days Fields
Table 6-1.

© Copyright IBM Corporation 2011. Form Properties | 315

 Calculates planned duration, triPlannedStartDT Input
planned working days and hours, triPlannedEndDT Output
planned total working hours
based on planned start and triPlannedDU Output
planned end date. triPlannedWorking- Output
HoursNU
triPlannedWorking- Input
InputHrsNU
triPlannedWorking- Input
InputDaysNU

CalcPlannedEndDateFromWkghrs Fields
Calculates planned duration, triPlannedStartDT Input
planned end date, planned triPlannedEndDT Output
working days and hours based on
planned start date and planned triPlannedDU Output
total working hours. triPlannedWorking- Input
HoursNU
triPlannedWorking- Output
InputHrsNU
triPlannedWorking- Output
InputDaysNU
CalcPlannedStartDateFromDura-
tion Fields
Calculates planned start date, triPlannedStartDT Output
planned working days and hours, triPlannedEndDT Input
planned total working hours
based on planned end date and triPlannedDU Input
planned duration. triPlannedWorking- Output
HoursNU
triPlannedWorking- Output
InputHrsNU
triPlannedWorking- Output
InputDaysNU
CalcPlannedStartDateFromWkg-
days Fields
Table 6-1.

316 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Calculates planned total working triPlannedStartDT Output
hours, planned start date, triPlannedEndDT Input
planned duration based on
planned working days and hours triPlannedDU Output
and planned end date. triPlannedWorking- Output
HoursNU
triPlannedWorking- Input
InputHrsNU
triPlannedWorking- Input
InputDaysNU
CalcPlannedStartDateFrom-
Wkghrs Fields
Calculates planned start date, triPlannedStartDT Output
planned working days and hours triPlannedEndDT Input
based on planned end date and
planned total working hours. triPlannedDU Output
triPlannedWorking- Input
HoursNU
triPlannedWorking- Output
InputHrsNU
triPlannedWorking- Output
InputDaysNU
Table 6-1.

TIP: If you are using the Gantt scheduling Custom workflow tasks on a
server with no graphics card, start the Application Server with the fol-
lowing arguments to avoid java.awt.HeadlessExceptions when calling the
tasks: -Djava.awt.headless=true

© Copyright IBM Corporation 2011. Form Properties | 317

 Availability Sections
An Availability section is used to show the availability of resources
over a period of time. An Availability section looks like Figure 6-43.

Figure 6-43. Sample Availability Section

The left side of an availability section shows attributes of some

resources. Which resources are shown in the left side and which of
their attributes appear in the left side is determined entirely by a
query that is used by the Availability section.
The right side of the availability section shows the availability of the
resources over time. The availability of the resources is determined
by a free/busy status table that is internal to the IBM TRIRIGA Appli-
cation Platform. There is no way to directly manipulate the informa-
tion in the free/busy status table by editing records. Instead, the
contents of the free/busy status table are manipulated through cus-
tom Java workflow tasks that are described later on page 321 under
the heading “Manipulating the Free/Busy Status Table Through Work-
flow”.
The right side of the availability section contains a green and a red
line that you can drag left or right. The green line is called the start
line and the red line is called the end line. These lines are intended
to allow a person to interactively indicate that they want to work
with a particular range of time. However, there is no significance for

318 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

them built into the availability section. It is up to workflows to use
the position of these lines in a way that is useful. Requirements for
the Form and
Creating Availability Sections Underlying
Like other kinds of sections, you can create an Availability section by Business Object
selecting the tab that will contain the section and clicking the Add
Section action. You then set the value of the Type property to For an Availability section
to work properly, the
Availability Section. At this point, the Properties panel should look like
business object that the
Figure 6-44. form is based on must
have two Date and Time
fields named triPlannedStartDT
and triPlannedEndDT.

These two fields are used

by the Availability sec-
tion’s internal logic. Their
temporary values corre-
spond to the current posi-
tions of the green start
and the red end lines.
Applications should not
attempt to use these
fields for other purposes.

Because of the way Avail-

ability sections use
triPlannedStartDT and
triPlannedEndDT fields, forms
should not contain more
than one Availability sec-
tion. If a form contains
more than one Availability
section, their use of these
fields will cause them to
interfere with each other.

Figure 6-44. Properties for an Availability Section

“Common Section Properties” on page 243 includes information about

the following properties in an Availability section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show

© Copyright IBM Corporation 2011. Form Properties | 319

 Title Bar, Style Class, Start Row, Row Span, Start Column, and Col
Span. The properties in an Availability section that are not described
in “Common Section Properties” on page 243 follow:
Query
The value of this property is the name of the query that will be
used by this section to determine which records will be dis-
played. The direct results of this query are displayed in the left
side of the Availability section.
The information in the free/busy status table related to the
records retrieved by the query is displayed on the right side of the
Availability section, unless a value is selected for the Association
Type property. See the description of the Association Type prop-
erty for more information.
The details of how to specify the query that will be the value of
this property are described on page 277.
Workflow
The value of this property is the name of a synchronous workflow
that will be run when a person interactively moves the Availabil-
ity section’s green start line or its red end line. Workflows run this
way will usually examine the temporary value of the
triPlannedStartDT and triPlannedEndDT fields to determine the current
setting of the green start line and the red end line.
To specify the value of this property, click the icon. Clicking
the icon causes a list of synchronous workflows to appear. The
synchronous workflows in the list will be workflows launched from
records created from the business object associated with the form
that the Query section is part of. If you select one of the work-
flows in the list and click the OK action at the top of the list, the
workflow you selected becomes the value of this property.
If you want to clear the value of this property so that it has no
value, click the icon.
Association Type
If no value is specified for the Association Type property, the
free/busy status information displayed in the right side of the
Availability section is for the records returned by the query speci-
fied by the Query property.
If a value is selected for the Association Type property, it is the
name of an association. If an association name is specified, then
the Availability section expects each record returned by the query
to have the named associated with exactly one record. The right

320 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 side of the Availability section shows the free/busy status infor-
mation for the associated records. Free/Busy Status
The usefulness of the Association Type property is described in for Different
the sidebar. Kinds of
Resources
Interactive Edits of an Availability Section
It is common to use an
An Availability section does not provide any built-in way to edit any of Availability section to dis-
the information it displays. It is the responsibility of application play the free/busy status
developers to provide appropriate actions and workflows to perform of different kinds of
any appropriate editing. resources. For example,
you may need to display
Manipulating the Free/Busy Status Table Through Workflow the free/busy status of
people, conference rooms
Workflows are able to manipulate the free/busy status table through and equipment in the
Custom workflow tasks. A Custom workflow task allows a workflow to same Availability section.
access a part of the IBM TRIRIGA Application Platform’s internal logic.
Though records a query
There is a general discussion of Custom workflow tasks on page 554 returns need not be cre-
under the heading “Custom Task”. ated from the same busi-
Something common to all Custom workflow tasks is that they are ness object, they all must
be from the same module.
given a single record to work with. Using the record’s fields and asso-
To get around this limita-
ciations, the Custom workflow task must be able to do whatever it tion, use the Availability
needs to do. section’s Association
The pieces of internal logic that a Custom workflow task uses to Type property.
manipulate the free/busy status table all expect the same organiza- Have the query return
tion for the record that is passed to them. The expected organization records that summarize
is shown in Figure 6-45. real resource records. If
each of these summary
records has the associa-
Resource tion specified by the
Assigned To Has Resource Association Type prop-
triStatusCL
erty to a real resource
record, then the Availabil-
Task Person ity section will display the
free/busy status for
triPlannedStartDT resource records without
triPlannedEndDT
caring what kind of
records they are.
Figure 6-45. Organization of Records Manipulating Free/Busy Status

The names shown for the three records in Figure 6-45 are not record
types. The names just indicate the role that the record plays in
manipulating the free/busy status table. The three records can be

© Copyright IBM Corporation 2011. Form Properties | 321

 created from any business object, so long as they satisfy the follow-
ing requirements.
The record labeled Resource is the record that is passed to the Custom
workflow tasks. The Resource record must have a Classification field
named Resource. The root classification of the triStatusCL field should be
Status.

The Resource record must have an association named Has Resource with
exactly one other record. In Figure 6-45 this associated record is
labeled Person. This Person record should be the record that the Avail-
ability section will use for its right side.
The Resource record must also have an association named Assigned To
with exactly one other record. In Figure 6-45 this associated record is
labeled Task. This Task record must have Data and Time fields named
triPlannedStartDT and triPlannedEndDT. The internal pieces of logic used by
the Custom workflow task use the Task record to identify a single
chunk of time that the Person record is associated with a particular
free/busy status. Task records correspond to the colored rectangles
that appear on the right side of an Availability section.
The piece of internal logic that a Custom workflow task will use is
determined by the value of its Class Name field. Here are descrip-
tions for the pieces of internal logic a Custom workflow task can use
to manipulate the free/busy status table:
com.tririga.architecture.web.process.gantt.workflow.AddResourceFreebusy
Adds the free/busy information corresponding to the Task record for
the Person record. The beginning and end of the chunk of time will
come from the Task record’s triPlannedStartDT and triPlannedEndDT fields.
The status of this chunk of time in the free/busy status table will
be Tentative.
com.tririga.architecture.web.process.gantt.workflow.RemoveResourceFreebusy
Removes the free/busy information corresponding to the Task
record for the Resource record.
com.tririga.architecture.web.process.gantt.workflow.UpdateResourceFreebusy
Changes the start and end time for the free/busy information
corresponding to the Task record for the Person record. The new
beginning and end of the chunk of time will come from the Task
record’s triPlannedStartDT and triPlannedEndDT fields.

322 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

com.tririga.architecture.web.process.gantt.workflow.SetResourceFreebusy
Changes the status for the free/busy information corresponding to
the Task record for the Person record. The new status will come from
the Resource record’s triStatusCL field. The value must be Accepted,
Tentative, Declined, or Cancelled.

© Copyright IBM Corporation 2011. Form Properties | 323

 Stacking Sections
A Stacking section enables viewing of current or planned assignments
of demand (for example, organizations) to supply (for example, floor
area and capacity) and allows changes to be made moving some of the
demand from one location to another. A stacking section graphically
displays supply / demand data in a usable way and allows a user to
manipulate it by moving demand (for example, organization alloca-
tions) from one location to another (supply capacity) by picking one or
more demand blocks and placing them in a different supply location.
IBM TRIRIGA uses stacking sections in the IBM TRIRIGA Strategic Facil-
ity Planning product. Figure 6-46 on page 325 shows a stacking sec-
tion from IBM TRIRIGA Strategic Facility Planning. In IBM TRIRIGA
Strategic Facility Planning, demand is required area or capacity, sup-
ply is assignable area or capacity, and capacity is headcount per loca-

324 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

tion. Using this stacking section is described in the book IBM TRIRIGA
10 Strategic Facility Planning User Guide.

Figure 6-46. Example of a Stacking Section

To create a Stacking section, select the tab that will contain the sec-
tion and click the Add Section action. In the Properties panel for the
new section, set the value of the Type property to Stacking Section. At
this point the Properties panel looks like Figure 6-47.

© Copyright IBM Corporation 2011. Form Properties | 325

 Figure 6-47. Properties for a Stacking Section

When you finish defining the properties of the stacking section, click
the Apply action. To improve performance, the platform displays a
tan panel with the words “-Stacking Section-” in the middle.
“Common Section Properties” on page 243 includes information about
the following properties in a Stacking section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show
Title Bar, Style Class, Start Row, Row Span, Start Column, and Col
Span. The properties in a Stacking section that are not described in
“Common Section Properties” on page 243 follow:
Pre-Move Workflow
When the user performs a place operation, the platform executes
the pre-move workflow identified here, if one is configured. This
workflow determines whether the move is allowed. If an opera-

326 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 tion is denied, the platform displays a message to the user and
the demand block is not moved. The primary record for the work-
flow is the record for the form containing the Stacking section.
To specify a workflow, click the Search icon and choose from
the list presented.
Association Type
Select the association the section should use to access the triStack-
ControlData record from the primary record.

© Copyright IBM Corporation 2011. Form Properties | 327

 Group By Sections
A Group By section shows data in a tabular grid-like format grouped
by the values of a specified field. Figure 6-48 shows an example of a
Group By section used in a Space Forecast Survey form.

Figure 6-48. Example of Group By Section

The data in a Group By section is sourced from a query. The platform

takes sorted records from a query and displays them in a tabular for-
mat, showing data grouped by the values of one specific field. The
format shows more than one field for the record in the grouped by
section and allows dynamic runtime properties (Visible, Read-Only,
and Label) for these columns.
This section type allows a lot of data to be shown in a small amount
of real estate in a cross tab-like format. It condenses data, taking all
records with like “column” values and displaying them in a grid.

328 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

For example, if your query returned the 15 rows in Figure 6-49.

Figure 6-49. Example of Query Source for Group By Section

The result could be displayed in a Group By section as shown in

Figure 6-50. The first five rows in the query result, circled in red, cor-
respond to the first row in the Group By section, also circled in red.

Figure 6-50. Group By Section Based on Example Query

Fields in a group by section can be edited. A border indicates to the

user which fields can be edited. The platform can save the changes.
The organization of a Group By section includes three major parts, as
illustrated in Figure 6-51.

Figure 6-51. Organization of Group By Section

Group By Field
Field whose values the section will be grouped by. There should
be a discrete number of values for this field as its values deter-

© Copyright IBM Corporation 2011. Form Properties | 329

 mine the number of columns in the section. This is Period in
Figure 6-51 and is indicated by A.
Group By Columns
Fields to show in the Group By section. These are the fields that
show for each record in the row/column. This is B in Figure 6-51,
and the fields are: Actual, Actual Area, Forecast, and Forecast
Area. Notice not all are visible for each Group By field value. In
this example, the system uses runtime metadata to hide/show
based on the Group By Field value.
Columns
These fields determine the contents of the row. All records with
like valued columns make up a row. This is C in Figure 6-51, and
the fields are Location and Space Class. Raw data is sorted first on
Location, then on Space Class. All records with the same Loca-
tion/Space Class combination make up a row.
Each group of cells under a Group By Field value represents a record.

Creating Group By Sections

To create a Group By section, select the tab that will contain the sec-
tion and click the Add Section action. In the Properties panel for the
new section, set the value of the Type property to Group By Section. At
this point, the Properties panel looks like Figure 6-52.
When you finish defining the properties of the Group By section, click
the Apply action. To improve performance, the platform renders the
Group By section but does not execute the queries.
“Common Section Properties” on page 243 includes information about
the following properties in a Group By section: Type, Name, Label,
Height, Title Bar Color, Visible, Expand Section, Read Only, Show
Title Bar, Style Class, Start Row, Row Span, Start Column, and Col
Span. The properties in a Group By section that are not described in
“Common Section Properties” on page 243 follow:
Query
Click the Search icon to identify the query that defines the
Group By section. See “Selecting a Query” on page 279.
Group By
This radio button is always selected and grayed out for Group By
sections.

330 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Figure 6-52. Properties for a Group By Section

Orientation
Select either Horizontal or Vertical from the drop-down list to indi-
cate whether the grid will be horizontal or vertical in appear-
ance. It determines whether the Group By Columns and their
respective values are laid out horizontally or vertically.

© Copyright IBM Corporation 2011. Form Properties | 331

 Figure 6-53 shows an example of horizontal orientation.

Figure 6-53. Horizontal Group By Section

Figure 6-54 shows an example of a vertical orientation.

Figure 6-54. Vertical Group By Section

Although a Group By section has no automatically generated actions,

you may want to define section actions. See “Actions” on page 339.
On section save, when not in create mode, the platform checks to
make sure there is one and only one Group By field and at most one
Group By order field. If either is not true, the platform displays a
message and saves the section. On section publish, the platform
makes the same validation; however, if either is not true, the plat-
form does not publish the section. On section publish, if no query is
specified, the publish fails. Use the Validate action to help find issues
with the Group By section prior to section publish. The Validate action
is described on page 225.

Field Properties
The fields for a Group By section come from the query as Display Col-
umns for the primary business object. Use the Components panel to

332 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

add fields to the control. Figure 6-55 shows this relationship. All dis-
play columns in the Group By query can be added to the Group By sec-
tion. For example, triActualAreaNU has already been added to the Group
By section, and triForcastAreaActualNU has not yet been added but is
available in the Components section.

Figure 6-55. Example Showing Fields and Display Columns

Select what the fields represent with the Column Use property. Order
the fields left to right with the Start Row. The fields of type Column
must be first and in the sequence indicated by the query Order By set-
tings. Place the other fields in the sequence you want them to appear
in the Group By section.
The properties of a Group By section’s field are shown in Figure 6-56
on page 334.
Most are as described in “Fields” on page 247. The properties unique
to a Group By section’s field are as follows:
Label Style Class
If you do not specify a value for this property, the appearance of
Column labels and Group By value labels will be determined by
default settings in the Style Manager.
If you do specify a value for this property, it will be the name of a
field style sheet defined by the Style Sheet Editor. The style sheet
determines the appearance of the Column and Group By value
labels. The Style Sheet Editor is described in “Style Sheets” in the

© Copyright IBM Corporation 2011. Form Properties | 333

 Figure 6-56. Properties for a Group By Section’s Field

334 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 “Brand with Colors and Logos” chapter of the IBM TRIRIGA Appli-
cation Platform 3 User Experience User Guide.
Sub Label Style Class
If you do not specify a value for this property, the appearance of
this field’s Group By Column labels will be determined by default
settings in the Style Manager.
If you do specify a value for this property, it will be the name of a
field style sheet defined by the Style Sheet Editor. The style sheet
determines the appearance of the Group By Column label (these
are the circled labels in Figure 6-53 and Figure 6-54). The Style
Sheet Editor is described in “Style Sheets” in the “Brand with Col-
ors and Logos” chapter of the IBM TRIRIGA Application Platform 3
User Experience User Guide.
Column Use
The value of this property determines how the column is used
when the Group By section is rendered. The values are Group By
field, Group By order field, Group By Column, and Column.
Group By fieldis the area in the Group By section described in
“Group By Field” on page 329. During publish, the platform vali-
dates that a Group By field is defined.
Group By order field is the field supplying the values used to order the
Group By section.
is the area in the Group By section described in
Group By Column
“Group By Columns” on page 330.
Column is the area in the Group By section described in “Columns”
on page 330.
Only one field can be designated as either the Group By field or
the Group By order field. The platform validates this when you
click Apply.
If you do not set a Group By order field, the Group By field values
are sorted alphabetically.
Start Row
The sequence in which columns are displayed comes from the
Start Row property. This applies to Group By Columns and Col-
umns. It is extremely important that the Column’s Start Row is
the same order as the Order By in the defined query as this deter-
mines the layout order of the section.

© Copyright IBM Corporation 2011. Form Properties | 335

 Start Column
Use the Start Column property to indicate that the Group By Col-
umns should use two rows instead of one. For Group By Columns,
valid values are 1 and 2. The Hide Label property hides the label
on the second row if set.
Figure 6-57 shows an example of a horizontal orientation with
Start Column = 2 for Actual Area and Forecast Area, and with Hide
Label checked for Actual Area and Forecast Area:

Figure 6-57. Horizontal Orientation, Start Column = 2

If the Hide Label property had not been checked for Actual Area
and Forecast Area, the second row of labels would appear imme-
diately below the first row of labels, and would look like the fol-
lowing:

336 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 Figure 6-58 shows an example of a vertical orientation with Start
Column = 2 for Actual Area and Forecast Area, and with Hide
Label checked for Actual Area and Forecast Area:

Figure 6-58. Vertical Orientation, Start Column = 2

If there is an issue when the platform is building a multi-row /

multi-column Group By section, the platform attempts to use a
single-row layout.

Workflow Metadata
If you want to use metadata to influence the Visible, Read Only, or
Label property for the Group By Columns, the field specified as the
Group By field must be a reference field (i.e., a locator, classifica-
tion, or smart object). The metadata defined on its reference
instances will be used to determine the Visible, Read Only, or Label
properties for the Group By Columns. The data definition for the ref-
erenced object must include the Group By Column fields. Use a Mod-
ify Metadata task in a workflow to change the Group By Column
metadata on the Group By Field value records.
Labels changed via instance data are not translatable.

Data
Data in the Group By section that is editable will have Borders turned
on automatically. When the user clicks the Save or Save & Close
action, the platform updates the records with any changes made by
the user.
If there is more than one record for a given cell in the Group By sec-
tion, or there is no record for the cell, the platform writes a log
entry. If there is more than one record, the platform places one of

© Copyright IBM Corporation 2011. Form Properties | 337

 them in the cell. If there is no record, the platform places an empty
value in the cell.
The user will be able to click a read-only value in the Group By sec-
tion and see the linked record.
If the query reaches a threshold where the query results are large
enough that the platform cannot build a Group By section, the plat-
form displays a message to the user. This threshold is defined in the
TRIRIGAWEB.properties file.

Column Filters
Group By sections support column filters on the Columns type fields.
The operator and filter columns come from the query. After a user
enters a filter string, the platform re-executes the query and re-dis-
plays the Group By section filtered by the filter string.

Query
The query and the section are intertwined. The query determines the
fields available in the section by which fields are defined as the Dis-
play Columns. The query Order By determines how the data is ordered
and these must be designated as the Column fields in the Group By
section. Do not use the Group By feature of the query. The Filter Col-
umns in the query determine which Columns in the Group By section
have filters.

338 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Actions
Actions are things that can happen to something in the platform. In
this chapter, we are interested in actions that can happen to forms or
to parts of a form.
You can specify a specific response or set of responses to form
actions. Actions may be triggered by clicking something or by chang-
ing the value of a field. Actions can be associated with most parts of a
form.
Actions can be associated with the form itself. Hyperlinks to trigger
such actions appear at the top of the form. Actions associated with
the form are managed through the state transition family of the form
and underlying record. State transition families are discussed in Chap-
ter 4. The way that they control the actions of a form is discussed on
page 370 under the heading “State-Based Actions”.
Actions can be associated with sections. There are some actions that
the platform automatically creates and associates with some kinds of
sections. Section actions are discussed on page 340.
Actions can be associated with fields. Field actions are not triggered
through a hyperlink, but through changes to the contents of a field.
Field actions are discussed on page 363.
Buttons can and usually do have associated actions. Button actions are
triggered by a user clicking the button. The process of configuring a
button action is the same as the process of configuring a field action.
Button actions are also discussed on page 363.
When an action happens, the things you can specify to happen in a
sequence of responses depends on what the action is associated with.
Here are some of the possibilities:
• Some types of actions may allow you to specify that a record
should be created from a business object that you specify. If you
specify that the action should create a record, then the next thing
that will happen is that a window will pop up for a person to edit
the record’s fields.
• If the type of action does not allow you to create a record, it will
allow you to specify that a window should pop up that displays the
content from a URL that you specify.
• You may specify that a synchronous workflow should be run.

© Copyright IBM Corporation 2011. Actions | 339

 • If you specify that the action should run a synchronous workflow,
there may be the option of specifying an association that should
be created to allow the workflow to navigate to other records.

Section Actions
You can explicitly specify actions for a section in a form. You can also
request that the platform automatically generate some standard
actions. Except for properties used to request the automatic genera-
tion of standard actions, you cannot specify actions for a section until
after the first time you save the section.
If a section is a type of section for which you can explicitly specify
actions, after the first time you save the section, a list of actions will
appear below its properties. The list of actions will look like
Figure 6-59.

Figure 6-59. Empty Action List

This list of actions is initially empty for a Form section because it has
no automatically generated actions. You can add an action by click-
ing the Add action at the top of the list. You can delete an action, if
it is not automatically generated, by selecting the radio button next
to it and then clicking the Delete action.
You cannot delete automatically generated actions. To make an auto-
matically generated action not appear at the top of the section, edit
the action’s properties and uncheck the Visible property’s check box.
To edit the properties of an action, click its name.

340 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

The details of what actions and responses are available vary with the
type of section. There are separate descriptions for each type of sec-
tion:
Form Section page 341
Smart Section page 349
Query Section page 356
Report Section No action can be associated with a Report section.
Excel Section You cannot explicitly specify actions for an Excel section.
Gantt Section Only Form section Execute Workflow actions (see page 343)
can be associated with a Gantt section
Multi Tab Section No actions can be directly associated with a Multi Tab sec-
tion.

Form Section Actions

After you click the Add action to create a new action for a Form sec-
tion, the action’s properties look like Figure 6-60.

Figure 6-60. Initial Properties for a Form Section Action

The first few properties are always the same. If you select different
values for the Action Type property, you will see different properties
below the Action Type property. We begin our explanation of the
properties of a Form section’s actions with properties that do not
depend on the value of the Action Type property.
Label
This is the text of a hyperlink that will appear at the top the sec-
tion. Clicking the hyperlink will trigger this action.
Display Sequence
The value of this property is a number.

© Copyright IBM Corporation 2011. Actions | 341

 The order of the action hyperlinks displayed at the top of the sec-
tion depends on the value of the actions’ Display Sequence prop-
erty. The actions are displayed from lowest Display Sequence
value to highest Display Sequence value.
Popup
If the check box in this property is checked, a window will pop up
when someone clicks this action. The nature of the window that
pops up depends on the value of the Action Type property.
Visible
If this check box is checked, the hyperlink for this action will be
visible. If the check box is not checked, the hyperlink will be hid-
den. The default for this property is for the check box to be
checked.
Active
If the check boxes for both the Visible property and this property
are checked, then the hyperlink for this action will be displayed in
its normal way and clicking the hyperlink will trigger the action.
If the check box for the Visible property is checked, but the check
box for this property is not checked, then the hyperlink will be
grayed out. Clicking the hyperlink will not trigger this action.
Access Key
The value of this property identifies a way to execute this action
from the keyboard. The value of this property should be a single
character. Pressing the Alt key and the specified character then
the Enter key while working on the form will allow you to exe-
cute this action.
Action Type
The value of this property determines the type of response that
will be given to this action. The values you can select for this
property are determined by whether the check box for the Popup
property is checked.
If the check box for the Popup property is not checked, the only
value available for this property is Execute Workflow. The meaning of
this value is discussed in the next part of this chapter.
If the check box for the Popup property is checked, then the
value for this property may be one of
• Form
The meaning of this value is discussed on page 343.
• Query
The meaning of this value is discussed on page 346.

342 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 • URL
The meaning of this value is discussed on page 348.

Form Section Execute Workflow Actions

If the value of the Action Type property is Execute Workflow, the
response to the action will be to just run a synchronous workflow.
This option is available only if the check box for the Popup property is
not checked. Figure 6-60 on page 341 shows what the action’s proper-
ties look like when the value of the Action Type property is Execute
Workflow.

Here is an explanation of the properties that appear under the Action

Type property when its value is Execute Workflow:
Workflow
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with this form. The workflow you select from this list is the
workflow that will run when this action is triggered.
The name of this property is a hyperlink. Clicking the name of this
property will allow you to view or edit the definition of the
selected workflow.

Form Section Form Actions

If the value of the Action Type property is Form, the response to the
action will be to create a record and run synchronous workflows. This
option is available only if the check box for the Popup property is
checked.
When the value of the Action Type property is Form, the properties
for the action look like Figure 6-61. Here is an explanation of the
properties that appear under the Action Type property when its value
is Form:
Popup Module
The value of this property is the name of the module that con-
tains the form to use for editing records that will be created by
this action. The drop-down list for this property contains the
names of all modules in the IBM TRIRIGA Application Platform
environment.
Popup Form
The value of this property is the name of the form to use for edit-
ing records that will be created by this action. This also deter-

© Copyright IBM Corporation 2011. Actions | 343

 Figure 6-61. Form Section Form Action Properties

mines the type of record created by this action. The business

object used by this action to create records will be the business
object associated with the form named by this property.
The drop-down list in this property contains the names of forms in
the module named by the value of the Popup Module property.
Pre Form Workflow
The value of this property is the name of a synchronous workflow
that will be run before the window pops up that allows the user to
edit the record created by this action. The Pre Form workflow
runs after the record is physically created.
The workflow is able to navigate from the record being edited by
this form to the newly created record by using the association
specified by the Association property.
If this property does not have a value, then no workflow will be
run before the window pops up.
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with the form selected in the Popup Form property. The
workflow you select from this list is the workflow that will run
when this action is triggered. The selected workflow will run

344 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 instead of the workflow defined for the business object as the
Pre-Create Workflow property in Data Modeler. Pre-Create work-
flows are discussed on page 34.
The name of this property is a hyperlink. Clicking the name of this
property will allow you to view or edit the definition of the
selected workflow.
Workflow
The value of this property is the name of a synchronous workflow
that will be run after the person using the form is finished editing
the record this action created. More precisely, this workflow is
run after the person editing the newly created record initiates an
action that changes the state of the newly created record to a
state other than null and then closes the window that the record
was in.
The workflow is able to navigate from the record being edited by
this form to the newly created record by using the association
specified by the Association property.
If this property does not have a value, then no workflow will be
run after the newly created record has been edited.
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with this form. The workflow you select from this list is the
workflow that will run when this action is triggered.
The name of this property is a hyperlink. Clicking the name of this
property will allow you to view or edit the definition of the
selected workflow.
Association
The value of this property is the name of an association that will
be created by this action from the record being edited by this
form to the record created by this action. The workflow run by
this action can use this association to navigate to the newly cre-
ated record.
The names in this property’s drop-down list are the names in the
List Manager’s Association Types list.
Permanent Association
If the check box for this property is not checked, then the associ-
ation specified by the Association property is considered a tempo-
rary association. If the association is a temporary association,
then the association is automatically deleted after the workflows
have completed.

© Copyright IBM Corporation 2011. Actions | 345

 If the check box for this property is checked, then the association
specified by the Association property is considered a permanent
association. Permanent associations are not automatically
deleted.
Save On Form Popup
If the check box for this property is not checked, the underlying
parent record is not saved after the popup renders.
If the check box for this property is checked, the system saves the
underlying parent record data as soon as the popup is rendered.

Form Section Query Actions

If the value of the Action Type property is Query, the response to the
action will be to run a query, pop up a window containing the results
of the query, allow a person to select some of the query results and
then run a synchronous workflow. This option is available only if the
check box for the Popup property is checked.
When the Action Type property’s value is Query, the action’s proper-
ties look like Figure 6-62. Here is an explanation of the properties
that appear under the Action Type property when its value is Query:

Figure 6-62. Form Section Query Action Properties

346 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Popup Module
The value of this property is the name of the module that con-
tains the Query to be run. The drop-down list for this property
contains the names of all modules in the IBM TRIRIGA Application
Platform environment.
Popup Query
The value of this property is the name of the Query to be run.
The drop-down list in this property contains the names of queries
and reports in the module specified by the value of the Popup
Module property.
The name of this property is a hyperlink. Clicking the name of this
property will allow you to view or edit the definition of the
selected query or report.
Single Record Select
If this check box in this property is checked, the pop-up query will
only allow a user to be able to pick one of the query results.
If this check box in this property is not checked, the pop-up query
will allow a user to be able to pick any number of the query
results.
Workflow
The value of this property is the name of a synchronous workflow
that will be run after the person using the form is finished select-
ing query results. The workflow is able to navigate from the
record being edited by this form to the records that correspond to
the selected query results by using the association specified by
the Association property.
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with this form. The workflow you select from this list is the
workflow that will run when this action is triggered.
The name of this property is a hyperlink. Clicking the name of this
property will allow you to view or edit the definition of the
selected workflow.
Association
The value of this property is the name of an association that will
be created by this action from the record being edited by this
form to the records that correspond to the selected query results.
The workflow run by this action can use this association to navi-
gate to the selected records.

© Copyright IBM Corporation 2011. Actions | 347

 The names in this property’s drop-down list are the names in the
List Manager’s Association Types list.
Permanent Association
If the check box for this property is not checked, then the associ-
ation specified by the Association property is considered a tempo-
rary association. If the association is a temporary association,
then the association is automatically deleted after the workflows
have completed.
If the check box for this property is checked, then the association
specified by the Association property is considered a permanent
association. Permanent associations are not automatically
deleted.

Form Section URL Actions

If the value of the Action Type property is URL, the response to the
action will be to pop up a window. This option is available only if the
check box for the Popup property is checked.
When the value of the Action Type property is URL, the properties for
the action look like Figure 6-63. Here is an explanation of the proper-
ties that appear under the Action Type property when its value is URL:

Figure 6-63. Form Section URL Action Properties

URL
The content of the window that pops up will come from the URL
specified as the value of this property

348 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Smart Section Actions
The actions you can explicitly specify for a Smart section are similar
to those you specify for a Form section. See page 341 for a descrip-
tion of the actions you can explicitly specify for a Form section.
The kinds of actions that are automatically generated for Smart sec-
tions are discussed in the following parts of this chapter. Find actions
are discussed in the next section of this chapter. Clear and Delete
actions are discussed on page 352. Add actions for Smart sections are
discussed on page 353.

Smart Section Find Action

The IBM TRIRIGA Application Platform automatically generates a Find
action for Smart sections that reference a stand alone or link busi-
ness object. This Find action allows a person to use a query to find a
record and add the found record to the Smart section.
When a person clicks the Find action, a panel pops up displaying the
results of a query that finds records of the type referenced by the
underlying smart section. The person selects records in the panel that
he or she wants to be referenced by the smart section. The person
then clicks the panel’s Accept action which closes the panel and
causes the smart section to reference the selected record(s).
There are some slight differences in what the Find action does for
single-record smart sections and multiple-record smart sections. For
multiple-record smart sections, it is possible for the person who clicks
the Find action to select multiple records in the panel that pops up.
Also, the multiple-record smart section will reference the selected
records in addition to any records it previously referenced.
For single-record smart sections, the person who clicks the Find
action can select only one record. When the single-record smart sec-
tion is made to reference the selected record, it will no longer refer-
ence the record it previously referenced.
The Find action is not generated if the underlying smart section refer-
ences an embedded business object. Embedded records exist only in
smart sections, so they cannot be found using a query.

© Copyright IBM Corporation 2011. Actions | 349

 When you are setting up a Smart section, the Find action is gener-
ated when you first save the section. It will appear in the action list
looking like Figure 6-64.

Figure 6-64. Single-Record Smart Section Actions

You should edit the properties of a Find action, at least specifying the
query to use for finding records. The default query finds every record
that the Smart section’s underlying association would allow to be in
the Smart section. It displays only the name of the record. You will
generally want to be more selective about which records are dis-
played. Also, you will generally want more than just the name of the
records to be displayed. For these reasons, you will generally want to
create a query that is more appropriate for the Find action and edit
the Find action’s properties so that the Find action will use the
query.
To edit the properties of the Find action, click the Find hyperlink that
is its name. The properties of a Find action will look like Figure 6-65.

Figure 6-65. Properties for a Find Action

The property you will most usually set is the URL property. The value
of this property identifies the query that will be used to find records.
To select a query, click the icon in the URL property. Clicking the
icon causes a Select Items panel to pop up. You use the Select
Items panel to select a query. The details of how to use the Select
Items panel are discussed on page 279 under the heading “Selecting a
Query”.

350 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

If you want to reset the value of the URL property so that the Find
action uses the default query, click the icon.
The Find action has these other properties:
Label
This is the text of a hyperlink that will appear at the top the sec-
tion. Clicking the hyperlink will trigger this action.
Display Sequence
The value of this property is a number.
The order of the action hyperlinks displayed at the top of the sec-
tion depends on the value of the actions’ Display Sequence prop-
erty. The actions are displayed from lowest Display Sequence
value to highest Display Sequence value.
Popup
The check box in this property is always checked and grayed out.
You cannot change it.
Visible
If this check box is checked, this action will be visible. If the
check box is not checked, this action will be hidden. The default
for this property is for the check box to be checked.
If you do not want this action to be available to people, then
uncheck the check box for this property.
Active
If the check boxes for both the Visible property and this property
are checked, then the hyperlink for this action will be displayed in
its normal way. Clicking the hyperlink will trigger the action.
If the check box for the Visible property is checked, but the check
box for this property is not checked, then the hyperlink will be
grayed out. Clicking the hyperlink will not trigger this action.
Access Key
The value of this property identifies a way to execute this action
from the keyboard. The value of this property should be a single
character. Pressing the Alt key and the specified character then
the Enter key while working on the form will allow you to exe-
cute this action.
Action Type
The value of this property is always System Action.

© Copyright IBM Corporation 2011. Actions | 351

 Smart Section Delete/Clear Action
The IBM TRIRIGA Application Platform automatically generates an
action for Smart sections to cause them to stop referencing records.
For single-record Smart sections, the name of the action is Clear. This
action causes the underlying smart section not to reference a record.
For multiple-record Smart sections, the name of the action is Delete.
In a multiple-record Smart section there is a check box next to the
display of each record. This action causes the underlying smart sec-
tion to stop referencing records whose check box in the Smart section
is checked.
When you are setting up a Smart section, the Clear or Delete action is
generated when you first save the section. It will appear in the action
list looking like Figure 6-64 on page 350 for a single-record smart sec-
tion or Figure 6-66 for a multiple-record smart section.

Figure 6-66. Multiple-Record Smart Section Actions

If you click the name of the action, you will see the action’s proper-
ties which will look like Figure 6-67.

Figure 6-67. Properties for a Clear or Delete Action

Here are descriptions of the properties for these actions:

Label
This is the text of a hyperlink that will appear at the top the sec-
tion. Clicking the hyperlink will trigger this action.
Display Sequence
The value of this property is a number.

352 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 The order of the action hyperlinks displayed at the top of the sec-
tion depends on the value of the actions’ Display Sequence prop-
erty. The actions are displayed from lowest Display Sequence
value to highest Display Sequence value.
Popup
The check box in this property is always grayed out and not
checked. You cannot change it.
Visible
If this check box is checked, this action will be visible. If the
check box is not checked, this action will be hidden. The default
for this property is for the check box to be checked.
If you do not want this action to be available to people, then
uncheck the check box for this property.
Access Key
The value of this property identifies a way to execute this action
from the keyboard. The value of this property should be a single
character. Pressing the Alt key and the specified character then
the Enter key while working on the form will allow you to exe-
cute this action.
Active
If the check boxes for both the Visible property and this property
are checked, then this action’s hyperlink will be displayed in its
normal way. Clicking the hyperlink will trigger the action.
If the check box for the Visible property is checked, but the check
box for this property is not checked, then the hyperlink will be
grayed out. Clicking the hyperlink will not trigger this action.
Action Type
The value of this property is always System Action.

Smart Section Add Action

The IBM TRIRIGA Application Platform can automatically generate an
action to new records and add them to a Smart section’s underlying
smart section. The default label for this action is Add. Whether or not
the platform actually does generate the action depends on two
things:
• If the smart section references embedded records, the action is
always generated. However, if the smart section references
embedded records, the Smart section will have a property labeled
Quick Add. If the check box in the Quick Add property is

© Copyright IBM Corporation 2011. Actions | 353

 checked, the response to the action is different. The response
that is given if the Quick Add property is checked is described on
page 355 under the heading “Smart Section Quick Add Action”.
• If the smart section references stand alone or link records, the
section will have a property labeled Show Add. If the check box in
the Show Add property is checked, the action is generated.
When you are setting up a Smart section, the Add action is generated
when you first save the section. It will appear in the action list look-
ing like Figure 6-68.

Figure 6-68. Smart Section Add Action

If you click the name of the action, you will see the action’s proper-
ties which will look like Figure 6-69.

Figure 6-69. Properties for an Add Action

Here are descriptions of the properties for these actions:

Label
This is the text of a hyperlink that will appear at the top the sec-
tion. Clicking the hyperlink will trigger this action.
Display Sequence
The value of this property is a number.
The order of the action hyperlinks displayed at the top of the sec-
tion depends on the value of the actions’ Display Sequence prop-
erty. The actions are displayed from lowest Display Sequence
value to highest Display Sequence value.

354 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Popup
The check box in this property is always grayed out and checked.
You cannot change it.
Visible
If this check box is checked, this action will be visible. If the
check box is not checked, this action will be hidden. The default
for this property is for the check box to be checked.
If you do not want this action to be available to people, then
uncheck the check box for this property.
Active
If the check boxes for both the Visible property and this property
are checked, then the hyperlink for this action will be displayed in
its normal way and clicking the hyperlink will trigger the action.
If the check box for the Visible property is checked, but the check
box for this property is not checked, then the hyperlink will be
grayed out. Clicking the hyperlink will not trigger this action.
Access Key
The value of this property identifies a way to execute this action
from the keyboard. The value of this property should be a single
character. Pressing the Alt key and the specified character then
the Enter key while working on the form will allow you to exe-
cute this action.
Action Type
The value of this property is always System Action.

Smart Section Quick Add Action

If the smart section underlying a smart section references embedded
records, then the smart section will have a property labeled Quick
Add. If the check box in the Quick Add property is checked then the
response to an Add action is different. It creates a new record with-
out popping up a window to edit it. There are a few special consider-
ations to think about since the record is created without human
interaction:
• Like all other records, records created by quick add must have a
unique name. Since the record is embedded, the name only needs
to be unique within the records in the smart section that refer-
ences it. If the name is not at least unique within its smart sec-
tion, then the record will not be created.

© Copyright IBM Corporation 2011. Actions | 355

 Usually the uniqueness of a record’s name comes from a control
number field or a workflow.
• Fields that are not part of the name but are supposed to be
required should have a default value.
• You should think about default values for fields that are not
required.

Query Section Actions

After you create a Query section, its action list looks like Figure 6-70.

Figure 6-70. Initial Action List for a Query Section

Two actions are automatically generated for a Query section.

• The Find action pops up a window to find records that are not in
the Query section because they do not have the required associa-
tion with the record that contains the Query section. The Find
action is discussed in greater detail on page 359.
• The DeAssociate action removes the association between selected
records in the Query section and the record that contains the
Query section. The DeAssociate action is discussed in greater
detail on page 362.

356 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

If you click the Add action to create a new action for a Query sec-
tion, the action’s properties look like Figure 6-71.

Figure 6-71. Initial Properties for a Query Section Action

The first few properties are always the same. If you select different
values for the Action Type property, you will see different properties
below the Action Type property. We begin our explanation of the
properties of a Query section’s actions with properties that do not
depend on the value of the Action Type property.
Label
This is the text of a hyperlink that will appear at the top the sec-
tion. Clicking the hyperlink will trigger this action.
Display Sequence
The value of this property is a number.
The order of the action hyperlinks displayed at the top of the sec-
tion depends on the value of their Display Sequence property.
The actions are displayed from lowest Display Sequence value to
highest Display Sequence value.
Popup
If the check box in this property is checked, a window will pop up
when someone clicks this action. The nature of the window that
pops up depends on the value of the Action Type property.
Visible
If this check box is checked, the hyperlink for this action will be
visible. If the check box is not checked, the hyperlink will be hid-

© Copyright IBM Corporation 2011. Actions | 357

 den. The default for this property is for the check box to be
checked.
Active
If the check boxes for both the Visible property and this property
are checked, then the hyperlink for this action will be displayed in
its normal way and clicking the hyperlink will trigger the action.
If the check box for the Visible property is checked, but the check
box for this property is not checked, then the hyperlink for this
action will be grayed out. Clicking the hyperlink will not trigger
this action.
Access Key
The value of this property identifies a way to execute this action
from the keyboard. The value of this property should be a single
character. Pressing the Alt key and the specified character then
the Enter key while working on the form will allow you to exe-
cute this action.
Action Type
The value of this property determines the type of response that
will be given to this action. The values you can select for this
property are determined by whether the check box for the Popup
property is checked.
If the check box for the Popup property is not checked, the only
value available for this property is Execute Workflow. The meaning of
this value is discussed in the next part of this chapter.
If the check box for the Popup property is checked, then the
value for this property may be one of
• Form
The meaning of this value is exactly the same as for a Form
section action with its Action Type set to Form. This is dis-
cussed on page 343.
• Query
The meaning of this value is exactly the same as for a Form
section action with its Action Type set to Query. This is dis-
cussed on page 346.
• URL
The meaning of this value is exactly the same as for a Form
section action with its Action Type set to URL. This is dis-
cussed on page 348.

358 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Query Section Execute Workflow Action
If the value of the Action Type property is Execute Workflow, the
response to the action will be to just run a synchronous workflow.
This option is available only if the check box for the Popup property is
not checked. Figure 6-71 on page 357 shows what the action’s proper-
ties look like when the value of the Action Type property is Execute
Workflow.
Here is an explanation of the properties that appear under the Action
Type property when its value is Execute Workflow:
Workflow
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with this form. The workflow you select from this list is the
workflow that will run when this action is triggered.
The name of this property is a hyperlink. Clicking the name of this
property will allow you to view or edit the definition of the
selected workflow.
Association
The value of this property is the name of an association that will
be created by this action from the record being edited by this
form to the records that correspond to the selected query results.
The workflow run by this action can use this association to navi-
gate to the selected records.
The names in this property’s drop-down list are the names in the
List Manager’s Association Types list.
Permanent Association
If the check box for this property is not checked, then the associ-
ation specified by the Association property is considered a tempo-
rary association. If the association is a temporary association,
then the association is automatically deleted after the workflow
has completed.
If the check box for this property is checked, then the association
specified by the Association property is considered a permanent
association. Permanent associations are not automatically
deleted.

Query Section Find Action

A Query section’s Find action pops up a panel to find records that are
not in the Query section because they do not have the required asso-

© Copyright IBM Corporation 2011. Actions | 359

 ciation with the record that contains the Query section. For the con-
tents of the Find pop-up to make sense and be consistent with the
contents of the Query section you need to provide a query specifi-
cally for this purpose.
When someone is looking at the query results popped up by a Find
action, he can check the check boxes next to records he would like
added to the Query section. The Find action does not exactly add the
records to the Query section but does something else that should
accomplish the same thing if all is properly configured.
When someone clicks the Accept action at the top of the popped up
panel, it creates an association from the record associated with the
form to the records whose check boxes were checked in the pop-up
panel. The name of the association is the name specified as the value
of the Query section’s Association Type property, which is described
on page 281.
The Find action returns records only from the business object that the
Query section is defined against, unless multiple business objects are
used in the query.
If you click the name of the Find action, you will see its properties.
The properties of a Find action look like Figure 6-72.

Figure 6-72. Query Section Find Action Properties

The most important property is the URL property. This property’s

value identifies the query that will be used to find records.
To select a query, click the icon in the URL property. Clicking the
icon causes a Select Items panel to pop up. You use the Select
Items panel to select a query. The details of how to use the Select

360 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Items panel are discussed on page 279 under the heading “Selecting a
Query”.
If you want to reset the value of the URL property so that the Find
action uses the default query, click the icon.
The Find action has these other properties:
Label
This is the text of a hyperlink that will appear at the top the sec-
tion. Clicking the hyperlink will trigger this action.
Display Sequence
The value of this property is a number.
The order of the action hyperlinks displayed at the top of the sec-
tion depends on the value of the actions’ Display Sequence prop-
erty. The actions are displayed from lowest Display Sequence
value to highest Display Sequence value.
Popup
The check box in this property is always checked and grayed out.
You cannot change it.
Visible
If this check box is checked, this action will be visible. If the
check box is not checked, this action will be hidden. The default
for this property is for the check box to be checked.
If you do not want this action to be available to people, then
uncheck the check box for this property.
Active
If the check boxes for both the Visible property and this property
are checked, then the hyperlink for this action will be displayed in
its normal way and clicking the hyperlink will trigger the action.
If the check box for the Visible property is checked, but the check
box for this property is not checked, then the hyperlink will be
grayed out. Clicking the hyperlink will not trigger this action.
Access Key
The value of this property identifies a way to execute this action
from the keyboard. The value of this property should be a single
character. Pressing the Alt key and the specified character then
the Enter key while working on the form will allow you to exe-
cute this action.
Action Type
The value of this property is always System Action.

© Copyright IBM Corporation 2011. Actions | 361

 Query Section DeAssociate Action
This action removes records from a Query section if the check box
that corresponds to the record is checked. The way it removes records
for the Query section is to remove an association from the record
associated with the form to the records whose check boxes were
checked in the pop-up panel. The name of the association it removes
is the name specified as the value of the Query section’s Association
Type property, which is described on page 281.
The DeAssociate action may have other consequences, depending on
what else relies on the association.
The properties of a DeAssociate action are the same as for the Find
action, except that it does not have a URL property.

362 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Field and Button Actions
Field actions are triggered when the IBM TRIRIGA Application Plat-
form detects that a user has finished changing the value in a field.
Button actions are triggered when a user clicks a button. To create a
new field action, select a field in the Navigation panel. Scroll to the
bottom of the field's properties, and click Add in the Actions section.
To create a new button action, add a new Form Action field, as
described on page 265, and save the button. Now scroll to the bot-
tom of the properties, and click Add in the Actions section. The way
to set up field and button actions is very similar. Figure 6-73 shows
what the properties of a field action look like.

Figure 6-73. Field Action Properties

For both a field action and a button action, the value of the Label
property is read-only. For a field action the value of the Label prop-
erty is always onChange. For a button action the value of the Label
property is always onClick. That is the only difference in the setup for
the two kinds of actions.
Here are the things that you can arrange for in a response to a field or
button action:
• You can arrange for a window to pop up with the results of a
query. This will allow the user to select records that correspond
to query results.

© Copyright IBM Corporation 2011. Actions | 363

 • You can arrange for a workflow to run. If you also had the query
pop up in a window, the workflow can be aware of which records
were selected in the query.
• You can arrange for a record to be created and a form to pop up
so the person using the form can edit the new record.
Here are descriptions of the other properties for these actions:
Popup Module
The value of this property is the name of the module that con-
tains the query to be run. The drop-down list for this property
contains the names of all modules in the IBM TRIRIGA Application
Platform environment.
If no value is specified for this property, no query will be run.
Popup Query
The value of this property is the name of the query to be run. If
no value is specified for this property, no query will be run.
The drop-down list in this property contains the names of queries
and reports in the module specified by the value of the Popup
Module property.
The name of this property is a hyperlink. Click the name of this
property to view or edit the definition of the selected query or
report.
Single Record Select
If the check box in this property is checked, the person using the
form will only be able to pick one of the query results.
If the check box in this property is not checked, the person using
the form will be able to pick any number of query results.
Workflow
The value of this property is the name of a synchronous workflow
that will run after the person using the form is finished selecting
query results. If no query is run, the workflow is run immediately.
The workflow is able to navigate from the record being edited by
this form to the records that correspond to selected query results
by using the association specified by the Association property.
If this property does not have a value, no workflow will run after
the newly created record has been edited.
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with this form. The workflow you select from this list is the
workflow that will run when this action is triggered.

364 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 The name of this property is a hyperlink. Clicking the name of this
property will allow you to view or edit the definition of the
selected workflow.
Association
The value of this property is the name of an association that may
be created by this action. If a query is specified and a user selects
some of the query results, an association with the specified name
is created from the record being edited by this form to the
records that correspond to the selected query results. The work-
flow that runs after the query results are selected can use the
association to retrieve the selected records.
If it is specified that this action will create a record, an associa-
tion with the specified name is created from the record being
edited by this form to the newly created record. The workflows
specified by the Pre Form Workflow property or the Post Form
Workflow property can use this association to navigate from the
record being edited by this form to the newly created record.
The names in this property’s drop-down list are the names in the
List Manager’s Association Types list.
Permanent Association
If the check box for this property is not checked, the associations
created by this action are considered temporary. If the associa-
tions are temporary, they are automatically deleted after the
workflows have finished.
If the check box for this property is checked, the associations cre-
ated by this action are considered permanent and are not auto-
matically deleted.
Save On Form Popup
If the check box for this property is not checked, the underlying
parent record is not saved after the popup renders.
If the check box for this property is checked, the system saves the
underlying parent record data as soon as the popup is rendered.
Popup Form Module
The value of this property is the name of the module that con-
tains the form to use for editing records that will be created by
this action. The drop-down list for this property contains the
names of all the modules in the IBM TRIRIGA Application Platform
environment.

© Copyright IBM Corporation 2011. Actions | 365

 Popup Form
The value of this property is the name of the form to use for edit-
ing records that will be created by this action. This also deter-
mines the type of record created by this action. The business
object used by this action to create records will be the business
object associated with the form named by this property.
The drop-down list in this property contains the names of forms in
the module specified by the value of the Popup Module property.
Pre Form Workflow
The value of this property is the name of a synchronous workflow
that will be run before the window pops up that allows the user to
edit the record created by this action. The Pre Form workflow
runs after the record is physically created.
The workflow is able to navigate from the record being edited by
this form to the newly created record by using the association
specified by the Association property.
If this property does not have a value, no workflow will be run
before the window pops up.
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with the form selected in the Popup Form property. The
workflow you select from this list is the workflow that will run
when this action is triggered. The selected workflow will run
instead of the workflow defined for the business object as the
Pre-Create Workflow property in Data Modeler. Pre-Create work-
flows are discussed on page 34.
The name of this property is a hyperlink. Click the name of this
property to view or edit the definition of the selected workflow.
Post Form Workflow
The value of this property is the name of a synchronous workflow
that will run after the person using the form is finished editing the
record this action created. More precisely, this workflow is run
after the person editing the newly created record initiates an
action that changes the state of the newly created record to a
state other than null and the user closes the window he was using
to edit the record.
The workflow is able to navigate from the record being edited by
this form to the newly created record by using the association
specified by the Association property.

366 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 If this property does not have a value, no workflow will run after
the newly created record has been edited. If no value is specified
for the Popup Form property, no record will be created and the
workflow specified by this property will not run.
The drop-down list for this property contains the names of syn-
chronous workflows associated with the business object associ-
ated with this form. The workflow you select from this list is the
workflow that will run when this action is triggered.
The name of this property is a hyperlink. Click the name of this
property to view or edit the definition of the selected workflow.

© Copyright IBM Corporation 2011. Actions | 367

 Includes/Forms
The Includes/Forms tab of a Form Wizard window is used for two sep-
arate purposes. The top section is labeled Includes. It is used to con-
trol how records that are part of a hierarchy are displayed in a
manager and which form to use for them, based on the type of par-
ent they have. There is an explanation of how the Includes section is
used on page 587.
The bottom section is labeled Forms. It is used to specify what form
report templates will be available for use in the form’s Reports tab.
Form reports are described in the IBM TRIRIGA Application Platform 3
Reporting User Guide.
If the form’s Show Reports check box (described on page 232) is
checked, it means that the form will have an automatically gener-
ated Reports tab. If the form’s Show Reports check box is not
checked, it means that the form will not have a Reports tab and the
contents of the Form Wizard’s Forms section will be ignored.

368 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Style Sheets
For some applications, you may want certain kinds of fields, sections,
or tabs to be presented differently from others. You may want some
fields to present data with a different font or another kind of field to
have a label that is a different color. You may want some sections to
have a different colored title bar. If you do want to do such things,
you will want to do them not just in one form, but consistently
throughout your application.
The IBM TRIRIGA Application Platform provides a way to do this in the
form of style sheets. Fields have a property named Label Style Class
(described on page 256) that can determine what the field’s label
looks like. Fields have a property named Data Style Class that deter-
mines what the field’s data looks like. Sections and tabs have a prop-
erty named Style Class that determines their appearance.
The value for these properties is a name of a style sheet that has its
own properties associated with it. To view, edit or create style
sheets, you use a tool named the Style Sheet Editor. The Style Sheet
Editor is described in “Style Sheets” in the “Brand with Colors and
Logos” chapter of the IBM TRIRIGA Application Platform 3 User Experi-
ence User Guide.

© Copyright IBM Corporation 2011. Style Sheets | 369

 State-Based Actions
Actions that apply to an entire form are managed through the state
transition family of the business object associated with the form.
State transition families are described in Chapter 4.
You can use the State Transition tab of the Form Wizard to control
how the state transition family of the business object associated with
the form is used by the form. You can use the State Transition tab to:
• Make only part of the state transition family available through the
form.
• Cause a state transition to make the underlying record read only.
• Cause a state transition to close the window that the form is in.
• Associate a keyboard shortcut with a state transition.
• Cause a state transition to create a new record.
The sequence in which actions display on a form is determined by the
sequence in which the actions appear in the State Transition tab. Top-
to-bottom in the tab corresponds on the form to left-to-right for nor-
mal actions and top-to-bottom in the More menu. The value of the
MAX_FORM_ACTION_NUMBER property in TRIRIGAWEB.properties impacts this
behavior. This property sets the number of action buttons that can
appear on the form menu, not including the More button or the X. For
example, if the form has 7 primary actions and MAX_FORM_ACTION_NUM-
BER is 4, the first 4 actions will appear on the form as buttons and the
last 3 will be in the More menu.
When you first look at a form’s State Transition tab, it shows all the
states and transitions in the state transition family of the business

370 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

object associated with the form. It will look something like
Figure 6-74.

Figure 6-74. Form Wizard State Transition Tab

If you do not want this form to have access to the Published state or
the state transition that leads to the Published state, you can delete
the Published state from the form’s view of the state transition fam-
ily.
To delete a state from this form’s view of the state transition family,
begin by selecting the state you want to delete. When you click a

© Copyright IBM Corporation 2011. State-Based Actions | 371

 state it becomes selected. You can tell that a state is selected
because its color is cyan instead of yellow, like in Figure 6-75.

Figure 6-75. State Transition Tab with Selected State

Click the Delete action to delete the selected state and all state tran-
sitions connected to it from the form’s view of the state transition
family.
When a state is selected, actions to manipulate the state appear on
the left side of the State Transition tab. You can use the Move Left
or Move Right action to change the order in which the states appear
across the State Transition tab.
If you decide that you want to delete a state transition but not a
state, you can do that too. Begin by clicking the state transition you

372 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

want to delete. Clicking a state transition selects it. A selected state
transition looks like Figure 6-76.

Figure 6-76. State Transition Tab with Selected Transition

After you have selected a transition, you can delete it by clicking the
Delete action that appears on the left side of the Form Wizard.
There may be transitions or states defined in the state transition fam-
ily of the underlying business object that are not included in the
form’s State Transition tab. This can happen because they were pre-
viously deleted from the form’s State Transition tab or because they
were added to the state transition family of the underlying business
object after the form was created.
If there are any transitions or states defined in the state transition
family of the underlying business object that are not included in the
form’s State Transition tab, they can be added to the form’s State
Transition tab by clicking its Find action. When you click the Find
action, a window pops up. The window contains a list of the transi-
tions in the state transition family of the underlying business object

© Copyright IBM Corporation 2011. State-Based Actions | 373

 that are not shown in the form’s State Transition tab. The window
looks like Figure 6-77.

Figure 6-77. List of State Transitions Missing from Form

You can add state transitions that appear in this list to the form’s
State Transition tab by checking the check box for each state transi-
tion you want to add and then clicking the Ok action. If you add any
state transitions that are connected to a state that is not in the
form’s State Transition tab, that state is also added to the form’s
State Transition tab.
When a state transition is selected, there are properties you can spec-
ify for it that appear on the left side of the Form Wizard:
Read Only
When a state transition is triggered, the record’s read-only prop-
erty is set to true or false, depending on if the state it is transi-
tioning to is read only. To make a state read only all of the
transitions coming out of that state must have this check box
checked. If a record’s read-only attribute is set, then a form dis-
playing the contents of the record will not allow the value of any
of its fields to be changed.
Default Display
Determines whether the state transition action appears on the
form as an action button by default. In other words, if you want
this action to be selectable by the user on the form, check this
box. If you want the action to be hidden, leave it unchecked. Hid-
den actions are still useful as they can be triggered by workflows
or IBM TRIRIGA Connector for Business Applications. Workflows are
discussed in Chapter 7. IBM TRIRIGA Connector for Business Appli-
cations is described in the IBM TRIRIGA Connector for Business
Applications 3 Technical Specification. Note that a sub-action can
use its Inclusion Exclusion section to override the Default Display.
See page 198 for details about using Inclusion Exclusion to change
the visibility of an action.

374 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Close Window
If the check box for this property is checked, an action that trig-
gers this state transition also will close the window that contains
the Form Wizard.
Secondary Action
If the check box for this property is checked, the action shows in
the More menu for that form.
If the check box for this property is not checked, the action
appears as a button on the form's menu bar (with an exception,
see below).
For example, if the set up is like that of Figure 6-78,

Figure 6-78. Example of Secondary Action Setup

where each action named Secondary has its Secondary Action

property check box checked and each action named Primary has

© Copyright IBM Corporation 2011. State-Based Actions | 375

 its Secondary Action property unchecked, the actions on the form
will appear as shown in Figure 6-79.

Figure 6-79. Result of Secondary Action Example Setup

Aside from allowing you to limit the number of actions that

appear on the form's menu, this property also allows you to put
rarely used or destructive actions, such as Copy or Retire, into the
More menu so they are not as prominent to the user and he or she
is less likely to accidentally click it.
Note that there is a TRIRIGAWEB.properties that impacts this behav-
ior, MAX_FORM_ACTION_NUMBER. This property limits the number of
buttons that can appear on the form menu, not including the More
button or the X. For example, if we have a set up with 7 primary
actions and MAX_FORM_ACTION_NUMBER is 4, the first 4 actions will
appear on the form as buttons, and the last 3 will be in the More
menu.
Access Key
The value of this property can be a single character. At runtime,
pressing the Alt key and the single character at the same time
then pressing the Enter key will be treated the same as clicking the
action for the state transition.
Module
The value of this property is the module that contains the form
used to edit the new record created if someone clicks an action
that triggers this state transition.
If this property has no value, then triggering this state transition
will not cause any records to be created.

376 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

 The drop-down list in this property contains a list of the modules
that are defined in the IBM TRIRIGA Application Platform environ-
ment.
Form
The value of this property is the name of the form used to edit
the new record created if someone clicks an action that triggers
this state transition. The business object associated with the
named form is used to create the new record.
If this property has no value, then triggering this state transition
will not cause any records to be created.
When a state transition is selected, there are Move Up and Move
Down actions that you can click to move the selected state transition
up or down in the form’s State Transition tab. The sequence in which
the transitions from a state appear from top to bottom in the form’s
State Transition tab corresponds to the left to right order in the
form’s action buttons, and corresponds to the top to bottom order in
the More action button for Secondary Actions, as illustrated in
Figure 6-78 and Figure 6-79.
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.

Attention: Be sure to click the Apply action on the left side of

the Form Wizard after you have finished editing the
properties of the selected state transition. If you
move on to something else without first clicking that
Apply action, then any changes you made to the state
transition’s properties will be lost.

© Copyright IBM Corporation 2011. State-Based Actions | 377

 User Messages
There are any number of messages that a form may be required to
display to a user to explain a problem or to alert the user to a note-
worthy situation. It is a common situation for multiple forms to be
required to display some of the same messages.
Many of these messages have a fixed part that is always the same and
a variable part that may be different each time the message is gener-
ated. To clarify this distinction between the fixed and variable parts
of a message, consider this example. Suppose you want to generate a
message that looks like this:
Your start date 03/08/2006 must be before your end date 02/15/2006.
The fixed part of this notification would probably be
Your start date _______ must be before your end date ________.
The variable part of the message would be the pieces of text that get
put in the blanks. In the case of the preceding example, these would
be:
• 03/08/2006
• 02/15/2006
The mechanism that satisfies these needs involves two kinds of
records that play different roles in the message creation process:
• triUserMessage records are templates for messages. The fixed por-
tion of a message’s content is specified by a User Message record.
• triUserMessageHelper records supply the variable part of a message’s
content.
In the following sections of this chapter, we supply the details needed
to use this mechanism.

User Message Records

triUserMessage records are templates for messages. They provide the
fixed portions of a message’s content. These records are normally
created interactively by a person. triUserMessage records are found in
Tools > System Setup > General > User Messages.

378 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Figure 6-80 shows an example of a triUserMessage record in a User Mes-
sage form.

Figure 6-80. User Message

The value of the ID field is used by workflows to identify the

triUserMessage record that is to be used for creating a message.

The value of the Message Content field is used to create the body of
the message. Notice that the text in the Message Content field con-
tains numbers in curly braces like {2}.
Each of these numbers in curly braces is a place holder for some text
that can be supplied from a triUserMessage record. The contents of the
Description field should describe the purpose of each of the place
holders.
TIP: If you want to display a message containing a single quote (for
example, I'm {1}), you need to escape the single quote by adding
another single quote (for example, I''m {1}).
The value of the Language field identifies the language in which the
value of the Message Content field is written.

© Copyright IBM Corporation 2011. User Messages | 379

 TIP: By creating User Message records with the same ID but different
languages, you can configure messages that are automatically trans-
lated for your users.

triUserMessageHelper
To create finished message text, a workflow creates a
record from the triUserMessageHelper business object in
triUserMessageHelper
the triHelper module. After creating the record, the workflow sets the
values of its fields and then finishes the message by triggering a
Calculate action on the triUserMessageHelper record. After the message is
finished, the workflow that triggered the Calculate action can copy
the finished message text to the appropriate field in a form.
Here are descriptions of the relevant fields in a triUserMessageHelper
record:
triIdTX
Workflows must set the value of the triIdTX field to the ID of the
triUserMessage record that will provide the fixed portion of the mes-
sage’s content.
triLanguageLI
Workflows must set the value of the triIdTX field to the Language of
the triUserMessage record that will provide the fixed portion of the
message’s content. For a given ID there could be text for multi-
ple languages. This field determines which message to retrieve. If
the language selected is not found, the helper looks for a mes-
sage in “US English”.
triInput1TX, triInput2TX,
…, triInput9TX
These fields correspond to the place holders {1}, {2}, …, {9} that
may appear in the fixed content provided in the triUserMessage
record. The value in each of these fields will be substituted for
the corresponding place holder in the content.
triUserMessageTX
Triggering a Calculate action on the triUserMessageHelper record
launches a workflow that creates a finished message with the
value of the appropriate field substituted for each place holder.
After the workflow is done, the finished message is in the
triUserMessageTX field.

380 | Chapter 6: Building User Interfaces © Copyright IBM Corporation 2011.

Chapter 1\
In this chapter: CHAPTER 7
• Managing workflows.
• Workflow naming
conventions. Creating Workflows
• Detailed description of
each workflow task type.

This chapter assumes that you are familiar with all of the workflow
concepts discussed in Chapter 5.
This chapter contains detailed descriptions of the different kinds of
workflow tasks.

Workflow Manager
Before you actually create or modify any workflows, you must first
navigate to a part of the IBM TRIRIGA Application Platform called the
Workflow Builder. The Workflow Builder is used to create new work-
flows and to modify existing workflows.
To navigate to the Workflow Builder, click the Workflow Builder item
in the Admistration menu. The Workflow Builder will appear. It looks
like Figure 7-1 on page 382.
The Workflow Builder organizes workflows by the module with which
they are associated. It shows a list of the workflows associated with
whichever module is selected. You can select a module by clicking its
name on the left side of the Workflow Builder. Clicking the name of a
module causes workflows associated with the module or one of the
business objects in the module to be listed on the right side of the
Workflow Builder.
Most workflows are associated with a particular business object in a
module. If many business objects in a module have associated work-
flows, you may prefer to select just one business object and see just
the workflows associated with that business object.
If you do not see the names of business objects in the relevant mod-
ule, click the plus sign ( ) next to the module’s name to expand the

© Copyright IBM Corporation 2011. 381

 Figure 7-1. Workflow Builder

list. The business objects in the module now show under the mod-
ule’s name. Also the plus sign ( ) next to the module name changes
to a minus sign ( ). To contract the list of business objects, click the
minus sign ( ).
The Workflow Builder has a menu of actions that can be performed on
workflows:
New
Click this action to create a new workflow.
Copy
Sometimes, you want to create a new workflow that is similar to
an existing workflow. It is easier to create a similar workflow by
starting with a copy of the selected workflow and modifying it.
Clicking the Copy action creates a new workflow that is a copy of
the currently selected workflow.
Publish
Click this action to make the selected workflow available for use.
New workflows are not available for use until they are published.
When you modify an existing workflow, the modified workflow is
not automatically put into use. The modified version of the work-
flow does not replace the version of the workflow currently in use
until the modified version of the workflow is published.

382 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 Publishing is described in greater detail on page 9.
Revise
The Publish action sets the state of a workflow to Published. As a
safeguard against unintentional modification, while the state of a
workflow is Published you cannot modify the workflow.
If you want to revise a published workflow, click the Revise
action. This changes the state of the selected workflow to Revision
In Progress. While the state of the workflow is Revision In Progress you
are allowed to modify the workflow.
Revising is described in greater detail on page 9.
Retire
Clicking the Retire action takes the currently selected workflow
out of use. It can be put back in use by publishing the workflow
again.
If the workflow to be retired is referenced by a Call Workflow task
in another workflow, the system displays a warning. Retiring is
allowed after confirmation. To see the list of workflows calling
the selected workflow, open the workflow’s Start task and click
the Callers action on the Workflow Properties section bar.
Delete
Clicking the Delete action deletes the selected workflow.
If the workflow to be deleted is referenced by a Call Workflow
task in another workflow, the system displays a warning and will
not allow the deletion. To see the list of workflows calling the
selected workflow, open the workflow’s Start task and click the
Callers action on the Workflow Properties section bar.
The Workflow Builder has a menu of actions that give you information
about a workflow. First select the radio button next to the name of
the workflow. Then select one of the following actions:
List Active Instances
Shows the record of the selected workflow being run.
List All Instances
Shows instances of this workflow that are still running.
List All Versions
Shows all versions of this workflow. The system creates a history
record whenever you change a workflow.

© Copyright IBM Corporation 2011. Workflow Manager | 383

 Where Used
A window pops up showing what references or uses the selected
workflow. The fields displayed are: Name, Type, Module, Object,
Form, Action, and Additional Information. The Type could be
other workflows, business object pre-create workflows, smart sec-
tion workflows to initialize a record, form pre-load workflows,
form Query section workflows, form Gantt section workflows,
form Availability section workflows, form Stacking section pre-
move workflows, form action workflows and pre-form workflows,
query action pre-create workflows, state transitions, and man-
ager action pre-create workflows.
If you want to export the information in the Where Used window,
click the Export Usage action at the top of the window. You will
be offered the choice of saving or opening a csv file. Clicking the
linked object opens the builder for the reference for most object
types.
Refer to page 46 for a list of references reported by Where Used.
The workflow editor allows you to view or modify a workflow. Click-
ing the New action causes the workflow editor to pop up so you can
edit the new workflow. To modify or view an existing workflow in the
workflow editor, click the workflow’s name in the Workflow Builder.

Workflow Editor
The Workflow Editor allows you view and modify workflows. Details of
the kinds of tasks that make up a workflow are discussed in following
sections.
The Workflow Editor pops up in its own window. When you create a
new workflow, the workflow editor looks like Figure 7-2.
The Workflow Editor shows the tasks of a workflow as shapes. Each
kind of task has a different color and shape. The newly created work-
flow shown in Figure 7-2 has two tasks: a Start task and an End task.
The Workflow Editor shows arrows connecting tasks. The purpose of
the arrows is to show the order in which the tasks will be performed.
The arrow in Figure 7-2 shows that after the Start task is performed,
the next task to be performed is the End task.
The Workflow Editor is organized into three sections called:
• diagram
• properties

384 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 Figure 7-2. New Workflow in Workflow Editor

• task palette
The diagram section is shown in Figure 7-2. The diagram section is the
only section of the workflow editor that is always visible.
The properties section of the workflow becomes visible when you
click one of a workflow’s tasks. The properties section that appears
after clicking the Start task is shown in Figure 7-3 on page 386.
The properties section always appears at the bottom of the window.
It shows the properties of the task that was clicked. You can tell
which task’s properties the properties section is showing because the
task is highlighted in the diagram section, as shown in Figure 7-3.
Each kind of task has a different set of properties. The properties of
each kind of workflow task are described in the following sections of
this chapter as part of the description of each kind of task.
If the properties section is already visible and you click a different
task, that task’s properties are displayed in the properties section. To
make the workflow editor stop displaying any properties section, click
the background of the diagram section.
The task palette section appears when you move the mouse pointer
over the New Task bar on the left side of the workflow editor. It looks
like Figure 7-4 on page 387.
The shapes in the task palette correspond to the different kinds of
tasks that can be in a workflow. The shape of each type of workflow
task is included in the descriptions of the workflow tasks that appear
in the following sections of this chapter.
Depending on the context and properties set in the workflow’s Start
task, some kinds of tasks may not be visible in the task palette. If a

© Copyright IBM Corporation 2011. Workflow Editor | 385

 Figure 7-3. Workflow Editor Properties Section

kind of task is visible in the task palette only under certain condi-
tions, those conditions are noted in the description of the individual
workflow task.
Use the task palette to add a task to the workflow. To add a task to
the workflow, move the mouse pointer over the New Task bar. After

386 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 Figure 7-4. Workflow Editor Task Palette

© Copyright IBM Corporation 2011. Workflow Editor | 387

 the task palette appears, click the task’s shape in the task palette.
The task palette disappears except for the shape that you clicked. As
you move the mouse pointer, the shape follows the mouse. Use the
mouse to move the task to the end of the arrow that should lead to
the task.
When you move the shape to the end of an arrow, the workflow edi-
tor shows a preview of what the workflow will look like if you leave
the task where it is. At this point you can click the task shape to leave
it where it is or move the mouse pointer to take the task shape some-
where else.
To delete a task from a workflow, click the task to make its proper-
ties visible in the properties section. If the task can be deleted (some
tasks cannot be deleted under certain circumstances), there will be a
Delete action in the menu of the properties section. Clicking the
Delete action deletes the task.

No Ok, Apply, or Cancel

You may have noticed that nowhere on the workflow editor is there
an Ok, Save, or Cancel action to click. The workflow editor works dif-
ferently in this respect from the rest of the IBM TRIRIGA Application
Platform. All changes you make to a workflow or to the properties of
a task take effect as you make them and click elsewhere, on another
task or in the background. They are not saved if you close your
browser without clicking elsewhere.

Workflow State Transitions

If a workflow triggers a state transition action and that action has
multiple sub actions, only the first sub action will be executed. The
first sub action is determined by listing the sub action labels alpha-
betically. Use actions that have at most one sub action instead of
multiple sub actions.

Workflow Naming Standards

When designing or developing workflows, they will be much easier to
understand if you use a naming convention for your tasks and work-
flows. This allows someone who is reviewing the workflow to know
your intentions for the workflow as a whole and for each task in the
workflow without interpretation. Use the following standard naming

388 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

conventions for each task type. Each task also should have a descrip-
tion that further clarifies its intent.
For Business Object names, use the Business Object upon which the
task is performing work. If the task could be doing work on any Busi-
ness Object in the Module, use the Module name. You may need to
further qualify the Business Object name to give it a more descriptive
context. For example, if you have multiple employee records that will
be used in the workflow, you could use “Supervisor” and “Employee”
to distinguish them. If you are referencing a Business Object associ-
ated to another Business Object, indicate both Business Objects and
the association relationship.
All tasks in a workflow should have unique names. Remember to add
context where required.
Figure 7-5 shows workflow naming standards. Static wording is bold.
Task Naming Conventiona Example
Business Object Name - Action - triPeople - triActivate - Trigger
Description Approval Process
or or
Business Object Name - Associate triPeople - Associate - triSpace -
- Secondary Business Object Name
Primary Location
(Asynchronous Workflow) - Description
Business Object Name - Action - cstAsset - Subflow - Count asset
Description inventory

(Subflow Workflow)
If the workflow references an as- cst-triLocation - Synchronous -
delivered business object: Populate parent fields on create
cst + “-”Business Object Name -
Action - Descriptionb
or
or
(Synchronous Workflow) cstNewBOName - Synchronous -
If the workflow references a
newly created business object: Populate parent fields on create
Business Object Name - Action -
Description
Create Business Object Name Create cstAddress from Building
from Business Object Name Primary cstAddress
(source)

Figure 7-5. Naming Conventions for Workflows

© Copyright IBM Corporation 2011. Workflow Naming Standards | 389

 Task Naming Conventiona Example
Set Business Object Name (target) Set cstProperty from cstLocation
from Business Object Name
or
(source)
or Add cstProperty: cstAddressOther
with cstAddress
Add Business Object Name (tar-
get):Section Name with Business
Object Name (source)c
Get Business Object Name (tar- Get cstProfile from cstGroup
get) from Business Object Name associated to cstBuilding
(source)

Assoc Business Object Name (tar- Assoc cstNotification to

get) to Business Object Name cstLocation
(source)
or or
DeAssoc Associate Business DeAssoc cstPeople from
Object Name (target) from Busi-
cstLocation
ness Object Name (source)
Action [space] Business Object cstRemove Temp cstAddress;
Name
Issue cstPurchaseOrder

Trigger Action Task

Delete Reference to Business Delete Reference to cstProfile
Object Name (source) from Busi- from cstGroup Associated to
ness Object Name (target) cstBuilding

Delete Reference Task

Add Child Business Object Name Add Child cstSpace to cstFloor
(source) to Business Object Name
(target)

Add Child Task

Set Project of Business Object Set Project of cstInvoiceItem
Name (target) from Business from cstContract
Object Name (source)

Attach File Name to Business Attach Deleted Cost Code.rpt to

Object Name cstNotification

Figure 7-5. Naming Conventions for Workflows (continued)

390 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Task Naming Conventiona Example
Get query Get cstPeople Associated with
cstBuildings

Assign User or Group Name to Assign Admin Group to Remove

Action Business Object Name cstContactRoles Associated to
Retired cstPeople

Assign User or Group Name to Assign At Bat cstPeople to

Approve Business Object Name Approve cstPurchaseOrder

Schedule Action for Business Schedule cstFinalIssue for

Object Name cstBidResponse

Get Temp Business Object Named Get Temp cstPeople

Set Context for Business Object Set ID to Read Only for cstPeople
Name, Form Name (if to a partic-
ular form)

Commit Temp Business Object Commit Temp cstPeople

Name

Iterate for each Business Object Iterate for each cstPeople

Name

Figure 7-5. Naming Conventions for Workflows (continued)

© Copyright IBM Corporation 2011. Workflow Naming Standards | 391

 Task Naming Conventiona Example
Call Context Call Update cstTask
triAcutalEndDT

Populate Context with Business Populate bid.xls with cstBid

Object Name

Distill Context into Business Distill bid.xls into cstBid

Object Name

Call Business Object Name - Con- Call cstTask - Permanent Save

text Validatione

Process Business Object Name Process cstPOBody

Define Variable Name Define cstInvoiceCount

Assign Variable Name Assign cstInvoiceCount

Figure 7-5. Naming Conventions for Workflows (continued)

a Do not use the ', <, >, =, or % special characters in workflow names or workflow task names.
b No spaces between the “cst-:” and the tri object name.
c Use Add when mapping records from the other task as the source to append to a section of a record.
d When performing other tasks to the results of a Get Temp Record task, use the modifier “Temp” for the
Business Object Name. For example, if you are using a Modify Records task “Add Temp cstProperty:cstAd-
dressOther with cstAddress”.
e This is the synchronous workflow name with the “ - Synchronous” removed.

392 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Workflow Tasks
The remainder of this chapter is detailed descriptions of the tasks
that can be included in a workflow. Below is a table showing on which
page you will find each type of task described.
Workflow Task Name Page Number
Add Child Task 485
Approval Task 414
Associate Records Task 464
Attach Format File Task 646
Break Task 536
Call Workflow Task 543
Create Record Task 416
Custom Task 554
DataConnect Task 561
Delete Reference Task 478
Distill File Task 722
End Task 518
Fork Task 530
Get Temp Record Task 575
Iterator Task 540
Loop Task 533
Modify Metadata Task 511
Modify Records Task 432
Notification Example 653
Populate File Task 713
Query Task 452
Retrieve Records Task 440
Save Permanent Record Task 578
Schedule Task 510 and 621
Set Project Task 492
Start Task 394
Stop Task 518
Switch Task 519
Trigger Action Task 473
User Action Task 406
Variable Assignment Task 570
Variable Definition Task 568

© Copyright IBM Corporation 2011. Workflow Tasks | 393

 Start Task
A Start task is always the first task in a workflow. It cannot be deleted
or moved. The properties of a Start task are in fact properties for the
entire workflow. The shape for a Start task is shown in Figure 7-6.
Figure 7-3 on page 386 shows the form that is initially displayed to
Figure 7-6. Start Task Shape
collect the parameters for a new workflow.
Because you cannot delete a Start task, it does not have a Delete
action in the menu for its properties as do most other kinds of tasks.
The following actions may appear in the menu for a Start task’s prop-
erties:
Publish
This action appears only if the workflow is new or under revision.
Clicking this action makes a new workflow available for use or
puts revisions to an existing workflow into use.
Publishing is described in more detail on page 9.
Revise
This action appears only if the workflow has been published.
Clicking this action creates a new version of the workflow that
you can revise without affecting the version of the workflow that
is currently in use.
Revising is described in more detail on page 9.
Retire
Clicking this action takes the existing version of the workflow out
of use. It can be put back into use by publishing it again.
If the workflow to be retired is referenced by a Call Workflow task
in another workflow, the system displays a warning. Retiring is
allowed after confirmation. To see the list of workflows calling
the selected workflow, click the Callers action on the Workflow
Properties section bar.
Retiring is described in more detail on page 9.
Callers
Click this action to see a list of the workflows that call this work-
flow.
Parameters
Clicking this action causes a list of the parameters and return val-
ues in this workflow to appear. If the workflow is synchronous or
subflow you can define input parameters and return values. More
information about workflow parameters and return values can be
found in “Workflow Parameters and Return Values” on page 402.

394 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The Start task always refers to the permanent version of the record in
the database. Any workflow tasks that refer back to the business
object of the Start task are referring to the last saved version of the
record. This means that any changes that workflow tasks make to the
Start task record are made immediately to the record in the data-
base. The exception would be if the workflow is marked as a tempo-
rary workflow or using DataConnect with Temporary setting.
The properties in a Start task’s properties are actually properties for
the entire workflow. A Start task’s Workflow Properties section has
these fields:
Name
This is the name of the workflow. This is the name that will
appear in the Workflow Builder and the name you will use to iden-
tify the workflow.
The name of the workflow is not the Start task’s label. Start tasks
do not have a label that you can change. The label that appears
on the Start task in the workflow editor’s diagram section is
always Start.
Workflow naming conventions are discussed on page 388.
Description
This is a description of the whole workflow.
Concurrence
This property is used to determine whether the workflow will be
synchronous, subflow, or asynchronous. The distinction between
synchronous and asynchronous is explained starting on page 207.
If you select the Synchronous radio button, the workflow will be
synchronous. The Start task’s properties will look like Figure 7-3
on page 386. As a synchronous workflow, it will have access to
temporary data. However, there will be no way to associate the
workflow with events, since synchronous workflows cannot be
associated with events. Nor can a synchronous workflow be used
to migrate data from staging tables into IBM TRIRIGA records
because the Integration property is not available to synchronous
workflows.
Synchronous workflows that are triggered by actions on IBM
TRIRIGA records’ forms are processed to completion before allow-
ing the user to continue. This makes them good for performing
validations or automating processes that need to complete before
the user performs their next task.

© Copyright IBM Corporation 2011. Workflow Tasks | 395

 If you select the Subflow radio button, the workflow allows
required parameters. Standard synchronous workflows only allow
optional parameters. A Subflow workflow can be selected only in
a Call Workflow task. A Subflow workflow cannot be selected as
the workflow to run for a form action, a state action, or the like.
If you select the Asynchronous radio button, the workflow will be
asynchronous. The Start task’s properties will look like Figure 7-8
on page 399. As an asynchronous workflow, it will not have access
to temporary data. However, you will be able to associate the
workflow with an event, since asynchronous workflows are
launched in response to an event. An asynchronous workflow can
be used to migrate data from staging tables into IBM TRIRIGA
records because the Integration property is available to asynchro-
nous workflows.
Temporary Data
This property is only visible if the value of Concurrence is Synchro-
nous.
The value of this property determines whether the workflow will
be accessing temporary or permanent data. This distinction is
described in more detail on page 211.
If the Permanent radio button is selected, the workflow only can
access permanent data that is stored in the record used to launch
this workflow.
If the Temporary radio button is selected, the workflow can
access temporary or permanent data that is stored in the record
used to launch this workflow.
Module
The value of this property is the module with which the workflow
is associated. This association between workflows and modules
serves two purposes:
• The Workflow Builder uses the association between workflows
and modules to organize workflows by module.
• If the workflow is associated with a particular business object,
the module is used to help identify the business object with
which the workflow will be associated.
Set the value of this property by clicking the icon. Clicking the
icon causes a list of modules to pop up. Click the module name
you want to be the value of this property.

396 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Object Type
Workflows are launched as a result of an action or system event
being performed on a record.
The value of this property is either the name of a business object
in the specified module or -Any-. If the value of this field is the
name of a business object, the workflow can be launched only as
a result of something happening that is related to a record cre-
ated from the named business object.
If the value of this property is -Any-, the workflow can be launched
by something happening related to a record created from any
business object in the specified module. The workflow will be
restricted to accessing only the fields in a record it is launched for
that have the same name as fields in the module’s base business
object.
Save Workflow Instances
If this check box is checked, a record will be kept of every time
this workflow is run. The record includes the execution path that
the workflow followed.
To see the record of this workflow being run, click the List All
Instances action at the top of the Workflow Builder. To see just
instances of this workflow that are still running, click the List
Active Instances action at the top of the Workflow Builder. These
actions are shown in Figure 7-1 on page 382.
The statuses in the list of workflow instances are described on
page 696.
It is also possible to see a list of workflow instances that have run
from a particular record. This is discussed on page 695 under the
heading “Workflow Instances”.
If this check box is not checked (the default for new workflows),
no record will be kept of this workflow running. This can produce
a noticeable speed improvement.
Lock Record For Other Users
The forms for User Action tasks and Approval tasks have a check
box with this same label. The value of this check box is used as
the default value for the like-named check boxes for User Action
and Approval tasks.
The User Action task is documented on page 406. The Approval
task is documented on page 414.

© Copyright IBM Corporation 2011. Workflow Tasks | 397

 Propagate Integration Status
The Propagate Integration Status check box indicates whether the
workflow should consider the Integration property. If the work-
flow is called by an Integration workflow, the Integration status is
propagated if the Propagate Integration Status property is
checked. If the workflow is called by an Integration workflow and
the Propagate Integration Status property is not checked, the
Integration status of the calling workflow is not propagated. The
default is for this property to be checked.
Integration is a property available to asynchronous workflows. The
Integration property is discussed on page 399.
The Start task properties if the workflow is subflow are in Figure 7-7.

Figure 7-7. Start Task Properties for Subflow Workflow

398 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The following additional properties may be visible only if the work-
flow is asynchronous.

Figure 7-8. Start Task Properties for Asynchronous Workflow

Integration
This property is always visible if the workflow is asynchronous.
When the property is selected, the workflow is used to migrate
data from staging tables into IBM TRIRIGA records. This type of
workflow is used extensively in IBM TRIRIGA DataConnect. More
information about DataConnect can be found in the DataConnect
chapter of Application Building for the IBM TRIRIGA Application
Platform 3: Data Management book.
Tasks can check the Integration status to control flow through the
workflow.

© Copyright IBM Corporation 2011. Workflow Tasks | 399

 If an event is generated while the workflow has Integration status
on and the Propagate Integration Status flag on, when that event
is processed the workflow context for the workflow(s) executed
will have the Integration status set on (true).
The Integration status can be included in a condition expression in
a Start task condition or a Switch task condition. For example, if
there are steps in a workflow that should not be called if exe-
cuted from an Integration workflow, check the Integration setting
with a Switch Condition or in the Start Condition.
On Process Completion
This property is always visible if the workflow is asynchronous.
When this property is selected, the workflow only runs when all
other asynchronous workflows for the primary event (the initiat-
ing event) have been executed. For example, assume the On Pro-
cess Completion check box is checked for workflow W1 that fires
on a Save event. Workflows W2, W3, and W4 also fire on the Save
event. A user clicks Save. W1 does not execute until W2, W3, and
W4 have finished.
The initiating event is specified by the values of the Module,
Object Type, and Event properties.
When the workflow agent detects that a process has completed, it
posts a special event. The event is constructed by taking the
event name and the record from the initiating event information.
The workflow lookup process uses the initiating event information
to identify the event as being for process completion and restricts
the workflow lookup to be for On Process Completion type work-
flows for the given module, business object, and event name of
the event.
Only one process completion event is posted for a given process.
Use an On Process Completion workflow for final processing and
clean up. Do not use it to initiate another batch of involved pro-
cessing.
To aid in debugging, the event name used in the agent thread
name has (pc) appended to it, for example, triActivate(pc).
Event
This property is always visible if the workflow is asynchronous.
The value of this property is the action or system event that can
launch this workflow. The launching of workflows is discussed on
page 208 under the heading “Launch Conditions”.

400 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 This field is a drop-down list that contains system events and the
actions that are used by the state families available to business
objects in the specified module.
If an action from the business object’s or module’s state transi-
tion family is chosen, it means that the workflow will be asyn-
chronous. The workflow will be launched when the specified
action is performed on a record created from the specified busi-
ness object. If the specified business object is -Any-, the workflow
will be launched when the specified action is performed on a
record created from any business object in the specified module.
If a system event is selected from the drop-down, the workflow is
launched when the system event happens to a record created
from the specified kind of business object. System events are dis-
cussed in more detail on page 212.
If the selection from the drop-down is the system event Associate or
the system event De-Associate, three additional fields appear to
allow the affected association to be specified: Associated Mod-
ule, Object Type, and Association.
Associated Module
This field is visible only if the selected value for Event is Associate
or De-Associate.
The value of this property is the name of the module in which the
business object used to create records at the other end of the
association is defined.
Object Type
This property is visible only if the selected value for Event is
Associate or De-Associate.
The value of this property is the name of the business object used
to create records at the other end of the association.
Association
This property is visible only if the selected value for Event is
Associate or De-Associate.
This is the name of the affected association.
At the bottom of each of the Start task examples above (e.g.,
Figure 7-8 on page 399) is a section labeled Start Conditions. You can
use the Start Conditions section to specify that the workflow should
only be launched under certain conditions.

© Copyright IBM Corporation 2011. Workflow Tasks | 401

 You can specify more than one start condition. If more than one start
condition is specified, the workflow will launch only if all the start
conditions are true.
The mechanics of specifying start conditions are described on
page 521 under the heading Workflow Condition Builder.

Workflow Parameters and Return Values

The Workflow Parameters and Return Values screen appears when-
ever you click the Parameters action. It shows the parameters and
return values for the workflow.
An example best explains how to use the Workflow Parameters and
Return Values screen. Figure 7-9 on page 402 starts this example with
a subflow workflow containing variables to hold the input parameters
and the value to be returned. The example could also be a synchro-
nous workflow, except the parameters must be optional. Figure 7-9
shows the Start task of the example workflow; the user is about to
click the Parameters action.

Figure 7-9. Start Task Example

402 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The Workflow Parameters and Return Values screen appears as shown
in Figure 7-10. Note there are two sections: the Parameters section

Figure 7-10. Initial Workflow Parameters and Return Values Screen

and the Return Values section. Clicking Add in the Parameters sec-
tion allows you to define input parameters. Clicking Add in the Return
Values section allows you to define return values. In order to have
either of these the workflow must contain some variables. Variables
are defined with the Variable Definition task, which is described in
“Variable Definition Task” on page 568.
Click Add in the Parameters section. The Workflow Parameter Defini-
tion screen appears as shown in Figure 7-11.

Figure 7-11. Adding a Required Parameter

Give the parameter a Name. The choices in the Variable drop down
are the variables defined in the workflow. Check the Required check
box if the parameter is required. In a synchronous workflow, this

© Copyright IBM Corporation 2011. Workflow Tasks | 403

 option is not available because all synchronous workflow parameters
are optional. Figure 7-12 shows adding an optional parameter.

Figure 7-12. Adding an Optional Parameter

Click the Add action in the Return Values section. When adding a
Return Value, specify its Name and select its source from the Vari-
able drop-down list, as shown in Figure 7-13.

Figure 7-13. Adding a Return Value

404 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Now the Workflow Parameters and Return Values screen looks like
Figure 7-14.

Figure 7-14. Example of Workflow Parameters and Return Values

To see how this example Start task is used with a calling workflow,
see the Call Workflow task discussion starting on page 547.

© Copyright IBM Corporation 2011. Workflow Tasks | 405

 User Action Task
A User Action task creates an action item. The action item can be
assigned to a specific person or to a group.
The shape for a User Action task is shown in Figure 7-15. The User
Figure 7-15. User Action Shape Action shape is in the task palette only if the workflow is asynchro-
nous.*
The form for a User Action task is shown in Figure 7-16. It is orga-
nized into five sections. Here are descriptions of the fields that
appear in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Use Record This label is also what the person who gets the action item as a
Locking Carefully result of this task sees as a description of what to do in his Action
Items portal section.
It is important to lock
records when more than one Description
person at a time may be A description of this task goes in this field.
changing the contents of the Lock Record For Other Users
same record; otherwise
If this check box is checked, the record identified by this task is
changing the contents of a
record can produce confu- locked for the assignee(s) identified by this task from the time
sion. that the action item is created until the time that the action item
is completed. If any other user tries to access the record while it
Be careful how you manage
is locked, they will not be able to perform any actions on the
locked records, or the locks
can produce their own sort of record.
confusion. If a record is Note that a user lock does not prevent other workflows from mod-
locked for use by a user who ifying the same record. Also, users with administrator privileges
has gone on vacation, others will still be able to perform actions on the record.
may be inconvenienced
because they cannot modify Action
the record until the person This field contains a drop-down list to select the specific action
on vacation comes back. that will complete action items created by this workflow task.
The usual way to get a record Action items will only be considered complete when the specified
unstuck in this situation is for action is performed on the action item’s record.
a user who is a member of
the administrator group to
perform the action that will
end the user action.
* This aspect of a workflow is specified by its Concurrence property which is described on
page 395.

406 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Figure 7-16. User Action Properties

Records Section
The second section of the form for User Action task properties is
labeled Records. The purpose of the Records section is to identify
the record that will be in the action item. The following explanation
of the Records section may be easier to understand if you take
another look at Figure 7-16.
There are fields at the top of the Records section that are used to
identify a target record. The target record is used to determine the
record that will be used for an action item created by this task.

© Copyright IBM Corporation 2011. Workflow Tasks | 407

 There are radio buttons below these fields. The way that the target
Multiple Actions record is used to determine the record that will be the action item
depends on which one of the radio buttons is selected.
The Action field allows you
to specify a single action Here are descriptions of the fields that appear at the top of the
that will complete an action Records section:
item. Occasionally you have
a situation where you want Take the
to have two or more ways to This is a drop-down list that can have one of three possible val-
complete an action item. ues:
There is an indirect way of • Business Object
creating action items that If Business Object is selected, the record associated with the task
can be completed with more specified by the field to the right of this one will be the tar-
than one action. The way to get record.
do it is make the action
specified in the Action field • Secondary BO
a hidden action. For each This option is available if the workflow is launched in response
action that you want to to an Associate or De-Associate system event. If the value of
complete the action item, this field is Secondary BO, the record at the other end of the
attach a workflow that per- association is the target record.
forms the hidden action.
The mechanism for perform-
This option is also available if the workflow is launched in
ing an action on a record response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
from a workflow is discussed tem event. If the value of this field is Secondary BO, the Event
on page 473. record that triggered the system event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record used by an action item.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of each radio button.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.

408 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Here are the descriptions:
Use it
If this is selected, the target record is used for the action item.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target record will be used for the action item cre-
ated by this task. When you select this radio button, a window
pops up that allows you to choose from the smart sections and
locator fields in the target record.
If the record referenced by the smart section or locator field is a
link, the record used for the action item will be the link, not the
underlying record. Do not do this because link records do not have
a form to display to the person receiving the action.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, a record associated with the target record will
be used for the action item created by this task. When you select
this radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Records section in the
Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.

© Copyright IBM Corporation 2011. Workflow Tasks | 409

 You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
This is similar to the Use its Association radio button.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the target
record’s parent will be the record to use for the action item.
When you select this radio button, a window pops up for you to
select the business object to assume was used to create the par-
ent record. This selection of a business object is not used for fil-
tering.
The selection of a business object represents an assumption about
what kind of record the parent will be. Because of this assump-
tion, subsequent tasks will be able to access the parent record’s
fields. If the actual parent was not created from the assumed
business object, the task may fail if the actual record does not
have an expected field.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this is the equivalent of selecting the mod-
ule’s base business object (the one with the same name as the
module).
At the bottom of the Records section is a read-only field labeled
Object Type. The value displayed in this field is the type of the
record that will be used as an action item. If the record can have
been created from any business object in a particular module, then
the name of the module appears in the Object Type field.

410 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Assign To Section
The third section of the form for user action task properties is labeled
Assign To. The purpose of the Assign To section is to specify three
things:
• The person or people who should receive action items created by
this task. There is a group of radio buttons at the top of the sec-
tion for this purpose.
• How long it should take for the action item to be completed.
There are three fields in the middle of the section for this pur-
pose.
• The start time to use when determining the actual time it has
taken for the action to be completed. There is a group of radio
buttons at the bottom of the section for this purpose.
Reviewing the appearance of the Assign To section in Figure 7-16 on
page 407 may help you to better understand this description.
Both groups of radio buttons in the Assign To section have a but-
ton to the left of them. Initially only the currently selected radio but-
ton is visible in each group. Clicking the button alternately makes
all the radio buttons visible or just the selected radio button visible.
Here are descriptions of the radio buttons at the top of the Assign To
section that specify who should receive action items created by this
task:
User
If User is selected, action items created by this task will be
assigned to a specified person.
When this radio button is selected, a window pops up allowing you
to select a person from among the people who have a user ID to
sign into the IBM TRIRIGA Application Platform.
Group
If Group is selected, then anyone in a specified group will be able
to accept and complete the action item created by this task.
When this radio button is selected, a window pops up allowing you
to select a group.
After someone in the group accepts the action item, the action
item will appear only in that person’s action item queue.

© Copyright IBM Corporation 2011. Workflow Tasks | 411

 Assignee from task ____
If this radio button is selected, then the action item created by
this task will be assigned to the same user as was assigned to a
previous task.
The field to the right of the radio button has a drop-down list that
you use to specify a task. The action item created by this task will
be assigned to the same user or group that was the assignee of
the specified previous task.
The assignee of a workflow’s start task is considered to be the
currently logged in user.
People BO from task ____
If People BO is selected, then the action item created by this task
will be assigned to the user whose My Profile record is associated
with a triPeople record associated with the specified task. The field
to the right of the radio button has a drop-down list that you use
to specify the task.
To the right of the label Expected Time to Complete are three fields
that allow you to specify the expected amount of time that action
items created by this task will take to complete. These three fields
allow you to specify the expected amount of time in days, hours and
minutes.
The group of radio buttons at the bottom of the Assign To section is
used to specify the start time that will be used to compute the actual
amount of time it has taken to complete an action item. There are
two choices:
Estimate Start Date from System Date
If this radio button is selected, the actual time to complete an
action item is computed based on the system time when the
action item was created. Usually you will choose this option.
Estimated Start Date from Field
If this is selected, use the value of a specified Date or Date and
Time field as the start time to compute actual time to complete.
The field to the right of the radio button contains a drop-down list
that allows you to specify the task associated with the record that
contains the start time. When you select the radio button, a win-
dow pops up to allow you to select a field from the specified
record.

412 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Reminder Section
The fourth section of the form for user action task properties is
labeled Reminder. The purpose of the Reminder section is to specify
whether the recipient of an action item should receive a reminder to
complete the action item.
The field Send Reminder to Assignee has a drop-down list with these
items in it:
Never
If this is selected, no reminder will be sent.
Before Estimated Due Date
If this is selected, a reminder will be sent a specified amount of
time before the action item is due.
After Estimated Due Date
If this is selected, a reminder will be sent a specified amount of
time after the action item is due.
Under the Send Reminder to Assignee field is a field labeled
Expected Time to Complete. This is not what it sounds like. It is the
amount of time before or after the action item is due that a reminder
should be sent if the action item is not completed.

Note Section
Arbitrary notes about the task can be put here. They are copied
into the action item record when the user action task is executed.

© Copyright IBM Corporation 2011. Workflow Tasks | 413

 Approval Task
An Approval task is very similar to a User Action task. The difference
is how the action item completes. The actions to complete the action
item are always approve and reject. The Approval task understands
acceptance and rejection, which it translates into success and failure.
For action items created by an Approval task to work properly, the
target of the Approval task must include the approval state transi-
tions. If it does not, records associated with the action items will not
have accept or reject actions. It will be impossible to complete the
action item.

Figure 7-17. Approval Shape

Figure 7-18. Approval State Transitions

The shape for an Approval task is shown in Figure 7-17. The Approval
shape is in the task palette only if the workflow is asynchronous.*
The form for an Approval task is very similar to the form for a User
Action task (described on page 406). It differs from the User Action
task form shown in Figure 7-16 in only these ways:
• The heading says Approval Task Properties instead of User Task
Properties.
• There is no Lock Record for Other Users check box. It is not
needed because Approval tasks always lock the record to be
approved.
• There is no Action field. It is not needed because the actions that
complete an Approval task are always Approve and Reject.
In all other ways, the properties form for an Approval task is the same
as for a User Action task and the same descriptions apply.
You may notice that in the IBM TRIRIGA 10 applications an approval
engine has been implemented that expands the options to the user to
include other actions than Approve and Reject. This approval engine

* This aspect of a workflow is specified by its Concurrence property which is described on

page 395.

414 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

is described in the document IBM TRIRIGA 10 Application Administra-
tion User Guide.

© Copyright IBM Corporation 2011. Workflow Tasks | 415

 Create Record Task
The Create Record task creates new records. The shape for a Create
Record task is shown in Figure 7-19. The form for the properties of a
Figure 7-19. Create Shape Create Record task is shown in Figure 7-20.

Figure 7-20. Create Record Properties (Workflow)

The properties form for a Create Record task is organized into three
sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

416 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Module
The value of this property is the module that contains the busi-
ness object this task will use to create new records. The value of
this property appears to the right of the icon.
You set the value of this property by clicking the icon. Click-
ing the icon causes a list of modules to pop up. Click the mod-
ule name you want to be the value of this property and it will be.
Object
This field contains a drop-down list of the business objects in the
module specified in the Module field. Select the business object
that this task will use to create new records.
Form
The value of this property is the name of the form that will be
used to edit or view records created by this task.
Action
This task creates records in three steps. First, it creates an empty
Null State
record. Next, it sets the value of the record’s fields. Finally, it When a record is first cre-
performs an action on the new record to change its state from null ated it is in a special state
to something else. called null. When a record’s
state is null, it is not stored
The purpose of this field is to select the action this task will per- in the database. Records in
form on new records after it has finished setting the values of the null state disappear
their fields. Select an action from the drop-down list in the Action after the operation cur-
field to specify the action that this task will perform on new rently using the record is
records. Note that you need to make sure the proper values are done. It is important for a
task that creates a record to
set to create a unique name for this record or this task will fail.
do something to take it out
See Determining a Unique Name for Records on page 48. of the null state. Firing an
Formulas action to take the record
Defines the formula recalculation behavior on this task when the out of the null state is the
record is saved. The default is Disable Auto Recalculation. To change way this is done.
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-

© Copyright IBM Corporation 2011. Workflow Tasks | 417

 lated only if any input value of the formula changed during
the task’s activities.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

Initialize From Section

The second section of the form for a Create Record task’s properties
is labeled Initialize From. After a Create Record task has created an
empty record, it sets the values of the new record’s fields to their ini-
tial values. Setting the initial values of the fields happens in two
steps.
First the fields are set to their default values. Then specified values
are copied from a task or a record. The way the values are specified is
described on page 425 under the heading Object Mapping.
The Initialize From section has two radio buttons to specify where
data to copy to a new record will come from. These radio buttons are
labeled:
Workflow Activity
If this radio button is selected, it means that values will be cop-
ied from a preceding workflow task or a record associated with a
preceding workflow task.

418 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Existing Record
If this radio button is selected, it means that values will be cop-
ied from a specified record that exists now, at the time you are
editing this workflow.
The selection of one of these radio buttons determines what appears
in the Initialize From section. Figure 7-20 on page 416 shows what
the Initialize From section looks like when the Workflow Activity
radio button is selected.
When the Workflow Activity radio button is selected, the Initialize
From section has fields to select a workflow task from which values
can be copied. The Initialize From section also has a field and radio
buttons to identify a record that is associated with the specified
workflow task. Values from this record may be copied to a newly cre-
ated record.
Under the Workflow Activity radio button there are fields used to
identify a target record that is used to determine the record from
which values may be copied.
There are radio buttons below these fields. The way that the target
record is used to determine the existing record depends on which one
of the radio buttons is selected.
Here are descriptions of the fields used to determine the target
record:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record. If a specified task has multiple records
associated with it, then there are multiple target records. If
there are multiple target records, there will be multiple exist-
ing records to copy values from. This task will create as many
records as it has existing records to copy values from.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.

© Copyright IBM Corporation 2011. Workflow Tasks | 419

 This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the system event is the target
record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine from which existing record values may be
copied.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are descriptions of the radio buttons:
Use it
If this is selected, the target record will be the existing record
that values may be copied from.
Use its Reference
If this is selected, values may be copied from an existing record
referenced by a smart section or locator field of the target
record. When you select this radio button, a window pops up that
allows you to choose from the smart sections and locator fields in
the target record.
If the record at the other end of the reference used by the smart
section or locator field is a link, then values will be copied from
the link and not its underlying record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.

420 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Use its Association
If this is selected, values may be coped from a record associated
with the target record. When you select this radio button, a win-
dow pops up that allows you to specify the type of association to
use. It allows you to identify the association by the type of record
that must be on the other end of the association and optionally
the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Initialize from section in
the Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.

© Copyright IBM Corporation 2011. Workflow Tasks | 421

 Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, the values may
be copied from the target record’s parent.
When you select this radio button, a window pops up for you to
select the business object that is assumed to have been used to
create the parent record. This selection of a business object is not
used for filtering. It is used to allow this task to access the par-
ent’s fields.
The selection of a business object represents an assumption about
what kind of record the parent will be. Because of this assump-
tion, subsequent tasks will be able to access the parent record’s
fields. If the actual parent was not created from the assumed
business object, the task may fail if the actual record does not
have an expected field.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the Initialize from section is a read-only field
labeled Object Type. The value displayed in this field is the type of
the record that values may be copied from. If the record can have
been created from any business object in a particular module, the
name of the module appears in the Object Type field.
It is possible for there to be multiple records to copy values from.
This happens if there are multiple target records or if a target record
is associated with multiple records or references multiple records that
fit the specification. This task will create one new record for each
record it has to copy values from.
If you want to initialize records with information that is determined
by the application’s configuration, select the option of using an exist-
ing record in the Intialize from section. When Existing Record is
selected, the Intialize from section looks like the one in Figure 7-21.
Specify the value for the Module and Object properties so that this
task knows what kind of record you want to copy values from. Then
click the Record link to find the specific record you want this task to
use.

422 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Figure 7-21. Create Record Properties (Existing)

Transaction Section
The third section of the Create Record task properties form is labeled
Transaction. The purpose of the Transaction section is to specify the
scope of the transaction being processed. The Transaction setting only
applies to the creation of the object record prior to post-create and
record transition processes. The Transaction setting is not applied to
post-create and record transition of the newly created records, which
means that pre-create and transition workflows called within a Cre-
ate Record task will not be wrapped in the currently controlling trans-
action. The choices for Transaction are as follows:
• None
Indicates that the record is committed right after it is created. No
transactions are created; the processing of the task follows stan-
dard workflow rules.
• Per X Source Records
A new context is created for each X number of source records to
be created from and committed when that number of source
records is reached. The default value is 1, which means the
records are committed after each creation.
When a Create Record task is within a DataConnect task, the outer-
most DataConnect task is in control of the transaction for that Create
Record task, regardless of setting in the Transaction section of the
nested Create Record task. The Create Record task only can apply its

© Copyright IBM Corporation 2011. Workflow Tasks | 423

 Transaction setting if the controlling DataConnect task’s Transaction
setting is None.

At this point we have a newly created record to initialize with data

and an existing record to copy data from. The next step is to specify
what data is to be copied. This is done by clicking the Edit Map action
on the Initialize From section bar. Clicking the Edit Map action
causes the Object Mapping window to pop up so you can specify what
values should be copied to the newly created record. The Object
Mapping window is described in the next part of this chapter.
If you want to reset the object mapping to its defaults without pop-
ping up the object mapping window, click the Reset Map action.

424 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Object Mapping
The Object Mapping window is accessed from the properties of a Cre-
ate Record task to specify how values will be copied to new records to
initialize them. It is also accessed from the properties of a Modify
Records task to specify how values will be copied to existing records
to modify them.
An example of an Object Mapping Window is shown in Figure 7-22.
For the sake of brevity, in this explanation of the Object Mapping
Window, we will refer to the record that values will be copied from as
the source record.
The first section of an Object Mapping window is labeled with the
name of the business object that is expected to have been used to
create the record being modified or created. In this particular case,
the type of record being created is a BSI Observed Condition.
In the middle of the first section’s top bar is the name of the busi-
ness object used to create the source record.
In the first section is a drop-down field labeled Association Type. If
an association is selected in this field, the selected type of associa-
tion will be created between the record being initialized or modified
and the source record. The drop-down list of Association Types is
defined by the object-level associations defined for the Object record
being created in the Association Manager or Data Modeler.
If the Object Mapping Window is being used to specify how to initial-
ize new records, two check boxes appear under Association Type.
These check boxes are not in the Object Mapping Window when it is
used to specify how to modify an existing record.
The Association Type setting in the Object Mapping window is used to
create a record-level association from the record being created to the
record listed in the Initialize From section of the Create Record task.
Use Source Project
If this is checked, records created by this task will be part of the
same project as the source record.
If this is not checked, records created by this task will be part of
whatever project is the current project. For a top-level record, its
project will be that of the user’s project context. For a new child
record, its project will be that of its parent record. For an exist-
ing record that is made to be the child of another record, its
project will be that of its parent record.

© Copyright IBM Corporation 2011. Workflow Tasks | 425

 Figure 7-22. Object Mapping

426 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Include Child Records
If the source record is part of a hierarchy module, copies of all of
the source record’s children will be made. The copies will be chil-
dren of the newly created record.
The copying of child records include all children in the hierarchy,
the values of their fields, any embedded records, and any associa-
tions. Note that even though the associations are copied, the
associated records are not copied. Constants
The following sections of the Object Mapping Window are labeled with for Time &
the names of smart sections in the record to be initialized or modi- Duration
fied. In each of these sections is a list of the fields in the named There is a special constant
smart section. you can specify that means
The Object Mapping Window always has a section labeled General. to copy the current time
into a field. If you map a
The section labeled General is different from the other sections
field to the constant
because it contains a list of fields that are not in any smart section. $$CURRENTTIME$$, the map-
To the right of each field name and section name is text that ping operation will copy the
describes what the mapping operation will do to the field. current time and date to the
field. If mapping $$CURRENT-
The simplest case is that there is no text to the right of the field TIME$$ to a text field, it
name. This means that the mapping operation will do nothing to the maps a formatted date time
field. value. If mapping to a num-
ber field, it maps a millisec-
The area to the right of the field name may contain text like ond value
General::PeopleFillName
To set a duration to a con-
that is the name of a section and field in the source record. If such a stant value, express the
string appears to the right of the field name, the new value for the duration as a number of mil-
field will be copied from the specified field. You do not type in this liseconds. A duration of one
hour is 3600000 millisec-
sort of text yourself. Instead, the text gets put there as a result of a
onds. A duration of one
selection you make elsewhere. week is 604800000 millisec-
If the text is in a text field, it means that the text is constant text onds. A duration of one day
that will be used as-is. This means that the mapping operation will is 86400000 milliseconds.
Because a duration of one
always set the field to that value. To enter constant text into a text
day is relatively common,
box, check the check box to the right. When the check box is there is a special way to
checked, a box appears and you will be able to type text into it. represent a duration of one
Workflow constant mapping for a locator field is case sensitive. day that is easier to remem-
ber and easier to read.
Text mapping should not be used to populate locator fields. Instead, Instead of entering
use a mechanism to identify the record to be mapped into a locator 86400000, you can enter
via the task’s Map From or Initialize From section and use the Source $$DAY$$.
mapping option. It may require an extra Retrieve Records task or

© Copyright IBM Corporation 2011. Workflow Tasks | 427

 Query task to get a handle on the record, but doing so ensures that
the current record is being mapped into the locator.
A circumstance where text mapping can be used safely is when the
value being mapped is either the full publish name for non-hierarchi-
cal objects, or the full hierarchy path for hierarchical objects. Only
do so if the locator field has those respective fields set in the locator
field’s business object.
If you click the search icon to the right of the check box, a small
window pops up. This window contains radio buttons for the fields and
sections of the source record. An example of this window is shown in
Figure 7-23.

Figure 7-23. Attribute Picker

428 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

This small pop-up window is called an Attribute Picker. If you want
the mapping operation to copy data from a field in the source record,
click the for the field you want the data copied to and select the
radio button for the source field. The procedure is similar if you want
to copy from a smart section in the source. Copy Versus
There are two radio buttons in an attribute picker window that do not Reference
correspond to a field or a section. These radio buttons are labeled If you use the Source radio
None and Source. button to put a record in a
smart section, what actually
If you select the radio button labeled None, it means that the map-
happens depends on the kind
ping operation will not do anything to the affected field. The text to of record that is the source
the right of the field’s name will be blank. for the task.
If you selected the radio button labeled Source, it means that you If the source is a stand alone
want to use the entire source record. This is useful, for example, if record, then a reference is
you want to point a smart section or locator field at a particular created from the smart sec-
record. When populating a locator field or smart section via the work- tion to the source record.
flow Object Mapping window, always choose the Source option from If the source is an embedded
the Attribute Picker . This ensures that a valid reference gets cre- or link record, then a copy is
ated to the record being placed in the locator field or smart section. made of the source record
and a reference is created
There is another source of data for a mapping operation to copy. from the smart section to the
Some tasks perform computations. The results of these computations copy.
are associated with the task that performed them rather than with a
record. Tasks that perform computations are discussed later in this
chapter.
If you want a mapping operation to copy the results of one of these
computations to a field, click the binoculars icon ( ), the second icon
to the right of the field. It will cause a window to pop up like the one
in Figure 7-24.
For each of the tasks that precede the current task, you can pick a
count, sum, or list of records that the task computed. This is only use-
ful if the task actually does compute the selected value.
Sometimes you want a mapping operation to use a formula to com-
pute a value. You can use an extended formula as the source of data
for a field. Extended formulas are described in the book Application
Building for the IBM TRIRIGA Application Platform 3: Calculations.

© Copyright IBM Corporation 2011. Workflow Tasks | 429

 Figure 7-24. Task Data Picker

To specify an extended formula as the source of data for a field, click

the icon. Clicking the icon causes an Extended Formula window
to pop up that looks like Figure 7-25.

Figure 7-25. Extended Formula Window for Object Mapping

This Extended Formula window differs in three ways from the one dis-
cussed in the book Application Building for the IBM TRIRIGA Applica-
tion Platform 3: Calculations. First, extended formulas are available
for fields of any data type in the Workflow Builder, they are not lim-
ited to numbers and dates. Second, the extended formula does not
have an Outputs section. An extended formula used in object map-
ping always has exactly one output, which is the field it is being used
to provide data for. Third, extended formulas can access fields in the
source record of the object map only, fields from associated objects
cannot be accessed. With these exceptions, specifying an extended

430 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

formula for use in an object mapping operation is exactly the same as
using an extended formula anywhere else.
The Object Mapping Window also allows you to map associations from
the source object to the target object. In the Association Mapping
portion of the object map a list of all of the associations defined for
the target business object are displayed. If you click the search icon
to the right of one of these associations, a small window pops up.
This window contains radio buttons for the association definitions of
the source record. An example of this window is shown in Figure 7-24.

Figure 7-26. Association Picker

This small pop-up window is called an association picker. You will

notice that the association definition of the target is used to filter
which associations you see from the source to those of the same Busi-
ness Object. If you want the mapping operation to copy associations
from the source record, click the search icon for the association
definition you want copied to and select the radio button for the
source association definition.
At runtime if an association is found from the source to the selected
business object with the selected string, a new association will be
made from the target using the definition selected. If the target asso-
ciation is flagged as dependent, a copy of the record associated to the
source will be made and associated to the target.
To clear the mapping for a field, section or association click the erase
icon.

© Copyright IBM Corporation 2011. Workflow Tasks | 431

 Modify Records Task
The Modify Records task modifies values in existing records. The
shape for a Modify Records task is shown in Figure 7-27. The form for
a Modify Records task is shown in Figure 7-28 on page 432.
Figure 7-27. Modify Shape

Figure 7-28. Modify Records Properties (Workflow)

The properties form for a Modify Records task is organized into four
sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

432 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities. This is the default value.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option provides
performance optimization.
An example of the use of Disable Auto Recalculation is within a
DataConnect task that is importing a large number of space
records. You may wish to delay any floor/space rollup recalcu-
lations until after all the space records have been imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

Map To Records Section

The second section of the properties form for a modify records task is
labeled Map To Records. The purpose of this section is to identify the
record(s) that the task will modify.

© Copyright IBM Corporation 2011. Workflow Tasks | 433

 At the top of the Map To Records section are fields used to identify a
target record. The target record is used to determine the record that
will be modified.
There are radio buttons below these fields. The way that the target
record is used to determine the record that will be modified depends
on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, the record associated with the task
specified by the field to the right of this one will be the tar-
get record. If multiple records are associated with the task,
there will be multiple target records.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, the record at the other end of the
association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the system event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right will be the tar-
get record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record that will be modified.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.

434 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record that is
modified.
Use its Reference
If this is selected, records referenced by a smart section or loca-
tor field of the target record will be modified. When you select
this radio button, a window pops up that allows you to choose
from the smart sections and locator fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
be modified. When you select this radio button, a window pops up
that allows you to specify the type of association to use. It allows
you to identify the association by the type of record that must be
on the other end of the association and optionally the name of the
association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Map To Records section in
the Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.

© Copyright IBM Corporation 2011. Workflow Tasks | 435

 You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on
the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, the
record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, the target
record’s parent will be modified.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow this task to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this is the equivalent of selecting the mod-
ule’s base business object (the one with the same name as the
module).
Under the radio buttons is a check box labeled Only if association is
. This can be useful if there may be more than one record to be
modified. Checking this check box enables filtering of records to be
modified. The filtering is based on associations that these records
may have with the other records. If the check box is checked and
there is a name to the right of the icon, only records having an
association with the specified name will be modified. If the check box
is checked and there is nothing to the right of the icon, only
records that have an association of any sort will be modified. For the
purpose of this check box, it does not matter what kind of record is at
the other end of the association.
To specify what appears to the right of the icon, click the icon.
A list of association names pops up. Click the association name that
you want to appear to the right of the icon. If you want nothing to

436 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

appear after the icon, click -Any- which appears at the top of the
list.
At the bottom of the Map To Records section is a read-only field
labeled Object Type. The value displayed in this field is the type of
the record that will be modified. If the record can have been created
from any business object in a particular module, the name of the
module appears in the Object Type field.

Map From Records Section

The third section of the properties form for a modify records task is
labeled Map From Records. The purpose of this section is to identify
the record that values will be copied from (source).
The Map From Records section has two radio buttons to specify
where data to copy to the record being modified will come from.
These radio buttons are labeled:
Workflow Activity
Copy values from a preceding workflow task or a record associ-
ated with a preceding workflow task.
Existing Record
Copy values from a specified record that exists now.
The selection of one of these radio buttons determines what appears
in the Map From Records section. Figure 7-28 on page 432 shows
what the Map From Records section looks like when the Workflow
Activity radio button is selected.
When the Workflow Activity radio button is selected, the Map From
Records section has all the fields that are in the Map To Records sec-
tion, except for the Only if association is check box. The differ-
ence between the fields in these sections is that the fields in the Map
To Records section are used to select records to modify and the fields
in the Map From Records section are used to select records from
which to copy values.
If you want to modify records with information that is determined by
the application’s configuration, you should select the option of using
an existing record in the Map From Records section. When Existing
Record is selected, the Map From Records section looks like the one
in Figure 7-29.
You specify the value for the Module and Object properties so that
this task knows what kind of record you want to copy values from.

© Copyright IBM Corporation 2011. Workflow Tasks | 437

 Figure 7-29. Modify Records (Existing)

Then click the Record link to find the specific record you want this
task to use.

Transaction Section
The fourth section of the Modify Records task properties form is
labeled Transaction. The purpose of the Transaction section is to
specify the scope of the transaction being processed. The choices for
Transaction are as follows:
• None
Indicates that the record is committed right after it is modified.
No transactions are created; the processing of the task follows
standard workflow rules.
• Per X Source Records
A new context is created for each X number of records to be modi-
fied and committed when that number of records is reached. The
default value is 1, which means the records are committed after
each modification.
When a Modify Records task is within a DataConnect task, the outer-
most DataConnect task is in control of the transaction for that Modify
Records task, regardless of setting in the Transaction section of the

438 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

nested Modify Records task. The Modify Records task only can apply
its Transaction setting if the controlling DataConnect task’s Transac-
tion setting is None.

At this point, you are ready to specify how the records specified in
the Map To Records section will be modified by data copied from
records specified in the Map From Records section. You specify this
by using the Object Mapping window.
Access the Object Mapping window by clicking the Edit Map action on
the Map To Records section bar. The Object Mapping window is
described on page 425.
If you want to reset the object mapping to its defaults without pop-
ping up the object mapping window, click the Reset Map action.

© Copyright IBM Corporation 2011. Workflow Tasks | 439

 Retrieve Records Task
A Retrieve Records task retrieves a list of records, filters out
unwanted records, and performs a computation on the filtered
records. The result of the computation can be used by another task.
Figure 7-30. Retrieve Shape The shape for a Retrieve Records task is shown in Figure 7-30. The
form for a Retrieve Records task is shown in Figure 7-31.

Retrieve
vs. Query
The Retrieve Records and
the Query workflow tasks
are similar in that the essen-
tial purpose of both work-
flow tasks is to find records.
They differ in the way that
they find records.

The Retrieve Records task

finds record through their
association with a record
already associated with a
workflow task.

A Query workflow task does

not use associations. Instead
it runs a query and uses the
records returned by the
query.

Figure 7-31. Retrieve Properties

The properties form for a Retrieve Records task is organized into five
sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.

440 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Description
A description of this task goes in this field.

Retrieve
The second section of the properties form for a Retrieve Records task
is labeled Retrieve. The purpose of this section is to specify the com-
putation that is to be performed on the records that are retrieved.
The computation is determined by which one of the radio buttons in
this section is selected.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button they appear next to.
Here are the descriptions:
A List
If this option is selected, the task will take the retrieved and fil-
tered records and make them the result list that is associated
with this task.
____ Record(s) with the Greatest value In CHOOSE FIELD
If this option is selected, this task will take the specified number
of retrieved and filtered records that contain the greatest values
in the specified field and make them the result list associated
with this task. Note there is no unit of measure considerations, it
is a straight comparison.
Records with a null value will be returned last. You can add a
static filter in the Filter Using section if you want to eliminate
null returns. Information about the Filter Using section starts on
page 446.
When you click this radio button, a window pops up for you to
specify which field this task should use. After you have specified
which field to use, the name of the field appears as the text of
the hyperlink in place of the previous text. Clicking the hyperlink
will pop up the window again to you can change the specified
field.

© Copyright IBM Corporation 2011. Workflow Tasks | 441

 The result list can be used by subsequent tasks to initialize or
modify records. This is described on page 429.
____ Record(s) with the Least value In CHOOSE FIELD
If this option is selected, this task will take the specified number
of retrieved and filtered records that contain the least values in
the specified field and make them the result list associated with
this task. Note there is no unit of measure considerations when
taking this sum, it is a straight comparison.
field.
Records with a null value will be returned first. You can add a
static filter in the Filter Using section if you want to eliminate
null returns. Information about the Filter Using section starts on
page 446.
When you click this radio button, a window pops up for you to
specify which field this task should use. After you have specified
which field to use, the name of the field appears as the text of
the hyperlink in place of the previous text. Clicking the hyperlink
will pop up the window again to you can change the specified
field.
The result list can be used by subsequent tasks to initialize or
modify records. This is described on page 429.
The Sum of CHOOSE FIELD
If this option is selected, this task will take the retrieved and fil-
tered records, add the numbers in the specified field and make
the sum the result sum that is associated with this task. Note
there is no unit of measure considerations when taking this sum,
it is a straight addition.
When you click this radio button, a window pops up for you to
specify which field this task should use. After you have specified
which field to use, the name of the field appears as the text of
the hyperlink in place of the previous text. Clicking the hyperlink
will pop up the window again to you can change the specified
field.
The result sum can be used by subsequent tasks to initialize or
modify records. This is described on page 429.
Financial Data from Token CHOOSE TOKEN
If this option is selected, this task will filter the retrieved finan-
cial records so that only those that have a Financial Rollup field
that uses the specified financial token will be included in the
result list associated with this task.

442 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 When you click this radio button, a window pops up for you to
specify which token this task should use. After you have specified
which token to use, the name of the token appears as the text of
the hyperlink in place of the previous text. Clicking the hyperlink
will pop up the window again to you can change the specified
token.
The result list can be used by subsequent tasks to initialize or
modify records. This is described on page 429.
The description of Financial Rollup fields and financial tokens is in
the “Financial Transactions and Rollups” chapter of the book
Application Building for the IBM TRIRIGA Application Platform 3:
Calculations.
All Descendants
If the retrieved records are created from a business object that is
part of a hierarchy module and this option is selected, then this
task takes the descendants of the retrieved and filtered records
and makes them the result list associated with this task.
If the Including Self check box to the right of this radio button is
checked, then the result list will include the retrieved and fil-
tered records along with their descendants.
The result list can be used by subsequent tasks to initialize or
modify records. This is described on page 429.
All Ancestors
If the retrieved records are created from a business object that is
part of a hierarchy module and this option is selected, then this
task takes the retrieved and filtered records along with their
ancestors and makes them the result list associated with this task.
If the Including Self check box to the right of this radio button is
checked, then the result list will include the retrieved and fil-
tered records along with their ancestors.
The result list can be used by subsequent tasks to initialize or
modify records. This is described on page 429.

From Records
The purpose of the From Records section is to specify the records
that this task will retrieve.
At the top of the From Records section are fields used to identify tar-
get records. The target records are used to determine the records
that will be retrieved.

© Copyright IBM Corporation 2011. Workflow Tasks | 443

 There are radio buttons below the fields. The way that the target
records are used to determine the records that will be retrieved
depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then records associated with the
task specified by the field to the right of this one will be the
target records.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the records at the other end of
the association are the target records.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the event is the target record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
records will be associated with.
The radio buttons under these fields determine how the target
records will be used to determine the records that will be retrieved.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:

444 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Use it
If this is selected, the target records will be the records that are
retrieved.
Use its Reference
If this is selected, records referenced by a smart section or loca-
tor field of the target record will be retrieved. When you select
this radio button, a window pops up that allows you to choose
from the smart sections and locator fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
be retrieved. When you select this radio button, a window pops
up that allows you to specify the type of association to use. It
allows you to identify the association by the type of record that
must be on the other end of the association and optionally the
name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Map To Records section in
the Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-

© Copyright IBM Corporation 2011. Workflow Tasks | 445

 ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target records are created from a business object that is
part of a hierarchy module and this option is selected, the target
records’ parent will be retrieved.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow this task to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the Map To Records section is a read-only field
labeled Object Type. The value displayed in this field is the type of
records that will be retrieved. If the records can have been created
from any business object in a particular module, then the name of the
module appears in the Object Type field.

Filter Using
The purpose of the Filter Using section is to specify filter conditions
that will be used to filter the retrieved records. A filter condition is
something about a retrieved record that can be either true or false.
This task’s computation will only use retrieved records for which all
the filter conditions are true. If any filter conditions are false for a
retrieved record, the retrieved record is discarded and not used.
To add a filter condition to the Filter Using section, click the Add
Filter action on the Filter Using section bar. Once you have added fil-
ter conditions to the Filter Using section, you will see a check box for
each filter condition. To remove a filter condition from the Filter

446 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Using section, check the filter condition’s check box and click the
Delete Filter action on the section bar.
When you click the Add Filter action on the Filter Using section bar,
a Task Filter window pops up so you can specify the details of a filter
condition. When you click the link in the filter condition’s Left Side
Data field a Filter Window pops up to allow you to modify the details
of an existing filter condition.
A Task Filter window looks like Figure 7-32 if the List check box in the
Left Side Data section is not checked.

Figure 7-32. Task Filter Window (List not Checked)

A Task Filter window has two sections. The purpose of the Left Side
Data section is to specify how retrieved records will be used in the fil-
ter condition. The purpose of the Right Side Data section is to spec-
ify what the retrieved records will be compared to.
When the List check box in the Left Side Data section is not checked,
it means that the value of a field in each retrieved record will be
compared to one other value. The field in the retrieved records to use
for the comparison is specified by the Section Name and Field Name
fields.

© Copyright IBM Corporation 2011. Workflow Tasks | 447

 The comparison to use is specified by the value of the Operator field.
The Operator field is a drop-down list that allows you to choose from
the following:

• Equals • Start With - Case Sensitive

• Not Equals • End With
• Less Than • End With - Case Sensitive
• Less Than or Equals • Before
• More Than • After
• More Than or Equals • In
• Contains • Not In
• Contains - Case Sensitive • Does Not Contain
• Start With • Does Not Contain - Case Sensitive
At the end of this section, we will explain what each of these compar-
isons are for.
The value to compare the Left Side Data to is specified by the Right
Side Data section. The three radio buttons at the top of the Right
Side Data section determine which of three places the value will
come from. Fields underneath the three radio buttons provide addi-
tional details about the value.
If the Source radio button is selected, the other value will come from
a record specified by the Filter Record section of the Retrieve
Records task properties. It will use the field in the record specified by
the Section Name and Field Name fields of the Right Side Data sec-
tion. If the Target radio button is selected, then the other value for
the comparison will come from the field of the retrieved record speci-
fied by the Section Name and Field Name fields of the Right Side
Data section.
If the source or target is a list of records, one of the records in the list
will be chosen to do the comparison. Instead, ensure the source or
target for filtering is a single record when the List property is not
checked.
If the Constant radio button is selected, then the Section Name and
Field Name fields of the Right Side Data section are not visible.
Instead, there is another field labeled Value where you can type the
actual other value to be used for the comparison. If you are checking
to see if the field is empty, compare it to a constant value of Null.
If the List check box in the Left Side Data section is checked, the
Task Filter window looks like Figure 7-33 on page 449.

448 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 Figure 7-33. Task Filter Window (List Checked)

When the List check box in the Left Side Data section is checked it
means that the set of retrieved records will be compared to the set of
records specified by the Filter Using section of the Retrieve Records
task’s properties form. Since you are comparing lists of records, both
the From Records and the Filter records should be created from the
same module.
The comparison to use is specified by the value of the Operator field.
The Operator field is a drop-down list that allows you to choose from
the following values: In or Not In.
Check the List check box in the Right Side Data section.
We conclude this description of the Task Filter window by describing
what the comparison operators are for:
Equals, Not Equals
These are useful for comparing individual values. If both values
are the same, then Equals is true. If the values are different then
Not Equals is true.
To test for the existence of a date value, use Equals or Not Equals for
the operator and Null for the value; do not use More Than or Less Than
zero to test for the existence of a date value.
Less Than, Less Than or Equals, More Than, More Than or Equals
These are used to compare individual number values. Less Than is
true if the value specified by the Left Side Data section is less
than the value specified by the Right Side Data section. The rest
of these comparisons work in a similar way.
To test for the existence of a date value, use Equals or Not Equals for
the operator and Null for the value; do not use More Than or Less Than
zero to test for the existence of a date value.

© Copyright IBM Corporation 2011. Workflow Tasks | 449

 Contains, Start With, End With, Does Not Contain
These are used to compare individual text values. Contains is true if
the text value specified by the Left Side Data section contains the
text value specified by the Right Side Data section. For example,
abcdefg contains bcd; abcdefg does not contain bug.
Start Withis true if the text value specified by the Left Side Data
section starts with the text value specified by the Right Side Data
section. For example abcdefg starts with abcd; abcdefg does not start
with xyz.
End With is true if the text value specified by the Left Side Data
section ends with the text value specified by the Right Side Data
section. For example abcdefg ends with fg; abcdefg does not end with
abc.
Does Not Contain is true if the text value specified by the Left Side
Data section does not contain the text value specified by the
Right Side Data section. For example, abcdefg contains bcd; abcdefg
does not contain bug.
Contains, Start With, End With, and Does Not Contain are not case sensi-
tive. Contains - Case Sensitive, Start With - Case Sensitive, End With - Case Sensi-
tive, and Does Not Contain - Case Sensitive are case sensitive.
Before, After
These are used to compare individual date, time and date and
time values. Before is true if the value specified by the Left Side
Data section is before the value specified by the Right Side Data
section. After is true if the value specified by the Left Side Data
section is after the value specified by the Right Side Data section.
In, Not In
These are used to compare sets of records. These are the only
comparisons that should be used if the List check box is checked.
If the List check box is not checked then one of the other compar-
ison operations should be used.
In is true for retrieved records that are in the set of records speci-
fied by the Filter Records section of the Retrieve Records task’s
properties form. Not In is true for retrieved records that are not in
the set of records specified by the Filter Records section.
After you click OK on the Task Filter, the platform displays the task
filter in the Filter Using section.
To remove a task filter from the list in the Filter Using section, select
the check box next to a filter and click Delete Filter.

450 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Filter Records
The purpose of the Filter Records section is to identify the records
that this task will use to filter retrieved records.
The Filter Records section has two radio buttons to specify where
records for filtering will come from. These radio buttons are labeled:
Workflow Activity
If this radio button is selected then the records for filtering will
be associated with a previously performed workflow task.
Existing Record
If this radio button is selected, then the record used for filtering
will be a specified record that exists now.
The selection of one of these radio buttons determines what appears
in the Filter Records section. Figure 7-31 on page 440 shows what the
Filter Records section looks like when the Workflow Activity radio
button is selected.
When the Workflow Activity radio button is selected, the Filter
Records section has all the fields that are in the From Records sec-
tion. The difference between the fields in these sections is that the
fields in the Filter Records section are used to select the records to
use for filter conditions that have their Source radio button selected.
If you want to filter records with information that is determined by
the application’s configuration, then you should select the option of
using an existing record in the Filter Records section. When the
Existing Record radio button is selected, the Filter Records section
looks like Figure 7-34.

Figure 7-34. Retrieve Record Filter Records Section (Existing Filter)

You specify the value for the Module and Object properties so that
this task knows what kind of record you want to copy values from.
Then click the Record link to find the specific record you want this
task to use.

© Copyright IBM Corporation 2011. Workflow Tasks | 451

 Query Task
A Query task retrieves the list of records found by a query. The result
list can be used by another task. The shape for a Query task is shown
in Figure 7-35. The form for a Query task is shown in Figure 7-36.
Figure 7-35. Query Shape

Query vs.
Retrieve
The Query and the Retrieve
Records workflow tasks are
similar in that the essential
purpose of both workflow
tasks is to find records. They
differ in the way that they
find records.
A Query workflow task runs a
query and uses the records
returned by the query.
The Retrieve Records task
does not use queries. Instead
it finds records through their
association with a record
already associated with a
workflow task.

Figure 7-36. Query Properties

When a query is set to Active Project and executed from the Report
Manager, the results are based on the scope of the project the user is
in if the record is in a capital project or on the scope of the project
the parent record is in if the record is not in a capital project. If the
same query is executed in a workflow, the results are based on all
projects including the Company Level. To resolve this discrepancy,
use a Set Project task at the start of the workflow. This ensures the
workflow returns the same results as the query returns when run from
the Report Manager.

452 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The properties form for a Query task is organized into four sections.
Here are descriptions of the fields in the first section:
Label
This is the caption used to identify this task. The text in this field
will be used as the caption for the shape in the drawing that rep-
resents this workflow task. Use the standards in “Workflow Nam-
ing Standards” on page 388.
Description
A description of this task goes in this field.
Query
Clicking the Query link causes a window to pop up that allows you
to select the query that this task will run. The name of the
selected query appears in a read-only field to the right of the
Query link.
The window that pops up to select the query looks like
Figure 7-37. Select the module of the query you want from the
drop-down list to the right of the Module label.

Figure 7-37. Select Item(s) Panel Showing Queries

If what you are looking for is not a query, but some other kind of
report, you will not see what you are looking for because the list

© Copyright IBM Corporation 2011. Workflow Tasks | 453

 initially includes only queries. You will need to select the type of
report you want to see it.
To select the type of report you want to see, click the icon to
the right of the Reports List label. A menu will pop up that looks
like Figure 7-38. From this menu, you can choose the type of
report you want to see a list of or you can choose the All menu
item to see a list that contains every kind of report.

Figure 7-38. Report Type Menu

Some queries have filter values that can be specified interactively

($$RUNTIME$$ filters). A Query task does not have any way to provide a
value for interactive filters. However, a Query task has other filtering
mechanisms that it can use. The purpose of the other sections of a
Query task’s properties are to control the filtering of query results.

Context Records
A query can have association filters or field filters specified to filter
out records in context of a particular record. This context is based on
the relationship to the record and is specified to filter records that
are not associated in a specified way or do not have the required val-
ues in particular fields. These are often used in query sections or
actions that the user interacts with based on the record the user is
currently viewing. In a workflow, the way to specify the records that
are used for this type of filter is called context records. Association
filters and field filters are discussed in the IBM TRIRIGA Application
Platform 3 Reporting User Guide.

454 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

At the top of the Context Records section are fields used to identify
target records. The target records are used to determine the records
that will be used as context records.
There are radio buttons below the fields. The way that the target
records are used to determine the records that will be used as con-
text records depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, records associated with the task
specified by the field to the right of this one will be the tar-
get records.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, the records at the other end of the
association are the target records.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
records will be associated with.
The radio buttons under these fields determine how the target
records will be used to determine the records that will be the con-
text records.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.

© Copyright IBM Corporation 2011. Workflow Tasks | 455

 The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target records will be the context records.
Use its Reference
If this is selected, records referenced by a smart section or loca-
tor field of the target record will be the context records. When
you select this radio button, a window pops up that allows you to
choose from the smart sections and locator fields in the target
record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
be the context records. When you select this radio button, a win-
dow pops up that allows you to specify the type of association to
use. It allows you to identify the association by the type of record
that must be on the other end of the association and optionally
the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Map To Records section in
the Context Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.

456 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target records are created from a business object that is
part of a hierarchy module and this option is selected, then the
target records’ parent will be the context record.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow this task to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
The Query task does not actually care about the fields of the con-
text record. The selection of a business object is just for consis-
tency with the way this mechanism works for other kinds of
workflow tasks.
At the bottom of the Map To Records section is a read-only field
labeled Context Object Type. The value displayed in this field is the
type of records that will be the context record. If the records can
have been created from any business object in a particular module,
then the name of the module appears in the Context Object Type
field.

© Copyright IBM Corporation 2011. Workflow Tasks | 457

 Filter Using
The purpose of the Filter Using section is to specify filter conditions
that will be used to filter the query results. A filter condition is some-
thing about a record in the query results that can be either true or
false. This task will only use records in the query results for which all
the filter conditions are true. If any filter conditions are false for a
query result record, the record is discarded and not used.
To add a filter condition to the Filter Using section, click the Add
Filter action on the Filter Using section bar. Once you have added fil-
ter conditions to the Filter Using section, you will see a check box for
each filter condition. To remove a filter condition from the Filter
Using section, check the filter condition’s check box and click the
Delete Filter action on the section bar.
When you click the Add Filter action on the Filter Using section bar,
a Task Filter window pops up so you can specify the details of a filter
condition. When you click the link in the filter condition’s Left Side
Data field, a Filter Window pops up to allow you to modify the details
of an existing filter condition.
A Task Filter window looks like Figure 7-32 if the List check box in the
Left Side Data section is not checked.

Figure 7-39. Task Filter Window (List Not Checked)

A Task Filter window has two sections. The purpose of the Left Side
Data section is to specify how query result records will be used in the
filter condition. The purpose of the Right Side Data section is to spec-
ify what the query result records will be compared to.

458 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

When the List check box in the Left Side Data section is not checked,
it means that the value of a field in each query result record will be
compared to one other value. The field in the query result records to
use for the comparison is specified by the Section Name and Field
Name fields.
The comparison to use is specified by the value of the Operator field.
The Operator field is a drop-down list that allows you to choose from
the following:

• Equals • Start With - Case Sensitive

• Not Equals • End With
• Less Than • End With - Case Sensitive
• Less Than or Equals • Before
• More Than • After
• More Than or Equals • In
• Contains • Not In
• Contains - Case Sensitive • Does Not Contain
• Start With • Does Not Contain - Case Sensitive
At the end of this section, we will explain what each of these compar-
isons are for.
The value to compare the Left Side Data to is specified by the Right
Side Data section. The three radio buttons at the top of the Right
Side Data section determine which of three places the value will
come from. Fields underneath the three radio buttons provide addi-
tional details about the value.
If the Source radio button is selected, then the other value will come
from a record specified by the Filter Records section of the Query
task properties. It will use the field in the record specified by the
Section Name and Field Name fields of the Right Side Data section.
If the Target radio button is selected, then the other value for the
comparison will come from the field of the query result record speci-
fied by the Section Name and Field Name fields of the Right Side
Data section.
If the source or target is a list of records, one of the records in the list
will be chosen to do the comparison. Instead, ensure the source or
target for filtering is a single record when the List property is not
checked.

© Copyright IBM Corporation 2011. Workflow Tasks | 459

 If the Constant radio button is selected, then the Section Name and
Field Name fields of the Right Side Data section are not visible.
Instead, there is another field labeled Value where you can type the
actual other value to be used for the comparison. If you are checking
to see if the field is empty, compare it to a constant value of Null.
If the List check box in the Left Side Data section is checked, the
Task Filter window looks like Figure 7-33 on page 449.

Figure 7-40. Task Filter Window (List Checked)

When the List check box in the Left Side Data section is checked it
means that the set of query result records will be compared to the set
of records specified by the Filter Using section of the Query task’s
properties form. Since you are comparing lists of records, both the
From Records and the Filter records should be created from the same
module.
The comparison to use is specified by the value of the Operator field.
The Operator field is a drop-down list that allows you to choose from
the following values: In, Not In, or Associated To.
Check the List check box in the Right Side Data section.
We conclude this description of the Task Filter window by describing
what the comparison operators are for:
Equals, Not Equals
These are useful for comparing individual values. If both values
are the same, then Equals is true. If the values are different then
Not Equals is true.
To test for the existence of a date value, use Equals or Not Equals for
the operator and Null for the value; do not use More Than or Less Than
zero to test for the existence of a date value.
Less Than, Less Than or Equals, More Than, More Than or Equals
These are used to compare individual number values. Less Than is
true if the value specified by the Left Side Data section is less

460 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 than the value specified by the Right Side Data section. The rest
of these comparisons work in a similar way.
To test for the existence of a date value, use Equals or Not Equals for
the operator and Null for the value; do not use More Than or Less Than
zero to test for the existence of a date value.
Contains, Start With, End With, Does Not Contain
These are used to compare individual text values. Contains is true if
the text value specified by the Left Side Data section contains the
text value specified by the Right Side Data section. For example,
abcdefg contains bcd; abcdefg does not contain bug.
Start Withis true if the text value specified by the Left Side Data
section starts with the text value specified by the Right Side Data
section. For example abcdefg starts with abcd; abcdefg does not start
with xyz.
End With is true if the text value specified by the Left Side Data
section ends with the text value specified by the Right Side Data
section. For example abcdefg ends with fg; abcdefg does not end with
abc.
Does Not Contain is true if the text value specified by the Left Side
Data section does not contain the text value specified by the
Right Side Data section. For example, abcdefg contains bcd; abcdefg
does not contain bug.
Contains, Start With, End With, and Does Not Contain are not case sensi-
tive. Contains - Case Sensitive, Start With - Case Sensitive, End With - Case Sensi-
tive, and Does Not Contain - Case Sensitive are case sensitive.
Before, After
These are used to compare individual date, time and date and
time values. Before is true if the value specified by the Left Side
Data section is before the value specified by the Right Side Data
section. After is true if the value specified by the Left Side Data
section is after the value specified by the Right Side Data section.
In, Not In
These are used to compare sets of records. These are the only
comparisons that should be used if the List check box is checked.
If the List check box is not checked then one of the other compar-
ison operations should be used.
In is true for retrieved records that are in the set of record speci-
fied by the Filter Records section of the Query task’s properties
form. Not In is true for retrieved records that are not in the set of
records specified by the Filter Records section.

© Copyright IBM Corporation 2011. Workflow Tasks | 461

 Associated To
This comparison is available only if the List check box is checked.
When Associated To is the Operator in the Left Side Data section
of a Task Filter, three properties show in the Right Side Data Sec-
tion: Record From Task, With Association Name, and Or Its Chil-
dren.
In Record From Task, specify from which task to retrieve the
associated record. If the task does not return a record, the plat-
form skips this filter.
In Association Name, specify the association to use. -Any- is one of
the values available.
Selecting the Or Its Children check box causes the association fil-
ter to also check the associated record’s children.
After you click OK on the Task Filter, the platform displays the task
filter in the Filter Using section.
To remove a task filter from the list in the Filter Using section, select
the check box next to a filter and click Delete Filter.

Filter Records
The purpose of the Filter Records section is to identify the records
that this task will use to filter query result records.
The Filter Records section has two radio buttons to specify where
records for filtering will come from. These radio buttons are labeled:
Workflow Activity
If this radio button is selected then the records for filtering will
be associated with a previously performed workflow task.
Existing Record
If this radio button is selected, then the record used for filtering
will be a specified record that exists now.
The selection of one of these radio buttons determines what appears
in the Filter Records section. Figure 7-36 on page 452 shows what the
Filter Records section looks like when the Workflow Activity radio
button is selected.
When the Workflow Activity radio button is selected, the Filter
Records section has all the fields that are in the Context Records
section. The difference between the fields in these sections is that
the fields in the Filter Records section are used to select the records

462 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

to use for filter conditions that have their Source radio button
selected.
If you want to filter records with information that is determined by
the application’s configuration, then you should select the option of
using an existing record in the Filter Records section. When the
Existing Record radio button is selected, the Filter Records section
looks like Figure 7-41.

Figure 7-41. Query Filter Records Section (Existing Filter)

You specify the value for the Module and Object properties so that
this task knows what kind of record you want to copy values from.
Then click the Record link to find the specific record you want this
task to use.

© Copyright IBM Corporation 2011. Workflow Tasks | 463

 Associate Records Task
An Associate Records task can create an association between two
records or remove an association between two records. Also, if
defined in the Data Modeler, the reverse association is created or
removed. The shape for an Associate Records task is shown in
Figure 7-42. Associate Shape Figure 7-42. The form for an Associate Records task is shown in
Figure 7-43.

Figure 7-43. Associate Records Properties for Associate using

The properties form for an Associate Records task is organized into

three sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

464 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The radio buttons under these fields determine whether this task will
create or remove an association.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons:
Associate using ____
If the Associate using radio button is selected, an association hav-
ing the specified name is created from the records identified by
the Create the association from section to the record identified
by the To section, unless such an association already exists.
Remove the association____
If the Remove the association radio button is selected, an associ-
ation having the specified name is removed from the records iden-
tified by the Remove the association from section to the record
identified by the Where the associated record is section. The

© Copyright IBM Corporation 2011. Workflow Tasks | 465

 form for an Associate Records task when Remove the association
is selected is shown in Figure 7-44.

Figure 7-44. Associate Records Properties for Remove the association

To the right of both radio buttons is a icon. The icon is used to

specify the name of the association to be created or removed. The
name of the specified association appears to the right of the icon.
To change the specified association name, click the icon. A list of
association names appears. Click the association name you want to be
the specified association name.
Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas

466 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.
The next two sections identify the records to use.
Create the association from / Remove the association from
The second section of the Associate Records task properties form
is labeled Create the association from or Remove the
association from, depending on whether the Associate using or
the Remove the association radio button is selected. The pur-
pose of this second section is to identify the first record in the
association.
For the sake of brevity, we refer to the record in this section as
the first record and refer to the record in the next section as the
second record. You can think of this as Create an association from

© Copyright IBM Corporation 2011. Workflow Tasks | 467

 the first record to the second record, or Remove the association
from the first record to the second record.
To / Where the associated record is
The third section of the Associate Records task properties form is
labeled To or Where the associated record is, depending on
whether the Associate using or the Remove the association radio
button is selected. The purpose of the third section is to identify
the second record in the association.
This section also provides the option of using an existing record.

Options for Record Selection

The options for record selection in these two sections are the same
except that the To / Where the associated record is section pro-
vides an option to select an existing record, which is discussed fur-
ther on page 472.
The To / Where the associated record is section has two radio but-
tons to specify where the second record will come from. These radio
buttons are labeled:
Workflow Activity
If this radio button is selected, the second record will come either
directly or indirectly from a previously performed workflow task.
Existing Record
If this radio button is selected, the second record will be a speci-
fied record that currently exists. More information is on page 472.
Figure 7-43 on page 464 and Figure 7-44 on page 466 show what the
third section looks like when the Workflow Activity radio button is
selected.
The following description of the fields for record selection apply to
the Create the association from / Remove the association from sec-
tion and the To / Where the associated record is section when its
Workflow Activity ratio button is selected:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, a record associated with the work-
flow task specified by the field to the right of this one will be
used to select the record for this section.

468 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 • Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, the secondary record in the Associ-
ate/De-Associate will be used to select the record for this sec-
tion.
This option also is available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART, or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event will be used to select the
record for this section.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be used to select the record for this section.
of Task
The value of this field is the label of the workflow task to retrieve
the record from.
The radio buttons under these fields determine how the record identi-
fied will be used to determine the record used for this section.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the record identified will be used for this sec-
tion.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the record identified will be used for this section.
When you select this radio button, a window pops up that allows
you to choose from the smart sections and locator fields in the
record identified in this section.

© Copyright IBM Corporation 2011. Workflow Tasks | 469

 After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, a record associated with the record identified
will be used for this section. When you select this radio button, a
window pops up that allows you to specify the type of association
to use. It allows you to identify the association by the type of
record that must be in the second record and optionally the name
of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
second record. If that is not the correct module, click the icon.
A list of modules will pop up. Click the correct module.
You also may specify that the second record must have been cre-
ated by a particular business object in the specified module. If
the name of a business object appears in the drop-down list to the
right of the module name, the second record must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, the second record may have been created from any
business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-,
which appears at the top of the list.

470 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Use its Parent
If the record identified is created from a business object that is
part of a hierarchy module and this option is selected, the
record’s parent will be used for this section.
When this radio button is selected, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record that will be
the second record. If the record can have been created from any busi-
ness object in a particular module, the name of the module appears
in the Object Type field.

© Copyright IBM Corporation 2011. Workflow Tasks | 471

 To / Where the associated record is
This section provides the option of using an existing record.
If the Existing Record radio button is selected, the second record will
be a specified record that currently exists. When the Existing Record
radio button is selected, the third section looks like the one in
Figure 7-45.

Figure 7-45. Associate Records (Existing)

Specify the value for the Module and Object properties so that this
task knows what kind of record you want for the second record. Then
click the Record link to find the specific record you want this task to
use.

472 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Trigger Action Task
A Trigger Action task performs a specified action on specified records.
The shape for a Trigger Action task is shown in Figure 7-46. The form
for a Trigger Action task is shown in Figure 7-47.
If there are multiple records for a Trigger Action task to perform an Figure 7-46. 
action on, the action is performed on all of the records, one at a Trigger Action Shape
time. If the actions launch asynchronous workflows, depending on
how the IBM TRIRIGA Application Platform and its environment are
configured, some or all of the launched workflows may run at the
same time.

Figure 7-47. Trigger Action Properties

The properties form for a Trigger Action task is organized into two
sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.
Action
This field is a drop-down list of the actions that can be performed
on the kind of records specified in the Records section of this

© Copyright IBM Corporation 2011. Workflow Tasks | 473

 task’s properties form. The action specified by this field is the
action that this task will perform on its records.
Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

474 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Records
The second section of the Trigger Action task properties form is
labeled Records. The purpose of the Records section is to identify
the records this task will perform its action on.
At the top of the Records section are fields used to identify a target
record. The target record is used to determine the records that the
action will be performed on.
There are radio buttons below the fields. The way that the target
records are used to determine the records an action will be per-
formed on depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, a record associated with the task
specified by the field to the right of this one will be the tar-
get record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, the record at the other end of the
association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the records on which to perform the action.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the

© Copyright IBM Corporation 2011. Workflow Tasks | 475

 visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record on which
the action is performed.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target record will be the record on which the
action is performed. When you select this radio button, a window
pops up that allows you to choose from the smart sections and
locator fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, a record associated with the target record will
be the record on which the action is performed. When you select
this radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon

476 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on
the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, the
record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, the target
record’s parent will be the record on which the action is per-
formed.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It allows this task to know what action will be available and
also allows other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the records on which
the action will be performed. If the record can have been created
from any business object in a particular module, the name of the
module appears in the Object Type field.

© Copyright IBM Corporation 2011. Workflow Tasks | 477

 Delete Reference Task
A Delete Reference task removes references to records from a smart
section. The shape for a Delete Reference task is shown in
Figure 7-48. The form for a Delete Reference task is shown in
Figure 7-48.  Figure 7-49.
Delete Reference Shape

Figure 7-49. Delete Reference Properties

The properties form for a Delete Reference task is organized into

three sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

478 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Delete Reference From Section
This field is a drop-down list of smart section names. The value of
this field is the name of the smart section from which to remove a
reference.
Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

© Copyright IBM Corporation 2011. Workflow Tasks | 479

 Delete Reference From Record
The second section of the properties form for a Delete Reference task
is labeled Delete Reference From Record. The purpose of this sec-
tion is to specify the record that contains the smart section from
which the reference to a record will be removed.
At the top of the Delete Reference From Record section are fields
used to identify a target record. The target record is used to deter-
mine the record that contains the smart section from which a refer-
ence to a record will be removed.
There are radio buttons below the fields. The way that the target
record is used to determine the record that contains the smart sec-
tion depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Record
If Record is selected, the record associated with the task speci-
fied by the field to the right of this one will be the target
record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate action. If the value of this
field is Secondary BO, the record at the other end of the associa-
tion is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.

480 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The radio buttons under these fields determine how the target record
will be used to determine the record that contains the reference to
be removed.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record that con-
tains the smart section.
Use its Reference
If this is selected, records referenced by a smart section or loca-
tor field of the target record will contain the smart section. When
you select this radio button, a window pops up that allows you to
choose from the smart sections and locator fields in the target
record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
contain the smart section. When you select this radio button, a
window pops up that allows you to specify the type of association
to use. It allows you to identify the association by the type of
record that must be on the other end of the association and
optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is

© Copyright IBM Corporation 2011. Workflow Tasks | 481

 also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, the target
record’s parent will contain the smart section.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields
and smart sections.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record that will
contain the smart section. If the record can have been created from

482 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

any business object in a particular module, the name of the module
appears in the Object Type field.

To Record
The third section of the properties form for a Delete Reference task is
labeled To Record. The purpose of this section is to identify the
record that is referred to by the reference that will be removed from
the smart section.
The To Record section has two radio buttons to specify how to find
the referenced record. These radio buttons are labeled:
Workflow Activity
The referenced record will be associated with a preceding work-
flow task.
Existing Record
The referenced record will be a record that exists now.
The selection of one of these radio buttons determines what appears
in the To Record section. Figure 7-50 on page 484 shows what the To
Record section looks like when the Workflow Activity radio button is
selected.
When the Workflow Activity radio button is selected, the To Record
section has all the fields that are in the Delete Reference From
Record section. The difference between the fields in these sections is
that the fields in the To Record section are used to select the record
to remove and the fields in the Delete References From Record sec-
tion are used to select the record that contains the smart section.
If you want to remove a reference to record that is part of the appli-
cation’s configuration information, you should select the option of

© Copyright IBM Corporation 2011. Workflow Tasks | 483

 using an existing record in the To Record section. When Existing
Record is selected, the To Record section looks like 7-50.

Figure 7-50. Delete Reference Properties (Existing)

You specify the value for the Module and Object properties so that
this task knows what kind of record you want to remove a reference
to. Then click the Record link to find the specific record you want this
task to use.

484 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Add Child Task
An Add Child task adds a child record to a record. The shape for an
Add Child task is shown in Figure 7-51. The form for an Add Child task
is shown in Figure 7-52.
Figure 7-51. Add Child Shape

Figure 7-52. Add Child Properties

This will work only if the child records are allowed to be children of
the candidate parent record. For this to be the case, the parent and
child records must have been created from business objects that are
part of the same hierarchy module. An Is Parent of association defini-
tion must exist from the business object used to create the parent
record to the business object used to create the child records.
The properties form for an Add Child task is organized into three sec-
tions. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.

© Copyright IBM Corporation 2011. Workflow Tasks | 485

 Description
A description of this task goes in this field.
Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

486 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Parent Record
The second section of the Add Child task properties form is labeled
Parent Record. The purpose of the Parent Record section is to iden-
tify the record that will be the parent.
The Parent Record section has two radio buttons to specify where the
primary record will come from. These radio buttons are labeled:
Workflow Activity
If this radio button is selected, the parent record will be associ-
ated with a previously performed workflow task.
Existing Record
If this radio button is selected, then the parent record will be a
specified record that exists now.
The selection of one of these radio buttons determines what appears
in the Parent Record section. Figure 7-52 on page 485 shows what the
second section looks like when the Workflow Activity radio button is
selected.
When the Workflow Activity radio button is selected, below the radio
buttons, the Parent Record section has all the fields that are in the
Child Record section. The difference between the fields in these sec-
tions is that the fields in the Parent Record section are used to select
the parent record and the fields in the Child Record section are used
to select child records. Because of these similarities, the description
of these fields is part of the description of the Child Record section.
If you want the parent record to be part of the application’s configu-
ration, you should select the option of using an existing record. When

© Copyright IBM Corporation 2011. Workflow Tasks | 487

 you select the Existing Record radio button, the second section looks
like the one in Figure 7-53.

Figure 7-53. Add Child Properties (Existing)

Specify the value for the Module and Object properties so that this
task knows what kind of record will be the parent. Then click the
Record link to find the specific record you want this task to use.

Child Record
The third section of the association task properties form is labeled
Child Record. The purpose of the Child Record section is to identify
child records for this task.
The following description of the fields in the third section also applies
to the fields in the second section that appear in the Parent Record
section when its Workflow Activity radio button is selected. The
fields in the Parent Record section serve a purpose similar to the cor-
responding fields in the Child Record section. The difference between
the corresponding fields in the Parent Record section is that they are
used to identify the parent record for this task and the fields in the
Child Record section are used to identify child records for this task.
At the top of the Child Record section are fields used to identify tar-
get records. The target records are used to determine the child
records.

488 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

There are radio buttons below the fields. The way that target records
are used to determine the child records depends on which one of the
radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then records associated with the
task specified by the field to the right of this one will be the
target records.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the records at the other end of
the association are the target records.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the event is the target record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
records will be associated with.
The radio buttons under these fields determine how the target
records will be used to determine the child records.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.

© Copyright IBM Corporation 2011. Workflow Tasks | 489

 Here are the descriptions:
Use it
If this is selected, the target records will be the child records.
Use its Reference
If this is selected, records referenced by a smart section or loca-
tor field of the target records will be the child records. When you
select this radio button, a window pops up that allows you to
choose from the smart sections and locator fields in the target
records.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target records will
be the child records. When you select this radio button, a window
pops up that allows you to specify the type of association to use.
It allows you to identify the association by the type of record that
must be on the other end of the association and optionally the
name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on

490 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, then
the record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target records are created from a business object that is
part of a hierarchy module and this option is selected, then the
target records’ parent will be the child records.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the records that will be
child records. If the records can have been created from any business
object in a particular module, then the name of the module appears
in the Object Type field.

© Copyright IBM Corporation 2011. Workflow Tasks | 491

 Set Project Task
A Set Project task has two functions. It (1) sets the current project for
the following tasks in this execution of this workflow, or (2) changes
the project on a record to the specified project. Projects are
Figure 7-54. 
described on page 675.
Set Project Shape The shape for a Set Project task is shown in Figure 7-54. The form for
a Set Project task depends on selections made in the first section.
The form initially displayed is shown in Figure 7-55.

Figure 7-55. Set Project Properties

The properties form for a Set Project task is organized into one, two,
or three sections, depending upon selections made in the first sec-
tion. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.
Under these fields are four radio buttons:

492 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Set Workflow Project to Company Level
If this radio button is selected, this task will cause the Company
Level project to be the current project. The Company Level
project is the top level project and includes all other projects.
Set Workflow Project from Record
If this radio button is selected, the current project will be set to
the project associated with the record specified in the Project
Record section of this form. If the record specified in the Project
Record section is from the triProject module, the current project
will be set to the actual record found.
Change Project for Records to Company Level
If this radio button is selected, the project on the records speci-
fied in the To Records section of this form is changed to the Com-
pany Level.
If an affected record has children and the RECORD_PROJECT_CONTAIN-
MENT property in TRIRIGAWEB.properties is set to Y, the children are
put in the Company Level, and the children’s children, and so on.
If an affected record has children and the RECORD_PROJECT_CONTAIN-
MENT property in TRIRIGAWEB.properties is set to N, the project for the
children is not changed. Only the record’s project is affected.
See the IBM TRIRIGA Application Platform 3 Installation and Imple-
mentation Guide for details about the TRIRIGAWEB.properties file and
the RECORD_PROJECT_CONTAINMENT property.
Change Project for Records from Record
If this radio button is selected, the project on the records speci-
fied in the To Records section of this form will be set to the
project associated with the records specified in the From Record
section of this form. If more than one record is pulled from the
From Record section at runtime, the system uses the first record
pulled.
If an affected record has children and the RECORD_PROJECT_CONTAIN-
MENT property in TRIRIGAWEB.properties is set to Y, the children are
put in the Company Level, and the children’s children, and so on.
If an affected record has children and the RECORD_PROJECT_CONTAIN-
MENT property in TRIRIGAWEB.properties is set to N, the project for the
children is not changed. Only the record’s project is affected.
See the IBM TRIRIGA Application Platform 3 Installation and Imple-
mentation Guide for details about the TRIRIGAWEB.properties file and
the RECORD_PROJECT_CONTAINMENT property.

© Copyright IBM Corporation 2011. Workflow Tasks | 493

 Set Workflow Project to Company Level
Initially, the current project for a workflow is the project that was
the current project for the user that launched the workflow. If the
workflow was launched from a Call Workflow task, the initial project
is the project context at the time the Call Workflow task was exe-
cuted.
When a query is set to Active Project and executed from the Report
Manager, the results are based on the scope of the project the user is
in if the record is in a capital project or on the scope of the project
the parent record is in if the record is not in a capital project. If the
same query is executed in a workflow, the results are based on all
projects including the Company Level. To resolve this discrepancy,
use a Set Project task at the start of the workflow. This ensures the
workflow returns the same results as the query returns when run from
the Report Manager.
Selecting the Set Workflow Project to Company Level radio button
changes the form to a Set Project task to look like Figure 7-56.

Figure 7-56. Set Project Properties - Set Workflow Project to Company Level

With this setting, a Set Project task sets the current project for the
following tasks in this execution of the workflow to Company Level.
The properties form for a Set Project task when Set Workflow
Project to Company Level is selected is organized into one section.

Set Workflow Project from Record

Initially, the current project for a workflow is the project that was
the current project for the user that launched the workflow. If the
workflow was launched from a Call Workflow task, the initial project
is the project context at the time the Call Workflow task was exe-
cuted.

494 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

When a query is set to Active Project and executed from the Report
Manager, the results are based on the scope of the project the user is
in if the record is in a capital project or on the scope of the project
the parent record is in if the record is not in a capital project. If the
same query is executed in a workflow, the results are based on all
projects including the Company Level. To resolve this discrepancy,
use a Set Project task at the start of the workflow. This ensures the
workflow returns the same results as the query returns when run from
the Report Manager.
Selecting the Set Workflow Project from Record radio button dis-
plays the form for a Set Project task in Figure 7-55 on page 492.
With this setting, a Set Project task sets the current project for the
following tasks in this execution of the workflow to the project associ-
ated with the record specified in the Project Record section of the
form.
The properties form for a Set Project task when Set Workflow
Project from Record is selected is organized into two sections.

Project Record Section.

The second section of the properties form for the Set Project task
when Set Workflow Project from Record is selected is labeled Project
Record. The purpose of the Project Record section is to identify the
record whose associated project will become the current project or to
select a record from the triProject module.
At the top of the Project Record section are fields used to identify a
target record. The target record is used to determine the record that
will be used to set the current project.
There are radio buttons below the fields. The way that the target
record is used to determine the record that will be used to set the
project depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, a record associated with the task
specified by the field to the right of this one will be the tar-
get record.

© Copyright IBM Corporation 2011. Workflow Tasks | 495

 • Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, a record at the other end of the asso-
ciation is the target record.
This option also is available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART, or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record that will be used to set the cur-
rent project.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record used to set
the current project.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target records will be the record used to set the
current project. When you select this radio button, a window pops
up that allows you to choose from the smart sections and locator
fields in the target record.

496 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, a record associated with the target record will
be used to set the current project. When you select this radio
button, a window pops up that allows you to specify the type of
association to use. It allows you to identify the association by the
type of record that must be on the other end of the association
and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on
the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, the
record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that

© Copyright IBM Corporation 2011. Workflow Tasks | 497

 are not restricted to a particular association name, click -Any-,
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, the target
record’s parent will be used to set the current project.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of record that will be used
to set the project. If the record could have been created from any
business object in a particular module, the name of the module
appears in the Object Type field.

Change Project for Records to Company Level

If this radio button is selected, the project on the records specified in
the To Records section of this form is changed to the Company Level.
If an affected record has children and the RECORD_PROJECT_CONTAINMENT
property in TRIRIGAWEB.properties is set to Y, the children are put in the
Company Level, and the children’s children, and so on.
If an affected record has children and the RECORD_PROJECT_CONTAINMENT
property in TRIRIGAWEB.properties is set to N, the project for the children
is not changed. Only the record’s project is affected.
See the IBM TRIRIGA Application Platform 3 Installation and Imple-
mentation Guide for details about the TRIRIGAWEB.properties file and the
RECORD_PROJECT_CONTAINMENT property.

498 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Selecting the Change Project for Records to Company Level radio
button changes the form to a Set Project task to look like Figure 7-57.

Figure 7-57. Set Project Properties - Change Project for Records to Company
Level

The properties form for a Set Project task when Change Project for
Records to Company Level is selected is organized into two sections.
The second section, To Records, identifies the target records to be
changed to the Company Level.

To Records Section.
The second section of the properties form for the Set Project task
when Change Project for Records to Company Level is selected is
labeled To Records. The purpose of the To Records section is to
identify the records whose associated project will become the Com-
pany Level.
At the top of the To Records section are fields used to identify tar-
get records whose associated project will be changed to the Company
Level.
There are radio buttons below the fields. The way that the target
records are determined depends on which one of the radio buttons is
selected.
Here are descriptions of the fields:

© Copyright IBM Corporation 2011. Workflow Tasks | 499

 Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, records associated with the task
specified by the field to the right of this one will be the tar-
get records.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, records at the other end of the associ-
ation are the target records.
This option also is available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART, or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target
records will be determined.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target records will have their project
changed to Company Level.

500 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Use its Reference
If this is selected, records referenced by a smart section or loca-
tor field of the target records will be the records that have their
project changed to Company Level. When you select this radio
button, a window pops up that allows you to choose from the
smart sections and locator fields in the target records.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
have their project changed to Company Level. When you select
this radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You also may specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on
the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, the

© Copyright IBM Corporation 2011. Workflow Tasks | 501

 record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-,
which appears at the top of the list.
Use its Parent
If the target records are created from a business object that is
part of a hierarchy module and this option is selected, the target
records’ parent will have its project set to the Company Level.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this is the equivalent of selecting the mod-
ule’s base business object (the one with the same name as the
module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of record that will have its
project changed to Company Level. If the records could have been
created from any business object in a particular module, the name of
the module appears in the Object Type field.

Change Project for Records from Record

If this radio button is selected, the project on the records specified in
the To Records section of this form will be set to the project associ-
ated with the records specified in the From Record section of this
form. If more than one record is pulled from the From Record sec-
tion at runtime, the system uses the first record pulled.
If an affected record has children and the RECORD_PROJECT_CONTAINMENT
property in TRIRIGAWEB.properties is set to Y, the children are put in the
Company Level, and the children’s children, and so on.
If an affected record has children and the RECORD_PROJECT_CONTAINMENT
property in TRIRIGAWEB.properties is set to N, the project for the children
is not changed. Only the record’s project is affected.

502 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Selecting the Change Project for Records from Record radio button
changes the form to a Set Project task to look like Figure 7-58.

Figure 7-58. Set Project Properties - Change Project for Records to Company
Level

The properties form for a Set Project task when Change Project for
Records from Record is selected is organized into three sections. The
second section, To Records, identifies the target records to be
changed. The third section, From Record, identifies the source record
that contains the project to which the target will be changed.

To Records Section.
The second section of the properties form for the Set Project task
when Change Project for Records from Record is selected is labeled
To Records. The purpose of the To Records section is to identify the
records whose associated project will be changed.
At the top of the To Records section are fields used to identify tar-
get records. The target records will have their project changed.

© Copyright IBM Corporation 2011. Workflow Tasks | 503

 There are radio buttons below the fields. The way that the target
records are determined depends on which radio button is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, records associated with the task
specified by the field to the right of this one will be the tar-
get records.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, records at the other end of the associ-
ation are the target records.
This option also is available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART, or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target
records will be determined.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:

504 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Use it
If this is selected, the target records will have their project
changed.
Use its Reference
If this is selected, records referenced by a smart section or loca-
tor field of the target records will be the records that have their
project changed. When you select this radio button, a window
pops up that allows you to choose from the smart sections and
locator fields in the target records.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
have their project changed. When you select this radio button, a
window pops up that allows you to specify the type of association
to use. It allows you to identify the association by the type of
record that must be on the other end of the association and
optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You also may specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on

© Copyright IBM Corporation 2011. Workflow Tasks | 505

 the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, the
record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target records are created from a business object that is
part of a hierarchy module and this option is selected, the target
records’ parent will have its project changed.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of record that will have its
project changed. If the records could have been created from any
business object in a particular module, the name of the module
appears in the Object Type field.

From Record Section.

The third section of the properties form for the Set Project task when
Change Project for Records from Record is selected is labeled From
Record. The purpose of the From Record section is to identify the
record whose associated project is the source for the project of the
record identified in the To Record section or to select a record from
the triProject module.
If more than one record is pulled from the From Record section at
runtime, the system uses the first record pulled.
At the top of the From Record section are fields used to identify a
target record. The target record is used to determine the record that

506 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

will be used to set the project in the record identified in the To
Record section.
There are radio buttons below the fields. The way that the target
record is used to determine the record that will be used to set the
project depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, a record associated with the task
specified by the field to the right of this one will be the tar-
get record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, a record at the other end of the asso-
ciation is the target record.
This option also is available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART, or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record that will be used to change the
project on the records identified in the To Records section.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-

© Copyright IBM Corporation 2011. Workflow Tasks | 507

 tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record used to set
the project in the records in the To Records section.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target record will be the record used to set the
project in the records in the To Records section. When you select
this radio button, a window pops up that allows you to choose
from the smart sections and locator fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, a record associated with the target record will
be used to set the project in the records in the To Records sec-
tion. When you select this radio button, a window pops up that
allows you to specify the type of association to use. It allows you
to identify the association by the type of record that must be on
the other end of the association and optionally the name of the
association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.

508 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on
the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, the
record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-,
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, the target
record’s parent will be used to set the project in the records in
the To Records section.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of record that will be used
to set the project. If the record could have been created from any
business object in a particular module, the name of the module
appears in the Object Type field.

© Copyright IBM Corporation 2011. Workflow Tasks | 509

 Schedule Task
Schedule tasks allow a mapping operation to be scheduled once or as
something to be done on a recurring basis. Schedule tasks are
described in detail in Chapter 10 titled “Calendar and Time Based
Figure 7-59. Schedule Shape Events” on page 621.
The shape for a Schedule task is shown in Figure 7-59.
Instead of designing applications to create scheduled events manu-
ally, use the Event form, as described in Chapter 10.

510 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Modify Metadata Task
The purpose of the Modify Metadata task is to modify the metadata
that controls the presentation of a form for a particular record. The
shape for a Modify Metadata task is shown in Figure 7-60.
Figure 7-60. 
The form for a Modify Metadata task is shown in Figure 7-61. Modify Metadata Shape

Organization of
Form Metadata
For each kind of form that can
be used to edit a record, a set
of metadata is kept with the
record. This means that if
there is more that one form
for a record, you can use a
Figure 7-61. Modify Metadata Properties Modify Metadata task to make
a field appear in red text for
Using the Modify Metadata task, you can do things like make sections one form and the same field
for field hidden or visible, change the color of text in a field or the in blue text for another form.
text of a label. Alternatively, you can set the
color of text for a field to
The properties form for a Modify Metadata task is organized into two black in all forms that can be
sections. Here are descriptions of the fields in the first section: used with the record.

Label Bear in mind that if two peo-

This is the label used to identify this task. This field’s text ple are using the same form to
look at the same record, they
appears on the shape in the drawing that represents this work-
are not just seeing the same
flow task. Use the standards in “Workflow Naming Standards” on data, they are also seeing the
page 388. same metadata.
Description
A description of this task goes in this field.
Form
The value of this field determines which form(s) will be affected
by this task. This field’s value is selected from its drop-down list.
The drop-down list includes the names of all forms associated
with the business object shown in the Object Type field at the

© Copyright IBM Corporation 2011. Workflow Tasks | 511

 bottom of the Modify Metadata task properties. If you select one
of these, the Modify Metadata task will alter just the named form
for working with the record specified in the second section.
You may need to fill in the second section of this form before set-
Metadata is not ting the value of this field, otherwise the drop-down list for this
Temporary field may not contain the right form names.
Data comes in permanent and In addition to the names of forms, there are two other items that
temporary varieties. This dis- appear in this field’s drop-down list.
tinction is described in detail
in Chapter 8. If the value you select for this field is -Current-, this task will mod-
ify the metadata for whichever form is currently being used with
There is no temporary meta-
data, just permanent meta-
the record identified by the second section.
data. Even if a workflow is If the value you select for this field is -All-, the modifications this
supposed to be working with tasks makes will be for the metadata of all forms associated with
temporary data, all modifica-
the business object for the record identified by this task’s second
tions to metadata are perma-
nent. The changes will stay in section of properties. This is not often used since there is always
effect until the next time the a single form associated with a record. Instead of using -All-, use
metadata is modified. the -Current- option, which has better performance if there are sev-
eral forms associated to the business object.
Reset Before Modification
If this check box is checked, before this task makes its modifica-
tions to metadata, the form’s metadata will be reset to the val-
ues specified for the form in the Form Builder.

Records
The second section of the Modify Metadata task properties form is
labeled Records. The purpose of the Records section is to specify the
record associated with the form whose metadata is to be modified.
At the top of the Records section are fields used to identify a target
record. The target record is used to determine the record associated
with the form(s) to be modified.
There are radio buttons below the fields. The way that target records
are used to determine the record associated with the form(s) depends
on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:

512 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 • Business Object
If Business Object is selected, record associated with the task
specified by the field to the right of this one will be the tar-
get record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, the record at the other end of the
association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record associated with the form.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record associated
with the form(s).
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target records will be the record associated with
the form(s). When you select this radio button, a window pops up

© Copyright IBM Corporation 2011. Workflow Tasks | 513

 that allows you to choose from the smart sections and locator
fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
be the record associated with the form(s). When you select this
radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-

514 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the target
records’ parent will be the record associated with the form.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record that will be
associated with the form(s).
You can access the Form Mapping window by clicking the Edit Map
action at the top of the Records section. The Object Mapping window
is described below in Figure 7-62.
If you want to reset the object mapping to its defaults without pop-
ping up the object mapping window, click the Reset Map action.

Figure 7-62. Form Mapping Root

There are special attributes that can be set at the root level of the
Form Map. The Change GUI To attribute allows you to change the
form to any form defined for the business object of the record. The
Close Window attribute overrides the Close option of the state transi-
tions for the form defined on page 370 for this particular runtime

© Copyright IBM Corporation 2011. Workflow Tasks | 515

 instance of the workflow. This property is reset to that of the form
state transition each time the record is opened. Typically, this
attribute is used for the “fail” path of a validation workflow to ensure
the form is not closed if the workflow did not save the record perma-
nently.
All other attributes are described in the chapter Building User Inter-
faces on page 219. The navigation of the Form Mapping tree is also
the same as in the Layout tab of the Form Wizard. When you click one
of the nodes in this tree you will see attributes that correspond to
your selection, they will be different if you select a tab, section, field
or action. Figure 7-63 shows the attributes for a tab.

Figure 7-63. GUI Mapping Tab

You will notice that there are three ways to populate the map. You
can either type directly into the Value column, select from a list in
the Value column or for some attributes check the box in the Task
column. When you check the box in the task column a binoculars icon
( ) is displayed. When you click the binoculars icon ( ), another
window is displayed which shows a list of all tasks in the workflow,
you can select the result of one of these tasks to populate the

516 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

attribute. Figure 7-63 below shows the selection window when map-
ping from a task.

Figure 7-64. Form Mapping From Task

NOTE: If the task selected has a list of records, one of the records in
the list will be chosen to do the map into the metadata. Instead, use
a task for mapping that results in a single record.

Attention: Be sure to click the Apply action on the left side of

the Form Mapping after you have finished editing the
map. If you move on to something else without first
clicking that Apply action, then any changes you made
to the map will be lost.

© Copyright IBM Corporation 2011. Workflow Tasks | 517

 End Task
An End task is used to indicate the end of a workflow. When a work-
flow reaches an End task, the workflow is complete and there are no
more tasks to be performed. The workflow is considered to have com-
Figure 7-65. End Shape
pleted normally.
All workflows are created with an End task. The End task that a work-
flow is created with cannot be deleted. End tasks that are added to a
workflow after it is created can be deleted.
The shape for an End task is shown in Figure 7-65. End tasks do not
have any properties.

Stop Task
A Stop task is used to indicate the end of a workflow. When a work-
flow reaches a Stop task, no more of its tasks will be performed. The
Figure 7-66. Stop Shape workflow is considered to have completed abnormally.
The shape for a Stop task is shown in Figure 7-66. Stop tasks do not
have any properties.

518 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Switch Task
A Switch task contains two sequences of tasks. Based on conditions
specified as properties of a Switch task, it causes only one of its task
sequences to be performed. After the task sequence has been per-
formed, the task after the Switch task is performed. The Switch task
is much like the traditional “If statement.”
The palette shape for a Switch task is shown in Figure 7-67.
Figure 7-68 on page 519 shows a simple example of a workflow that Figure 7-67. Switch Shape
contains a Switch task.

Figure 7-68. Switch Example

The sample workflow in Figure 7-68 begins by creating a record. If the

create task is successful, the record is modified and is then used for
an action item created by the User Action task. If the create task is
not successful, the workflow ends in failure.
One thing to notice about the switch task as it appears in Figure 7-68
is that there is more of it than just its palette shape. The bottom of

© Copyright IBM Corporation 2011. Workflow Tasks | 519

 the switch task is where the two alternate task sequences come
together. You can click the top or the bottom of a switch task to see
its properties.
The properties form for a switch task is shown in Figure 7-69 on page
520. The properties form for a switch task has more actions than we
have seen in previous task forms. Like other task property forms, it
has a Delete action to delete the task from the workflow. Be particu-
larly careful when deleting a switch task from a workflow, because
deleting a switch task also deletes the task sequences contained in
the switch task.

Figure 7-69. Switch Properties

The contents of the Switch task form is a condition that is either true
or false. If the condition is true when a switch task is performed, the
task sequence attached to the green circle is performed. If the condi-
tion is false, the task sequence attached to the red square is per-
formed.
The Swap action swaps the positions of the green circle and the red
square, while leaving the task sequences where they are. After a
Swap action, the task sequence that was attached to the green circle

520 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

is attached to the red square and the task sequence that was
attached to the red square is attached to the green circle.

Workflow Condition Builder

Some types of tasks use a condition to decide what they should do. A
condition is a comparison between values. A condition is either true
or false. The properties forms for these tasks share a common organi-
zation to create and edit conditions. An example of one of these
forms is in Figure 7-69 on page 520.
The Condition Builder’s purpose is to build a formula in its bottom
panel that is either true or false. You build the formula using the Edit
and Insert menus at the top of the condition builder, along with the
Tasks, Basic Ops and System Function panels.
The Tasks panel allows you to insert task attributes and fields of
records into the condition.
The Basic Ops panel allows you to insert operators into the condition.
The System Function panel allows you to insert system defined and
user defined functions into a condition.
The following example shows the use of these panels and menus.
After this example are more detailed explanations.
The example we will work through is for a workflow to be launched
for an Employee record. The example will be to build a condition that is
true if a preceding Create workflow task succeeded and if the cur-
rent time is on or after the date that the employee was hired. When
we are all finished, the condition will look like
Create Record::Success=="SUCCESS" && Start::Employee::Detail::DateHire<=CurrentTime()

When we first begin building a new condition, the bottom panel of the
Condition builder looks like Figure 7-70.

Figure 7-70. Empty Condition

In the beginning there is no formula. There is just a small gray rectan-

gle in the bottom panel. The Condition Builder puts a gray rectangle
before each part of the formula.

© Copyright IBM Corporation 2011. Workflow Tasks | 521

 When you add a part to the formula, it gets added to the right of the
currently selected gray rectangle. You can select a gray rectangle by
clicking it. You can tell that a gray rectangle has been selected
because it will have a blinking cursor inside of it.
The gray rectangle in an empty Condition Builder is already selected.
The first thing we will add to the condition is a reference to the Cre-
ate Record task’s success attribute. To do this, we use the Tasks
panel.
We begin by clicking the icon next to the name of the Create Record
task. Clicking the icon causes the attributes and business objects asso-
ciated with the task to be displayed under the task. The icon
changes to a icon.
The attributes now displayed under the Create Record task include an
attribute named Success. Clicking the name Success causes the name of
the attribute along with the name of the task to be copied to the con-
dition. The Condition Builder now looks like Figure 7-71.

Figure 7-71. Condition Builder Success Attribute

When we add the reference to the Success attribute, the Condition

builder adds another gray rectangle after what we added. The new

522 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

rectangle after what we added is automatically selected, so the next
thing we add will be to the right of that.
The next thing to add to the condition is ==. The == will compare the
value of the Success attribute to whatever we put to the right of the ==.
The comparison will be true if the two have the same value or false if
they do not.
To add the == click the == in the Basic Ops panel.* Clicking an opera-
tor in the Basic Ops panel adds the operator to the condition. After
you click the == the Condition Builder looks like Figure 7-72.

Figure 7-72. Condition Builder ==

The next thing to do is add the text "SUCCESS" so that the condition can
be true if the value of the Create Record task’s Success attribute is
equal to "SUCCESS". To put a text or number value in a condition, we
use the Insert menu at the top of the condition builder.
When you click the Insert menu, its menu items appear. They look Figure 7-73. 
Insert Menu
like Figure 7-73.

* There is a complete list with explanations of the operators in the Basic Ops section on
page 527 under the heading “Condition Builder Operators”

© Copyright IBM Corporation 2011. Workflow Tasks | 523

 Clicking the Number menu item allows you to add a Number value to
a condition. Clicking the String menu item allows you to add a text
value to a condition. Clicking either of these menu items creates a
box in the Condition where you can enter a number or text value as
appropriate.
To enter a string value into the box that is added when you click the
String menu item, click the box and then type the value. After you
type the value "SUCCESS", the condition builder looks like Figure 7-74.

Figure 7-74. Condition Builder String

The next thing to add to the condition is the operator &&. The &&
operator is a logical && operator. The and operator is true if the condi-
tions on both sides of the && operator are true.
After we added "SUCCESS" to the condition, the part of the condition
that was selected was the box that contains "SUCCESS". The Condition
Builder will not allow us to do anything to the condition unless one of
the gray boxes is selected. Before we can add the && operator to the
end of the condition, we must select the gray box at the end of the
condition by clicking it. We then add the && operator by clicking && in
the Basic Ops panel.
The next thing we add to the condition is a reference to the DateHire
field in the Employee record that was used to launch the workflow.

524 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Since the record that was used to launch the workflow is associated
with the Start task, click the Start task’s icon to see the list of things
under the Start task. This list includes the Employee record that was
used to launch the workflow.
To see what is in the Employee record we click the icon next to the
name Employee. The Condition Builder now looks like Figure 7-75.

Figure 7-75. Condition Builder &&

The list that appears in the Tasks panel under the name of a kind of
record is a list of section names. An icon appears next to each sec-
tion name. If what appears next to a section’s name is a icon, the
section is a type of section that the Condition Builder cannot use to
access fields.
At the time of this writing, the Condition Builder is unable to access
fields in multiple-record smart sections. Most of the sections in
Figure 7-75 that have a icon are multiple-record smart sections.
If what appears next to a section’s name is a icon or a icon, then
the Condition Builder is able to access the section’s fields. At the
time of this writing, there are only two kinds of sections that have a
icon or a icon next to their name. Single-record smart sections have
one of these icons next to their name.

© Copyright IBM Corporation 2011. Workflow Tasks | 525

 The other kind of section that has a icon or a icon next to its
name really is not a section. The Condition Builder pretends that a
business object’s fields that are not in a smart section are in a sec-
tion named General. This artificial General section has a icon or a
icon next to its name.
An Employee record’s DateHire field is in a section named Detail. To see
the Detail section we scroll down to a lower part of the Tasks panel
and click the icon next to the name of the Detail section. We can
now see the name of the DateHire field, so we click it. The Condition
Builder now looks like Figure 7-76.

Figure 7-76. Condition Builder Field

The next thing to add to the condition is a <= that will be used to
determine if the value of the DateHire field is before or equal to the
current time. We add it by clicking the <= in the Basic Ops panel.

526 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

We finish by clicking CurrentTime in the System Function panel. The
Condition Builder now looks like Figure 7-77.

Figure 7-77. Condition Builder Done

The system functions that you can click in the System Function panel
are the same system functions that are used for extended formulas.
See “Formulas Predefined by the Platform” in the book Application
Building for the IBM TRIRIGA Application Platform 3: Calculations.
You can access user defined functions by clicking the button labeled
User Defined Function. These are the same user defined functions
that are used for extended formulas. See “Predefining Your Own For-
mulas” in the book Application Building for the IBM TRIRIGA Applica-
tion Platform 3: Calculations.
The operators in a condition are evaluated strictly from left to right,
except for parentheses. For example, this is always true:
2 + 3 * 4 == 4 * (3 + 2)

For Integration, 0 is Not Selected and 1 is Selected. See “Integration”

on page 399 for more information.

Condition Builder Operators

The Basic Ops section of the Condition Builder contains the operators
shown in the following table:

© Copyright IBM Corporation 2011. Workflow Tasks | 527

 ( The left parenthesis is used with the right parenthesis to
change the order in which operations in a formula are per-
formed.

) The right parenthesis is used with the left parenthesis to

change the order in which operations in a formula are per-
formed.

- A minus sign is used for subtraction.

+ A plus sign is used for addition.

* A star is used for multiplication.

/ A slash is used for division.

< A less-than evaluates to true if the expression to its left eval-

uates to less than the expression to its right.

> A greater-than evaluates to true if the expression to its left

evaluates to greater than the expression to its right.

<= A less-than-or-equals evaluates to true if the expression to its

left evaluates to less than or equal to the expression on its
right.

<= A less-than-or-equals evaluates to true if the expression to its

left evaluates to less than or equal to the expression on its
right.

>= A greater-than-or-equals evaluates to true if the expression

to its left evaluates to greater than or equal to the expres-
sion to its right.

== A double equals sign is used for equals. It evaluates to true if

the expressions on both sides of it evaluate to the same
value.

!= Exclamation point equals is used for not-equals. It evaluates

to true if the expressions on both sides of it evaluate to dif-
ferent values.
Figure 7-78.

528 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 && A double ampersand is used for logical “and”. It evaluates to
true if the expressions on both sides of it evaluate to true.

|| A double vertical bar is used for logical “or”. It evaluates to

true if the expressions on either or both sides of it evaluate
to true.
Figure 7-78.

© Copyright IBM Corporation 2011. Workflow Tasks | 529

 Fork Task
A Fork task defines multiple sequences of tasks. A Fork task allows all
its task sequences to be performed at the same time. After all the
task sequences have been performed, the task after the Fork task is
performed.
Figure 7-79. Fork Shape The palette shape for a Fork task is shown in Figure 7-79. Figure 7-80
shows a simple example of a workflow that contains a Fork task.

Figure 7-80. Fork Example

530 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

One thing to notice about the Fork task as it appears in Figure 7-80 is
that there is more of it than just its palette shape. The bottom of the
Fork task is where the task sequences come together.
The purpose of the sample workflow shown in Figure 7-80 is to get
two approvals for the record that caused the workflow to be
launched. Rather than waiting for one approval to be made before
waiting for the second, the workflow waits for both approvals to hap-
pen at the same time. This way, the workflow can finish as soon as
both approvals have been made, no matter which one happens first.
The workflow in Figure 7-80 begins with a Fork task. The fork has two
branches, one for each of the two approvals. The task after the fork is
not performed until after all of the fork’s branches are finished being
performed, which is when both of the approvals have been done.
Each branch of the fork contains a similar sequence of tasks.* Each
branch begins by creating a record for the kind of approval that the
fork is responsible for. It then performs an approval task to get the
appropriate approval.
When both approval tasks have completed, the fork is done. The task
that follows the fork task is a switch task that causes the appropriate
task to be performed, based on whether both approval tasks resulted
in an approval or not.
You can click the top or bottom of a Fork task to see its properties
form. A Fork task’s properties form does not contain any properties. It
does have two actions:
• The form for a fork has a Delete action for deleting the Fork task.
This should be used with care, since deleting a Fork task also
deletes all the tasks in all its branches.
• The form for a fork also has an Add Branch action. Clicking the
Add Branch action has the effect of adding a new empty branch
to the fork.
Clicking the circle at the bottom of a branch has the effect of select-
ing the branch and causing the properties form for the branch to be
displayed. The properties form for a branch does not contain any
properties, but it does have a Delete action for deleting the branch
and all the tasks that the branch contains.

* It is not unusual for the branches of a fork to do different things. We chose an example
in which the branches of a fork do similar things to keep the example in Figure 7-80 sim-
ple.

© Copyright IBM Corporation 2011. Workflow Tasks | 531

 There are some benefits to allowing more than one thing to happen at
the same time. The most obvious is that work can be completed
sooner if some parts of the work can be done at the same time rather
than completing the parts one after the other. If all the parts are
done one after the other then the time required to finish the work
will be the sum of the times it takes to perform each part. If all the
parts are done at the same time, then the work takes only as long as
the longest part.
When different parts of some work are being done at the same time,
it is very important that the tasks being performed on the different
parts do not interfere with each other. This one important consider-
ation is the reason that the example in Figure 7-80 on page 530 is
structured the way that it is structured.
Simply having two approval tasks try to approve the same record at
the same time will not work because an approval task automatically
locks the record to be approved from the time that the task starts
until there is an action that ends the approval. This locking is not
something that we want to try to bypass. The locking happens
because it is always a bad idea to have one person modifying a record
while someone else is modifying the record.
To avoid conflicts between whatever else is happening with the
record being approved and the approvals, the example in Figure 7-80
on page 530 creates new records for the approval. Because each
approval works on a record that exists only for that approval, there
can be no possible interference between the approvals and anything
else.

532 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Loop Task
A Loop task contains a sequence of tasks that may be performed mul-
tiple times. The palette shape for a Loop task is shown in Figure 7-81.
Figure 7-82 shows an example of a workflow that contains a Loop
task.
One thing to notice about the Loop task as it appears in Figure 7-82 is Figure 7-81. Loop Shape
that there is more of it than just its palette shape. The bottom of the
Loop task has an arrow that goes back to the top.
The purpose of the sample workflow shown in Figure 7-82 is to find
slots in a warehouse to put a new batch of products. The workflow
begins by creating a temporary record that it will use to keep track of
which slots remain to be checked. It retrieves the slots that may have
sufficient storage space available. It then associates the slots with the Iterator is
temporary record. The next task is the loop task. Simpler
All that the Loop task does is perform the sequence of tasks it con- Than Loop
tains over and over. The first task in its sequence retrieves one of the
The Loop task is very flexible
slots associated with the temporary record. and can be used to create a
The next task is a Break task. A Break task works with the Loop task great variety of loops. One of
the most common kinds of
that contains it. What a Break task does is decide if the next task to
loops is a loop where each
be performed should be the next task inside the loop or the task after time through the loop, the
the loop. body of the loop works on a
different record in a list of
The Break task in Figure 7-82 checks if there was a next slot for the
records.
preceding task to retrieve. If there was a slot to retrieve, the next
task in the loop is the next task that will be performed. However, if Because this is a particularly
there was no next slot, then the Break task breaks out of the loop, common case, the platform
has another workflow task
making the next task to be performed the end task after the loop. named Iterator that makes it
Break tasks are described in more detail in the next section of this simpler to write this common
type of loop. Use the Iterator
chapter.
task instead of the Loop task.
If the loop continues after the Break task, it adds as much of the
The Iterator task is discussed
product batch as still remains and will fit to the slot. It then reduces on page 540.
the amount of product remaining to be stored. Finally, it removes the
association between the slot it just checked and the temporary
record.
After it finishes this, the Loop task has finished performing its
sequence of tasks. The Loop task continues by executing its sequence
of tasks again, beginning with the task labeled Retrieve Next.
The Loop task maintains a count of the current loop it is in. The loop
count is exposed as the Result Count. The Loop task can be named so you

© Copyright IBM Corporation 2011. Workflow Tasks | 533

 Figure 7-82. Loop Example

534 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

can identify it in other tasks. The loop Result Count can be used in condi-
tions, for example, in a Break task or Switch task condition.
The Loop task has a delay value. When the delay value is greater than
10, the loop will delay that many milliseconds before executing the
next iteration.
Often, it is possible to arrange for a sequence of tasks to be per-
formed on multiple records at once. When you can find such a
sequence of tasks, it is always a better way to do things that way than
using a loop. Loops are more complicated to set up, more difficult to
get right and they take longer to run. Avoid loops when you can.

© Copyright IBM Corporation 2011. Workflow Tasks | 535

 Break Task
A Break task works within an enclosing Loop task, Iterator task, or
DataConnect task to decide whether the enclosing task should con-
tinue performing the sequence of tasks that it contains or exit the
sequence, and whether the exit should be considered a success or an
error. The palette shape for a Break task is shown in Figure 7-83. The
Figure 7-83. Break Shape workflow in Figure 7-82 on page 534 contains an example of a Break
task. As you develop a workflow that contains a Break task, the Break
task shape and color may change depending on the properties you
select.
A Break task decides whether to continue with its enclosing task or to
exit out of it based on the Break task properties and whether or not
all of the conditions associated with them are true. The form for a
Break task is used to set properties, to associate conditions with a
Break task, and to manage conditions. The creation and management
of conditions is discussed on page 521 under the heading “Workflow
Condition Builder”.
The form for a Break task is shown in Figure 7-84.

Figure 7-84. Break Task Properties

The properties form for a Break task is organized into three sections.
Here are descriptions of the fields in the first section:
Flow Type
Loop, Iterator, and DataConnect tasks are tasks that define a
block of tasks. Select Break if the workflow should exit from the
block when the condition is met. Select Continue if the workflow
should continue processing from the beginning of the block when
the condition is met. The block to Break out of, or the block to
Continue in, is determined by the Scope property.

536 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 If a Break task is encountered, the next task is determined by the
values in the Break Scope section. The Flow Type (Continue or
Break) determines whether it continues on the next iteration or
loop of the enclosing task or breaks out. The Task Status deter-
mines what the transaction management should do.
Task Status
Indicates how the status of the enclosing block should be set on
Break or Continue. In a DataConnect task the status is used as
part of the transaction control. The DataConnect task is described
on page 561. Selecting Success may cause a commit if the value
of the block in the Break Scope section is a controlling block and
it is time for the commit based on the transaction settings or if
breaking out of the controlling block. Selecting Error causes a
rollback if the value of the block in the Break Scope section is the
controlling block or if breaking out of the controlling block.

Break Scope
The second section of the Break task properties form is labeled Break
Scope. The purpose of the Break Scope section is to specify what the
Break task is controlling. The values for Break Scope are as follows:
Current Block
When the workflow encounters this Break task, processing either
continues or breaks from the current block.
Selected Block
When the workflow encounters this Break task, processing either
continues or breaks at the block selected from the drop-down list.
The tasks available in the Selected Block drop-down are above the
current task.

DataConnect
The third section of the Break task properties form is labeled Data-
Connect. The purpose of the DataConnect section is to specify what
happens to the temporary data.
The platform ignores properties in the DataConnect section when the
Break task is not used in conjunction with a DataConnect task or when
temporary data is not enabled (Use Temporary Data not checked) for
the DataConnect task.
The values for DataConnect are as follows:

© Copyright IBM Corporation 2011. Workflow Tasks | 537

 Discard Temporary Data
When the workflow encounters this Break task,
None = do not discard temporary data
Current = discard the temporary data in the current iteration
All = discard all temporary data.
Fail Staging Rows
This property is visible only when Discard Temporary Data is Cur-
rent or All. Select the Fail Staging Rows check box to fail the Data-
Connect row that the DataConnect task was processing.
When the Fail Staging Rows check box is selected, the system dis-
plays Current and All properties for the Fail Staging Rows property.
These properties are read-only and mirror the properties in Dis-
card Temporary Data.
If the workflow has multiple DataConnect tasks, one within another,
and the Break scope of an inner DataConnect task points to an outer
DataConnect task, if Discard Temporary Data is Current, the platform
discards the current iteration of the outer DataConnect task (and
therefore also discards all the inner DataConnect task iterations).

The shape and color of the Break task changes depending on how it is
configured. If there is a red dot inside the Break task, it means the
Task Status will be Error if the condition is met. No dot inside the
Break task means the Task Status will be Success if the condition is
met.
A Break task with a round interior and green color indicates a regular
Break or Continue. If the interior is square and the task shape is gold
color, the condition is swapped.
The chart below shows the different shapes for the Break task:
Shape Description

Break

Figure 7-85. Break Task Shapes

538 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Shape Description

Break with swapped conditions

Break with error status

Break with swapped conditions and error status

Continue

Continue with swapped conditions

Continue with error status

Continue with swapped conditions and error status

Figure 7-85. Break Task Shapes

The normal color for a Break task is green. If a Break task is green, it
is normal (not swapped) and will break (or continue at the top) when
the condition is true. Clicking the Swap action in the task’s proper-
ties form causes the Break task to turn gold. If the Break task is
already gold, clicking the Swap action causes it to turn green.

© Copyright IBM Corporation 2011. Workflow Tasks | 539

 Iterator Task
An Iterator task contains a sequence of tasks that may be performed
multiple times, once for each record associated with a specified work-
flow task. Iterators are used to loop through a finite set of records
and perform one or more tasks individually on the records that the
Iterator loops through. The palette shape for an Iterator task is shown
Figure 7-86. Iterator Shape in Figure 7-86. Figure 7-87 shows an example of a workflow that con-
tains an Iterator task.

Figure 7-87. Iterator Example

One thing to notice about the Iterator task as it appears in Figure 7-87
is that the end of the Iterator task is the Iterator palette shape upside
down.
Here is a summary of what the workflow in Figure 7-87 does:
• It retrieves work orders associated with a person.
• The Iterator task performs the workflow tasks inside of it, once
for each retrieved work order.

540 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 • Using a complex condition, the Switch task determines if each
work order is proceeding normally or is a problem.
The properties for an Iterator task specify which other task’s associ-
ated records will be used for looping. An Iterator task performs the
sequence of tasks it contains once for each record associated with the
specified task. Each time it performs the sequence of tasks, the Itera-
tor task becomes associated with a different one of the records that is
associated with the other task.
The form for an Iterator task is shown in Figure 7-88.

Figure 7-88. Iterator Properties

The properties form for an Iterator task is organized into two sec-
tions. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

Iterate Records
The second section of the Iterator task properties form is labeled
Iterate Records. The purpose of the Iterate Records section is to
specify the workflow task whose associated records will control the
looping of this task.
At the top of the Iterate Records section are fields used to identify
the record that will control this task’s looping.

© Copyright IBM Corporation 2011. Workflow Tasks | 541

 Here are descriptions of the fields:
Take the
This is a drop-down list. Though it is possible to select other val-
ues, the value of this field should be Business Object.
of Task
The value of this field is the label of the task that will control this
task’s looping.
At the bottom of the Iterate Records section is a read-only field
labeled Object Type. The platform sets the value of this field to the
type of record that is associated with the workflow task specified by
the of Task field.

542 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Call Workflow Task
The purpose of the Call Workflow task is to launch a synchronous or
subflow workflow. Synchronous workflows are described on page 207
under the heading “Synchronous vs. Asynchronous Workflows” and
subflow workflows are described in the Start task on page 396.
The initial project for a Call Workflow task is the project context at
the time the Call Workflow task was executed.
Figure 7-89. 
The shape for a Call Workflow task is shown in Figure 7-89. The form Call Workflow Shape
for a Call Workflow task is shown in Figure 7-90.

Figure 7-90. Call Workflow Properties

The properties form for a Call Workflow task is organized into two
sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.
Workflow
The value of this field is the name of the workflow that this task
will launch. This field’s value is chosen from its drop-down list.
The names in the drop-down list will be the names of synchro-
nous and subflow workflows that can be launched from the type
of record identified in this form’s Records section.

© Copyright IBM Corporation 2011. Workflow Tasks | 543

 The Workflow list in a Call Workflow task is limited to those work-
flows that have the same business object as set in the Records
section of the task. Module-level workflows for the module of the
object specified are also listed.
You may need to set the value of the fields in the Records sec-
tion before you can set this field to its proper value.
Clicking the View Workflow action causes the workflow identi-
fied in the Workflow drop down to appear in the workflow editor.
This is handy for making sure the workflow you have identified is
the one you want.
The Parameters action only appears if the workflow identified has
parameters or return values. Clicking the Parameters action
brings up the Workflow Parameters and Return Values screen.
There is more information about this screen in “Workflow Parame-
ters and Return Values” on page 547.

Records
The second section of the Call Workflow task properties form is
labeled Records. The purpose of the Records section is to specify the
record that will be used to launch the workflow.
At the top of the Records section are fields used to identify a target
record. The target record is used to determine the record that will be
used to launch the workflow.
There are radio buttons below the fields. The way that target records
are used to determine the record that will be used to launch the
workflow depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.

544 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the event is the target record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record that will be used to launch the
workflow.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record used to
launch the workflow.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target records will be the record used to launch
the workflow. When you select this radio button, a window pops
up that allows you to choose from the smart sections and locator
fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
be the record used to launch the workflow. When you select this
radio button, a window pops up that allows you to specify the

© Copyright IBM Corporation 2011. Workflow Tasks | 545

 type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the target
records’ parent will be the record used to launch the workflow.

546 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record that will be
used to launch the workflow.
If multiple records are identified by the information in the Records
section, a separate instance of the workflow will be launched for each
of the records. The initiating workflow will not continue to the next
task until the called workflow is complete for all records.

Workflow Parameters and Return Values

The Workflow Parameters and Return Values screen appears when-
ever you click the Parameters action. It shows the parameters and
return values from the workflow being called.
An example best explains how to use the Workflow Parameters and
Return Values screen. Figure 7-91 starts this example with a work-
flow containing variables to hold the input parameters and the return

© Copyright IBM Corporation 2011. Workflow Tasks | 547

 value for a call to a subflow workflow. The example could also be a
synchronous workflow, except the parameters could not be required.

Figure 7-91. Call Workflow Task Example

Of course to really be of value this workflow would contain some tasks

that would assign values to the variables we are using as the source
for our input parameters.
Click Parameters. The Parameters link in the Workflow Parameters
and Return Values screen appears. The first time you click the Param-
eters link the screen does not show any values.

Figure 7-92. Initial Workflow Parameters and Return Values Screen

548 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Click the Initialize action and the system fills in the initial values in
both the Parameters section and the Return Values section based on
the workflow being called.

Figure 7-93. After Initialize Action

The parameter and return value names from the subflow are filled in.
One of the parameters is required and therefore does not have a
check box to allow selecting it to be deleted.
The variables to use within this workflow have not been assigned yet.
Assign them by clicking on the Name. The Workflow Parameter Defini-
tion screen appears.

Figure 7-94. Workflow Parameter Definition

The choices in the Variable drop down are the variables defined at
the top of the workflow. Click OK after selecting the Variable. The

© Copyright IBM Corporation 2011. Workflow Tasks | 549

 value displayed in the Required field reflects the value in the work-
flow being called.

Figure 7-95. Workflow Parameter Defined

Repeat the definition process for the other parameter and the return
value. Since the second parameter is optional it could be deleted
rather than assigning it a value. You can always choose to ignore any
returned values by deleting them. Any that are left in the Workflow
Parameters and Return Values screen must be valid, which means the
input parameters must be assigned to variables. Any left with <Not set>
in the Variable column will prevent the workflow from publishing.
In the following figure, the second (optional) input parameter has
been deleted and the return value assigned a variable.

Figure 7-96. Optional Parameter Deleted

550 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

If after deleting a parameter or return value you decide you want it
back, click Initialize and assign a variable to it.

Figure 7-97. All Parameters and Return Values Defined

If the calling workflow has invalid parameters or returns (either

required parameters missing or any that do not have a variable
assigned), it cannot be published. Attempting to do so produces an
error message.

Figure 7-98. Error Message When Calling Workflow Has Invalid Parameter

© Copyright IBM Corporation 2011. Workflow Tasks | 551

 If you were to try to publish the called workflow while there is a call-
ing workflow with invalid parameters or returns, the system displays a
warning. As this is a warning message, you can choose to publish it
and then go fix the calling workflow(s) later or can cancel and look at
the calling workflow(s) now. You can use the Callers link to view the
workflows that have problems. Clicking Callers brings up the Calling
Workflows Parameters Check screen. Click a hyperlinked Name to
open the workflow so the problem can be resolved.

Figure 7-99. Calling Workflows Parameters Check

Note the Calling Workflows Parameters Check identifies the work-

flows with errors by showing Invalid in red in the Parameters column.
Within a workflow, Call Workflow tasks that call a workflow with
parameters are checked to verify that the parameter and return value
mapping is valid. If the mapping is not valid the Call Workflow task is
outlined in red and the workflow will not publish. The following con-
ditions make the mapping invalid:

552 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 • A required subflow parameter is not assigned a value.
• A parameter is assigned and the parameter does not exist on the
called workflow (can happen due to modifications to the called
workflow after the mapping was defined).
• A parameter is assigned and the type is not compatible (can hap-
pen due to modifications to the called workflow after the map-
ping was defined).
• A variable is assigned from a return value that does not exist on
the called workflow (can happen due to modifications to the
called workflow after the mapping was defined).
When a workflow with parameters and/or return values is published,
the system checks calling workflows to verify that the parameter and
return value mappings are valid. Any workflows that have invalid
mappings an be viewed by using the Callers link.

© Copyright IBM Corporation 2011. Workflow Tasks | 553

 Custom Task
The purpose of the Custom task is to allow external code to be exe-
cuted within the context of a firing workflow. This is something that
no other platform-supplied workflow task can do. Among the possible
uses for this are complex computations, communication with other
applications, and interfacing with IBM TRIRIGA Connector for Business
Applications.
To understand and successfully use a Custom task, you must have a
thorough understanding of the IBM TRIRIGA Application Platform, the
fundamental concepts required to build applications on this platform,
and Java development.
Figure 7-100. 
Custom Task Shape The shape for a Custom task is shown in Figure 7-100. The form for a
Custom task is shown in Figure 7-101.

Figure 7-101. Custom Task Properties

The Custom task can work with any Java class that implements either
the com.tririga.pub.workflow.CustomTask interface shown in Figure 7-102 on
page 559 or the com.tririga.pub.workflow.CustomBusinessConnectTask inter-
face. The task creates an instance of the specified class using a zero
argument constructor. The task then calls the instance’s execute
method, passing it the IDs of the records in the result list of a speci-
fied task. The called Java code can then use the record IDs to inter-
act with the IBM TRIRIGA Application Platform using IBM TRIRIGA
Connector for Business Applications. IBM TRIRIGA Connector for Busi-
ness Applications is described in the IBM TRIRIGA Connector for Busi-
ness Applications 3 Technical Specifications.

554 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Each time the Custom task is performed, it determines which inter-
face is being used, creates a new instance of the specified Java class,
and calls its execute method.
The custom Java class must be specified in the Class Name field of
the Custom Task object in the workflow. In order for the execution to
occur properly, the specified class must be in the application class-
path. For example, if you were using JBoss as your application server
and you had a Custom task with the Class Name of com.company.myFirst-
CustomTask, you would place the compiled com.company.myFirstCustomTask.
class file into the jboss/server/all/lib directory.

Custom Task Properties Form

The properties form for a Custom task is organized into two sections.
Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.
Class Name
This is the name of a Java class that implements the interface.
Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities.

© Copyright IBM Corporation 2011. Workflow Tasks | 555

 Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

Records
The second section of the Custom task properties form is labeled
Records. The purpose of the Records section is to specify the
record(s) whose ID will be passed to the Java method.
At the top of the Records section are fields used to identify a target
record. The target record is used to determine the record(s) whose ID
will be passed to the Java method.
There are radio buttons below the fields. The way that target records
are used to determine the record(s) whose ID will be passed to the
Java method depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, the record associated with the task
specified by the field to the right of this one will be the tar-
get record.

556 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 • Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, the record at the other end of the
association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART, or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record(s) whose ID will be passed to the
Java method depends.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the ID of the target record(s) will be passed to
the Java method.
Use its Reference
If this is selected, the ID of record(s) referenced by a smart sec-
tion or locator field of the target records will be passed to the
Java method. When you select this radio button, a window pops
up that allows you to choose from the smart sections and locator
fields in the target record.

© Copyright IBM Corporation 2011. Workflow Tasks | 557

 After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, the ID of record(s) associated with the target
record will be passed to the Java method. When you select this
radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, click the icon. A list of modules will pop up. Click
the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, the record on
the other end of the association must have been created from the
named business object. If -Any- appears in the drop-down list, then
the record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that

558 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the ID of
the target records’ parent will be passed to the Java method.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record whose ID will
be passed to the Java method.

CustomTask Interface
The Java class is com.tririga.pub.workflow.CustomTask shown in Figure 7-102.
package com.tririga.pub.workflow;

/**
* This interface must be implemented by any class specified in
* the "Class Name" field of a Custom Workflow Task.
* The implementing class must have a zero argument constructor.
* The workflow runtime engine will get the Class and call the
* zero argument constructor through reflection.
* It will then call the execute method and set the success
* attribute of the task based on the value returned.
*/
public interface CustomTask {
/**
* This method is called by a custom workflow task.
*
* @param recordIds
* An array of record IDs specified by the Record
* section of the task’s properties.
* @return true if successful, false if not
*/
public boolean execute(long[] recordIds);
}
Figure 7-102. Java Interface for Custom Task

© Copyright IBM Corporation 2011. Workflow Tasks | 559

 CustomBusinessConnectTask Interface
The Java interface class CustomBusinessConnectTask contains one method
called execute whose parameters are a preauthenticated TririgaWS
Interface object, the userId of the person who triggered the work-
flow, and the array of Record objects.
public interface CustomBusinessConnectTask {
public boolean execute(TririgaWS twsClient, long userId, Record [] records);
}

When implementing this class, the first thing that needs to be done in
order to allow the twsClient to work properly is to call the register
method. This will verify the context of the client in relation to the
workflow that triggered it. The register method takes the userId as an
argument. An example is provided below:
public boolean execute(TririgaWS tws, long userId, Record [] records) {
try {
//you must validate that the tws object has been preauthenticated
//and that an existing active session user is being utilized
tws.register(userId);
//...
} catch(Exception e) {
e.printStackTrace();
return false;
}
}

560 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

DataConnect Task
The purpose of the DataConnect task is to invoke IBM TRIRIGA Data-
Connect for moving data from IBM TRIRIGA staging tables into IBM
TRIRIGA native business object records. The properties of this task
determine which record type is processed. Please see the “DataCon-
nect” chapter of Application Building for the IBM TRIRIGA Application
Platform 3: Data Management for more information about DataCon-
nect.
Figure 7-103. 
The palette shape for a DataConnect task is shown in Figure 7-103. DataConnect Shape
The DataConnect task is in the task palette only if the workflow is
asynchronous and has the Integration property checked. Asynchro-
nous workflows are described on page 207 under the heading “Syn-
chronous vs. Asynchronous Workflows”. Integration is described on
page 399 under the heading “Integration”.
Figure 7-104 shows an example of a workflow that contains DataCon-
nect tasks.
One thing to notice about each DataConnect task as it appears in
Figure 7-104 is that there is more of it than just its palette shape. The
bottom of the DataConnect task reflects the iterative nature of a
DataConnect task.
The purpose of the sample workflow shown in Figure 7-104 is to
import a purchase order body and its purchase order line items. The
workflow begins by using the first DataConnect task to import the pur-
chase order body. The second DataConnect task imports the line items
for each purchase order body. Within the second DataConnect task
are tasks performing business logic on each purchase order line item.
The DataConnect task acts in two parts:
• Retrieves records to work on from the appropriate staging table.
• As an iterator, creates a new record or updates an existing record
for each row and runs the body of the DataConnect task for each
row. Other task steps can be positioned within the body of the
DataConnect task.

© Copyright IBM Corporation 2011. Workflow Tasks | 561

 Figure 7-104. DataConnect Example

562 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

The form for a DataConnect task is shown in Figure 7-105.

Figure 7-105. DataConnect Task Properties

The properties form for a DataConnect task is organized into three

sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.
Module
The value of this property is the module containing the business
object DataConnect is to process.
Set the value of this property by clicking the icon. Clicking the
icon causes a list of modules to pop up. Click the module name
you want to be the value of this property.
Object
The value of this property is the business object DataConnect is to
process. Select the appropriate business object from the drop-
down list.
This indicates the staging table to pull from and what IBM TRIRIGA
business objects will be created or updated by the integration
process.

© Copyright IBM Corporation 2011. Workflow Tasks | 563

 Initial State
For the value of this field select the state in which the record for
the business object should be created by DataConnect. The drop-
down list displays the valid states for the business object config-
ured in Object.
Keep in mind the record created or updated will not be transi-
tioned to the state, it will be put into that state. If you want the
record to be transitioned, use null in the Initial State and use a
Trigger Action task within the DataConnect task body to transi-
tion the record to the desired state. On update, the Initial State
property is ignored.
Use Temporary Data
This property determines whether the DataConnect task uses per-
manent or temporary data. When the DataConnect task applies
the incoming data, if the Use Temporary Data check box is
selected, the platform inserts or applies updates to temporary
data rather than to the permanent record. In this scenario, within
a DataConnect task, referring to the DataConnect task allows
access to permanent values and referring to a Get Temp Record
task allows access to the incoming values. This enables data vali-
dation and cleansing of incoming values within the workflow and
even data mapping on update if fields are blank in the staging
tables.
If you leave a DataConnect task that is processing temporary data
either through a Break task or by running out of iterations, and
have not used a Save Permanent Record task, the temporary data
is no longer available to the workflow. A Save Permanent task
must be executed prior to leaving the DataConnect task to ensure
the data is made permanent.
Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed
Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation

564 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

 Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

Correlation Section
The second section of the DataConnect task properties form is labeled
Correlation. The purpose of the Correlation section is to specify
where the task should get the correlation number. The correlation
number is a secondary key to help with sequencing or to signify child
records for a specific parent. The choices for Correlation are as fol-
lows:
• In-Sequence
Indicates that the correlation on the staging entry should be used
in ordering the rows to process and will be used in the Order By in
conjunction with the Sequence Number. This is the default and
the most common scenario unless you have DataConnect tasks one
within another.
• Task Step

© Copyright IBM Corporation 2011. Workflow Tasks | 565

 Indicates that the correlation should come from an enclosing
DataConnect task and should be used in the Where clause to
determine what entries to process (Job Number + Correlation
Number, ordered by Sequence Number). Using this allows the
DataConnect task to get the correlation number from one of the
enclosing DataConnect task’s data. For example, if you are work-
ing on the fourth POBody in the job, you only want the POLines
that go with that POBody. The Correlation setting along with the
staging table data allow this type of relationship. The drop-down
list contains the DataConnect task steps this step is contained
within, if any. Only DataConnect task steps are valid for this ref-
erence. Select the task step from those listed in the drop-down
list.

Transaction Section
The third section of the DataConnect task properties form is labeled
Transaction. The purpose of the Transaction section is to specify the
scope of the transaction being processed. The Transaction setting only
applies to the outermost DataConnect task. If a DataConnect task is
nested within another DataConnect task, the first, outer task speci-
fies the Transaction value. The choices for Transaction are as follows:
• None
Indicates that the record created or updated is committed before
the DataConnect task processes the tasks inside the body of the
DataConnect task, right after the record is created. No transac-
tions are created; the processing of the block follows standard
workflow rules.
• Per X Iterations
A new context is created for each X iterations and committed
when that number of iterations is complete. The default value is
1, which means the records are committed after each iteration.
• All Iterations
A new context is created before the task starts any processing and
is committed when all iterations have been completed.

The body of a DataConnect task should not contain User Action or

Approval tasks. The User Action task and Approval task require user
intervention. DataConnect tasks are intended to be run on non-peak
hours to avoid impacting system performance and it is unlikely the

566 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

required user would be present to respond to a User Action or
Approval task.

© Copyright IBM Corporation 2011. Workflow Tasks | 567

 Variable Definition Task
The purpose of the Variable Definition task is to define a variable for
use in a workflow. Workflow variables can represent a task step
instance within a workflow. This includes step values (e.g., sum,
count, success), the result record, and the result list.
Figure 7-106. 
Variable Definition Shape The shape for a Variable Definition task is shown in Figure 7-106. The
form for a Variable Definition task is shown in Figure 7-107.

Figure 7-107. Variable Definition Task Properties

The properties form for a Variable Definition task is organized into

two sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task as well as the name of
the variable. The label must be unique within the workflow. This
field’s text appears on the shape in the drawing that represents
this workflow task. Use the standards in “Workflow Naming Stan-
dards” on page 388.
Description
A description of this task goes in this field.
Module
The value of this property is the Module with which this variable is
associated. Set the value of this property by clicking the icon.
Clicking the icon causes a list of Modules to pop up. Click the
Module name you want to be the value of this property.
Object
Set the value of this property to the Business Object within the
Module with which this variable is associated. Select the appropri-
ate Business Object from the drop-down list. The Business Objects
in the list are those defined for the module.

568 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Value
The second section of the Variable Definition task properties form is
labeled Value. The purpose of the Value section is to specify the
source of the initial value for this variable. The possible values are:
Clear
The initial value of the variable is empty.
Set From
When you select the Set From radio button, the system presents a
drop-down list containing the compatible preceding task steps
whose result type (Module and Business Object) match that of the
variable. Choose a task step from those presented.

© Copyright IBM Corporation 2011. Workflow Tasks | 569

 Variable Assignment Task
The purpose of the Variable Assignment task is to assign a value to a
variable within a workflow. Workflow variables can represent a task
step instance within a workflow. This includes step values (e.g., sum,
count, success), the result record, and the result list.
Figure 7-108.  The shape for a Variable Assignment task is shown in Figure 7-108.
Variable Assignment Shape The form for a Variable Assignment task is shown in Figure 7-109.

Figure 7-109. Variable Assignment Task Properties

The properties form for a Variable Assignment task is organized into

three sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

Assign Variable
The second section of the Variable Assignment task properties form is
labeled Assign Value. The purpose of the Assign Value section is to
identify the variable being assigned a value in this task.
Variable
The value of this property is the variable being assigned a value.
Select from the drop-down list. The variables listed are those
defined above this task in the workflow.

570 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.

Object Type
After you select the Variable, the system displays the Variable’s
business object.

Value
The third section of the Variable Assignment task properties form is
labeled Value. The purpose of the Value section is to specify the
value for this variable. The possible values are:
Clear
The value assigned to the variable is empty.
From Task
When you select the From Task radio button, the system presents
a drop-down list containing the compatible preceding task steps
whose result type (module and business object) match that of the
variable. Choose a task step from those presented.
The Append Results option allows building up a result from multi-
ple source tasks. Selecting the Append Results option adds the
result (record list) from the source task to any existing values in
the variable rather than replacing them.

© Copyright IBM Corporation 2011. Workflow Tasks | 571

572 | Chapter 7: Creating Workflows © Copyright IBM Corporation 2011.
Chapter 1
In this chapter: CHAPTER 8
• The difference between
temporary and permanent
data. Temporary Data

Most of the data stored by the IBM TRIRIGA Application Platform is

permanent data. Permanent data is the data stored in the fields of
records that persists in the database until something happens to
explicitly change the permanent data or delete the record that con-
tains it.
While someone is editing a record with a form, the system keeps a
temporary version of the record’s data. Whenever a user switches
tabs or does something that can cause a workflow to run, the system
updates the temporary version of the record’s data.
When someone saves the data they are editing with a form, what hap-
pens behind the scenes is that the system copies the record’s tempo-
rary data and replaces the record’s permanent data. If the user closes
the form without saving, the system discards the temporary data.
The concept of temporary data is important for writing workflows
that enrich the quality of interaction between the IBM TRIRIGA Appli-
cation Platform’s forms and users. Some of the useful things a work-
flow can do with temporary data to enrich the interaction between
forms and people are:
• Perform calculations on temporary data and put the results in a
form field, so that you have computed values that appear in the
form but are not part of the underlying permanent data.
• Based on values in the temporary data, change the colors, fonts,
or other metadata used in fields to give people feedback about
missing, wrong, or questionable values.
• Validate combinations of values in the temporary data, setting the
contents of a form field to contain an explanation of any prob-
lems.

© Copyright IBM Corporation 2011. 573

 • Save the temporary data as permanent data.
• Allow people to explore what-if scenarios by performing calcula-
tions on temporary data, restoring the temporary data to a
record’s permanently stored values if a what-if is rejected, and
then finally saving the temporary values as permanent when they
are accepted.

Accessing Temporary Data

To process temporary data, you need a workflow (described in Chap-
ter 7) that will do the actual processing and also a sub action
(described on page 197) or form component (described on page 223
under the heading “Structure of Forms”) that can be used to launch
the workflow.
Workflows launched this way must be synchronous. Synchronous work-
flows are discussed on page 207.
In order for a workflow to be able to access temporary data, some of
its properties must be specified to have certain values. The proper-
ties of a workflow are discussed on page 394 under the heading “Start
Task”.
To be able to access temporary data, a workflow must have the value
of its Concurrence property specified to be Synchronous and the value
of its Temporary Data property to be Temporary.
If a workflow has its properties set this way, then the workflow tasks
that are used to get and save temporary data are included in the
workflow editor’s task palette. The names of these workflow tasks are
Get Temp Record Task and Save Permanent Record Task. These
workflow tasks are described in the following parts of this chapter.
Asynchronous workflows processing data from staging tables with
DataConnect task(s) are exceptions to the above. Get Temp Record
tasks and Save Permanent Record tasks can occur within a DataCon-
nect task. Read more about DataConnect tasks in “DataConnect Task”
on page 561.

574 | Chapter 8: Temporary Data © Copyright IBM Corporation 2011.

Get Temp Record Task
The purpose of the Get Temp Record task is to access the temporary
data associated with a record. Temporary data is data that the user
has created or modified that has not yet been permanently saved.
This kind of task is in the workflow editor’s task palette only if the
workflow is synchronous and allowed to access temporary data or if
within a DataConnect task.
After a Get Temp Record task has successfully completed, its result
list contains a record that contains the temporary data associated
with the record that was used to launch the current workflow.* In the
case of a Get Temp Record task used within a DataConnect task, the
result list contains a record created or updated by the staging table
input.
Use a Modify Records task (described on page 432) to change the val-
ues in the temporary data. Then use a Save Permanent Record
(described on page 578) task to update the record’s permanent data
from the temporary data.
Figure 8-1. 
The shape for a Get Temp Record task is shown in Figure 8-1. The Get Temp Record Shape
form for a Get Temp Record task is shown in Figure 8-2.

Figure 8-2. Get Temp Record Properties

* If a workflow is defined as temporary and is called through a callable workflow task from
an asynchronous workflow, there is no user interacting with the data and therefore there
is no temporary data. In this case, all of the tasks defined to do work on the temporary
data will do that same work on the permanent data.

© Copyright IBM Corporation 2011. Get Temp Record Task | 575

 The properties form for a Get Temp Record task is organized into two
sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

Records
The second section of the Get Temp Record task properties form is
labeled Records. The purpose of the Records section is to specify the
record whose temporary data is to be fetched.
At the top of the Records section are fields used to identify a target
record. For the Get Temp Record task, the target record is the record
whose temporary data is to be fetched.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record. Although the other two options below are
available in the list, this is the option you want to select.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the event is the target record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.

576 | Chapter 8: Temporary Data © Copyright IBM Corporation 2011.

of Task
The value of this field is the label of the task that the target
record will be associated with. Although this looks similar to the
like-named field used for the properties of other kinds of tasks,
the value of this field is always forced to be the Start task, unless
the Get Temp Record task is within a DataConnect task.
When a Get Temp Record task is within a DataConnect task, the
values in the of Task drop-down are the DataConnect tasks above
it in the workflow.

© Copyright IBM Corporation 2011. Get Temp Record Task | 577

 Save Permanent Record Task
The purpose of the Save Permanent Record task is to update a
record’s permanent data with temporary data that was previously
fetched by a Get Temp Record task. The Save Permanent Record task
is an all or nothing task; it saves everything that is in temporary data.
Temporary data is described in Chapter 8. The Get Temp Record task
is described on page 575.
This kind of task is in the workflow editor’s task palette only if the
workflow is synchronous and allowed to access temporary data or if
within a DataConnect task.
Figure 8-3. 
Save Permanent Record Shape The shape for a Save Permanent Record task is shown in Figure 8-3.
The form for a Save Permanent Record task is shown in Figure 8-4.

Figure 8-4. Save Permanent Record Properties

The properties form for a Save Permanent Record task is organized

into two sections. Here are descriptions of the fields in the first sec-
tion:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.
Formulas
Defines the formula recalculation behavior on this task when the
record is saved. The default is Disable Auto Recalculation. To change
the value, click the recalculate formulas icon .
The three possible values are as follows:
• Recalculate as Needed

578 | Chapter 8: Temporary Data © Copyright IBM Corporation 2011.

 Recalculates most formulas only if any input value of the for-
mula changed during the task’s activities. Extended formulas
that contain query and/or association tokens are recalculated
on every save.
• Disable Auto Recalculation
Extended formulas that contain query and/or association
tokens are not recalculated. All other formulas are recalcu-
lated only if any input value of the formula changed during
the task’s activities.
Extended formulas that contain query and/or association
tokens can take longer to calculate, so this option is an avail-
able performance optimization for isolated use cases.
An example of an appropriate use of Disable Auto Recalculation is
within a DataConnect task that is importing a large number of
space records. You may wish to delay any floor/space rollup
recalculations until after all the space records have been
imported.
• Recalculate All
Forces every formula to be recalculated during the record’s
save.
Selecting Recalculate All may slow performance.
An example of an appropriate use of Recalculate All is in a data
cleansing workflow that refreshes formula values in the data-
base that are stale for whatever reason. For example, if the
definition of a formula changes for a business object, existing
records may contain incorrect values as a result of the
change. You may wish to use Recalculate All in a maintenance
workflow that runs through the records and updates their for-
mula values.

Records
The second section of the Save Permanent Record task properties
form is labeled Records. The purpose of the Records section is to
specify the record that contains the temporary data.
There is no need to separately identify the related record that con-
tains the permanent data. The connection between the record that
contains the permanent data and the record that contains the tempo-
rary data is established by the Get Temp Record task when it gets the
record that contains the temporary data.

© Copyright IBM Corporation 2011. Save Permanent Record Task | 579

 At the top of the Records section are fields used to identify a target
record. For the Save Permanent Record task, the target record is the
record that contains temporary data.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, the record associated with the task
specified by the field to the right of this one will be the tar-
get record. Although the other two options below are avail-
able in the list, this is the option you want to select.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, the record at the other end of the
association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, the Event
record that triggered the event is the target record.
• Assignee
If Assignee is selected, the My Profile record of the user assigned
to the task specified by the field to the right of this one will
be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with. Although this looks similar to the
like-named field used for the properties of other kinds of tasks,
the value of this field is always forced to be a Get Temp Record
task.

580 | Chapter 8: Temporary Data © Copyright IBM Corporation 2011.

Chapter 1
In this chapter: CHAPTER 9
• How to organize records
into hierarchies.
Hierarchies

The IBM TRIRIGA Application Platform allows almost any data organi-
zation to be constructed using records and associations as building
blocks. The platform provides special support for constructing hierar-
chies.
This chapter describes the special support for hierarchies built into
the IBM TRIRIGA Application Platform. It begins with an explanation of
what a hierarchy is and describes some hierarchies built into the plat-
form. Then it describes how to build your own hierarchies. The chap-
ter finishes by describing special features of the IBM TRIRIGA
Application Platform that are built on top of hierarchies.

Hierarchy Modules
A hierarchy is an organization of records connected to each other in a
special way. One record is chosen to be the root of the hierarchy.
Other records are connected directly to the root. Other records may
be connected to those. Figure 9-1 on page 582 is an example of a
hierarchy organization.
There are a few points about the hierarchy shown in Figure 9-1 that
are important to notice.
• The hierarchy contains more than one kind of record, but they all
must be from the same module. This is common. However, it is
not necessary for a hierarchy to contain more than one kind of
record.
• A record can appear in only one place in a hierarchy. The same
record cannot appear in more than one place in a hierarchy.

© Copyright IBM Corporation 2011. 581

 World
Geography

Canada Georgia U.S.A. ...

Country Country Country Country

Ajaria
Alberta Georgia
Autonomous
Province State`
Republic

Abkhazia
British Columbia
Autonomous
Province Atlanta
Republic
City

South Ossettia
Autonomous
Vancouver Macon
Republic
City City

T'Blisi
Victoria City ...
City City

...
... City Nevada
City State

... ...
Province State

Figure 9-1. Geography Hierarchy Organization

582 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

 • Except for the record at the root of a hierarchy, every record in a
hierarchy has exactly one parent. The record at the root of the
hierarchy has no parent.
• A record in a hierarchy can have any number of children.
• It may be possible for two records in the hierarchy to have the
same name, but records with the same parent cannot have the
same name. The hierarchy in Figure 9-1 has a country named
Georgia and a state named Georgia. They are represented in the
hierarchy by two different kinds of records with two different par-
ents that have the same name.
The diagram in Figure 9-1 is just for the purpose of explaining what a
hierarchy is. The IBM TRIRIGA Application Platform does not display a
hierarchy that way. Figure 9-2 shows how the platform displays a hier-
archy.

Figure 9-2. Geography as Displayed

To improve the performance in hierarchy trees with a large number of

children, only the first 1000 children display along with an informa-
tional message “1000 results displayed. Use Manager Queries to view
more.” Child records to the nodes that are not displayed in the hier-

© Copyright IBM Corporation 2011. Hierarchy Modules | 583

 archy tree can be added by opening the record from the Master/Detail
Query and using the Includes tab. The Includes tab displays the tree
from the record being shown.

Examples of Hierarchies
The hierarchy shown in Figure 9-2 on page 583 is an example of a
hierarchy that is built into the IBM TRIRIGA Application Platform. Four
hierarchies are built into the platform that are used to support spe-
cific data types of fields:
• Geography
• Location
• Organization
• Classification
The hierarchy shown in Figure 9-2 on page 583 is part of the Geography
hierarchy. The Location hierarchy is used to describe such things as the
location of a building or a particular room in a building. The
Organization hierarchy is used to describe organizations and sub-organi-
zations.
A business object field can refer directly to a Geography, Location or
Organization record. Even though they do not appear in the Data Mod-
eler, the IBM TRIRIGA Application Platform supplies one of each of
these in the layout for every business object as a non-display field.
You can use the connection records may have to a Geography, Location,
Organization, Classification or other hierarchical record to manage or orga-
nize records. This is discussed in greater detail in the IBM TRIRIGA
Application Platform 3 User Experience User Guide.
The Geography and Organization hierarchies also can be used with the IBM
TRIRIGA Application Platform’s security features to control access to
specific records. These security features are discussed in Chapter 13.
The Classification data type is based on the classification hierarchy.

Creating Hierarchies
The following paragraphs describe the steps needed to create a new
hierarchy. Most of these steps also apply to the task of adding new
records to an existing hierarchy.
It is more common to add new kinds of records to the Classification hier-
archy than it is to create an entirely new hierarchy.

584 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

Hierarchies are built using business objects in a module that has its
Hierarchy Module check box checked. When you create or edit a
module’s properties, you use a panel that looks like Figure 9-3.

Figure 9-3. Data Modeler Panel with Hierarchy Module Checked

Checking the module’s Hierarchy Module check box means that

records created from the module’s business objects will be used in a
hierarchy. Checking the Hierarchy Module check box also causes the
Show Quantity check box to appear.
Leave the Show Quantity check box unchecked. You may see it
checked in some IBM TRIRIGA-provided modules.
After you have finished editing a module’s properties, you are ready
to start defining business objects in the newly defined hierarchy mod-
ule. Like any other module, the first business object you must define
in a hierarchy module is the base business object that has the same
name as the module. A record created from the module’s base busi-
ness object will serve as the root of the hierarchy.
All business objects you will use to create records in a hierarchy
should be defined as Stand Alone (described on page 28).
As you specify fields that will be in the records of a hierarchy, pay
extra attention to the fields or combination of fields that will be used
as the record’s name. In addition to the requirement that each exist-
ing record created from the same business object has a different
name, you also should be sure that the names will be suitable as
labels in the hierarchy.

© Copyright IBM Corporation 2011. Examples of Hierarchies | 585

 Is Parent Of
Is Parent Of
In addition to other steps you perform when defining new business
Revises a objects, there is an additional step to perform if a business object
Business Object will be used to create records for a hierarchy.
The IBM
platform
TRIRIGA treats
Application
associa- For each kind of record that can appear in a hierarchy, the platform
Platform
tions named treats an associa-
Is Parent Of spe-
restricts what kinds of records may appear under it in the hierarchy.
tion named
cially. Associations
Is Parentwith Of
specially
other names in can
a number
be defined of
The way this is controlled is through the business objects used to cre-
ways. published
for Associationsbusinesswith ated the records. The kinds of child records that a record in a hierar-
other names
objects can be defining
because defined chy can have is determined by associations defined for the business
for
them published
does not changebusiness
the object used to create the record. If an association named Is Parent Of is
objects because
business objects thatyou canthe defined from a business object, records created from the business
define an association
association references.with- object can be in the hierarchy as the parent of a record created from
out changing the business a business object on the other side of the association.
Because associations
objects that named
the association
Is Parent Of
references. are treated spe- On the parent side, the name of the association must be Is Parent Of.
cially, when you define one,
The association name Is Parent Of is treated specially. When you spec-
the platform
Because makes changes
associations named
to ify that the name on the near side an association will be Is Parent Of,
Is the
Parentbusiness
Of are object
treatedon
the Is Parent
specially, when Of side of the
you define the Data Modeler forces the name on the far side of the association to
association.
one the platform The changes
has to be Is Child Of. It also forces the module that contains the business
are needed
make to account
some changes for
to the object on the far side of the association to be the same as on the near
the additional
business object onstructure
the Is side.
that the
Parent newofassociation
Of side the associ-
imparts to a hierarchy.
ation. Due to the special significance of the Is Parent Of association, it is dis-
played specially in the Data Modeler’s Association List with cyan color
Rather than
Rather than preventing
preventing youyou coding as shown in Figure 9-4.
from defining
from defining anan association
association
named Is
named Is Parent
Parent Of Of on
on its
its
near
near side
side that
that also
also refers
refers to
to
a
a published
published business
business object
object
on
on its
its near
near side,
side, the
the plat-
plat-
form
form changes
changes thethe state
state ofof
the
the business
business object
object from
from
Published
Published to to Revision
Revision in in
Progress. After you define
an association named Is
Parent Of, the changes to the
hierarchy will not be visible
outside the Data Modeler
until you publish the busi-
ness object on the near side
of the association.

Figure 9-4. Is Parent Of Association

586 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

Is Parent Of associations are used to determine the structure of a
request central portal section. Request central portal sections are dis-
cussed in the IBM TRIRIGA Application Platform 3 Getting Started User
Guide.

Includes
The IBM TRIRIGA Application Platform is organized to provide a clear
separation between the design of a user interface and the internal
organization of records. In keeping with this principle, you need to
organize a hierarchy of forms to create a hierarchy of form records.
This hierarchy of forms does not need to precisely mirror the organi-
zation of the record hierarchy. If the same kind of record can appear
under two different kinds of parents, you can choose to use the same
or a different form in each context.
The way the Form Wizard organizes this hierarchy is that for each
form that can be used in a hierarchy, you specify what form to use for
each kind of child record. If you do not specify a form to create a par-
ticular kind of child record under a form, you will not be able to cre-
ate that kind of child from that form.
To specify what forms can be used to create child records from a par-
ent form, use the Form Wizard’s Includes/Forms tab, which is shown
in Figure 9-5.
For each business object that can be used to create a child of a
record this form is used to edit, you can add a form to the Includes
section of the Form Wizard’s Includes/Forms tab.
Each row of the Includes section specifies a form that is to be used
when creating a child record from a particular business object. You
can have one row in the Includes section for each business object
that may be used to create a child record under the type of record
that the form edits.
In addition to specifying the form that will be used to create child
records, the rows of the Includes section also specify the label that
will be used in a hierarchy tree to indicate the type of record that a
child is.
The other columns in the Includes section are intended to specify the
appearance of a child record’s label and icon image in a hierarchy
tree. At the time of this writing, these platform does not use the val-
ues specified in these columns.

© Copyright IBM Corporation 2011. Examples of Hierarchies | 587

 Figure 9-5. Form Wizard – Includes/Forms Tab

Biological Hierarchy
We will explain how to build a hierarchy by working through an exam-
ple. The example will be to create a hierarchy to model the scientific
classification of living things (biological taxonomy). The top three lev-
els of this hierarchy will be built using records created from business
objects named Kingdom, Phylum, and Class, respectively.
Begin by creating a hierarchy module named LivingThing. The proper-
ties for the LivingThing module look like Figure 9-6.

Figure 9-6. Living Things Module

588 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

In the module, create stand alone business objects named
LivingThing
LivingThing, Kingdom, Phylum,
and Class. Each of these business objects has
a Text field named Name. In each business object’s mapping informa-
tion, the Name field is identified as containing the name of records
created from the business object.
The permissible structure of the hierarchy is that Kingdom records can
be under a LivingThing record, Phylum records can be under a Kingdom
record, and Class records can be under a Phylum record. To specify this
structure, we specify the associations shown in Figure 9-7.

Figure 9-7. Associations Defining Structure of Living Thing Hierarchy

As you are creating these associations, the Association Properties

panel in the Data Modeler will look like Figure 9-8 on page 590.
The form for specifying an association’s properties treats an Is Parent Of
association specially. If you specify that the name on the near side of
the association is Is Parent Of, the module of the business object on the
other side of the association is forced to be the same as the module
on the near side of the association. Also, the name on the far side of
the association is forced to be Is Child Of.
After you save an Is Parent Of association, the Associate Business
Object form is replaced with an Includes in Hierarchy form that Figure 9-9. Include Properties
looks like Figure 9-9.
After you have finished creating the business objects and associa-
tions, the next step is to create the forms you will use to edit records
in the LivingThing hierarchy. Begin by creating a form to edit Class
records, which will be at the bottom of the hierarchy.

© Copyright IBM Corporation 2011. Examples of Hierarchies | 589

 Figure 9-8. Properties for Is Parent Of Association.

Phylum records will appear in the hierarchy as parents of Class records,

so the next form we create is a form to edit Phylum records. After we
have laid out the Phylum form in the Form Wizard’s Layout tab, the
next step is to specify what form will be used to create child records
for a Phylum record.
To specify that the Class form that is used to edit Class records will be
used to create and edit records under a Phylum record, navigate to the
Includes/Forms tab of the Form Wizard. Initially, the Includes sec-
tion of the Includes/Forms tab is empty and looks like Figure 9-10.

Figure 9-10. Empty Includes/Forms Tab

590 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

To add a form to the Includes section, click the Add action on the
Includes section bar. When you click the Add action, a panel pops up
that allows you to select existing forms that can edit records that are
allowed to appear in the hierarchy under the kind of record this form
edits. The panel looks like Figure 9-11.

Figure 9-11. Select Items for Includes

In order to create records for this hierarchy, you will need to create a
couple more items. First, you should create a manager query defini-
tion for a hierarchy using the Report Builder. Then you will need to
create a navigation item for a master/detail hierarchy.
To create the manager query, navigate to My Reports. Select the Sys-
tem Reports sub-tab. Click New to create a new System Report. Click
the Add Business Object link. Select the Living Thing Module, -All- Busi-
ness Objects, and -All- Forms. Click Ok. Fill the remaining fields as
shown in Figure 9-12.
Select the Columns tab. Add the Name (triNameTX) field to the Display
Columns. Select the Advanced tab. Click the Add action in the Associ-
ation Filters section. Set the Module to -Any-, Business Object to All,
Association Type to Is Parent Of, Reverse Association to No, and Filter
Type to Record. Then type $$RECORDID$$ in the Record/Query field, as
shown in Figure 9-13. Click OK. Click Save & Close to save the query.
The final step is to add a navigation item to your menu so that you
can create new records in your hierarchy. Before you do this, check
your menu by going to the People record > Profile tab, as shown in
Figure 9-14. This will be the menu, also known as a navigation item
collection, to modify. Note: Any change you make to this navigation
item collection will affect all other users who have the same naviga-
tion item collection set as their menu. Make sure you are working in
your own environment, or undo all changes at the end, or create a

© Copyright IBM Corporation 2011. Examples of Hierarchies | 591

 Figure 9-12. Create System Report

Figure 9-13. Create Association Filters

custom navigation item collection for this example. See the IBM
TRIRIGA Application Platform 3 User Experience User Guide for more
details about navigation collections.

592 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

Figure 9-14. Menu in People Record

Go to Tools > Navigation Builder. Select your menu and click Edit as
shown in Figure 9-15.

Figure 9-15. Navigation Item Collection

Now click Navigation Items Library on the bottom of the page. Click
Add to create a new navigation item. Set the Name to Hierarchy - Living
Things and Label to Living Things. Now set the Target Type to Master/Detail
Hierarchy. Make sure to check the Modify Hierarchy check box. Then set
the Hierarchy to Living Thing, the Query Module to Living Thing, and the
Report to the query you just defined, as shown in Figure 9-16. Click
Save & Close.

© Copyright IBM Corporation 2011. Examples of Hierarchies | 593

 Figure 9-16. Create Navigation Item

The last step is to add the navigation item to your menu. Select your
navigation item on the left panel and Landing Page - Portfolio on the right
panel. Click Add to collection. If you now expand Landing Page - Portfolio,
the new navigation item is there. Now click Save and Close, as shown
in Figure 9-17 (the left side of the Navigation Builder) and in
Figure 9-18 (the right side of the Navigation Builder), to save the
changes to your menu. To update your menu, either refresh the
browser, or sign out and sign back in.
Navigate to Portfolio > Living Things. As shown in Figure 9-19, the
Hierarchy is displayed in the left panel. It only contains the record
that is the root of the hierarchy. The right panel displays all the
records that the root Living Thing is a Parent of, currently none. Note

594 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

Figure 9-17. Left Side of Navigation Builder

that if you had not defined the query earlier and set it as the query
for the navigation item, the right panel would show “No queries
defined”; you would still be able to use the hierarchy to create and
open records, however.
The IBM TRIRIGA Application Platform automatically creates the root
record of a hierarchy. The way that root records are created is
unique. No pre-create workflow is run. Both the name and the state
of the record is initially null, yet the record is saved in the database.
If you wanted to edit the record that is the root of the hierarchy,
click the Open action. You should edit the root record of a new hier-
archy if only to just set its name.
To add additional records to the hierarchy, click the New action.
Clicking the New action causes a menu to appear that contains a list

© Copyright IBM Corporation 2011. Examples of Hierarchies | 595

 Figure 9-18. Right Side of Navigation Builder

Figure 9-19. Living Thing Hierarchy

596 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

of the different kinds of records that can be added to the hierarchy.
The menu looks like Figure 9-20.

Figure 9-20. Select Type of New Record for Living Thing Hierarchy

The kinds of records that appear in the menu are determined by the Is
Parent Of associations you created in the Data Modeler and the Includes
defined in the Form Builder. The LivingThings business object has an Is
Parent Of association with only the Kingdom business object, so Kingdom is
the only choice in the menu.
At this point, you can click Kingdom in the menu to create a new
Kingdom record under the root of the hierarchy. If you change your
mind about wanting to create a new Kingdom record under the hierar-
chy’s root, click the x at the top of the list to get rid of the list.
When you click Kingdom, a form appears in the details view for you to
enter in the values of the new Kingdom record. After you click the
form’s Create action, the new Kingdom record appears in the hierar-
chy. Repeat this four times, to create records for all five of the bio-
logical kingdoms. The hierarchy now looks like Figure 9-21.

Figure 9-21. Kingdoms Added

© Copyright IBM Corporation 2011. Examples of Hierarchies | 597

 You can add Phylum records under the Kingdom records in the hierarchy.
Names in To do this, first click the name of the Kingdom record you want the
Hierarchies Phylum record to appear under. This causes the Kingdom record to
become the selected record. If any record other than the root is
The IBM TRIRIGA Application
Platform requires every
selected, its name becomes red.
record created from the same When you click the New action in the Hierarchy panel, it means that
business object to have a dif-
you are trying to create a new record under the selected record.
ferent name. There is an addi-
tional naming constraint for If you make the mistake of putting a record under the wrong member
records in a hierarchy. of the hierarchy, it is easily to fix the mistake by following these
The children of a parent steps:
record in a hierarchy are
required to have different • Select the record you want to move to a different place in the
names, even if they were cre- hierarchy.
ated from different business
objects. This constraint
• Click the Cut action.
ensures that there is never • Select the member of the hierarchy that you want the record to
any confusion about which appear under. This has the effect of replacing the Cut action with
record is being referred to in a a Paste action.
hierarchy when it is identified
• Click the Paste action.
by its name and path.

Auto-Populate
In the Data Modeler, among the properties of each field in a business
object is a check box labeled Do not Auto Populate. If this check box
is checked, it disables a feature of the IBM TRIRIGA Application Plat-
form called auto-populate.
The auto-populate feature supplies initial values for fields in new
records that do not have a specified default value. The auto-populate
feature uses as a source of default values the triPeople or other kind of
record that describes the logged in person. If a field in a new record
has the same name as a field in record that describes the logged in
person, the value of the like-named field is copied to the field in the
new record.
If a new record is created as part of a hierarchy, its parent is used as
a second source of data for auto-populate. If the record that
describes the logged in person does not have a field with the same as
a field in a new record in a hierarchy but its parent has a field with
the same name as a field in the new record, the value is copied from
the field in the parent to the corresponding field in the new record.

598 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.

If you do not want the auto-populate feature to set the initial value of
a field, when you are defining the field be sure to check the Do not
Auto Populate check box.

Parent-Child Reports
The Report Manager does not allow you to explicitly define reports on
types of records that have a parent-child relationship in a hierarchy.
However, it does allow us to create such a report by treating the con-
nection between a parent and its children as an association named Is
Parent Of.

© Copyright IBM Corporation 2011. Parent-Child Reports | 599

600 | Chapter 9: Hierarchies © Copyright IBM Corporation 2011.
Chapter 1
In this chapter: CHAPTER 10
• How to make an application
do things based on dates
and the passage of time.
• How to use a calendar to
Calendar and Time
track things that have
happened and will happen Based Events
to records.

The IBM TRIRIGA Application Platform has the ability to do things

based solely on the passage of time. It is possible to schedule an
event to happen at any future point in time. When an event happens,
it can cause a workflow to be launched.
Because events and other things can happen to records at different
points in time, the IBM TRIRIGA Application Platform associates a cal-
endar with records to help keep track of what has happened or will
happen to a record and when.
The following paragraphs of this chapter explain how to do the follow-
ing things with calendars and events:
• Configure a record’s calendar.
• Schedule events into a calendar.
• Arrange for workflows to run at the beginning or end of an event.

Calendars
Although every record has a calendar associated with it, to see a
record’s calendar in the user interface, the business object it was cre-
ated from must be configured with its Has Calendar check box
checked. The properties of business objects, including the Has
Calendar check box, are discussed on page 26 under the heading “A
Business Object’s Basic Information”.
If the Has Calendar check box for a business object is checked and
the Show Calendar check box is checked for a form, the form will be
displayed with a tab named Calendar that otherwise would not
appear.

© Copyright IBM Corporation 2011. 601

 You should also build a tab named triCalendarDetails in your form. The
purpose of a Calendar Details tab is to specify details that are needed
to schedule events for the resource that a record represents. The
Calendar Details tab looks like Figure 10-1.

Figure 10-1. Calendar Details Tab

The system does not depend on this tab existing in your form to func-
tion properly. Instead there are two things you must add to your busi-
ness object in the Data Modeler. For the scheduling engine to work
properly you should add a field to your business object named triTime-
ZonesCL. You also should make an association to the triCalendar business
object in the triSetup module with the association name Has Calendar
and reverse string of Calendar For. This field and association are not
added automatically.
The Time Zone field (triTimeZonesCL) is used to specify the time zone
that is used to schedule the resource represented by the record.
Another field used if working in conjunction with the Reserve product
is the Reservable flag. If the Reservable (triReservableBL) check box is
checked it means that the resource can be reserved for an event. This

602 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
is normally checked for things like conference rooms and audio-visual
equipment, but not for people.
If you want the calendar to include events from an external Microsoft
Exchange server or a Lotus Notes server that the IBM TRIRIGA Applica-
tion Platform environment has been configured to work with, specify
the appropriate login information in the Mail Server Login field (triEx-
ternalLoginTX).

NOTE: If using Microsoft Exchange 2007, be sure to configure Plain text

logon (Basic authentication) in Microsoft Exchange > Server Configuration >
Client Access > IMAP4 Properties > Authentication tab.
The Availability Calendar section is used to specify when the
resource is available. This section can reference multiple Calendar
records. If there are multiple triCalendar records, the resource is avail-
able at any time that any of the calendars say it is available. The
Query section here is based on the association named Has Calendar.
The information about when a resource is available is in a separate
record because it is usually the case that availability of multiple
resources follows the same pattern. For example, if the resource is a
person, it will usually be the case that multiple people work the same
hours. Putting this common information in a shared place makes it
easier to maintain.

© Copyright IBM Corporation 2011. Calendars | 603

 Calendar records are located in Tools > System Setup > General > Cal-
endars. Figure 10-2 shows a triCalendar record.

Figure 10-2. Calendar Form

604 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
The Scheduling Assumptions section identifies the working hours per
day, working days per week, and working days per month for
resources using this calendar.
The Working Hours section is used to specify ranges of time that
resources are available during days of the week. When you select the
Quick Add action to add an entry to this section, an open line appears
at the top of the section; enter the new day, start time, and end
time. Click one of the triangle icons or the circle icon to sort
the information shown.
The Non-Working Events section is used to specify individual days on
which resources are not available. In the example shown, it is used to
indicate non-working holidays for people. When you select the Quick
Add action to add an entry to this section, an open line appears at the
top of the section; enter the date and the name of the new event.
Click one of the triangle icons or the circle icon to sort the
information shown.
A Calendar tab looks like Figure 10-3.

Figure 10-3. Calendar Tab

This tab is shown automatically in your form if the Show Calendar

option is selected. In addition to just showing dates, it shows sched-

© Copyright IBM Corporation 2011. Calendars | 605

 uled events and three numbers. There are no events in the calendar
in Figure 10-3. The three numbers are labeled P, S, and A. This is
what they mean:
P The planned number of hours of availability.
S The overall number of hours that at least one event is scheduled.
If events overlap in time, the overlapped period of time is
counted just once, no matter how many events are scheduled at
the same time.
A The remaining available time.
The three numbers have this relationship: A = P - S
The view of the calendar shown in Figure 10-3 is the Monthly view.
There are four buttons to the right of the year that allow you to
select the view that you want. The buttons are:
Y Press this for a year view.
Q Press this for a quarterly view.
M Press this for a monthly view.
W Press this for a weekly view.
Everything we have looked at doing with a calendar so far is done
manually by a person interacting with the user interface. However,
there is no entirely manual way to add events to a calendar. At least
one step involved in putting an event in a calendar must be done by a
workflow.

Events
Before we discuss the details of putting events in calendars, it is help-
ful to explain just what we mean by an event. When we are talking
about events that can appear in a calendar, we are talking about
scheduled events. A scheduled event begins at a particular time. It
has a duration. After a scheduled event begins and its duration has
passed, the scheduled event ends.
A Scheduled Event record is used to represent a scheduled event in the
IBM TRIRIGA Application Platform. To be useful, Scheduled Event records
should not be created directly. Instead, they should be created indi-
rectly by a SCHEDULE action performed on an Event record. The form
for editing Event records does not have an action in its menu bar for
performing a SCHEDULE action on an Event record.

606 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
At least three workflow tasks are needed for a workflow to create
Scheduled Event records. The first task is a Schedule task. A Schedule
task does not create Scheduled Event records. What it does is create an
Event record. The Event record describes one or more scheduled events.

After the Event record is created, one or more workflow tasks are
needed to set the fields in the Event record.
The last workflow task needed is a Trigger Action task to perform a
SCHEDULE action on the Event record. This causes the Scheduled Event
records to be created.
The Schedule workflow task is described on page 621 under the head-
ing “Schedule Workflow Task”.
The Event and Scheduled Events business objects are in the Mail module.
Setting the fields of the Event record is described on page 631 under
the heading “Event Records”.
Trigger Action workflow tasks are described on page 473.
What happens after a SCHEDULE action is performed on an Event record
is described on page 633 under the heading “Scheduled Events”.

Manual Event Scheduling

It is possible to manually enter the information needed to create
Scheduled Event records. This works by having people use the Event form
to create an Event record and then using an action on another form to
launch a workflow that performs a SCHEDULE action on the Event record.
Instead of designing applications to create Scheduled Event records this
way, use the Event form because it offers more options for the sched-
uling and recurrence of events. Some of the options may be inappro-
priate or confusing for some applications.
To avoid having to train people about event scheduling options they
do not need and to avoid people choosing event scheduling options
that are inappropriate for an application, provide an application-spe-
cific form.
If you do not want to read about manual entry of event scheduling
information, skip ahead to the section named “Schedule Workflow
Task” on page 621.
Here is an outline of the things involved in manually entering event
scheduling information:

© Copyright IBM Corporation 2011. Manual Event Scheduling | 607

 • At design time:
• Define an association between the Event business object and
the business object used to create the records for which you
want to create Scheduled Event records. Both sides of the associ-
ation should be named Scheduled.
• To the form used to edit the records that events should be
scheduled for, you must add a way to create and edit an asso-
ciated Event record. The simplest way to do this is to add a sin-
gle smart section to the business object that underlies the
form.
• You will need a way to perform a SCHEDULE action on the asso-
ciated Event record. The simplest way to do this is to write a
one task synchronous workflow that is launched from a form
and performs a SCHEDULE action on the associated Event record.
• At runtime:
• The person who wants to associate Scheduled Event records with
another record creates and edits the associated Event record,
specifying when the event should happen, the event’s dura-
tion, if the event should be repeated and when the event
should be repeated.
• When the scheduling information is correctly entered, the
person must click whatever has been provided to perform a
SCHEDULE action on the Event record. Performing the SCHEDULE
action on the Event record causes the Scheduled Event records to
be created and associated with the same record associated
with the Event record.
Having outlined these activities, we describe some of them in greater
detail.
Use the Association Manager to define the association named Scheduled
between the Event business object and the other business object. The
associations and the Association Manager are described on page 61
under the heading “Defining Associations”.
Smart sections are described on page 74.
If the Event record is accessed through a single-record smart section,
the simplest way to provide an action for performing a SCHEDULE action
on Event records is to add the action to the smart section in the form
that is used to access the single-record smart section.
It is easiest to first create the simple workflow that will perform a
SCHEDULE action on the associated Event record before adding an action

608 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
to a form to launch the workflow. In the Workflow Editor, the work-
flow will look like Figure 10-4. Like all workflows, this workflow has a
Start task and an End task which do not do anything. Between them is
a Trigger Action workflow task that triggers the SCHEDULE action.
The properties for the workflow’s Start task will look like Figure 10-5.
The most important thing to notice about the settings in Figure 10-5 is
that the Module and Object Type fields specify the business object
used to create records that contain the single-record smart section.
Figure 10-4. 
SCHEDULE Workflow

Figure 10-5. SCHEDULE Workflow Properties

The properties for the Trigger Action task labeled Trigger SCHEDULE are
shown in Figure 10-6. Notice the following things about the settings in
Figure 10-6:
• The action that the task will perform is specified in the Action field
as SCHEDULE. It will perform the SCHEDULE action on the Event record
referenced by the Event single-record smart section.

© Copyright IBM Corporation 2011. Manual Event Scheduling | 609

 • The Records section of the workflow task’s properties specifies
that to find the record to perform the action on, the task should
begin with the record associated with the Start task. This is the
record that contains the smart section. It is the target record for
the Records section.
The Records section also specifies that the action should be per-
formed on the record referenced by the target record’s Event record
section.

Figure 10-6. SCHEDULE Workflow Trigger Action Properties

After the workflow is created, the next thing to do is add an action to

the form’s smart section to launch the workflow. Adding an action to
a form’s smart section is discussed on page 349 under the heading
“Smart Section Actions”.
Having discussed these design-time activities, we are now ready to
discuss what a person will need to do at runtime to schedule an event
using the Event form.
The form for a new Event record initially looks like Figure 10-7 on page
611.
Begin filling out this form by supplying values for the fields in the
Event Info section.
The Subject field can be used to enter a brief comment about the
purpose of the event.
The Event Type field allows a person to select a value that work-
flows may use to distinguish between different kinds of events. This
field’s drop-down list may contain values that are appropriate for

610 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
Figure 10-7. Event Form, Event Tab

some applications but not others. The items in the drop-down list are
managed by the List Manager under the name Event Type.
A person should set the value of the Event Start Date field to the
time and date when the event will be scheduled to start. If the event
will be recurring, the date portion of this field will be used to deter-
mine the earliest start date, not the actual start date. The actual
date(s) when the event will occur will be determined by the recur-
rence information instead.
The default value for this field is the current time and date. For most
events, this is not a useful default.
The Event Duration field may be filled in with the duration of the
event.
After you have finished entering values into the fields of the Event
Info section, the next thing to do is select one of the Recurrence

© Copyright IBM Corporation 2011. Manual Event Scheduling | 611

 Pattern Type radio buttons. The portion of the form below the
Recurrence Type section will look different, depending on which one
of these radio buttons you select. The headings that follow corre-
spond to these radio buttons.
Something that appears on the bottom of this form, no matter which
radio button is selected, is the Shadowing Events section. The use of
this section is described on page 619 under the heading “Event Shad-
owing”.

Manually Scheduling a Single Occurrence

When its Single Occurrence radio button is selected, the Event form
looks like Figure 10-8 on page 612.

Figure 10-8. Event Form with Single Occurrence Radio Button Selected

612 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
Selecting the Single Occurrence radio button means that the event
will occur just at the one date and time specified by the Event Start
Date field.

Manually Scheduling a Daily Occurrence

When its DAILY radio button is selected, the Event form looks like
Figure 10-9 on page 613.

Figure 10-9. Event Form with DAILY Radio Button Selected

Selecting the DAILY radio button means that the event will recur with
a frequency measured in days. It will recur after the number of days
specified in the Recur Every ___ Day(s) field has elapsed. For exam-

© Copyright IBM Corporation 2011. Manual Event Scheduling | 613

 ple, if the value of the Recur Every ___ Day(s) field is 2 then the
event will recur every other day.
Use the Weekday and Weekend Day check boxes to define whether
the event will recur on just weekdays (i.e., Monday through Friday),
weekend days (i.e., Saturday and Sunday), or both.
The event will continue to recur until it has completed the number of
occurrences specified in the End After ___ Occurrences field. If no
value is specified in the End After ___ Occurrences field, the event
will continue recurring forever.
If an event recurs, a Scheduled Event record will be created for each
recurrence. However, these Scheduled Event records may not be gener-
ated all at the same time. Instead, just the next few Scheduled Event
records that are needed are generated. The exact number that will be
generated is determined by the value of the Generate __ Day(s) of
Events (rolling) field.
After the first of the scheduled events happens, another Scheduled Event
record is created. This keeps the number of pre-generated Scheduled
Event records at the number specified by the Generate __ Day(s) of
Events (rolling) field. Once the number of remaining scheduled
events for the recurrence specified falls below the Generate ___
Day(s) of Events (rolling) field value, the system stops generating
additional Scheduled Event records.
In the Exclude Dates section, specify ranges of dates. During these
ranges of dates, the event will not recur.

Manually Scheduling a Weekly Occurrence

When its WEEKLY radio button is selected, the Event form looks like
Figure 10-10 on page 615.
Selecting the WEEKLY radio button means that the event will recur
with a frequency measured in weeks. It will recur after the number of
weeks specified in the Recur Every ___ Week(s) On field has
elapsed. For example, if the value of the Recur Every ___ Week(s)
On field is 2 then the event will recur every other week.
On weeks when the event occurs, it will happen on the days of the
week that correspond to the checked check boxes in the Weekly
Recurrence section.
The event will continue to recur until it has completed the number of
occurrences specified in the End After ___ Occurrences field. If no

614 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
Figure 10-10. Event Form with WEEKLY Radio Button Selected

value is specified in the End After ___ Occurrences field, the event
will continue recurring forever.
If an event recurs, a Scheduled Event record will be created for each
recurrence. However, these Scheduled Event records may not be gener-
ated all at the same time. Instead, just the next few Scheduled Event
records that are needed are generated. The exact number that will be
generated is determined by the value of the Generate __ Week(s) of
Events (rolling) field.
After the first of the scheduled events happens, another Scheduled Event
record is created. This keeps the number of pre-generated Scheduled
Event records at the number specified by the Generate __ Week(s) of
Events (rolling) field. Once the number of remaining scheduled
events for the recurrence specified falls below the Generate ___

© Copyright IBM Corporation 2011. Manual Event Scheduling | 615

 Week(s) of Events (rolling) field value, the system stops generating
additional Scheduled Event records.
In the Exclude Dates section you can specify ranges of dates. During
these ranges of dates, the event will not recur.

Manually Scheduling a Monthly Occurrence

When its MONTHLY radio button is selected, the Event form looks like
Figure 10-11.

Figure 10-11. Event Form with MONTHLY Radio Button Selected

Selecting the MONTHLY radio button means that the event will recur
with a frequency measured in months. It will recur after the number
of months specified in the Recur Every ___ Month(s) On field has

616 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
elapsed. For example, if the value of the Recur Every ___ Month(s)
On field is 2 then the event will recur every other month.
The day of the month on which the event happens can be determined
by one of three methods. If it is desired to have the event occur on a
specific numbered day of the month, the Day of month (1-31) field
value can be set. For example, if the value of the Day of month (1-
31) field is 2, the event will happen on the second day of the month.
If the value in the Day of month (1-31) field is 29, 30, or 31 and a
recurrence falls in a month that does not have that many days, the
event happens on the last day of the month. So, if you want an event
to be repeated on the last day of every month, specify 31 for the
value of the Day of month (1-31) field.
Alternately, the day of the month on which the event happens can be
determined by setting the Week of month or Day of Week value. Set-
ting a value for Week of month instructs the system to have the
event happen on the week number selected. The Day of Week value
defines which day of the week the event happens for the week
selected in the Week of month field.
The event will continue to recur until the date specified in the End
After ___ Occurrences field. If there is no value specified in the End
After ___ Occurrences field, the event will continue recurring for-
ever.
If an event recurs, a Scheduled Event record will be created for each
recurrence. However, these Scheduled Event records may not be gener-
ated all at the same time. Instead, just the next few Scheduled Event
records that are needed are generated. The exact number that will be
generated is determined by the value of the Generate __ Month(s) of
Events (rolling) field.
After the first of the scheduled events happens, another Scheduled Event
record is created. This keeps the number of pre-generated Scheduled
Event records at the number specified by the Generate __ Month(s) of
Events (rolling) field. Once the number of remaining scheduled
events for the recurrence specified falls below the Generate ___
Month(s) of Events (rolling) field value, the system stops generating
additional Scheduled Event records.
Specify ranges of dates in the Exclude Dates section. During these
ranges of dates, the event will not recur.

© Copyright IBM Corporation 2011. Manual Event Scheduling | 617

 Manually Scheduling a Yearly Occurrence
When its YEARLY radio button is selected, the Event form looks like
Figure 10-12 on page 618.

Figure 10-12. Event Form with YEARLY Radio Button Selected

Selecting the YEARLY radio button means that the event will recur
every year. It will recur in the month specified by the Recur Every __
_ Year(s) On field on the day specified in the Day of Month (1-31)
field.
The event will continue to recur until it has completed the number of
occurrences specified in the End After ___ Occurrences field. If no
value is specified in the End After ___ Occurrences field, the event
will continue recurring forever.

618 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
If an event recurs, a Scheduled Event record will be created for each
recurrence. However, these Scheduled Event records may not be gener-
ated all at the same time. Instead, just the next few Scheduled Event
records that are needed are generated. The exact number that will be
generated is determined by the value of the Generate __ Year(s) of
Events (rolling) field.
After the first of the scheduled events happens, another Scheduled Event
record is created. This keeps the number of pre-generated Scheduled
Event records at the number specified by the Generate __ Year(s) of
Events (rolling) field. Once the number of remaining scheduled
events for the recurrence specified falls below the Generate ___
Year(s) of Events (rolling) field value, the system stops generating
additional Scheduled Event records.
In the Exclude Dates section you can specify ranges of dates. During
these ranges of dates, the event will not recur.

Manually Scheduling an Ad Hoc Occurrence

When its Ad Hoc radio button is selected, the Event form looks like
Figure 10-13.
Selecting the Ad Hoc radio button means that the event will recur but
with no particular pattern. In addition to the event happening on the
date specified by the Event Start Date field, it will also happen on
the dates you specify in the Also Schedule On section.

Event Shadowing
Sometimes you may have multiple events fall on the same day and
want just one of the events to happen, not all of them. For example,
there may be a weekly event for shampooing the carpet in a hallway.
There also may be an annual event to paint the hallway. You do not
want the rug shampooing to happen when it would coincide with the
painting. There is a feature called event shadowing that controls
things like this.
There are two steps to make one event shadow another. The first is to
put the event that has priority in the Shadowing Events section of the
other. In the above example, you would put the painting event in the
Shadowing Events section of the rug shampooing event. The other
step is to supply a value for the OffsetDate Duration (for Shadowing)
field.

© Copyright IBM Corporation 2011. Manual Event Scheduling | 619

 Figure 10-13. Event Form with Ad Hoc Radio Button Selected

An event is shadowed if another event referenced in its Shadowing

Events section occurs within the number of days specified by the
value of the OffsetDate Duration (for Shadowing) field. If you did not
want the rug shampooing to happen if it is scheduled within two days
of a painting event, then you would set the value of the rug shampoo-
ing event’s OffsetDate Duration (for Shadowing) field to 2.

620 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
Schedule Workflow Task
Instead of designing applications to create scheduled events manu-
ally, use the Event form, as described earlier in this chapter.
To use a workflow to automate the entire process of scheduling
events, write a workflow that uses the Schedule workflow task. The
Schedule task handles a number of details that would otherwise have
to be done by a few other tasks.
A Schedule workflow task creates an Event record and associates it
with the record on which events will be performed. A Schedule task
also creates a Recurrence record, sets the value of its fields, and associ-
ates the Recurrence record with the Event record.
A Schedule task does not schedule an event to happen. A Trigger
Action workflow task is needed to do that. The Trigger Action work-
flow task is discussed on page 473. Figure 10-14. Schedule Shape
The shape for a Schedule task is shown in Figure 10-14. The form for a
Schedule task is shown in Figure 10-15 on page 622.
The properties form for a Schedule task is organized into three sec-
tions. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this workflow task. The text in
this field is used as the label for the shape that represents this
kind of workflow task in drawings.
Description
A description of this workflow task goes in this field.

Records
The second section of the form for a Schedule task’s properties is
labeled Records. The purpose of this section is to specify which
record or records the event(s) will happen to.
The top of the Records section has two radio buttons to specify how
the Schedule task will find the record(s). These radio buttons are
labeled:
Workflow Activity
If this radio button is selected, the event(s) will happen to a
record or records associated directly or indirectly with a preced-
ing workflow task.

© Copyright IBM Corporation 2011. Schedule Workflow Task | 621

 Figure 10-15. Schedule Properties

Existing Record
If this radio button is selected, the event(s) will happen to a
record that exists at the time the workflow is being created.
The selection of one of these radio buttons determines what appears
in the Records section. Figure 10-15 shows what the Records section
looks like when the Workflow Activity radio button is selected.
After we finish describing the way that the Records section works
when the Workflow Activity radio button is selected, we describe (on

622 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
page 625) what happens when the Existing Record radio button is
selected.
The fields and radio buttons that appear in the Records section under
the Workflow Activity radio button are visible only if the Workflow
Activity radio button is selected. Under the Workflow Activity radio
button are two fields used to identify a target record(s). The target
record is used to determine the record(s) that events will happen to.
There are radio buttons below the two fields. The way that the tar-
get record(s) will be used to determine the record(s) that events will
happen to depends on which one of the radio buttons is selected.
Here are descriptions of the two fields:
Take the
This drop-down list can have one of three possible values:
• Record
If Record is selected, then the record associated with the task
specified by the field to the right of this one will be the tar-
get record. If multiple records are associated with the task,
there will be multiple target records.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right will be
the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under the two fields determine how the target
record(s) will be used to determine the record(s) that events will hap-
pen to.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:

© Copyright IBM Corporation 2011. Schedule Workflow Task | 623

 Use it
If this is selected, the target record will be the record that the
event(s) happen to.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target record will be the record(s) that the
event(s) happen to. When you select this radio button, a window
pops up that allows you to choose from the smart sections and
locator fields in the target record.
If the record referenced by the smart section or locator field is a
link, the record used for the action item will be the link, not the
underlying record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
be the records that the event(s) happen to. When you select this
radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Records section in the
Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.

624 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
 You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
This is similar to the Use its Association radio button.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the events
will happen to the parent of the target record.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this is the equivalent of selecting the mod-
ule’s base business object (the one with the same name as the
module).
At the bottom of the Records section is a read-only field labeled
Object Type. The value displayed in this field is the type of the
record that the event(s) will happen to. If the record can have been
created from any business object in a particular module, then the
name of the module appears in the Object Type field.
If you want event(s) to happen to record(s) that are part of the appli-
cation’s configuration, then you should select the option of using an
existing record in the Records section. When the Existing Record
radio button is selected, the Records section looks like the one in
Figure 10-16.

© Copyright IBM Corporation 2011. Schedule Workflow Task | 625

 Figure 10-16. Schedule Properties, Existing Record Selected

You use the Module and Object drop-downs to specify a kind of

record and then click the Record link to find the specific record that
the event(s) should happen to.

Recurrence
The third section of the form for a Schedule task’s properties is labeled
Recurrence. The purpose of this section is to specify how often and
how many times the event should be repeated, if at all.

626 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
The Recurrence section contains a group of radio buttons that allows
you to select how often the event will be repeated. Under these radio
buttons is a field that contains a date used to calculate when the
event will first happen. Under this field is another set of radio but-
tons used to select when the repetitions of the event will end.
Here are explanations of the radio buttons that control how often the
event will be repeated:
None
If this radio button is selected, the event will not be repeated.
Every _____ Days
If this radio button is selected, the event will happen after a
specified number of days have elapsed. The event will first hap-
pen on the date specified in the Start field. After that, the event
will happen every time the specified number of days has elapsed.
The number of days between recurrences of the event is speci-
fied in the field between the words Every and Days. For example,
Every 3 Days
means that beginning on the date specified in the Start field, the
event will happen every third day.
Every Weekday
If this radio button is selected, the event will happen on every
Monday, Tuesday, Wednesday, Thursday and Friday on or after the
date specified in the Start field.
Every Weekend Day
If this radio button is selected, the event will happen every Satur-
day and Sunday on or after the date specified in the Start field.
_____ Days After Each Task is Complete
If this radio button is selected, the event will first happen on the
date specified in the Start field. It will be repeated the specified
number of days after the end of the event. The number of days is
specified in the field to the right of the radio button.
The end of an event is determined by the time that the event
starts and the value in the Event record’s EventDuration field. The
value of the EventDuration field must be set after the Event record is
created by the Schedule workflow task. The EventDuration field is
described on page 631.
Every _____ Weeks on _____
If this radio button is selected, the event will first happen on or
after the date specified in the Start field, the first time that the

© Copyright IBM Corporation 2011. Schedule Workflow Task | 627

 current day is the specified day of the week. After the first repe-
tition, the event is repeated every n weeks. n is specified by the
field between Every and Weeks. The day of the week is specified
by its selection in the drop-down list to the right of Weeks on. For
example,
Every 3 Weeks on Monday
means that the event will happen on the first Monday on or after
the date in the Start field and then repeat every three weeks.
_____ Weeks After Each Task is Complete
If this radio button is selected, the event will first happen on the
date specified in the Start field. It will be repeated the specified
number of weeks after the end of the event. The number of
weeks is specified in the field to the right of the radio button.
The end of an event is determined by the time that the event
starts and the value in the Event record’s EventDuration field. The
value of the EventDuration field must be set after the Event record is
created by the Schedule workflow task. The EventDuration field is
described on page 631.
On Day _____ Every _____ Months
If this radio button is selected, the event will first happen on or
after the date specified in the Start field, on the first day that is
the specified day of the month. The event will be repeated after
the specified number of months, on the specified day of the
month. The day of the month is specified by the field between
Day and Every. The number of months is specified in the field
between Every and Months.
For example, suppose that the value of the Start field is April 12,
2004 and the recurrence setting is
On Day 1 Every 3 Months
The event would first happen on May 1, 2004 because that is the
first day on or after the start date that is the first day of a month.
The event would be repeated on August 1, 2004, November 1,
2004 and so on.
If the specified day of the month is 29, 30 or 31 and a repetition
falls in a month that does not have that many days, then the rep-
etition happens on the last day of the month. For example, if you
want an event to be repeated on the last day of every month, you
should specify
On Day 31 Every 1 Months

628 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
On the _____ _______ Every _____ Months
If this radio button is selected, the event will first happen on or
after the date specified in the Start field, on the first day that is
the specified day of the month. The event will be repeated after
the specified number of months has elapsed on the specified day
of the month.
The number of months is specified in the field between Every and
Months.
The day of the month is specified as either the first, second,
third, fourth or last occurrence of a particular day of the week in
the month. The selection of first, second, third, fourth or last is
specified in the drop-down list to the right of On the. The day of
the week is specified in the drop-down list to the left of Every.
Selecting the last occurrence of a day of the week means that the
event will happen on the fifth occurrence in a month of the speci-
fied day of the week if there is a fifth occurrence; otherwise the
event will happen on the fourth occurrence in a month of the
specified day of the week.
_____ Months After Each Task is Complete
If this radio button is selected, the event will first happen on the
date specified in the Start field. It will be repeated the specified
number of months after the end of the event. The number of
months is specified in the field to the right of the radio button.
The end of an event is determined by the time that the event
starts and the value in the Event record’s EventDuration field. The
value of the EventDuration field must be set after the Event record is
created by the Schedule workflow task. The EventDuration field is
described on page 631.
Every _______ _____
If this radio button is selected, the event will first happen on or
after the date in the Start field on the first day that is the speci-
fied day of the year. The event will be repeated every year after
that on the specified day of the specified month. The month is
specified by selecting it in the drop-down list to the immediate
right of Every. The day of the month is specified in the field to
the right of the drop-down list.
If February 29 is specified, on years that are not leap years the
event will happen on February 28.

© Copyright IBM Corporation 2011. Schedule Workflow Task | 629

 On the _____ _______ of _______
If this radio button is selected, the event will first happen on or
after the date in the Start field on the first day that is the speci-
fied day of the specified month. The event will repeat once a year
on the specified day of the specified month. The month is speci-
fied by selecting it in the drop-down list to the right of of.
The day of the month is specified as either the first, second,
third, fourth or last occurrence of a particular day of the week in
the month. The selection of first, second, third, fourth or last is
specified in the drop-down list to the immediate right of On the.
The day of the week is specified in the drop-down list to the left
of of.
Selecting the last occurrence of a day of the week means that the
event will happen on the fifth occurrence in a month of the speci-
fied day of the week if there is a fifth occurrence; otherwise the
event will happen on the fourth occurrence in a month of the
specified day of the week.
_____ Years After Each Task is Complete
If this radio button is selected, the event will first happen on the
date specified in the Start field. It will be repeated the specified
number of years after the end of the event. The number of years
is specified in the field to the right of the radio button.
The end of an event is determined by the time that the event
starts and the value in the Event record’s EventDuration field. The
value of the EventDuration field must be set after the Event record is
created by the Schedule workflow task. The EventDuration field is
described on page 631.
The Start field is under the set of radio buttons used to select how
often the event will happen. The Start field contains the date used to
determine on what day the event will first happen. The exact way this
date is used depends on which one of the above radio buttons is
selected. The description of each radio button contains more specif-
ics.
The time that the event will happen is the time portion of the value
in the Event record’s EventStartDate field. This is discussed in greater
detail on page 631.
Under the Start field are radio buttons for selecting how long the
event will continue to be repeated. Here are descriptions of the radio
buttons:

630 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
End Never
If this is selected, the event will never stop repeating.
End After _____ Occurrences
If this is selected, the event will stop repeating after it has hap-
pened the specified number of times. The number of times is
specified in the field between After and Occurrences.
End by _____
If this is selected, there will be no repetitions of the event on or
after the specified date. The date is specified in the field to the
right of End by.

Event Records
Once an Event record has been created, the values of its fields must
be set. A Schedule workflow task does not set the values of an Event
record’s fields, except for EventRefId. This is what a Schedule task
does:
• A Schedule workflow task creates an Event record.
• A Schedule workflow task creates a Recurrence record.
• A Schedule task sets the values of the Recurrence record’s fields
with what is specified in the Schedule task’s Recurrence section.
• A Schedule task associates the Recurrence record with the Event
record.
An Event record has these fields:
EventStartDate
This is the date and time when the event will happen.
If the Event record has an associated Recurrence record and the
selection of recurrence is not None, the date portion of this field
will be used to determine the earliest start date, not the actual
start date. In this case, the information in the associated
Recurrence record determines the actual dates on which the event
happens.
The time of day an event starts is always the time of day in this
field.
The value of this field must be specified.
EventDuration
This is the duration of the event.
The value of this field must be specified, but can be zero.

© Copyright IBM Corporation 2011. Event Records | 631

 EventEndDate
The value of this field is when the event ends.
This is a read-only field. Its value is calculated from the values of
EventStartDate and EventDuration fields. The date portion of this value
is meaningful only if the date portion of the EventStartDate field is
meaningful.
Subject
A person can type a few words into this field to describe what the
event is about. The value of this field is copied into the Subject
field of Scheduled Event records created from the Event record. The
text in a Scheduled Event record’s Subject field is used in the label for
the Scheduled Event record that is displayed in a calendar tab.
EventType
This is a list field. A workflow may use the value of this field to
determine something about the nature of an event.
The value of this field will be an item from a list named Event Type.
The Event Type list contains values that are used by multiple appli-
cations. Feel free to add items to the Event Type list for other
applications. However, it is not safe to remove items in this list or
change them unless you are certain that it will not hurt any appli-
cations.
EventInstruction
This is a read-only text field that is used to present some text in
the Event form.
EventRefId
This is a read-only control number that is used as an Event record’s
name.
Recurrence Id
This is a read-only field that is used internally by the IBM TRIRIGA
Application Platform. It must never be modified by a workflow or
the user.
When the values of all the fields of an Event record and its associated
Recurrence record have been set to the correct values, you can cause
the event they describe to be scheduled by performing a Schedule
action on the Event record.
Performing a Schedule action on an Event record causes a Scheduled Event
record to be created for occurrences of the event that are sched-
uled. Another consequence of performing a Schedule action on an Event
record is that a SCHEVENTCREATE system event happens to the record
that the event is scheduled for.

632 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
The way that the life cycle for an Event record is organized, a Schedule
action can be performed only once on an Event record.
After a Schedule action is performed on an Event record, its scheduling
effect can be undone by performing an Unschedule action on the Event
record. Performing an Unschedule action on the Event record does not
allow another Schedule action to be performed on the Event record.

Scheduled Events
A Scheduled Event record is used to represent each time that an event
has been scheduled. If the form for a record includes a Calendar tab,
you can see links to Scheduled Event records in the calendar.
Scheduled Event records are involved in at least these two associations:
• There is an association between a Scheduled Event record and the
Event record that it was created from. The name on both sides of
the association is RECURRENCE.
• There is an association from a Scheduled Event record to the record
for which the event is scheduled. Its name is also RECURRENCE.
At the time a Scheduled Event record says that an event is supposed to
start, a SCHEVENTSTART system event happens to the record that the
event is scheduled for. At the time a Scheduled Event record says that an
event is supposed to end, a SCHEVENTEND system event happens to the
record that the event is scheduled for.

© Copyright IBM Corporation 2011. Scheduled Events | 633

634 | Chapter 10: Calendar and Time Based Events © Copyright IBM Corporation 2011.
Chapter 1\
In this chapter: CHAPTER 11
• The mechanisms for
integrating your application
with applications that are
outside the platform.
Integration with
External Applications

This chapter explains different ways applications running on the IBM

TRIRIGA Application Platform can be made to work with applications
that run outside the IBM TRIRIGA Application Platform. There are a
variety of mechanisms available for this purpose. These mechanisms
are intended for different sorts of applications and data. They differ
from each other in a number of ways.
One of the ways integration mechanisms differ from each other is the
extent to which they require the services of a professional program-
mer. The following is a list of integration mechanisms in order of how
much programmer involvement is required.
Integration
Mechanism Description Programmer Needed
E-Mail An e-mail message is sent to an external appli- Only if the external applica-
cation that can interpret the message. tion is not already able to pro-
cess e-mail messages.
Form Report Form reports provide a mechanism of present- Not usually.
ing data in an Excel spreadsheet, Word docu-
ment, or external report through IBM TRIRIGA.
The application developer is responsible for
creating the spreadsheet, document, or exter-
nal report.
DataConnect The DataConnect solution employs staging DataConnect may require a
tables and workflow tasks, allowing an external programmer to move the data
source to write data directly into the IBM into the staging tables. The
TRIRIGA staging tables and have IBM TRIRIGA workflows require a person
workflow process this data for insertion into that knows the business pro-
native IBM TRIRIGA business objects. cesses of the integration.
Table 11-1. Integration Mechanisms

© Copyright IBM Corporation 2011. 635

Integration
Mechanism Description Programmer Needed
Data Integrator Reads data from simple spreadsheets or Extracting data from another
comma-separated files into IBM TRIRIGA Appli- source into a comma-sepa-
cation Platform records. rated file or simple spread-
sheet may require the
assistance of a programmer.
Financial The IBM TRIRIGA Application Platform processes No programmer needed to
Transactions financial transactions in a way that makes indi- make data available. Some
vidual journal entries available to an external applications will require pro-
accounting program. grammer involvement to get
the application to access the
data.
IBM TRIRIGA Con- IBM TRIRIGA Connector for Business Applications This requires a programmer
nector for Business allows programmers to write programs that who is knowledgeable about
Applications work directly with the IBM TRIRIGA Application SOAP technology and this part
Platform, solving most integration problems of the IBM TRIRIGA Applica-
that cannot be solved with other integration tion Platform or the services
mechanisms. of IBM TRIRIGA’s consultants.
Java Objects This is a custom piece of software that can be This requires a programmer
invoked to communicate with the platform and who is skilled at Java and is
other software. This is the most general possi- able to use IBM TRIRIGA Con-
ble integration mechanism. nector for Business Applica-
tions.
Table 11-1. Integration Mechanisms (continued)

The rest of this chapter describes these integration mechanisms in

greater detail.

E-Mail
Some applications are able to process e-mail messages in a useful way
if they are in a particular format. You can create a workflow in the
IBM TRIRIGA Application Platform to send e-mail messages. The
details of doing this are discussed in Chapter 12.

Form Reports
Form reports are the usual mechanism that you use to integrate
Microsoft Word, Microsoft Excel, or external reports with the IBM
TRIRIGA Application Platform. Form reports are described in detail in
the IBM TRIRIGA Application Platform 3 Reporting User Guide.
For the purposes of integration, there are three different ways a form
report can be presented. Each has slightly different uses.

636 | Chapter 11: Integration with External Applications © Copyright IBM Corporation 2011.
 • A form report can be presented as part of a record’s form. It can
either be in the form’s Reports tab or it can be in a report sec-
tion. This is a good solution if the integration goal is to interac-
tively present the contents of an Excel spreadsheet, a Word-based
form, or external report to a person.
This presentation also can be useful as a way to allow a person to
copy and paste data in a form that is formatted by Excel or Word.
It has the drawback that not all the format information is avail-
able that would be available if a person were copying it directly
out of an Excel spreadsheet or a Word document.
The reason for this is that even though the form report looks like
an Excel spreadsheet or a Word document, it is actually part of
the HTML that makes up the record’s form.
On the other hand, using this presentation to facilitate copy and
paste operations has the advantage of convenience. Presenting a
form report in this way may require the least effort on the part of
a person.
• A form report can be presented as the body of an e-mail mes-
sage. This is the most convenient way of sending a form report to
someone who many not be logged into the IBM TRIRIGA Applica-
tion Platform environment. For form reports using Word or Excel
this works particularly well for people who receive the form on a
mobile device, such as a laptop or PDA.
This presentation also can be used to send the form report to
applications that run outside the IBM TRIRIGA Application Plat-
form and can receive data through e-mail.
For form reports using Word or Microsoft Excel this presentation is
also HTML based. This means that it has the same disadvantages
of the presentation in a record’s form. It has some additional dis-
advantages:
• Because it is HTML, it will not be useful to send to applica-
tions that are expecting an actual Excel spreadsheet or Word
document.
• Some e-mail reading programs will not correctly render the
HTML.
For form reports using Crystal Reports, the report is attached to
the email as a PDF file. This means that it has the same disadvan-
tages of the presentation in a record’s form. It has an additional
disadvantage: The person receiving the e-mail must have a PDF
viewer.

© Copyright IBM Corporation 2011. Form Reports | 637

 • A form report can be presented as an actual Excel spreadsheet,
Word document, or, if generated from a Crystal Report as a PDF
file attached to an e-mail message. This is perfect for integrating
with applications that can take their input in the form of an Excel
spreadsheet, Word document, or PDF file attached to an e-mail
message.
The details of writing a workflow to send an e-mail are discussed in
Chapter 12. The details of sending a form report as part of an e-mail
are also discussed on page 646 under the heading “Attach Format File
Task”.

IBM TRIRIGA DataConnect

The IBM TRIRIGA DataConnect imports data from external systems into
the IBM TRIRIGA system. It is useful for initial loads of data and for
batch insert/update of data on a recurring basis. The DataConnect
solution employs staging tables and workflow tasks, allowing an exter-
nal source to write data directly into the IBM TRIRIGA staging tables
and using IBM TRIRIGA workflow to process this data for insertion into
native IBM TRIRIGA business objects.
The basic steps in the DataConnect process are as follows:
• Create a staging table for each business object that will be popu-
lated or updated from the external source.
• Make the job business object. This business object controls the
instance of the integration.
• Move data from the external source into the appropriate business
object staging table and the DataConnect Job Control table.
• The DataConnect Agent will initiate a process (a synchronous
workflow) within IBM TRIRIGA that reads records from the busi-
ness object staging tables and either inserts new instances or
updates existing instances while validating the input data and
executing associated business logic.
More information about DataConnect can be found in the DataCon-
nect chapter of Application Building for the IBM TRIRIGA Application
Platform 3: Data Management.

Data Integrator
The Data Integrator is a tool provided by the IBM TRIRIGA Application
Platform to allow records to be created or updated from data in a

638 | Chapter 11: Integration with External Applications © Copyright IBM Corporation 2011.
kind of file called a tab-delimited file. If you want an application that
runs in the IBM TRIRIGA Application Platform to receive data from an
external application that runs outside of the IBM TRIRIGA Application
Platform, the Data Integrator is the simplest way to get the data into
the IBM TRIRIGA Application Platform. Application Building for the IBM
TRIRIGA Application Platform 3: Data Management describes the Data
Integrator in detail.
Tab-delimited files can be created from spreadsheets. There are a
number of accounting packages and other kinds of programs that can
produce tab-delimited files.
The simplest way to run the Data Integrator is for it to be run interac-
tively by a person. If you run the Data Integrator this way, no pro-
grammer involvement is needed.
In some cases, it is not practical to have a person run the Data Inte-
grator every time there is data to be received into the IBM TRIRIGA
Application Platform from a tab-delimited file. For these cases, it is
possible to schedule data to be read from a tab-delimited file periodi-
cally without the involvement of a person.

Financial Transactions
Among the integration requirements for an application may be
requirements for the application to record transactions that capture
the impact of numbers recorded by an application. For example,
when a customer buys something, an application may generate a
transaction to bill the customer and decrease the value of the inven-
tory by the amount that was sold.
Requirements to record numbers as ACID* transactions and feed them
to an accounting package are rather common. They are so common
that the IBM TRIRIGA Application Platform has a special facility for
generating financial transactions. This is described in the book Appli-
cation Building for the IBM TRIRIGA Application Platform 3: Calcula-
tions.

* ACID stands for Atomic, Consistent, Isolated and Durable.

© Copyright IBM Corporation 2011. Financial Transactions | 639

 IBM TRIRIGA Connector for
Business Applications
IBM TRIRIGA Connector for Business Applications allows programmers
to write external programs that interact directly with IBM TRIRIGA
Application Platform using a technology called SOAP. This mechanism
allows external programs to manipulate records in the platform envi-
ronment.
There are two ways a programmer can use the SOAP APIs. One is to
modify an existing external application to use the APIs directly. The
other is to write a separate program that uses the APIs and acts as an
intermediary between the IBM TRIRIGA Application Platform and the
external programs with which it needs to be integrated.
IBM TRIRIGA Connector for Business Applications is described in IBM
TRIRIGA Connector for Business Applications 3 Technical Specification.

Java Objects
A method of a custom Java object can be invoked to perform any cus-
tom logic or solve any integration problem. The mechanism that
makes this work is described on page 554 under the heading “Custom
Task”.

640 | Chapter 11: Integration with External Applications © Copyright IBM Corporation 2011.
Chapter 1
In this chapter: CHAPTER 12
• How to send internal and
external notifications.
Notifications

This chapter describes how workflows generate notifications that

appear in user’s portals or as e-mail messages. This mechanism allows
message content to be managed centrally and independent of work-
flows. The mechanism has a clean distinction between the fixed part
of a notification that is always the same when a particular notifica-
tion in generated and the variable part of a notification that may be
different each time a particular notification is generated.
To clarify this distinction between the fixed and variable parts of a
notification, consider this example. Suppose you want to generate a
notification that looks like this:
Michael Smith requested a snack cart in room W342 at 
03/08/2006 10:30 AM.
The fixed part of this notification would probably be
________ requested a _______ in ______ at __________.
The variable part of the message would be the pieces of text that get
put in the blanks. In the case of the preceding example, these would
be:
• Michael Smith
• snack cart
• room W324
• 03/08/2006 10:30 AM
The mechanism that satisfies these needs involves three kinds of
records that play different roles in the notification process:
• Notification Content records are templates for notifications. The
fixed portion of a notification’s content is specified by

© Copyright IBM Corporation 2011. 641

 Notification Content records. Notification Content records allow
you to predefine the content of notification messages.
• Notification Helper records supply the variable part of a notifica-
tion’s content and also may be used to associate a specific record
with a notification.
• triPeople records are used to specify the recipient(s) of notifica-
tions. The proper associations from a Notification Helper record to
triPeople records specify to whom the generated notifications will
be sent.
The following sections of this chapter supply details needed to use
this mechanism.

Notification Content
Notification Content records are templates for notifications. They
provide the fixed portions of a notification’s content. These records
are normally created interactively by a person. To manage Notifica-
tion Content records, navigate to Tools > Approvals & Notifications >
Notifications > Notification Content.

642 | Chapter 12: Notifications © Copyright IBM Corporation 2011.

Figure 12-1 shows an example of a Notification Content form.

Figure 12-1. Notification Content with Direct Content

© Copyright IBM Corporation 2011. Notification Content | 643

 Workflows use a combination of the value of the ID field and the Lan-
guage field to identify the Notification Content record for creating a
notification.
The system uses the value of the Notification Subject field to create
the subject of a notification and the value of the Notification
Content field to create the body of the notification.
Notice that the text in the Notification Subject field and in the
Notification Content field contains numbers in curly braces like {7}.
Each of these numbers in curly braces is a place holder for text that
can be supplied from a Notification Helper record. The Description
field should describe the purpose of each of these place holders.
The value of the Language field identifies the language in which the
values of the Notification Subject field and the Notification Content
field are written. The significance of the Language field is discussed
in greater detail in IBM TRIRIGA Application Platform 3 Localization
User Guide.
Please see the “Notifications” chapter in the IBM TRIRIGA 10 Applica-
tion Administration User Guide for more specifics about the makeup
of the Notification Content record.
If a Notification Content record references any form report tem-
plates, Notification Helper records that use the Notification Content
record will have the additional responsibility of identifying the record
that will provide the variable content for the form report.

Notification Helper
To send a notification, a workflow creates a Notification Helper
record from the Notification Helper business object in the triHelper
module. After creating the record, the workflow sets the values of its
fields, associates the record with triPeople records to identify the noti-
fication’s recipients, and then sends the notification by triggering a
Calculate action on the Notification Helper record.
Here are descriptions of the fields in a Notification Helper record:
triIdTX
Workflows must set the value of the triIdTX field to the ID of the
Notification Content record that will provide the fixed portion of
the notification’s content.

644 | Chapter 12: Notifications © Copyright IBM Corporation 2011.

triInput1TX, triInput2TX,…, triInput9TX
These fields correspond to the place holders {1}, {2}, …, {9} that
may appear in the fixed content provided by the
triNotificationContent record. The value in each of these fields will be
substituted for the corresponding place holder in the content.
triLanguageLI
Workflows must set the value of the triLanguageLI field to the Lan-
guage of the Notification Content record that will provide the
fixed portion of the notification’s content.
triLinkedRecordTX
If the notification should be associated with a record, this locator
field should refer to the appropriate record.
triLinkedRecordIdTX
If the notification should be associated with a record, this text
field should contain the system’s internal ID of the record refer-
enced by the triLinkedRecordTX field for the appropriate record. This
is the field that identifies the record that will provide the vari-
able content for the form report(s).
triLinkedBusinessObjectLI
The value of this field should be the label text of the business
object that was used to create the record referenced by the
triLinkedRecordTX field.
triLinkedFormLI
The value of this field should be the label text of the form associ-
ated with the record referenced by the triLinkedRecordTX field.
triLinkedRecordStateTX
The value of this field should be the state of the record refer-
enced by the triLinkedRecordTX field.
triLinkedRecordStatusCL
The value of this field should be the status of the record refer-
enced by the triLinkedRecordTX field.
triSkipLinkedRecordLinkCreationBL

The associations needed to identify the recipients of a notification are

discussed below under the heading “triPeople”.
Additional associations can be made to records in the Document Man-
ager that will attach specific documents to the resulting notification
that are not included in the Notification Content. To attach addi-
tional documents, associate the document record to the Notification
Helper using the association Has Notification Attachment. To attach addi-

© Copyright IBM Corporation 2011. Notification Helper | 645

 tional form reports, associate the document record to the Notifica-
tion Helper using the association Has Notification Report.
After the above fields are all set and the associations made, the work-
flow can trigger a Calculate action on the Notification Helper record
to send the notification. After the Calculate action, the triSubjectTX
field will contain the subject of the notification that was sent and the
triContentTX field will contain the body of the notification.

triPeople
The workflow triggered by the Calculate action knows where to send
the notification it creates because of associations named Notify that
the Notification Helper record has with triPeople records.
If an associated triPeople record identifies an active user, the notifica-
tion is put in the notification section of the user’s portal. If an associ-
ated triPeople record identifies an e-mail address, the notification is e-
mailed to the specified address.

Attach Format File Task

The Attach Format File workflow task is intended specifically for pre-
paring notifications to be sent to people.
An Attach Format File task attaches the output of a form report to a
Notification record in a way that causes the form report output to be
attached to messages sent using the Notification record. Form reports
are discussed in the IBM TRIRIGA Application Platform 3 Reporting
User Guide.

646 | Chapter 12: Notifications © Copyright IBM Corporation 2011.

The shape for an Attach Format File task is shown in Figure 12-2. The
form for an Attach Format File task is shown in Figure 12-3.

Figure 12-2. 
Attach Format File Shape

Figure 12-3. Attach Format File Properties

The properties form for an Attach Format File task is organized into
three sections. Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.
Format File
The Object Type field of this form’s Attach Format File From
section specifies the business object that must have been used to
create the record for which the form report will be produced.
The value of this field is the name of form report template file
that this task will use to produce form reports. To select a file,
click the hyperlink to the right of the Format File label. A win-
dow will pop up to allow you to select a file.

© Copyright IBM Corporation 2011. Attach Format File Task | 647

 The task checks whether the file type supplied is a supported for-
mat, and if not, it attaches the file as-is (note that this does not
work if Embed File is checked). The supported report formats are
HTML documents and RPT files.
After you select a file, the name of the selected file will replace
the previous text of the hyperlink.
Embed File
A form report can be included in an e-mail in two different ways:
• The form report can be embedded in the message, meaning
that it will appear as part of the message’s text. The advan-
tage of sending a message this way is that a person reading
the message need not do anything extra to see the report. To
send the form report this way, check the Embed File check
box.
• The form report can be sent as an attached Microsoft Word or
Excel file. When sent this way, the person reading the mes-
sage will generally need to perform an extra mouse click to
see the message in Word or Excel. The advantage is that the
report can be used in Word or Excel. To send the form report
this way, uncheck the Embed File check box.

Attach Format File From

The second section of an Attach Format File task’s properties form is
labeled Attach Format File From. The purpose of this section is to
specify the record whose data will be used to generate the form
report.
The Attach Format File From section has two radio buttons to spec-
ify the record used to generate the form report. These radio buttons
are labeled:
Workflow Activity
If this radio button is selected, then the record that contains the
data to generate the form report will be associated with a previ-
ously performed workflow task.
Existing Record
If this radio button is selected, then the record that contains the
data used to generate the form report will be a specified record
that exists now.
The selection of one of these radio buttons determines what appears
in the Attach Format File From section. Figure 12-3 on page 647

648 | Chapter 12: Notifications © Copyright IBM Corporation 2011.

shows what the second section looks like when the Workflow Activity
radio button is selected.
When the Workflow Activity radio button is selected, below the radio
buttons the Attach Format File From section has all the fields that
are in the To Notification section. The difference between the fields
in these sections is that the fields in the Attach Format File From
section are used to select the record that contains the data that will
be used to generate the form report and the fields in the To
Notification section are used to specify the Notification record that will
be used to send the form report. Because of these similarities, the
description of these fields is part of the description of the To
Notification section.
If you want the form report to be generated from a record that is part
of the application’s configuration, then you should select the option
of using an existing record. When the Existing Record radio button is
selected, the second section looks like the one in Figure 12-4.

Figure 12-4. Attach Format File Properties (Existing)

You specify the value for the Module and Object properties so that
this task knows what kind of record will be the parent. Then click the
Record link to find the specific record you want this task to use.

To Notification
The third section of the Association Task properties form is labeled To
Notification. The purpose of the To Notification section is to specify
the Notification record that will be used to send the form report.
The following description of the fields in the third section also applies
to the fields in the second section that appear in the Attach Format
File From section when its Workflow Activity radio button is
selected. The fields in the Attach Format File From section serve a
purpose similar to the corresponding fields in the To Notification sec-
tion. The difference between the corresponding fields in the Attach
Format File From section is that they are used to identify the record
that contains the data that will be used to generate the form report

© Copyright IBM Corporation 2011. Attach Format File Task | 649

 and the fields in the To Notification section identify the Notification
record used to send the form report.
At the top of the To Notification section are fields used to identify a
target record. The target record is used to determine the Notification
record that will be used to send the form report.
There are radio buttons below the fields. The way that target records
are used to determine the record used to send the report depends on
which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the event is the target record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record that will be used to send the
report.
When the properties form is first displayed, only the currently
selected radio button is visible. There is a button to the left of the

650 | Chapter 12: Notifications © Copyright IBM Corporation 2011.

visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the Notification record
used to send the report.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target records will be the Notification record used to
send the report. When you select this radio button, a window
pops up that allows you to choose from the smart sections and
locator fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, records associated with the target record will
be the Notification record used to send the report. When you select
this radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon

© Copyright IBM Corporation 2011. Attach Format File Task | 651

 is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the target
records’ parent will be the child record.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record that will be
used to send the notification. For this third section the value of this
field should be Notification.

652 | Chapter 12: Notifications © Copyright IBM Corporation 2011.

Notification Example
Here is a simple example of a workflow that always sends the same
message to the person who is currently logged in. The workflow dia-
gram looks like Figure 12-5.

Figure 12-5. Example of a Notification Sending Workflow

The first task creates the Notification record, sets the message con-
tent and makes the RefObject field refer to the record that was used
to launch the workflow.
The second task sets the recipient of the notification.
The third task triggers the Notify action on the Notification record.

© Copyright IBM Corporation 2011. Notification Example | 653

654 | Chapter 12: Notifications © Copyright IBM Corporation 2011.
Chapter 1
In this chapter: CHAPTER 13
• How to control access to
application features and
business objects. Security

In its most general sense, security is something that prevents bad

things from happening while allowing good things to happen. As it
applies to the IBM TRIRIGA Application Platform, security is what
allows people to look at or manipulate data they should be looking at
or manipulating, while preventing people from looking at or manipu-
lating data they should not be.
These are the main facets to security on the IBM TRIRIGA Application
Platform:
Authentication
This involves someone identifying themselves to the IBM TRIRIGA
Application Platform and then doing something else to prove that
he really is who he claims to be.
Licenses
A license allows a person to access specific features of an applica-
tion or to use tools provided by the IBM TRIRIGA Application Plat-
form. A license is useful for controlling access to applications and
tools. It is not helpful for controlling access to records.
Groups
A group is a list of people and other groups. A person can belong
to more than one group.
Access Permissions
Access permissions determine what kinds of records the members
of a group can access and what they can do with the records.
Organization and Geography
You can use a record’s association with an organization or geo-
graphic area to control which users can access the record.

© Copyright IBM Corporation 2011. 655

 Project
The project associated with a record can restrict who is able to
Other People view or modify the record.
Business Objects
The basic rule of IBM TRIRIGA Application Platform security is that a
If using a record created person can only look at something or perform an action if they belong
from a triPeople business
to a group that has permission to do so.
object is not appropriate
for your application, you
can create and use another
business object in the Authentication
triPeople module.
Setting up authentication for a person involves two steps:
The business object must
• Create a record that describes the person.
have an association with
the My Profile business • Create an embedded My Profile record that describes the person’s
object named Associated To user ID and how the person will interact with the IBM TRIRIGA
on both ends. Application Platform.
Its form should have a The usual procedure for creating a record that will describe a person
Profile tab similar to the is a manual procedure. Navigate to Portfolio > People. Here you can
one in the Consultant,
create triPeople records using the Employee, Consultant, or External
Employee or External Contact
form. The Profile tab Contact forms. You also may configure other types of records to
should have an action on it describe people.
that allows a My Profile The forms for these records have a number of tabs. After you have
record to be created that
describes the person’s user
filled in the required fields on the General tab, you are ready to fill in
ID. the details of the My Profile record that will describe the person’s user
ID to the IBM TRIRIGA Application Platform and the way the person
The easiest way to accom- will interact with the platform.
plish these things is to copy
what already exists. Cre- You can create the My Profile record indirectly by going to the Profile
ate the new business tab of the record you just created. It looks like Figure 13-1. The fields
object by copying the on the Profile tab have these meanings:
triPeople business object.
Copy the corresponding User Name
form to create the new This is the user ID that the person will use to sign in to IBM
form. TRIRIGA. This field must be filled in even though the form does
not indicate that it is required.
There is no field to set the person’s initial password. The pass-
word for a new user name is always password.
Active TRIRIGA User?
This check box should be checked if you want someone to be able
to sign in as a user.

©656 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Figure 13-1. Profile Tab

Initial Pwd Reset

When this check box is checked, the first time this user signs in to
IBM TRIRIGA the user will be prompted to change their password.
Home Page
Defines the main window, or portal, the user sees when the user
first signs into IBM TRIRIGA when at the Company Level. This also
displays whenever the user clicks the Home menu item. If this

© Copyright IBM Corporation 2011. Authentication | 657

 value is blank, IBM TRIRIGA renders a default portal. See the IBM
TRIRIGA Application Platform 3 User Experience User Guide for
more information about portals.
Menu
A navigation collection that defines the structure and content of
the menu bar at the top of page when at the Company Level. See
the IBM TRIRIGA Application Platform 3 User Experience User
Guide for more information about navigation collections and
menus.
Project Home Page
Similar to Home Page, but only applies when the user is working in
a Project context.
Project Menu
Similar to Menu, but only applies when the user is working in a
Project context.
Sitemap?
If this check box is checked, there will be a Sitemap link avail-
able for this user that will display a site index that has all the
selectable navigation items based on the user's menu. Note that
navigation items can be configured to only appear on the Sitemap,
and hence would be unavailable to users without the Sitemap
check box checked. See the IBM TRIRIGA Application Platform 3
User Experience User Guide for more information about sitemap
and navigation items.
Disable Company Level?
Normally you will want to leave this unchecked. If this check box
is checked, the Clear Project button is disabled for the user. This
needs to work in conjunction with application features that would
populate the last project used. Then the project selector would
enable the user to move between projects but the user would not
be able to exit a project in order to go to the Company Level.
User Language
The value of this field is the language that the person prefers to
use, such as US English, Spanish, French. The value of this field
determines which set of labels and other text the user sees.
The list of languages that you can choose from in this field is
determined by a list named Language.
The IBM TRIRIGA Application Platform 3 Localization User Guide
explains what is involved in getting an application to work in dif-
ferent languages.

©658 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Currency
Use this field to specify the default currency that the person will
use. Currency settings are discussed in detail in IBM TRIRIGA
Application Platform 3 Localization User Guide.
Time Zone
The time zone that the person is normally in. If blank, the system
uses the value of the SYSTEM_DEFAULT_TIMEZONE property in
TRIRIGAWEB.properties.
Delegate To
The purpose of this field is to allow someone else to handle this
user’s approval action items when this user is not able to do it. If
this field has a value, it is the person who is allowed to approve
action items on behalf of this user.
Approval Amount
The maximum amount that this user is authorized to approve on a
single transaction.
Group Details
The groups the user is in.
License Details
The licenses the user has.
Having filled in the fields of the Profile tab, you are ready to create
the person’s My Profile record by clicking the Activate action in the
menu. Once the My Profile record is created, the person can sign in to
IBM TRIRIGA.
By default the platform logs successful and failed logins and user
account changes in the security.log file. You can turn off this logging by
editing the log4j.xml file located in the <IBM TRIRIGA installation>\config
folder (for example, C:\Tririga\config\log4j.xml).
Being able to sign in is not useful by itself. If no licenses are granted
to a user, the user will not be able to access any application features
or tools provided by the platform. User IDs that have not been
granted any licenses are not allowed to sign in.
Having licenses without membership in a group is not useful either. In
order to be able to access any particular kind of record, you must
have permission to do so. To perform an action on a record, you must
have permission to perform the action on the record. A person gets
permissions by being a member of a group that has the necessary per-
missions.

© Copyright IBM Corporation 2011. Authentication | 659

Passwords
IBM TRIRIGA supports strong passwords. Using strong passwords low-
ers the overall risk of a security breach. Define your company’s imple-
mentation in Tools > System Setup > System > Password Setup.
Figure 13-2 shows the Password Setup form.

Figure 13-2. Password Setup Form

The system only uses the rules defined in the rest of the Password
Setup form when the Enforce Password Rules field is checked. When
Enforce Password Rules is not selected, the system uses the standard
IBM TRIRIGA password rules and ignores the rest of the values in the
Password Setup form. This is the default value.
The system begins to follow the rules defined in the Password Setup
as soon as the record is in Active status.
See the “Passwords” chapter in IBM TRIRIGA 10 Application Adminis-
tration User Guide for more information about strong passwords.

Single Sign-On
In some organizations, people may use multiple computers and appli-
cations. The larger the organization, the more likely this situation.

©660 | Chapter
Copyright 13: Security
IBM Corporation 2011.
When an organization first encounters this situation, a person may be
given a different user ID or password for each computer or applica-
tion they use. For example, an organization where people begin their
day by signing on to their computer. They then sign on to an applica-
tion to see their schedule for the day. They then sign on to another
application they use for most of their work. At the end of the day,
they sign on to another application to account for how they spent
their time that day.
Most people in this organization had four different user IDs and pass-
words to remember. This was inconvenient and it also hurt security.
People would try to use the same password for each computer or
application, but this was not always possible for a variety of reasons.
What people tend to do when they have multiple user IDs and pass-
words is to write them down. Usually, they put the paper with their
user IDs on it somewhere convenient for them to see when they need
it. Common locations are taped to the side of a monitor or in a desk
drawer. This is convenient for the person who needs to remember the
passwords. This also makes it easy for someone else to discover the
passwords.
To avoid the inconvenience and security issues that come with people
having multiple user IDs and passwords, many organizations have a
way for people to use a single user ID that works for everything. Some
organizations have improved convenience beyond having a single user
ID to having a single sign-on.
Single sign-on means that people use one user ID and password to sign
on when they start working and do not need to sign on to anything
else until the next time they return to work.
There are a variety of schemes that organizations use to support a sin-
gle sign-on. The IBM TRIRIGA Application Platform’s authentication
mechanism is designed to work with most single sign-on mechanisms.
There is more than one way to integrate the IBM TRIRIGA Application
Platform’s authentication mechanism with single sign-on mecha-
nisms. The essence of how it works is that the IBM TRIRIGA Applica-
tion Platform learns from an external trusted source the user ID of the
person who wants to be logged in to the platform. If the user ID from
the external source matches a user ID specified by a My Profile record,
then the platform accepts the user ID as authenticated and logs the
person in.

© Copyright IBM Corporation 2011. Single Sign-On | 661

The details of how to integrate the IBM TRIRIGA Application Plat-
form’s authentication mechanism with a single sign-on mechanism are
described in the book IBM TRIRIGA Application Platform 3 Single Sign-
On Setup User Guide.

License Management
A license allows access to menu items and tools in the IBM TRIRIGA
Application Platform. An installation of the platform includes a file
that contains quantities of different kinds of licenses. Each kind of
license can be used to give access to a different combination of
menus and tools.
You obtain licenses by buying them. You buy the kinds of licenses you
need in the quantity that you need and install them in your IBM
TRIRIGA Application Platform environment.
People cannot take advantage of a license unless it is assigned to
them. To assign licenses to people, use the License Manager in Tools >
Administration. The License Manager looks like Figure 13-3.

Figure 13-3. License Manager

Three kinds of licenses may appear in the License Manager:

• Product licenses allow people to access features of IBM TRIRIGA’s
application products. A user ID cannot sign in to the IBM TRIRIGA
Application Platform environment unless it has been assigned at
least one product license.
• Platform licenses determine the features or environment for
which a IBM TRIRIGA Application Platform environment is config-
ured. These affect the platform environment as a whole. They do
not have any direct relationship to what an individual user ID may
do.

©662 | Chapter
Copyright 13: Security
IBM Corporation 2011.
 • An IBM TRIRIGA Custom Application license is a special kind of
product license that does not provide access to any application
features. However, assigning a custom application license to a
user allows that user to sign in and use applications that were not
created by IBM TRIRIGA.
The left side of the License Manager is a list of available licenses.
When you select the radio button to the left of a license’s name, you
see the user IDs to which the license has been assigned.
At the top of the right side you can see the name of the license.
Under that displays a list of user IDs that the licenses have been
assigned to. You can add user IDs to the list by clicking the Add Users
action. You can remove user IDs from the list by selecting the check
box next to a user ID and clicking the Delete Users action.
The query on the Add User action can be customized. To have the sys-
tem run your query, name your query “Security License List” in the
Report Manager.
The licenses shown in the License Manager are synchronized with the
licenses shown in user profiles. Adding a user to the License Manager
triggers a workflow to update the user’s profile record. Deleting a
user from the License Manager triggers a workflow to remove the
license from the user’s profile record.

IBM TRIRIGA Application Platform

License
You need an IBM TRIRIGA Application Platform license to create or
modify business objects or to create or modify a workflow.

Attention: Be extremely careful to whom you assign an IBM

TRIRIGA Application Platform license. An IBM TRIRIGA
Application Platform license allows a user to circum-
vent all platform security features.

Groups
A group identifies a group of user IDs and the access they have to spe-
cific kinds of records and what they are allowed to do with the
records.

© Copyright IBM Corporation 2011. Groups | 663

Groups are managed by the IBM TRIRIGA Application Platform’s Secu-
rity Manager. To access the Security Manager, navigate to Tools >
Administration > Security Manager. The Security Manager looks like
Figure 13-4.

Figure 13-4. Security Manager

IBM TRIRIGA provides a number of predefined security groups corre-

sponding to roles our customers commonly have. Use these security
groups as a starting point to meet your company’s specific security
needs.
You can create new group by clicking the Add action. Click the hyper-
linked name of a group to edit it. To delete a group, select the check
box next to the group’s Name and click the Remove action.
The form for a group has three tabs that are used for security pur-
poses:
• General
• Members
• Access

©664 | Chapter
Copyright 13: Security
IBM Corporation 2011.
General Tab
The General tab looks like Figure 13-5.

Figure 13-5. Group General Tab

The General tab has two sections labeled General and Data Access.
Here are descriptions of the fields in the General section:
Name
The text in this field is the name of the group.
Description
This field contains a description of the group.
Personalize Portal
If Yes, users in this Group will have the ability to select Personal-
ize on their portal, which will allow them to customize their
Home page. If No or empty, the Personalize button will not be
available.
The IBM TRIRIGA 10 Getting Started User Guide describes how
users personalize portals.
Personalize Bookmarks
If Yes, users in this Group will have the ability to select Add to
Bookmarks and personalize their Bookmarks menu. If No or empty,
bookmarking will not be available for this user.

© Copyright IBM Corporation 2011. Groups | 665

 The IBM TRIRIGA 10 Getting Started User Guide describes how
users personalize bookmarks.
Ignorable For Nav. Overrides
If Yes, the Group is excluded from consideration in Group Over-
rides in a Navigation Collection.
If No or empty, the Group is included in Group Overrides in a Navi-
gation Collection.
See “Navigation Collections” in the “IBM TRIRIGA Portal and Navi-
gation Chapter” of the IBM TRIRIGA Application Platform 3 User
Experience User Guide for more information about Group Over-
rides.
Access All Profiles
If Yes, users in this Group can access their own My Profile record
or another user’s My Profile record.
If No or empty, users in this Group can access their own My Profile
record but cannot access another user’s My profile record. This is
the default value.
The ENABLE_PROFILE_ROW_LEVEL_SECURITY property in TRIRIGAWEB.proper-
ties must be set to Y for the value of Access All Profiles to control
user security access to My Profile records. Read more about
ENABLE_PROFILE_ROW_LEVEL_SECURITY and TRIRIGAWEB.properties in
“TRIRIGAWEB.properties” in the “IBM TRIRIGA Software Configura-
tions” chapter of IBM TRIRIGA Application Platform 3 Installation
and Implementation Guide.
Here are descriptions of the fields in the General tab’s Data Access
section.
System Organization
Members of the group have access to records associated with the
specified organization or associated with organizations below the
specified organization in the Organization hierarchy.
This is discussed in greater detail on page 674 under heading
“Organization and Geography”.
System Geography
Members of the group have access to records associated with the
specified geography or associated with the geographies below the
specified geography in the hierarchy.
This is discussed in greater detail on page 674 under heading
“Organization and Geography”.

©666 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Members Tab
The Members tab is used to control which people and other groups
are members of a group. The Members tab looks like Figure 13-6.

Figure 13-6. Group Members Tab

You can add people directly to the group by clicking the Add Users
action. Clicking the Add Users action causes a list of all of users with
user IDs to pop up with a check box next to each user ID. You can
then check the check box next to the user ID of everyone you want to
add. Clicking the pop-up window’s Accept action causes the pop-up
window to disappear and the selected user IDs to be added to the
group.
You can add people to a group indirectly by clicking the Add Groups
action. Adding a group as a member of another group causes all user
IDs and groups that are members of the added group to be members
of the group to which they were added. It also gives the Access Per-
missions in the added group to the group.
Clicking the Add Groups action causes a list of all groups to pop up
with a check box next to each group. You can then check the check
box next to the groups you want to add. Clicking the pop-up win-
dow’s Accept action causes the pop-up window to disappear and the
selected groups to be added to the group.

© Copyright IBM Corporation 2011. Groups | 667

You can delete members from the group by checking the check box of
members you want to delete and then clicking the Delete action.

Access Tab
The Access tab is used to determine how much access membership in
the group grants to records created from specified business objects. It
also determines what actions the members of the group are allowed
to perform on the records. In addition, the Access tab determines the
access the members of the group will have to the tabs and sections of
the form.
The appearance of the Access tab varies with the type of object for
which security is being defined. The Access tab has an Object sec-
tion on the left and an Permission section on the right.
The Object section shows a tree that contains all modules. The tree
also contains all of the tools that the IBM TRIRIGA Application Plat-
form provides, such as the Data Modeler and the Report Manager.
The content of the Permission section varies based on what is
selected in the Object section.
Modules that contain published forms are represented by a plus sign
icon ( ). You can expose the form under a module by clicking the
module’s plus sign icon ( ). Tools and modules that do not contain
any published forms are represented by a dot.
You can select a module, tool, or anything else that is exposed on the
left side of the Access tab by clicking its name. When something is
selected on the left side of the Access tab, relevant choices for per-
missions appear on the right side of the Access tab.
The permissions you see in the right side of the Access tab vary with
the type of object that is selected on the left side of the Access tab.
The meaning of the permission also varies with the type of object that
is selected on the left side of the Access tab.
TIP: Be sure to review the access permissions in any Group that you
create. A new custom Group by default may have Data Access set to
No Access and all items listed in Application Access and Form Access
unchecked (no access). Record instances covered by such a custom
Group are read-only. Furthermore, users in such a custom Group will
not have access to any form actions, which means that users will not
be able to commit any change made in a form.

©668 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Module
In Figure 13-7, a module is selected on the left side of the Access tab.

Figure 13-7. Group Access, Module Selected

Two kinds of permissions are shown on the right side of the Access
tab. At the top are Data Access permissions. In the bottom part are
Application Access permissions.
You may select one Data Access permission. Initially, No Access is
selected. No Access means just what it sounds like. The other levels of
data access permissions allow progressively more access to records,
all the way up to Read, Update, Create and Delete, which allows members
of the group to look at existing records, change the contents of
records, create new records, and delete records.

© Copyright IBM Corporation 2011. Groups | 669

Modules do not have fields of their own. The data access permission
that you select for a module is used as the default data access per-
mission for the forms in the module. If you do not select a data access
permission for a form in a module, the data access permission for the
form is the data access permission selected for the module.
The Application Access permissions are action permissions. Each of
the permissions corresponds to the name of an action in a state tran-
sition family. If you check the check box next to an action permis-
sion, it means that members of the group may perform the named
action using any form in the module.

Tool
Figure 13-8 shows the Access tab with a tool selected in the left side
of the Access tab.

Figure 13-8. Group Access Tab, Tool Selected

The permission choices for most tools are very simple and only define
Data Access permission. The members of the group can either have
full access to a tool or no access. The Report Manager has more per-
mission choices; these choices are described in “Reports” on
page 682.

©670 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Form
When you click the plus sign icon ( ) to the left of a module name, it
exposes the forms in the module. Figure 13-9 shows a form selected in
the left side of the Access tab.

Figure 13-9. Group Access, Form Selected

© Copyright IBM Corporation 2011. Groups | 671

When a form is selected in Object section of the Access tab, the right
side of the Access tab contains Data Access, Application Access, and
Form Action Access permissions.
You may select one Data Access permission. Initially, Inherit from Parent
is selected. The Inherit from Parent access permission sets the access
level of a lower tier component to be the same as its parent. This is
applicable at the form, tab, and section levels of the security group.
No Access means just what it sounds like. The other levels of data
access permissions allow progressively more access to records, all the
way up to Read, Update, Create and Delete, which allows members of the
group to look at existing records, change the contents of records, cre-
ate new records, and delete records.
The Application Access permissions shown for a form include only
actions from the state transitions that the form uses. Members of the
group will be able to perform an action on a record created from the
selected business object only if the action’s check box is checked in
the list for the selected form or its module.
The Form Action Access permissions shown for a form include all
actions added in the form to sections as well as any action fields.
Members of the group will be able to perform a form action on a
record created from the selected business object only if the action’s
check box is checked in the list for the selected form or they have
Read, Update, Create and Delete access to the form.

Tab
When you click the plus sign icon ( ) next to the name of a form, you
see the tabs that the form contains. If a tab contains a section, it will
be represented by a plus sign icon ( ) you can click to see the tab’s
sections. Figure 13-10 shows a form’s tabs and some of its sections
exposed and the Data Access permissions for a section.
The list of permissions for a tab is the same. Initially, Inherit from Parent
is selected. If the members of a group have No Access to a tab or a sec-
tion, they will not be able to see the tab or section.

The Admin Group

The Admin Group is a very special group for the IBM TRIRIGA Applica-
tion Platform. Members of the Admin Group automatically are allowed
to access all kinds of records and most tools in the platform environ-

©672 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Figure 13-10. Group Access, Section Selected

ment whether they have been granted explicit permission to do so or

not.
The only tool access that membership in the Admin Group does not
confer to its members is the tool access that is granted to user IDs
that have an IBM TRIRIGA Application Builder license. IBM TRIRIGA
Application Builder licenses are discussed on page 663.
To ensure the security of records in the IBM TRIRIGA Application Plat-
form environment, it is very important to limit the people who are
members of the Admin Group to a small number of trusted people.

© Copyright IBM Corporation 2011. Groups | 673

Organization and Geography
It is possible to restrict people’s access to records based on the asso-
ciation between individual records and Organization or Geography.
Most business objects have a field named OrgName and a field named
GeographyName. These fields are in the business object’s General sec-
tion. These fields are automatically supplied by the IBM TRIRIGA
Application Platform. Because the platform automatically adds these
fields, they do not appear in the Data Modeler. They do appear in the
Form Wizard as part of the layout.
The OrgNamefield can have as its value any Organization record. The
GeographyName field can have as its value any Geography record. The
Geography hierarchy and the Organization hierarchy can be accessed
in the Portfolio menu.
The default value for these fields is the value that these fields have in
the triPeople record that describes the currently logged in user. If the
person logged in has the values Acme Corporation and USA for these fields
in his My Profile record, then the default will be for records he creates
to be associated with Acme Corporation and USA.
If a record’s OrgName field has a value, the value of the field restricts
the people who can access the record. People will only be able to
access a record if they have been granted access to the organization
that is the value of its OrgName field or to an organization higher up in
the Organization hierarchy.
Similarly, if a record’s GeographyName field has a value, it restricts the
people who can access the record. People will only be able to access
a record if they have been granted access to the geography that is the
value of its GeographyName field or to a geography higher up in the
Geography hierarchy.
It is possible for a record to not have any value for its OrgName or
GeographyName fields. If a record’s OrgName field has no value, there is
no Organization-based restriction on who can access it. Similarly, if a
record’s GeographyName field has no value, there is no Geography-based
restriction on who can access it.
The definition of a Group in the Security Manager includes System Orga-
nization and System Geography in the Data Access section of the General
tab (as shown in Figure 13-5 on page 665). Users belonging to a Group
have access to this organization and also to every organization under
that in the Organization hierarchy. Similarly, users belonging to a

©674 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Group have access to this geography and also to every geography
under that in the Geography hierarchy. This access is subject to
restrictions imposed by project security (described on page 675) and
by restrictions specified in the Group’s Access tab.
The following table summarizes the relationship between a record’s
System Organization field and a Group’s System Organization field:

Record Record
System Organization System Organization
is Blank is NOT Blank
Group User in Group WILL see User in Group will NOT
System Organization is record see record
Blank
Group User in Group WILL see User in Group WILL see
System Organization is record record
NOT Blank
Table 13-1.

The following table summarizes the relationship between a record’s

System Geography field and a Group’s System Geography field:

Record Record
System Geography System Geography
is Blank is NOT Blank
Group User in Group WILL see User in Group will NOT
System Geography is record see record
Blank
Group User in Group WILL see User in Group WILL see
System Geography is record record
NOT Blank
Table 13-2.

Projects
One of the business objects that comes with the IBM TRIRIGA Applica-
tion Platform is triCapitalProject in the triProject module. triCapitalProject
records are intended to be used for tracking a set of related activi-
ties and their associated financial data. The triCapitalProject business
object is useful for applications that manage projects.
records have a security-related purpose that is indepen-
triCapitalProject
dent of project management. triCapitalProject records can be used to
restrict who can access records. They are similar to Organization and
Geography records in the way that the IBM TRIRIGA Application Plat-
form uses them to filter which records are visible to the user.

© Copyright IBM Corporation 2011. Projects | 675

Like Organization and Geography records, access to records associated
with a particular triCapitalProject record is limited to a specified set of
people. Unlike Organization and Geography records, you can allow some
people to view but not change records associated with a particular
Capital Project record.

Using Projects
The IBM TRIRIGA Application Platform comes with one built-in
triCapitalProject record that has the name Company Level. There are a few
things about the Company Level project that make it special:
• You may not edit or delete the Company Level project.
• Nobody is denied access to a record because it is associated with
the Company Level project.
• The user must have an IBM TRIRIGA Projects or IBM TRIRIGA
Projects Upgrade license to change their active triCapitalProject.
When a user signs on to the IBM TRIRIGA Application Platform, their
session with the platform is associated with a triCapitalProject record.
This triCapitalProject record is referred to as the active project. The
name of the active project is shown above the menu bar. It looks like
Figure 13-11. To the left of the project name is a search icon .

Figure 13-11. Company|Project Toggle

When a user clicks the Find Project icon and has permission to
change the active project to a triCapitalProject record other than Company
Level, a list of other triCapitalProject records pops up. The current
project can be changed to one of those Capital Project records by
selecting it in the list and clicking the OK action.
Clicking the Company button in Figure 13-11 sets the current project
back to the Company Level project. To change the appearance of the list
of capital projects that is popped up, update the query named Portal
Project Search in the Report Manager. For more information on editing
queries see the IBM TRIRIGA Application Platform 3 Reporting User
Guide.
When a user signs out, the system saves their active project. The next
time that user signs in, the system returns them to that project.

©676 | Chapter
Copyright 13: Security
IBM Corporation 2011.
When projects are displayed in a grid in the user’s portal, as shown in
Figure 13-12, the user can change the active project by clicking the

Figure 13-12. Project Context Switching Portal Section

project switching icon preceding the project name. The system

only displays the project switching icon if the record corresponds to a
Capital Project record and the user is granted project security privi-
leges.
When the user clicks the project switching icon for a record in a non-
default project, the user’s active project is switched to that record’s
project. When the user clicks the project switching icon for a record
in a default project, the user’s active project is switched to Company
Level, if not already there. The system updates the current project
name at the top of the home portal and refreshes the portal.
The active project is significant in two ways:
• Every record has an internal association with a triCapitalProject
record. When you interactively create a record, it is internally
associated with a triCapitalProject record.
When a workflow creates a record, it can either explicitly specify
a triCapitalProject record for the new record or use the triCapitalProject
record that is active for the current user.

© Copyright IBM Corporation 2011. Projects | 677

 • The data returned by reports and queries accessed through forms
can be limited to the active project. To restrict the data returned
by reports and queries accessed through forms to only projects to
which a user has security access, use the USE_PROJECT_SECURITY
property in the TRIRIGAWEB.properties file. (The IBM TRIRIGA Applica-
tion Platform 3 Installation and Implementation Guide describes
the USE_PROJECT_SECURITY property and the TRIRIGAWEB.properties file.)
After a record is created, it always has an internal association to the
same triCapitalProject record.
When a user creates a new record, the Capital Project associated with
that record depends on the following factors:
• The project for a top level record is the user’s current active
project.
• If the record is a new child record and the Project Containment Dis-
abled property in the association definition for the dependent busi-
ness object is off (the default, as discussed on page 65), its
project is that of its parent record. If the Project Containment Disabled
property is on (selected), its project is the user’s current active
project.
• The project for an existing record that is made to be the child of
another record is the project of that other record.
A record is considered to be a child if one of the following is true:
• It is associated to a record via a dependent association.
• It is a hierarchical child through a platform hierarchy. An excep-
tion is the child of root, which is treated as a new record.
• It is a record in a dependent section.
When requests come in to the server, the user’s active project is rele-
vant because that drives among other things what the project con-
text is when synchronous workflows run. To have the user’s current
active project always be the active project no matter what, set the
RECORD_PROJECT_CONTAINMENT property in the TRIRIGAWEB.properties file to
N. (The IBM TRIRIGA Application Platform 3 Installation and Implemen-
tation Guide describes the RECORD_PROJECT_CONTAINMENT property and
the TRIRIGAWEB.properties file.)
When using projects, be aware that when a user has access to multi-
ple projects, they may create records that should be part of one
project while in a different project. This can result in the wrong peo-
ple having access to the records, or in people who need access being
denied it.

©678 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Creating and Managing Projects
records are managed using the Capital Projects page. To
triCapitalProject
access the Capital Projects page, navigate to Projects > Capital as
shown in Figure 13-13.

Figure 13-13. Capital Projects Page

To create a new Capital Project, click New Project. To edit a Capital

Project record, click the hyperlinked name. To delete a Capital
Project record, click the check box next to it and click Delete
Project.

© Copyright IBM Corporation 2011. Projects | 679

The top part of the General tab of the Capital Project form looks like
Figure 13-14. When you are creating a Capital Project record solely
for security purposes, the only field in its General tab that you need
to fill in is the Name field.

Figure 13-14. Capital Project, Top of General Tab

All the Capital Project form’s security-related fields are on its

Security tab. The Security tab looks like Figure 13-15.
The Capital Project form’s Security tab is divided into sections that
control access to records associated with a Capital Project record.
People who are members of groups listed in the Group Access sec-
tion have access to records internally associated with the Capital
Project record. If a user ID’s only access is as a member of groups
that have their Read Only check box checked, the person will be able
to view but not change records internally associated with the Capital
Project. Use the Find action to add a group to the Group Access sec-
tion.
User IDs can also have access to a record internally associated with a
Capital Project record if they are listed in the User Access section. If
a user ID’s Read Only check box in the User Access section is checked
and the person does not belong to any groups listed in the Group
Access section that do not have their Read Only check box checked,

©680 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Figure 13-15. Capital Project, Security Tab

the person will be able to view but not change records internally asso-
ciated with that Capital Project record. Use the Find action to add a
person to the User Access section.
For this security to be enforced you must click the Activate action on
the Capital Project. Depending on the Approval Requirements for Capi-
tal Projects, the project may need to be approved. Once the project
has an Active status, the security will be enforced. More information
on Approval Requirements provided with IBM TRIRIGA 10 applications
is described in the document IBM TRIRIGA 10 Application Administra-
tion User Guide.

Workflows and Projects

When a synchronous or subflow workflow starts, its active project is
always the current project. If initiated by a user, the current project
is the active project of the user who initiated the workflow. If the
workflow was launched from a Call Workflow task, the initial project
is the project context at the time the Call Workflow task was exe-
cuted. Note that asynchronous workflows run with a setting of ‘no
project’.
The active project does not affect the ability of a workflow to access
records, because workflows are able to access all records without
being affected by project-related restrictions. However, Query tasks

© Copyright IBM Corporation 2011. Projects | 681

can filter results based on the active project. See “Set Project Task”
on page 492 for details.
Initially, new records are not assigned to any given project. When a
workflow task creates a new record, you can specify that the new
record should be associated with a triCapitalProject record in the follow-
ing ways:
• A workflow task can set the project on a record to a specified
project. The specified project can be either the Company Level or
provided by the project of another record.
• A workflow task can specify that a new record can be associated
with the same triCapitalProject record as another record.
• A workflow task can specify that a new record can be associated
with a specific triCapitalProject found through a query task or
another task.
Use a Set Project task to change the workflow’s current project con-
text or to change a record’s project. The Set Project task is described
on page 492.

Reports
There are three types of reports: System Reports, Community
Reports, and My Reports. As shown in Figure 13-16, you can control
the access to each report type for each Group. These options control
access to the tabs in the Report Manager, as shown in Figure 13-17 on
page 682.
If a Group has No Access to System Reports, users in that Group will not
see the System Reports tab in the Report Manager. If a Group has Full
Access to System Reports, users in that Group will be able to manage
(create, edit, copy, delete) and share any System Report.

Attention: Be careful to which Groups you give System Report

Full Access because users with such access can poten-
tially break the application with this access level.
If a Group has No Access to Community Reports, users in that Group will
not see the Community tab in the Report Manager. If a Group has View
Access to Community Reports, users in that Group will be able to run
those reports and copy those reports into their own My Reports tab.

©682 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Figure 13-16. Report Manager Security Options

Please note that Community Reports are actually System Reports that
have been designated as useful for end users to be able to copy and
modify for their own use as My Reports. In order to manage a Commu-
nity Report, a user must belong to a Group with access to System
Reports.
If a Group has No Access to My Reports, users in that Group will not see
the My Reports tab in the Report Manager, and users in that Group
will not be able to create or manage their own personal reports. If a
Group has Manage permission to My Reports, users in that Group will be
able to create, edit, copy, and delete their own personal reports. If a

© Copyright IBM Corporation 2011. Reports | 683

Figure 13-17. Report Manager Tabs

Group has Manage and Share permission to My Reports, users in that

Group also will be able to share their reports with other Groups.
The Copy as Community Report action, shown in Figure 13-17, only is
available to users belonging to a Group with Full Access to System
Reports. The Share Report action only is available to users belonging
to a Group with Manage and Share permission for My Reports.
In addition to controlling the access to the tabs in the Report Man-
ager through the Security Manager, you also can specify an additional
granularity of security for individual reports, based on the type of
report, through the Security sub-tab in the report’s definition.
For System Reports, there is no Security sub-tab. Groups either have
full access or no access to System Reports.
For Community Reports, the Security sub-tab can be used to allow
only specific Groups view access to that Community Report. For
example in Figure 13-18, this Community Report is configured to show
up in the Community tab for members of the IBM TRIRIGA Application
Administrator and IBM TRIRIGA Application Builder Groups (assuming
those Groups have View Access to the Community tab), but will not show
up in the Community tab for other Groups. Note that if the Security
sub-tab is empty, the Community Report is available to all Groups
that have access to the Community tab.
My Reports also has a Security sub-tab, as shown in Figure 13-19 on
page 686. If a user belongs to a Group with Manage and Share permission
for My Reports, that user can share personal reports with members of
other Groups. By default, shared Groups have View Access, i.e., they
can run the report. However, the owner of the report also can spec-
ify more granular levels of access to shared reports. In Figure 13-19,

©684 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Figure 13-18. Community Report Security Sub-Tab

the user has shared this report with members of three security
groups, IBM TRIRIGA Facilities Executive - Retail, IBM TRIRIGA Facili-
ties Manager, and IBM TRIRIGA Facility Assessment Manager. If the
user chooses, she can give one of the Groups All access, which effec-
tively grants that Group the same privileges as she has as the owner.
Note that the owner of a My Report always has view, edit, delete, and
copy access to his or her report.
The Report Manager has an Administration tab, shown in Figure 13-17
on page 682. This only displays for members of the Admin Group. The
Administration tab lists all My Reports for all users. In this tab, an
Administrator can change the owner of a report, or copy, delete, or
share My Reports. In addition, he or she can open individual My
Reports and update the Security sub-tab as needed.
For more details on Report Manager functionality, see the IBM TRIRIGA
Application Platform 3 Reporting User Guide.

© Copyright IBM Corporation 2011. Reports | 685

Figure 13-19. My Report Security Sub-Tab

Audit Trail
Some records may be considered so sensitive that you want to keep a
record of all changes made to them. A record of all changes made to
a record is called an audit trail.
These are the most common reasons for wanting an audit trail:
• People who have legitimate access to records may be tempted to
do something dishonest. This is most often the case when the
records in question are used to represent money or other things
that are worth money.

©686 | Chapter
Copyright 13: Security
IBM Corporation 2011.
 • There is an undesirable legal consequence if an improper change
to or action on a record is performed.
• There is a regulation or standard that requires you track changes
to records.
If any of these concerns is relevant to a record, it is important to have
an audit trail that tells who did what to each such record and when
they did it. Having an audit trail is a disincentive for dishonesty,
because it makes it easier to discover dishonest actions. An audit trail
removes speculation about what actually happened.
An audit trail is an historical record of everything that happened to a
record. Because it is an historical record, the information that is in an
audit trail cannot be altered or deleted.
There are two main reasons for not wanting an audit trail:
• Maintaining an audit trail increases the amount of time that an
operation takes. Saving the audit records takes additional time.
• Maintaining an audit trail can greatly increase the amount of stor-
age that an application uses. In addition to needing space to store
records, you need space to store the audit trail. The space
needed to store the history of everything that ever happened to a
record can be significantly larger than the record itself.
Support for audit trails is built directly into the IBM TRIRIGA Applica-
tion Platform. Though it is possible to implement audit trails as part
of an application’s business logic, IBM TRIRIGA strongly suggests that
you use the audit trail support that is built into the platform. There
are at least three reasons for this:
• An audit trail maintained by the platform is more secure than an
audit trail maintained by the application. An audit trail based on
an application’s business logic is only as reliable as the applica-
tion itself. If there are bugs or mistakes in the application, an
audit trail maintained by the application may not be accurate.
The accuracy of an audit trail maintained by the built-in audit
trail mechanism is unaffected by bugs or mistakes in an applica-
tion.
• It takes a lot more work to build the logic for an audit trail into an
application than it does to use the audit trail support that is built
into the platform.
• Though all audit trail mechanisms increase the amount of time it
takes an application to do things, an audit trail maintained by the

© Copyright IBM Corporation 2011. Audit Trail | 687

 platform’s built-in mechanisms will have less impact on perfor-
mance than an audit trail that is maintained by an application.
Setting up an audit trail for records created from a business object is
rather straightforward. You set the options for maintaining an audit
trail for records created from a business object by setting the rele-
vant properties of the business object using the Data Modeler. The
Data Modeler is described in Chapter 2.

©688 | Chapter
Copyright 13: Security
IBM Corporation 2011.
The properties of a business object are shown in Figure 13-20.

Figure 13-20. Business Object Properties

© Copyright IBM Corporation 2011. Audit Trail | 689

The following properties of a business object control the generation
of an audit trail for records created from the business object:
• If the Audit Actions check box is checked, when a user clicks a
sub action in a form that is editing a record created from this
business object, an audit record is created. Sub actions are
described on page 197.
Checking the Audit Actions check box enables the creation of
audit records that identify the sub action that was performed, the
user ID of the person who clicked the sub action, and when the
sub action was clicked. However, checking the Audit Actions
check box only enables the generation of audit records for sub
actions that you specify should be audited by checking their Log
check box. For audit records to be generated for a particular sub
action, the Log check box in the sub action’s properties must be
checked.
Check the Audit Actions check box for the Request for Informa-
tion (RFI) metrics and for reports in IBM TRIRIGA Workplace Per-
formance Management products.
• If the Audit Access check box is checked, every time a user uti-
lizes a form to view the contents of a record created from this
business object, an audit record is created.
• If the Audit Interactive Data radio button is selected, every time
a user uses a form to change the contents of a record created
from this business object, an audit record is made. The audit
record contains the user ID that made the change and the time of
the change. The audit record also contains the old value and new
value of every changed field.
• If the Audit All Data radio button is selected, an audit record is
made for every change to a record created from this business
object. This includes changes made by a user in a form, due to a
formula calculation or rollup calculation, or by a workflow. How-
ever, this does not include changes made if the record is modified
by an editable query.
• If the Require Explanation check box is checked, when a user uti-
lizes a form to change the contents of a record created from this
business object, the user is asked to enter a reason. If the Require
Explanation check box is checked, the system selects the Audit
Interactive Data property.
The reason given for the changes to the record is included in the
audit record along with the other information about the change.

©690 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Whether you are creating a new sub action or editing it, after you
click the appropriate action you will see a form that looks like
Figure 13-21. Check the Log check box to enable auditing of the sub
action.

Figure 13-21. Properties of an Existing Sub Action

Configuring the generation of audit records is only half of the IBM

TRIRIGA Application Platform’s built-in mechanism for maintaining an
audit trail. The other half is a mechanism for viewing audit records.
If a form is used to edit records for which audit records are gener-
ated for data access or changes, you will need to update that form to

© Copyright IBM Corporation 2011. Audit Trail | 691

show the Audit tab. To do so, revise the properties of the form for

Figure 13-22. Properties of a Form

the business object where you would like to see the Audit data and
check Show Audit Actions. The form properties are shown in
Figure 13-22.
Once the form has been published, the form will have a tab labeled
Audit. The purpose of the Audit tab is to display all the audit records
that contain data changes made to the record. The Audit tab looks
like Figure 13-23.
Three columns display in an Audit tab.
Modified By
Who made each set of data changes.

©692 | Chapter
Copyright 13: Security
IBM Corporation 2011.
 Figure 13-23. Audit Tab

Comment
If users are required to enter a reason for making changes to a
record through a form, the reason they enter appears in the
Comment column.
Modified On
When the data was changed.
TIP: You may not want everyone to see the contents of the Audit or
Audit Actions tabs. Access to those tabs is controlled through Group
permissions, just like any other tab.
To see details of the data changes that were made, click the hyper-
linked audit record that you want to see. This causes an Audit Details
window to pop up that looks like Figure 13-24.

Figure 13-24. Audit Details

© Copyright IBM Corporation 2011. Audit Trail | 693

The Audit Details window has these columns:
User Name
The person who made the change.
Field
The name of the field that was changed.
Old Value
The value of the field before it was changed. In this example, the
changes were made in the course of creating the record. Because
of this, the fields had no previous value, so in Figure 13-24 this
column is blank.
New Value
The value of the field after it was changed.
If a form is used to edit records for which audit records are gener-
ated as a result of clicking sub actions, the form will have a tab
labeled Audit Actions. The purpose of the Audit Actions tab is to dis-
play the audit records generated to record actions performed on the
record. The Audit Actions tab looks like Figure 13-25.

Figure 13-25. Audit Actions Tab

The Audit Actions tab shows every recorded sub action that has been
clicked on the record. The Audit Actions tab has three columns. The
first column shows the label of the sub action. The second column
shows who clicked the sub action. The third column shows when the
sub action was clicked. To allow a user to view this data, you need to

©694 | Chapter
Copyright 13: Security
IBM Corporation 2011.
update that form to show the Audit Actions tab. To do so, revise the
properties of the form for the business object where you would like to
see the Audit data and check Show Audit Actions. The form proper-
ties are shown in Figure 13-22.

Workflow Instances
Depending on your auditing requirements, it may be good enough to
know what sub actions have been clicked for records, when those sub
actions were clicked, and who clicked them. If you need to know what
workflows were launched as a result of the sub actions and what the
workflows did to records, you will need more information than is in
the Audit Actions tab.
The IBM TRIRIGA Application Platform provides a way for you to exam-
ine the actual workflows that ran in response to clicking sub actions
and see how they ran. The organization of this feature is based on the
fact that workflows run only in response to an action or system event
happening to a record. It allows you to see workflows that were actu-
ally run in response to something happening to specific records.
To be able to see workflows that were launched for a record, you will
need to:
• Decide which workflows are of interest.
• Specify that information about each running of those workflows
should be saved.
• Include a tab in appropriate forms for viewing the records of the
workflows that have run. The first step in enabling this feature is
to decide which business objects you need to modify.
In order for information to be saved each time a workflow is run, the
Save Workflow Instances check box in the workflow’s properties
must be checked. If this check box is not checked, no record will be
kept of when the workflow was run and what happened when it was
run. The Save Workflow Instances check box is discussed on
page 397.
If a workflow’s Save Workflow Instances check box is checked, every
time the workflow is run a copy of the workflow is kept with informa-
tion about how it ran. This saved information about a single running
of a workflow is called a workflow instance.

© Copyright IBM Corporation 2011. Audit Trail | 695

You can view all saved workflow instances for a workflow by using the
Workflow Builder. To do this, select the workflow of interest and then
click the List All Instances action.
For researching what a workflow did when it was run a particular time
with a particular record, you should include a Work Flow Instance tab
in a least some of the forms used to access the type of records that
are of interest. To configure a form to include a Work Flow Instance
tab, edit the form’s properties so that its Show Workflow Instance
check box is checked. The Show Workflow Instance check box is dis-
cussed on page 232.
A Work Flow Instance tab looks like Figure 13-26.

Figure 13-26. Work Flow Instance Tab

The Work Flow Instance tab shows the name of each workflow that
ran, the current status of the workflow, and when the workflow
started. There is no indication of what launched the workflow. You
will need to use the times sub actions were clicked and the times that
workflows were started to match them up.
The statuses showing in the Work Flow Instance tab are as follows:

©696 | Chapter
Copyright 13: Security
IBM Corporation 2011.
For synchronous workflows:
• Active (the workflow is currently running)
• Completed (the workflow has completed)
For asynchronous workflows:
• Aborted, Aborted-Warn (the workflow was aborted using the Stop
capability in the Administrator Console)
• Active (the workflow is currently running)
• Completed, Completed-Warn (the workflow has completed)
• Failed (the workflow encountered an error and could not con-
tinue; information about the problem was written to the System
Log)
• Skipped (the workflow would have run, but the Start Conditions
were not satisfied)
• Stopped, Stopped-Warn (the workflow executed a Stop task)
• Waiting, Waiting-Warn (the workflow is waiting for a user (user
action or approval task))
If Warn is on the status it means a problem was encountered, infor-
mation was written to the System Log, and the workflow continued
processing.
The workflow names in the Work Flow Instance tab are hyperlinks. If
you click a workflow name, the workflow editor pops up to show the
actual workflow that was run. Even if the workflow has changed since

© Copyright IBM Corporation 2011. Audit Trail | 697

 when it was run, you will be looking at the actual version of the work-
flow that was run.

Debugging
Workflows
The workflow trace you
see in the Work Flow
Instance tab can be very
useful in debugging a work-
flow, since dashed green
highlighting tells you the Figure 13-27. Workflow with Completed Tasks Highlighted
execution path that the
workflow followed. The workflow editor displays the workflow differently from when you
access it through the Workflow Builder. Workflow tasks that have
been performed are highlighted with a green dashed border. There is
an example of this in Figure 13-27. Looking at the highlighting, you
can see the path that was taken through the workflow when it ran.
If a workflow step was started but has not finished, it is highlighted
with a red dashed border.

Lifetime of Workflow Instances

The IBM TRIRIGA Application Platform does not keep workflow
instances indefinitely. The Cleanup Agent discards workflow instances
after a specified number of days have elapsed. The number of days
that the platform keeps workflow instances is determined by the plat-
form’s configuration properties.
The IBM TRIRIGA Application Platform’s configuration properties are
discussed in the book IBM TRIRIGA Application Platform 3 Installation
and Implementation Guide.

©698 | Chapter
Copyright 13: Security
IBM Corporation 2011.
About Audit Trails
By auditing the actions that people perform on a record and the
changes that people make to its data, it is possible to have a detailed
and accurate audit trail that allows you to determine exactly how the
record came to have its current data and state.
There are some rules that you must observe to ensure the integrity of
audit trails produced by the IBM TRIRIGA Application Platform:
Make changes to an application only when people are not using it.
It is a good idea to keep people from using an application while it
is being changed, just to be sure of getting consistent results.
Another reason to keep people from using an application while it
is being changed has to do with accurately interpreting audit
trails.
It is important to know whether the consequences of clicking a
sub action happened before or after a change to the way an appli-
cation works. If people are using an application at the same time
it is being changed, it may become difficult to know if an action
and its consequences happened before or after a change. If the
change affected which workflows are launched by the action, it
may not be possible to know which workflows were launched by
an action.
Restrict access to the Data Modeler.
Even if you are only auditing data changes, it is still important to
restrict access to the Data Modeler.
Through the Data Modeler, it is possible to turn off generation of
audit records for all records created from a business object and
then later turn the generation of audit records back on. While the
generation of audit records is turned off, someone can change
data in records without the change being recorded in an audit
trail. Also, there is no record in the audit trail that generation of
audit records was turned off or on.
Security settings should prevent people from deleting records that
you are keeping an audit trail for.
When a record is deleted, the audit records associated with the
record are also deleted.
Instead of designing audited records to be deleted, design them to
have a retired state that keeps them from being seen or used in
most contexts.

© Copyright IBM Corporation 2011. Audit Trail | 699

Avoid designing records that are likely to accumulate many audit
records.
There is no way for workflows to access audit records. They must
be interpreted manually. If a record accumulates a large number
of audit records, it may not be practical to interpret the audit
trail.
To avoid this problem, try to design records so that they do not
accumulate a large number of audit records.
Changes to records that have an audit trail only should be initiated
from a form.
Data audit records are only created by changes made to a record
through a form.
Audit records are not created when records are created or modi-
fied by the Data Integrator.
If you cannot live within these rules, but you still need to have a
secure audit trail, there is another option that we suggest. You can
use your database manager to keep an audit trail.
The platform creates a database table for each business object.
Records created from a business object are stored in the database
table that corresponds to the business object used to create the
record.
The details of auditing database tables vary with the database soft-
ware you are using. You need to consult your database administrator
or database documentation for the specifics.

Filtering Visible Records

Queries with filtering can be used to limit the records that are visible
in navigation items, query sections, and through Find and Add
actions. It is possible to carefully craft the queries that a person will
use so that they only will see those records that you want them to
see.
Limiting people’s access to records this way has one important advan-
tage. It gives you a great degree of flexibility in how you filter a per-
son’s view of records. However, it has enough drawbacks that you
should only use this technique as a last resort. Here are some of the
problems with this technique:

©700 | Chapter
Copyright 13: Security
IBM Corporation 2011.
 • Because multiple queries must be made consistent to present a
consistent view of things, errors are more likely when using this
security technique than with most other security techniques.
• Because the policy governing what records a person is allowed to
see may be replicated in multiple queries, this technique makes
changing the policy governing what a person can see more diffi-
cult to change and keep consistent.

Workflows Bypass Security

Workflows are not subject to any security restrictions. If you want any
filtering based on organization or geography, you must explicitly spec-
ify those restrictions in the workflow or in queries that the workflow
uses.

© Copyright IBM Corporation 2011. Workflows Bypass Security | 701

©702 | Chapter
Copyright 13: Security
IBM Corporation 2011.
Chapter 1
In this chapter: CHAPTER 14
• How to transfer data
between records and Excel
spreadsheets for offline
processing.
Offline Excel
Spreadsheets

An IBM TRIRIGA Offline form is an Excel spreadsheet with fields on the

sheet mapped to fields from an IBM TRIRIGA business object. Through
the mappings on this sheet, data in the IBM TRIRIGA application can
be exported into an Excel sheet for review and updates, and data can
be collected into the spreadsheet for import into the IBM TRIRIGA
application. Once the fields on the sheet are mapped to IBM TRIRIGA
business object fields, workflow tasks can process this data in the
application. This is useful for people who want to work with data in
spreadsheets outside of the platform environment.
In order for the IBM TRIRIGA Application Platform to copy data into or
out of an Excel spreadsheet, the spreadsheet must be in a binary field
of a record. There are specialized workflow tasks for copying data
into or out of a spreadsheet. In order for the specialized workflow
tasks to work with an Excel spreadsheet, the spreadsheet is required
to have a special organization.
NOTE: If using IBM TRIRIGA Connector for Offline Forms via Microsoft
Exchange 2007, be sure to configure Plain text logon (Basic authentication) in
Microsoft Exchange > Server Configuration > Client Access > IMAP4
Properties > Authentication tab.
The process flow in Figure 14-1 on page 704 describes the outbound
process:
The process flow in Figure 14-2 on page 705 describes the inbound
process.
The rest of this chapter describes the components of an IBM TRIRIGA
Offline form. The steps to create an IBM TRIRIGA Offline form include
the following:
• Create the Excel template for a specific business object.

© Copyright IBM Corporation 2011. 703

 Figure 14-1. Process Flow - Outbound - Round Trip

• Create a Binary field definition in that business object. This is

where the offline form instances will be stored a run time. See
“Binary” on page 95 for details on creating a Binary field.
• Define the IBM TRIRIGA Object Map to map the Excel template
cells to IBM TRIRIGA form fields. See “IBM TRIRIGA Object Map” on
page 705.
• Upload the Excel template with the IBM TRIRIGA Object Map into
IBM TRIRIGA. The Excel template records for the standard IBM
TRIRIGA applications are in the triOfflineContent business object.
• Use the Populate File workflow task to populate data from IBM
TRIRIGA into the Excel sheet. See “Populate File Task” on
page 713.

704 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
Figure 14-2. Process Flow - Inbound - Staging Table Validation

• Use the Distill File workflow task to distill the Excel data into the
IBM TRIRIGA application. See “Distill File Task” on page 722.

IBM TRIRIGA Object Map

To use an Excel spreadsheet with workflow tasks that copy data into
or out of it, the spreadsheet must contain a worksheet named Tririga
Object Map. The rows of this worksheet specify how to map values
from the Excel spreadsheet into records or vice versa. The relation-
ships specified in this worksheet between data in Excel spreadsheets
and data in records are collectively called a mapping. See Figure 14-3
for an example of an IBM TRIRIGA Object Map.
The first non-empty column of each row determines the purpose
served by the rest of the columns in the row. For example, if the first
column in a mapping row contains the value Field, then the row con-
tains information on how the value of a particular cell or cells in the

© Copyright IBM Corporation 2011. IBM TRIRIGA Object Map | 705

 Figure 14-3. IBM TRIRIGA Object Map

Excel spreadsheet map to a field in a record. This value in the first

non-empty value of a mapping row is called the row’s tag. In the pre-
vious example, one could just refer to the Field tag.
Empty rows in the worksheet are ignored, as are empty cells before
the tag on each row. On a given row, the meaning of cells after the
tag depends on the type of tag for that row. The cells to the right of a
row’s tag are called property cells, because they refer to the proper-
ties that define a particular tag. Each tag defines some number of
property cells, whose position is relative to the tag cell. For exam-
ple, if the tag that defines three properties is in column C, the prop-

706 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
erties for the tag will be in columns D, E, and F. If the tag were in
column A, the properties would be in columns B, C, and D.
Some tags in the mapping worksheet have a corresponding end tag.
This mechanism serves to enclose other tags between the given tag
and its corresponding end tag, giving the mapping a hierarchical
structure. Mapping in either direction starts with a root row. Various
tags in the mapping let the mapping engine navigate to other objects
related to the root through associations. Nesting these tags allows
navigation through multiple association hops. This document refers to
parent and child rows to describe these relationships. For example: if
we follow an association from the root row to row A, the root row is
the parent of row A and row A is a child of the root row. If we then
follow an association from the row A to row B, A is the parent of B and
B is the child of A.
All tag, object, field, association names, and the like are case sensi-
tive.

Records to Excel
This refers to the Tririga to Excel section in the Tririga Object Map on
the offline form. This section defines field mapping from IBM TRIRIGA
form fields to the offline form. The following describes the tags used
for mapping from records to an Excel spreadsheet:
Tririga to Excel
This tag is the root of the record to Excel spreadsheet mapping
and encloses all other tags in the map.
Properties:
None
End tag:
End
Selector
The Selector tag finds existing records associated to the parent so
that their data can be copied to the Excel spreadsheet.
Optionally, the Selector can specify a filter that compares a field
value in the records to a value in the map. It also can filter by
record type.
Sub-tags of this tag are applied to the records found.
Properties:
Association Name – The name on the parent side of the
association.

© Copyright IBM Corporation 2011. IBM TRIRIGA Object Map | 707

 Field Name – The name of the field in the child record to use in
the comparison.
Operator – The operator to use in the comparison. The only
supported value is =.
Filter Value – The value with which to compare the field value
from the child record.
Optional Properties:
Module Name – If this is specified, only records created by busi-
ness objects in the named module are included.
Object Type Name - Only records created by the specified busi-
ness object are included.
Query Section Name - Specifies the query section from which to
populate data. If present, the value must be in the next to
last column of the Selector row. If specified, you must provide
a Tab Name property. Query Section Name and Tab Name main-
tain the order of data in a query section. If specified, the pop-
ulate retrieves from the query defined in the query section
using the current record as the context record.
Tab Name - Specifies the name of the tab on the form that
contains the query section identified in Query Section Name. If
present, the value must be in the last column of the Selector
row. Query Section Name and Tab Name maintain the order of
data in a query section. If specified, the populate retrieves
from the query defined in the query section using the current
record as the context record.
End tag:
End Selector
Field
This tag defines how fields in records are mapped to cells in the
Excel spreadsheet. This tag can appear anywhere in the mapping
hierarchy. The field mapping is applied to the records that corre-
spond to that level in the hierarchy.
If there is more than one current record because the previous
Selector tag found multiple records, this tag will duplicate the row
of the referenced cell for each record and map the field from
each record into a cell in the copied row.
This action is coordinated with the sibling Field tags in the map-
ping. For example: Suppose the previous Selector tag found three
records. Also suppose there are two Field tags below the Selector
that reference cells in the same row of the document. The first

708 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
 Field tag maps field x to cell G4 and the second Field tag maps field
y to cell H4.
The mapping engine will make two copies of row 4 (plus the origi-
nal row makes three rows total) and insert them into the docu-
ment as rows 5 and 6. It will then map fields x and y from the first
record into cells G4 and H4, fields x and y from the second record
into cells G5 and H5, and fields x and y from the third record into
cells G6 and H6. Use this mechanism to create line items in the
Excel spreadsheets from line items in records.
Properties:
Section Name – The name of the section that contains the field
to be mapped. For smart section fields, specify the BO smart
section name, for example, triParkingClause.
Field Name – The name of the field in the current record(s)
from which data will be mapped.
Cell Reference 1 – A reference to the cell to which the data will
be copied.
End tag:
None

Excel to Records
This refers to the Excel to Tririga section in the Tririga Object Map on
the offline form. This section defines field mapping from the offline
form to IBM TRIRIGA form fields. The following describes the tags used
for mapping from an Excel spreadsheet to records:
Excel to Tririga
This tag is the root of the Excel spreadsheet to record mapping
and encloses all other tags in the map.
Properties:
None
End tag:
End
Association
This tag tells the mapping engine to create new child records
from a specified business object, trigger a specified action on the
new records, and associate them with the parent record. Field
tags within the Association tag define how data in the Excel spread-
sheet will be mapped into the newly-created child records.

© Copyright IBM Corporation 2011. IBM TRIRIGA Object Map | 709

 If Field tags contained within the Association tag reference multi-
ple values, then the Association tag will create multiple records.
The number of records created is equal to the maximum number
of values referenced by the enclosed Field tags.
Properties:
Association Name – The name to put on the parent side of the
association.
Module Name – The name of the module that contains the busi-
ness object that will be used to create records.
Object Type Name – The name of the business object that will
be used to create records.
Action – The name of the action to trigger on the newly-
created records.
End tag:
End Association
Selector
This tag is similar to the Association tag except that no new child
records are created. Instead, the Selector finds existing records
associated to the parent so they can be modified. Field tags within
the Selector tag define how data in the Excel spreadsheet will be
mapped into the child records found by the Selector.
Optionally, the Selector can specify a filter that compares a field
value in the child records to a value in the map. It also can filter
by record type. Use this mechanism to find a single associated
child in a list of children.
Properties:
Association Name – The name to put on the parent side of the
association.
Optional Properties:
Field Name – The name of the field in the child record to use in
the comparison.
Operator – The operator to use in the comparison. The only
supported value is =.
Filter Value – The value with which to compare the field value
from the child record.
Module Name – If this is specified, only records created by busi-
ness objects in the named module are included.
Object Type Name - Only records created by the specified busi-
ness object are included.

710 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
 End tag:
End Selector
Field
This tag defines how values in the Excel spreadsheet are mapped
to a single field in a record or records. This tag can appear any-
where in the mapping hierarchy. The field mapping is applied to
records that correspond to that level in the hierarchy.
If only one reference property is specified, a single value is
retrieved from the referenced cell in the spreadsheet and put into
the specified field in the records.
If a second reference is specified, the mapping engine collects all
values in the spreadsheet from the first reference (inclusive) to
the second reference (exclusive). The collected values will be set
to the given field in the records sequentially. This mechanism is
most useful inside an Association tag.
If a Field tag inside an Association tag references a range of three
values, the Association tag creates three child records and sets the
first value to the given field in the first created record, second
value to the second record, and third to the third. Use this mech-
anism to extract line items from the spreadsheet to create line
item records.
Excel formatted Time fields are correctly distilled into IBM
TRIRIGA.
Duration fields can be distilled when they are entered into the
Excel spreadsheet in the following format where each element is
optional: y Year(s) m Month(s) w Week(s) d Day(s) h Hour(s) m
Minute(s) s Second(s). For example, 2 Year(s) 3 Month(s) 4 Day(s)
and 5 Month(s) 2 Week(s) 7 Hour(s) 15 Minute(s).
Properties:
Section Name – The name of the section that contains the field
to be mapped. For smart section fields, specify the BO smart
section name, for example, triParkingClause.
Field Name – The name of the field to which data will be
mapped.
Cell Reference 1 – A reference to the cell that contains the data
to be put into the field.
Optional Properties:
Cell Reference 2 – A reference to a second cell in the docu-
ment. Specifying a second reference indicates that this Field
tag is working with a range of values from the document.

© Copyright IBM Corporation 2011. IBM TRIRIGA Object Map | 711

 End tag:
None
For a referenced smart section, such as a live link or reference only
section, you can have the distill look up an existing record to use as
the association in the section. Instead of the Field name, use the key-
word OfflineFindById or they keyword OfflineFindByName and then refer-
ence the record Id or the published name of an existing record for the
distill to use as the associated record for the section. If you do not
use either OfflineFindById or OfflineFindByName, the distill creates a new
associated record based on the information in the Excel spreadsheet
and uses that for the section.
For a single row smart section when a row already exists on the smart
object being distilled to, the distill updates the existing smart sec-
tion row with the data in the Excel spreadsheet.
For a multiple row smart section when rows already exist on the
smart object being distilled to, the distill deletes all existing rows and
replaces them with the rows specified in the Excel spreadsheet.

712 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
Populate File Task
The purpose of the Populate File task is to copy record data into an
Excel spreadsheet as defined in the Tririga Object Map. The required
organization of the Excel spreadsheet is described on page 705 under
the heading “IBM TRIRIGA Object Map”. This task requires a binary
field to store the Excel spreadsheet that contains the mapping and
which is the target of the populate.
The Populate File task always uses UTF-8 encoding.
Figure 14-4. 
The shape for a Populate File task is shown in Figure 14-4. Populate File Shape
The form for a Populate File task is shown in Figure 14-5.

Figure 14-5. Populate File Properties

The properties form for a Populate File task is organized into four sec-
tions that have these purposes:
• Name and describe the workflow task.
• Specify the record that the data will come from.
• Specify the binary field in a record that will contain a template
for the Excel spreadsheet.

© Copyright IBM Corporation 2011. Populate File Task | 713

 • Specify the binary field in a record that will contain the Excel
spreadsheet that is created from the data in the record and the
template in the other binary field.
Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

Populate from Record

The second section of the Populate File task properties form is
labeled Populate from Record. The purpose of the Populate from
Record section is to specify the record that data will be copied from.
At the top of the Populate from Record section are fields used to
identify a target record. The target record is used to determine the
record from which data will be copied.
There are radio buttons below the fields. The way that the target
record is used to determine the record from which data will be cop-
ied depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of these possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-

714 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
 tem event. If the value of this field is Secondary BO, then the
Event record that triggered the event is the target record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record from which data will be copied.
When the properties form is first displayed, only the currently-
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record from which
data will be copied.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target record will be the record from which data
will be copied. When you select this radio button, a window pops
up that allows you to choose from the smart sections and locator
fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, a record associated with the target record will
be the record from which data will be copied. When you select
this radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.

© Copyright IBM Corporation 2011. Populate File Task | 715

 After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the target
records’ parent will be the record from which data will be copied.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.

716 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
 One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record that will be
the record from which data will be copied.

From Binary Field

The third section of the form for a Populate File task’s properties is
labeled From Binary Field. This section specifies a binary field in a
record that contains the Excel spreadsheet. This workflow task cre-
ates a copy of the spreadsheet in the specified field and copies data
into the copy. The Excel spreadsheet in the specified field is not mod-
ified.
The From Binary Field section has two radio buttons to specify the
record that contains the template Excel spreadsheet. These radio but-
tons are labeled:
Workflow Activity
If this radio button is selected, it means that the record that con-
tains the binary field that contains the Excel spreadsheet will be
associated with a preceding workflow task.
Existing Record
If this radio button is selected, it means that the binary field that
contains the Excel spreadsheet is contained in a record that exists
now, at the time you are editing this workflow.
The selection of one of these radio buttons determines what appears
in the From Binary Field section. Figure 14-5 on page 713 shows what
the From Binary Field section looks like when the Workflow Activity
radio button is selected.
When the Workflow Activity radio button is selected, the From
Binary Field section has fields to select a workflow task to which a
record that is associated that contains the Excel Spreadsheet.
Under the Workflow Activity radio button there are fields used to
identify a target record that is used to determine the record that con-
tains the Excel spreadsheet.

© Copyright IBM Corporation 2011. Populate File Task | 717

 There are radio buttons below these fields. The way that the target
record is used to determine the record that contains the Excel spread-
sheet depends on which one of the radio buttons is selected.
Here are descriptions of the fields used to determine the target
record:
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the system event is the target
record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under the these fields determine how the target
record will be used to determine the record that contains the Excel
spreadsheet.
When the properties form is first displayed, only the currently-
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-

718 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are descriptions of the radio buttons:
Use it
If this is selected, the target record will be the record that con-
tains the Excel spreadsheet.
Use its Reference
If this is selected, the record that contains the Excel spreadsheet
will be referenced by a smart section or locator field of the tar-
get record. When you select this radio button, a window pops up
that allows you to choose from the smart sections and locator
fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, the record that contains the Excel spreadsheet
will be associated with the target record. When you select this
radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Initialize from section in
the Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.

© Copyright IBM Corporation 2011. Populate File Task | 719

 You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the record
that contains the Excel spreadsheet will be the target record’s
parent.
When you select this radio button, a window pops up for you to
select the business object that is assumed to have been used to
create the parent record. This selection of a business object is not
used for filtering. It is used to allow this task to access the par-
ent’s fields.
The selection of a business object represents an assumption about
what kind of record the parent will be. Because of this assump-
tion, subsequent tasks will be able to access the parent record’s
fields. If the actual parent was not created from the assumed
business object, the task may fail if the actual record does not
have an expected field.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
Below the radio buttons is a read-only field labeled Object Type. The
value displayed in this field is the type of the record that values may
be copied from. If the record can have been created from any busi-
ness object in a particular module, then the name of the module
appears in the Object Type field.

720 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
At the bottom of the From Binary Field is a record labeled Field. This
field has a drop-down list that contains the names of the binary fields
in the type of record shown in the Object Type field. The binary field
selected as the value of the Field field is the field that will be
expected to contain the Excel spreadsheet.
If you want to initialize records with information that is determined
by the application’s configuration, you should select the option of
using an existing record in the From Binary Field section.
You specify the value for the Module and Object properties so that
this task knows what kind of record you want to copy values from.
Then click the Record link to find the specific record that contains the
template Excel spreadsheet.
Once you have specified the record that contains the Excel spread-
sheet, you then specify the binary field in the record that contains
the spreadsheet by selecting its name as the value of the Field field.

To Binary Field
The fourth section of the form for a Populate File task’s properties is
labeled To Binary Field. This section specifies a binary field in a
record in which this workflow task will put a copy of the template
Excel spreadsheet that has had data copied to it.
Except for the fact that this section is used to specify the binary field
that will contain this workflow task’s result, the fields in this section
function identically to the corresponding fields in the From Binary
Field section.

© Copyright IBM Corporation 2011. Populate File Task | 721

 Distill File Task
The purpose of the Distill File task is to copy offline data into IBM
TRIRIGA records as defined in the Tririga Object Map spreadsheet. The
required organization of the Excel spreadsheet is described on
page 705 under the heading “IBM TRIRIGA Object Map”. This task
requires a binary field to store the Excel spreadsheet that contains
the mapping and which is the source of the distill.
The Distill File task always uses UTF-8 encoding.
Figure 14-6.  The shape for a Distill File task is shown in Figure 14-6. The form for a
Distill File Shape
Distill File task is shown in Figure 14-7.

Figure 14-7. Distill File Properties

The properties form for a Distill File task is organized into three sec-
tions that have these purposes:
• Name and describe the workflow task.
• Specify the record that the data will be copied to.
• Specify the binary field in a record that will contain the Excel
spreadsheet.

722 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
Here are descriptions of the fields in the first section:
Label
This is the label used to identify this task. This field’s text
appears on the shape in the drawing that represents this work-
flow task. Use the standards in “Workflow Naming Standards” on
page 388.
Description
A description of this task goes in this field.

Distill to Record
The second section of the Distill File task properties form is labeled
Distill to Record. The purpose of the Distill to Record section is to
specify the record that data will be copied to.
At the top of the Distill to Record section are fields used to identify a
target record. The target record is used to determine the record to
which data will be copied.
There are radio buttons below the fields. The way that the target
record is used to determine the record to which data will be copied
depends on which one of the radio buttons is selected.
Here are descriptions of the fields:
Take the
This is a drop-down list that can have one of these possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the event is the target record.
• Assignee
If Assignee is selected, then the My Profile record of the user

© Copyright IBM Corporation 2011. Distill File Task | 723

 assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under these fields determine how the target record
will be used to determine the record to which data will be copied.
When the properties form is first displayed, only the currently-
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are the descriptions:
Use it
If this is selected, the target record will be the record to which
data will be copied.
Use its Reference
If this is selected, a record referenced by a smart section or loca-
tor field of the target record will be the record to which data will
be copied. When you select this radio button, a window pops up
that allows you to choose from the smart sections and locator
fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, a record associated with the target record will
be the record to which data will be copied. When you select this
radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was

724 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
 selected appears at the bottom of this section in the Object Type
field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. This option is
also useful when the association defined in the Data Modeler was
to the base business object and you do not know which type of
business object in a module is selected at runtime.
When you select this radio button, you must specify a module,
unless the module whose name appears to the right of the icon
is the module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears in
the drop-down list to the right of the module name, then the
record on the other end of the association must have been cre-
ated from the named business object. If -Any- appears in the drop-
down list, then the record on the other end of the association may
have been created from any business object in the named mod-
ule.
To specify that a particular association name is required, click the
icon. A list of the association types defined in the List Man-
ager pops up. Click the association name that you want to appear
to the right of the icon. To retrieve association records that
are not restricted to a particular association name, click -Any-
which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the target
records’ parent will be the record to which data will be copied.
When you select this radio button, a window pops up for you to
select the business object that was used to create the parent
record. This selection of a business object is not used for filter-
ing. It is used to allow other tasks to access the parent’s fields.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the

© Copyright IBM Corporation 2011. Distill File Task | 725

 module’s base business object (the one with the same name as
the module).
At the bottom of the section is a read-only field labeled Object Type.
The value displayed in this field is the type of the record that will be
the record to which data will be copied.

From Binary Field

The third section of the form for a Distill File task’s properties is
labeled From Binary Field. This section specifies a binary field in a
record that contains the Excel spreadsheet from which data will be
copied. The Excel spreadsheet in the specified field is not modified.
The From Binary Field section has two radio buttons to specify the
record that contains the Excel spreadsheet. These radio buttons are
labeled:
Workflow Activity
If this radio button is selected, it means that the record that con-
tains the binary field that contains the Excel spreadsheet will be
associated with a preceding workflow task.
Existing Record
If this radio button is selected, it means that the binary field that
contains the Excel spreadsheet is contained in a record that exists
now, at the time you are editing this workflow.
The selection of one of these radio buttons determines what appears
in the From Binary Field section. Figure 14-7 on page 722 shows what
the From Binary Field section looks like when the Workflow Activity
radio button is selected.
When the Workflow Activity radio button is selected, the From
Binary Field section has fields to select a workflow task to which a
record is associated that contains the Excel Spreadsheet.
Under the Workflow Activity radio button there are fields used to
identify a target record that is used to determine the record that con-
tains the Excel spreadsheet.
There are radio buttons below these fields. The way that the target
record is used to determine the record that contains the Excel spread-
sheet depends on which one of the radio buttons is selected.
Here are descriptions of the fields used to determine the target
record:

726 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
Take the
This is a drop-down list that can have one of three possible val-
ues:
• Business Object
If Business Object is selected, then the record associated with
the task specified by the field to the right of this one will be
the target record.
• Secondary BO
This option is available if the workflow is launched in response
to an Associate or De-Associate system event. If the value of
this field is Secondary BO, then the record at the other end of
the association is the target record.
This option is also available if the workflow is launched in
response to a SCHEVENTCREATE, SCHEVENTSTART or SCHEVENTEND sys-
tem event. If the value of this field is Secondary BO, then the
Event record that triggered the system event is the target
record.
• Assignee
If Assignee is selected, then the My Profile record of the user
assigned to the task specified by the field to the right of this
one will be the target record.
of Task
The value of this field is the label of the task that the target
record will be associated with.
The radio buttons under the these fields determine how the target
record will be used to determine the record that contains the Excel
spreadsheet.
When the properties form is first displayed, only the currently-
selected radio button is visible. There is a button to the left of the
visible radio button. Clicking the button alternately makes all the
radio buttons visible or just the selected radio button visible.
The following descriptions explain the meaning of the radio buttons.
There are fields that appear to the right of some of the radio but-
tons. These fields contain additional information needed for the
choice represented by the radio button.
Here are descriptions of the radio buttons:
Use it
If this is selected, the target record will be the record that con-
tains the Excel spreadsheet.

© Copyright IBM Corporation 2011. Distill File Task | 727

 Use its Reference
If this is selected, the record that contains the Excel spreadsheet
will be referenced by a smart section or locator field of the tar-
get record. When you select this radio button, a window pops up
that allows you to choose from the smart sections and locator
fields in the target record.
After you have selected this radio button, the name of the
selected smart section or locator field is displayed in a read-only
field to the right of the radio button.
Use its Association
If this is selected, the record that contains the Excel spreadsheet
will be associated with the target record. When you select this
radio button, a window pops up that allows you to specify the
type of association to use. It allows you to identify the associa-
tion by the type of record that must be on the other end of the
association and optionally the name of the association.
After you have selected this radio button, if you specified an asso-
ciation name, the association name is displayed in a read-only
field to the right of the radio button. The type of record that was
selected appears at the bottom of the Initialize from section in
the Object Type field.
Use any Associated BO from Module ____ of type ____
This option is useful when you want to specify an associated
record without specifying which association to use. When you
select this radio button, you must specify a module, unless the
module whose name appears to the right of the icon is the
module that contains the business object used to create the
record on the other end of the association. If that is not the cor-
rect module, then click the icon. A list of modules will pop up.
Click the correct module.
You may also specify that the record on the other end of the asso-
ciation must have been created by a particular business object in
the specified module. If the name of a business object appears to
the right of the icon, then the record on the other end of the
association must have been created from the named business
object. If nothing appears to the right of the icon, then the
record on the other end of the association may have been cre-
ated from any business object in the named module.
To specify what appears to the right of the icon, click the
icon. A list of the business objects in the named module pops up.

728 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
 Click the business object that you want to appear to the right of
the icon. If you want nothing to appear after the icon, click
-Any- which appears at the top of the list.
Use its Parent
If the target record is created from a business object that is part
of a hierarchy module and this option is selected, then the record
that contains the Excel spreadsheet will be the target record’s
parent.
When you select this radio button, a window pops up for you to
select the business object that is assumed to have been used to
create the parent record. This selection of a business object is not
used for filtering. It is used to allow this task to access the par-
ent’s fields.
The selection of a business object represents an assumption about
what kind of record the parent will be. Because of this assump-
tion, subsequent tasks will be able to access the parent record’s
fields. If the actual parent was not created from the assumed
business object, the task may fail if the actual record does not
have an expected field.
One of the choices for the business object that created the par-
ent is -Any-. Choosing this will be the equivalent of selecting the
module’s base business object (the one with the same name as
the module).
Below the radio buttons is a read-only field labeled Object Type. The
value displayed in this field is the type of the record that values may
be copied from. If the record can have been created from any busi-
ness object in a particular module, then the name of the module
appears in the Object Type field.
At the bottom of the From Binary Field is a record labeled Field. This
field has a drop-down list that contains the names of the binary fields
in the type of record shown in the Object Type field. The binary field
selected as the value of the Field field is the field that will be
expected to contain the Excel spreadsheet.
If you want to initialize records with information that is determined
by the application’s configuration, then you should select the option
of using an existing record in the From Binary Field section.
You specify the value for the Module and Object properties so that
this task knows what kind of record you want to copy values from.

© Copyright IBM Corporation 2011. Distill File Task | 729

 Then click the Record link to find the specific record that contains the
template Excel spreadsheet.
Once you have specified the record that contains the Excel spread-
sheet, you then specify the binary field in the record that contains
the spreadsheet by selecting its name as the value of the Field field.

730 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
Using E-Mail
Typically when using the IBM TRIRIGA Connector for Offline Forms
processing functionality, you will want to use e-mail to send popu-
lated Excel files. The system can then use the populated Excel file to
update records.
The e-mail capabilities used for offline processing are not the same as
those used for notifications and do not support the same features as
available for notifications.
To configure the IBM TRIRIGA Application Platform to receive incom-
ing e-mail, you must first set up the SMTP server for your installation.
Details on how to set up the SMTP server can be found in the IBM
TRIRIGA Application Platform 3 Installation and Implementation
Guide. Next, you must set up at least one incoming e-mail address for
the system to listen for.
To create or modify incoming e-mail settings, navigate to Tools > Sys-
tem Setup > System > Incoming Mail Config. It should look like
Figure 14-8.

Figure 14-8. Managing Incoming Mail Config

You can use the Add or Edit actions to create or edit Incoming Mail
Config records.
If you add an Incoming Mail Config record, you will see a form that
looks like Figure 14-9. If you wish to have the IBM TRIRIGA Applica-
tion Platform listen for e-mail on multiple user account / folder com-
binations, set up an Incoming Mail Config record for each
combination.
The following explains the sections and fields in an Incoming Mail Config
record:

© Copyright IBM Corporation 2011. Using E-Mail | 731

 Figure 14-9. Incoming Mail Config Form

UID
This field stores the control number for this record assigned by
the system.
Host
This field stores the name of the host server that will received the
incoming e-mail.
Username
This field stores the user name that will receive the e-mail on the
host server.
Password
This field stores the password for the user that will receive the e-
mail on the host server.
Action
This field stores the name of the action that will be called on the
EmailMessage when a message is received for this user. Often this
field’s value is CREATE.
MailServerType
Select the mail server type from the drop-down list. pop3 is the
default.
When an e-mail is received for this account, a new EmailMessage record
is created. Additionally, new records are created for each attach-
ment to the message and for each e-mail address associated with the
message. The EmailAddress and EmailAttachment records are associated
to the EmailMessage record. Once these records are created and the
action specified is triggered, the EmailMessage record is moved from

732 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
the null state. Attach a workflow to the Action triggered to process
this e-mail and distill any attachments.

© Copyright IBM Corporation 2011. Using E-Mail | 733

734 | Chapter 14: Offline Excel Spreadsheets © Copyright IBM Corporation 2011.
 Index

Assignee from task, 412

Associate, 212
$$CURRENTTIME$$, 427 Associate using, 465
$$DAY$$, 427 Associated Business Object, 76
Associated To, 462
A association, 20, 26
Association List, 22
A List, 441 Association Module (start task), 401
Access All Profiles, 666 Association Name, 462
Action, 192, 408 Association Name (start task), 401
action, 30, 187, 209, 400 Association String, 99, 102
Action Labels, 202 Association Type, 425
Actions, 301 association type, 62
Active Project, 277, 676 association types, 62
Add, 49 Associations tab, 231
Add Section, 238 asynchronous, 207
Add Sub Action, 197 Asynchronous Concurrence, 396
Add Through Find Query, 84 asynchronous workflow, 401
Add Transition, 191 Attribute Picker, 429
Admin Group, 672 attribute picker, 431
Advanced Color Picker, 111 Attribute Type, 54
After, 448, 450, 459, 461 Audit Access, 30, 690
All Iterations, 566 Audit Actions, 690
Allow to Bookmark to create record, 231 Audit Actions (business object), 30
Allow to Bookmark to specific record, 231 Audit All Data, 30, 690
ANY, 397 Audit Interactive Data, 30, 690
-Any-, 397 audit trail, 30, 686
Append Results, 571 Authentication, 655
Application Access Permission, 670, 672 Auto Refresh, 280
Apply, 195, 237, 242 Autocomplete, 154, 272
Approval History, 31 auto-populate, 42, 57
Approval Task, 414 Autosort, 195
approval task, 414
Assign Value, 570
Assign Variable, 549 B
Assigned, 309 base business object, 25, 72
Assigned To, 309 base currency, 180

© Copyright IBM Corporation 2011. | 735

Based on Prefix, 55, 56 Col Span, 245, 258
Basic Color Picker, 111 Color, 111
Before, 448, 450, 459, 461 Column Filters, 338
Binary, 95 Column Sequence (field), 43
BO Label, 146 Column Use, 335
BO Mapping, 48, 181 Community Reports, 682
BO Publish Notification, 59 Company Level Project, 109
BO Record Id, 146 Comparison, 270
BO Type Id, 146 Comparison Association, 271
BO Type Name, 146 Concurrence, 207, 395, 574
Boolean, 96, 97 Condition Builder, 521
Border, 260 constant, 184, 427
Break, 536 Constant Text, 54
Break Properties, 536 Constant Value, 54, 202
Break Scope, 537 Consultant, 656
Break Task With Round Interior, 538 Container Task, 305
Break Task With Square Interior, 538 Contains, 448, 450, 459, 461
Business Object, 220 Contains - Case Sensitive, 448, 459
business object, 19, 21, 22, 26, 585 Content Field, 261
audit actions, 30 Continue, 536
base, 25 Control Number, 54, 113, 114
copy, 32 Controlling Block Task, 214
description, 28 Conversion Factor, 171
has calendar, 29 Conversion Group, 182
name, 28 Conversion Offset, 171
Business Object (data type), 98 Copy, 221, 382
business process, 21 Copy as Community Report, 684
Copy Section, 241
C Copy Tab, 236
Correlation, 565
Calculate Excel, 231 Cost, 56
calendar, 29 Country, 21
Call Workflow Task, 207, 218 Create Base Field, 137, 181
Callers, 552, 553 Create the association from, 467
Calling Workflows Parameter Check, 552 Created DateTime, 146
Cascade Read-Only, 66 Created DateTime (Number), 148
Change Project for Records from Record, 493, cst, 13
502 Currency Conversion Manager, 178, 179
Change Project for Records to Company Currency Symbol field, 174
Level, 493, 498 Current Block, 537
children, 583 Custom Workflow Tasks, 310
City, 21 Cut, 598
Class, 588, 589
Class or Ejb Name, 193
Classification, 96, 100–109, 124, 164, 584
D
Classification Rollup, 110 Data, 337
Clear, 569, 571 Data Access Permission, 669, 670, 672
Close Window, 193 Data Alignment, 256

736 | : © Copyright IBM Corporation 2011.

data association, 20
Data Dictionary Field Search, 38
E
Data Field, 248, 251 Edit, 521
Data Integrator, 638 Edit Map, 424
Data Modeler, 19, 22, 104, 221 Edit Module, 24
Data Section, 251 Employee, 656
Data Section Actions, 349 Encrypt - Reversible, 144
Data Style Class, 256 Encrypt Non-Reversible, 144
Data Type, 93 End Task, 518
DataConnect, 58, 537, 561 End With, 448, 450, 459, 461
DataConnect Agent, 213 End With - Case Sensitive, 448, 459
DataConnect Key, 81 Equals, 448, 449, 459, 460
DataConnect Task, 574 Error, 537
Date and Time, 117 Estimate Start Date from System Date, 412
De-Associate, 212 Estimated Start Date from Field, 412
Default Display, 193 Excel, 232, 705
Default UOM, 137 Exchange Date, 182
Defines Dependency, 307 Exclusion, 199
Delete, 44, 221, 383 Existing Record, 419, 437, 451, 462, 468, 472,
Delete BO, 60 483, 487, 623, 648, 717, 726
Delete Project, 679 Expected Time to Complete, 412
Deleting Business Objects, 59 Export Usage, 45, 220, 384
Delimiter for Control Number, 55 External Contact, 656
Delta Precision, 255 Externally Managed, 29
Delta Type, 254, 271
Demand, 324
Dependent, 84
F
Dependent Flag, 65 Fail Staging Rows, 538
Dependent List, 130 Field, 81
Dependent Section, 77 Name, 40
Description, 563 field, 19, 21, 49, 93, 185, 190, 201, 202, 429,
description (business object), 28 706
Description (field), 40 column sequence, 43
Description (List), 129 description, 40
Description (start task), 395 do not auto populate, 42
Disable Auto Recalculation, 417, 433, 467, 474, mobile field, 43
479, 486, 555, 564, 579 Mobile Field Seq., 43
Discard Temporary Data, 538 purpose, 40
Discussion Thread Section, 87 required, 42
Display Mask, 44, 137, 172 Result Column, 81, 131
Display Type, 253 result column, 43
Do Not Auto Populate, 42 Field Finder, 44
Document, 21 field label, 37
Does Not Contain, 448, 450, 459, 461 Field List, 22, 36
Does Not Contain - Case Sensitive, 448, 459 Field Name, 37
Duration, 119 Field Security, 672
Dynamic List, 130 Field Type, 37, 40
fields, 26, 88

© Copyright IBM Corporation 2011. | 737

Fields (List), 131 Has Staging Table, 29, 58, 59
Filter By, 128 hidden action, 199
Find link, 49 Hide Label, 259
Finish-to-Finish, 307 Hierarchical Fields, 256, 270
Finish-to-Start, 307 Hierarchical Parent, 256, 270
Flow Type, 536, 537 Hierarchical State, 257
form, 189 hierarchies, 584
Form Action, 248 hierarchy, 24, 581, 583, 585
Form Action Access Permission, 672 Hierarchy Module, 585
Form Builder, 3, 219 hierarchy module, 24, 485
Form Field, 248 Host, 732
Form Id, 146
Form Label, 146
Form Name, 146
I
form report, 5, 232 Ignorable For Nav. Overrides, 666
Form Security, 671 Image, 56, 122
Form Wizard, 224 Import, 195, 196
Formula, 184 Import from Business Object, 196
formula, 184 Import from State Family, 196
Formulas, 184, 417, 433, 466, 474, 479, 486, In, 448, 450, 459, 461
555, 564, 578 Include Child Record, 427
Forward Association, 62 Included In, 306
From Record, 506 Inclusion, 199
From Task, 571 Inclusion Exclusion, 198
Full Path, 101 Inherit from Parent, 672
Initial Pwd Reset, 657
G Initial State, 564
Initialize, 549, 551
Gantt section, 297 Input Width, 255
Geography, 21, 584 In-Sequence, 565
GeographyName, 674 Insert, 521
group, 411 Insert Row, 243
Group By, 330 Instruction, 235
Group By Section, 328 Integration, 399, 527
Group Seq, 258 Invalid Parameter, 551
Groups Security Invalid Return Value, 551
Field, 672 Is Parent Of, 599
Form, 671 Is Predecessor, 307
Module, 669 Is Resource For, 307, 309
Tab, 672 Iterator task, 540
Tool, 670
K
H Kingdom, 588, 589
Has Calendar (business object), 29
Has Dependency, 307
Has Predecessor, 307
L
Has Resource, 307, 309 Label, 220, 252

738 | : © Copyright IBM Corporation 2011.

label Manager Query, 4
field, 37 Map From Records, 437
label (section), 76 Map To Records, 433
Label Only, 123 Maximum Size, 253
Label Style Class, 252, 256, 333 Meeting, 21
Language (List), 130 metadata, 9, 19, 21
launch (workflow), 209 metadata association, 20
Left Side Data Section, 449 Method Name, 193
Less Than, 448, 449, 459, 460 Minimum Size, 253
Less Than or Equals, 448, 459 mobile field (field), 43
life cycle, 187, 189 Mobile Field Seq. (field), 43
life cycle diagram, 188, 202 Modified DateTime, 146
link, 88–91 Modified DateTime (Number), 147
business object Module, 563, 568
link, 28 module, 19, 21, 22, 24, 99, 130, 152
List, 96, 100, 124, 126, 164, 182 hierarchy, 24
Description, 129 name, 23
Fields, 131 Module (start task), 396
Language, 130 Module Security, 669
Module, 130 More Than, 448, 449, 459, 460
Name, 129 More Than or Equals, 448, 459
Object Type, 131 Move Section, 242
Sequence, 132 Multi Tab Sections, 275
Source Module, 131 Multiple-Record Smart Section, 74
Source Type, 130 multiplication, 185
Type, 129 My Profile, 42, 412
List Active Instances, 383 User Name, 656
List All Instances, 383, 397 My Reports, 682
List All Versions, 383
List Manager, 62, 127, 128, 129, 130, 182
List panel, 37
N
Live Link, 84 Name, 48, 49, 220, 235, 237, 242, 252
Living Thing, 589 name, 585, 598
Locate Using, 153 name (business object), 28
Location, 584 Name (Field), 37, 40
Locator Field, 86, 151, 153 Name (List), 129
Locator Module, 152 name (module), 23
Locator String, 154 name (section), 75
Lock Record For Other Users (start task), 397 Name (start task), 395
Lock Record For Other Users (user task), 406 Naming Convention
Log, 198 Design Elements, 13
Log check box, 691 Field Type Suffixes, 15
Lookup Query, 252 Name Prefix, 13
Loop task, 533 Publish Name, 17
Report, Query, Graph Keywords, 16
M Workflows, 388
Navigation Builder, 4
MailServerType, 732 Navigation Item, 3, 4

© Copyright IBM Corporation 2011. | 739

New, 220, 382, 595 People, 412
New Business Object, 26, 27, 104 People BO, 412
New List, 129 Per X Iterations, 566
New Project, 679 Per X Source Records, 423, 438
No Audit, 30 Permission, 668
non-display field, 584 Phylum, 588, 589
None, 423, 429, 438, 566 portal, 2, 5
Non-Working Events Section, 605 Portal Builder, 5
Not Equals, 448, 449, 459, 460 Position, 260
Not In, 448, 450, 459, 461 Pre-Create Workflow, 34, 209
Not Selected, 527 pre-create workflow, 34
Not Set, 550 Prefix, 54, 259
notes section, 86 Pre-Move Workflow, 326
null, 190, 417 Preview, 238
null state, 190 Print, 194
Number, 136 Print Preview Link, 272
project, 109
O Project Containment Disabled, 65
Project Id, 147
Object, 397, 563, 568, 571, 668 Project Name, 147
Object Browser, 22 Project Record, 495
Object Mapping, 154, 425 Propagate Integration Status, 400
Object Mapping Window, 425 Property, 22
Object State, 147 property cell, 706
Object Type (List), 131 Property panel, 48, 182
of Task, 408, 420, 434, 444, 455, 469, 475, 480, Publish, 382
489, 496, 500, 504, 507, 513, 542, 545, publish, 9
557, 577, 580, 650, 715, 718, 724, 727 Publish Business Object, 58
Open, 220, 595 Publish Name, 17
Open Gantt In New Window, 297, 301 Publish Workflow, 552
operator, 185 Purpose (field), 40
Or Its Children, 462
Organization, 584
OrgName, 674
Q
Orientation, 331 Quantity, 56
Overloading, 156 Query, 338
query, 28, 190
P
Pan Graphic, 195
R
Parameter, 218 Read Only, 111, 193, 260
Parameters, 402, 544, 547, 548 read-only, 374
parent, 583 Recalculate All, 418, 433, 467, 474, 479, 486,
Parent Id, 147 556, 565, 579
Parent List, 128 Recalculate as Needed, 417, 433, 466, 474, 479,
Password, 143 486, 555, 564, 578
Paste, 598 Record From Task, 462
Path, 147 Record Name, 147

740 | : © Copyright IBM Corporation 2011.

Record(s) with the Greatest value, 441 Section, 40
Record(s) with the Least value, 442 Associated Business Object, 76
RECORD_PROJECT_CONTAINMENT, 65, 493, 498 Discussion Thread, 87
RECURRENCE, 633 Smart
Red Dot Inside Break Task, 538 Multiple-Record, 74
Reference, 84 Single-Record, 74
Reference Only, 84 section
Reference With Modify, 84 label, 76
RefObject, 653 name, 75
Refresh Time in secs, 280 notes, 86
Remove the association, 465 report, 283
Remove the association from, 467 section properties
report, 28 Type, 240
Report Manager, 5 security, 30
Report Section, 283 Security License List, 663
Reports Tab, 232 Security Manager, 664
Require Explanation, 30, 690 Select, 80
Required, 97, 259, 403 Select Field, 49
Required (field), 42 Selected, 527
Required Field, 261 Selected Block, 537
Result Column (field), 43, 81, 131 Send Reminder to Assignee, 414
Retire, 383 Sequence (List), 132
Return Value, 218 sequence number, 83
Reverse Association, 62 Set From, 569
Reversible Encryption, 144 Set Workflow Project from Record, 493, 494
Revise, 383 Set Workflow Project to Company Level, 493, 494
Right Side Data Section, 449 Share Report, 684
Root, 102 Show Association, 231
root, 583 Show Embedded Link, 91, 241
Root Classification, 102, 252 Show Quantity, 585
Rounding Rule, 138, 173 Show Single Tab, 31, 231
Row Span, 257 Show UOM, 259
Single-Record Smart Section, 74, 241
S Smart Section, 74, 151, 268
Multiple-Record, 74
Save, 196 Single- Record, 74
Save BO, 29, 31 Smart Section Actions, 349
Save Mapping, 49 Sort List, 128
Save Module, 24 Sort Tab, 237
Save Sequence, 128 Source, 429
Schedule Task, 510 Source Details, 272
Scheduling Assumptions Section, 605 Source Module, 131
SCHEVENTCREATE, 213 Source Type (List), 130
SCHEVENTEND, 213 Stacking Section, 324
SCHEVENTSTART, 213 Staging Table Field, 43
Score Type, 254 Staging Table Key, 43
Scroll Life Cycle Diagram, 195 Stand Alone, 585
Secondary Action, 193 stand alone, 429

© Copyright IBM Corporation 2011. | 741

Start Column, 245, 258, 336 SYSTEM DC PROCESS JOB, 213
start condition, 210 system event, 208, 212, 400
Start Row, 245, 257, 335 Associate, 212
Start Task, 218 De-Associate, 212
start task, 218, 394 SCHEVENTCREATE, 213
Association Module, 401 SCHEVENTEND, 213
Association Name, 401 SCHEVENTSTART, 213
Description, 395 WF Q Accept, 213
Lock Record For Other Users, 397 System Geography, 666
Module, 396 System Organization, 666
Name, 395 System Read Only, 145
Start With, 54, 448, 450, 459, 461 System Reports, 682
Start With - Case Sensitive, 448, 459
Start-to-Finish, 307
Start-to-Start, 308
T
State, 21, 187 Tab Order, 259
state, 189, 198 Tab Security, 672
State Family Consists Of, 196 Table Sequence Attribute, 81, 83
State Family Rules, 195 tag, 706
state transition, 188, 190 Take the, 408, 419, 434, 444, 455, 468, 475, 480,
State Transition Action, 188, 208 489, 495, 500, 504, 507, 512, 542, 544,
State Transition Action Properties, 192 556, 576, 580, 650, 714, 718, 723, 727
State Transition Actions, 189 Target Business Object, 237
State Transition Attribute, 201 Target Form, 237
state transition diagram, 188 Target MultiTab, 242
state transition family, 189, 190, 194, 401 Target Tab, 242
State Transitions Panel, 189 Task Status, 537
Status, 220 Task Step, 565
Storage Precision, 138, 173 Tasks, 521
Style Manager, 244 Temporary Association, 85
Style Sheet Editor, 220 Temporary Data, 396, 574
sub action, 691 Text, 149
Sub Attribute Type, 145 The Sum of, 442
Sub Label Style Class, 335 Threshold Record Field, 280
SubAction Label, 198, 202 Threshold Source Attribute, 139
SubAction Label Details, 197 Time, 159
Subflow, 207 To, 468
Subflow Workflow, 218 To Records, 499, 503
Success, 537 Tool Security, 670
Suffix, 54 Transaction, 423, 566
Sum, 81 Transaction Processing, 214
sum field, 81 Transaction Scope, 214
Sum of, 442 Transactions, 214
Sum this Field, 140 transition, 188, 190
Supply, 324 Transition Properties, 194
synchronous, 207 triActualEndDT, 304
Synchronous Concurrence, 395 triActualPercentCompleteNU, 304
synchronous workflow, 34 triActualStartDT, 304

742 | : © Copyright IBM Corporation 2011.

triBaselineFinishDT, 304 Use it, 409, 420, 435, 445, 456, 469, 476, 481,
triBaselineStartDT, 304 490, 496, 500, 505, 508, 513, 545, 557,
triDependency, 306, 307 651, 715, 719, 724, 727
triDependencyRelationshipLI, 307, 308 Use its Association, 409, 421, 435, 445, 456, 470,
triFreeFloatDU, 305 476, 481, 490, 497, 501, 505, 508, 514,
triIdTX, 304 545, 558, 651, 715, 719, 724, 728
triLagInputDaysNU, 308 Use its Parent as the target, 410, 422, 436, 446,
triLagInputHoursNU, 308 457, 471, 477, 482, 491, 498, 502, 506,
triLagWorkingHoursNU, 308 509, 515, 546, 559, 652, 716, 720, 725,
triNameTX, 309 729
triPlannedEarlyFinishDT, 304 Use its Reference, 409, 420, 435, 445, 456, 469,
triPlannedEarlyStartDT, 304 476, 481, 490, 496, 501, 505, 508, 513,
triPlannedEndDT, 304 545, 557, 651, 715, 719, 724, 728
triPlannedLateFinishDT, 304 Use Source Project, 425
triPlannedLateStartDT, 304 Use Temporary Data, 564
triPlannedStartDT, 304 Used by DataConnect, 79, 81
triProjectPlanEndDA, 297 User, 411
triProjectPlanStartDA, 297 User Name (My Profile), 656
triResource, 308, 309 user task, 406
TRIRIGA Object Map, 705 Lock Record For Other Users, 406
triTask - Synchronous - Promote Task, 306
triTaskNameTX, 304
triTotalFloatDU, 305
V
Type, 249, 252 Validate, 225
Type (Field), 37 Validation, 137, 143
Type (List), 129 Value, 569, 571
Type Field, 261 Values Required, 79
Type property for section, 240 Variable, 216, 403, 570
Variable Assignment Task, 218
U Variable Definition Task, 218
Vertical Section, 77
UID, 732 View Workflow, 544
Umbrella Task, 305 Visible, 260
UOM Abbreviation, 171
UOM Decimal, 174
UOM Delimiter, 174
W
UOM Format, 174 -Warn, 697
UOM List, 137, 180, 181 WF DELETE FROM MGR, 213
UOM Type, 170 WF Q Accept, 213
URL (data type), 162 WF USER LOGIN, 213
Use, 139 WF USER LOGOUT, 214
Use any Associated BO, 409, 421, 435, 445, 456, WF WIZARD CANCEL, 214
470, 476, 481, 490, 497, 501, 505, 508, Where the associated record is, 468
514, 546, 558, 651, 716, 719, 725, 728 Where Used, 45, 220, 384
Use Custom Display Mask, 255 Where Used References, 46
Use Custom Precision and Mask, 139 wildcard search, 38
Word, 232
Work Flow Instance tab, 232

© Copyright IBM Corporation 2011. | 743

workflow, 192, 201, 212
launch, 209
synchronous, 34
Workflow Activity, 418, 437, 451, 462, 468, 483,
487, 648, 717, 726
Workflow Builder, 381
Workflow Diagram, 385
workflow editor, 384
Workflow Instance, 695
Workflow Instance Status, 696
Workflow Metadata, 337
Workflow Naming Standards, 388
Workflow New Task Bar, 386
Workflow Parameter, 218
Workflow Parameter Definition, 549
Workflow Parameters and Return Values, 547
Workflow Properties, 385
Workflow Select, 198
Workflow Task Palette, 385
Workflow to Initialize Record, 78, 85
Workflow Variable, 216
Working Hours Section, 605
World Region, 21

744 | : © Copyright IBM Corporation 2011.

 Notices

This information was developed for products and services offered in

the U.S.A.
IBM may not offer the products, services, or features discussed in this
document in other countries. Consult your local IBM representative for
information on the products and services currently available in your
area. Any reference to an IBM product, program, or service is not
intended to state or imply that only that IBM product, program, or
service may be used. Any functionally equivalent product, program,
or service that does not infringe any IBM intellectual property right
may be used instead. However, it is the user's responsibility to evalu-
ate and verify the operation of any non-IBM product, program, or ser-
vice.
IBM may have patents or pending patent applications covering sub-
ject matter described in this document. The furnishing of this docu-
ment does not grant you any license to these patents. You can send
license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) infor-
mation, contact the IBM Intellectual Property Department in your
country or send inquiries, in writing, to:
Intellectual Property Licensing

© Copyright IBM Corporation 2011. 745

 Legal and Intellectual Property Law
IBM Japan, Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any
other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this
statement may not apply to you.
This information could include technical inaccuracies or typographi-
cal errors. Changes are periodically made to the information herein;
these changes will be incorporated in new editions of the publica-
tion. IBM may make improvements and/or changes in the product(s)
and/or the program(s) described in this publication at any time with-
out notice.
Any references in this information to non-IBM Web sites are provided
for convenience only and do not in any manner serve as an endorse-
ment of those Web sites. The materials at those Web sites are not
part of the materials for this IBM product and use of those Web sites is
at your own risk.
IBM may use or distribute any of the information you supply in any
way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for
the purpose of enabling: (i) the exchange of information between
independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been
exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758
U.S.A.

746 | : Notices © Copyright IBM Corporation 2011.

Such information may be available, subject to appropriate terms and
conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed
material available for it are provided by IBM under terms of the IBM
Customer Agreement, IBM International Program License Agreement
or any equivalent agreement between us.
Information concerning non-IBM products was obtained from the sup-
pliers of those products, their published announcements or other pub-
licly available sources. IBM has not tested those products and cannot
confirm the accuracy of performance, compatibility or any other
claims related to non-IBM products. Questions on the capabilities of
non-IBM products should be addressed to the suppliers of those prod-
ucts.
All statements regarding IBM's future direction or intent are subject to
change or withdrawal without notice, and represent goals and objec-
tives only.
This information contains examples of data and reports used in daily
business operations. To illustrate them as completely as possible, the
examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the
names and addresses used by an actual business enterprise is entirely
coincidental.

Trademarks
IBM, the IBM logo, ibm.com, and TRIRIGA are trademarks or regis-
tered trademarks of International Business Machines Corp., registered
in many jurisdictions worldwide. Other product and service names
might be trademarks of IBM or other companies. A current list of IBM
trademarks is available on the Web at “Copyright and trademark
information” at www.ibm.com/legal/copytrade.shtml.
Microsoft, Windows, Windows NT, and the Windows logo are trade-
marks of Microsoft Corporation in the United States, other countries,
or both.

© Copyright IBM Corporation 2011. Trademarks | 747

748 | : Notices © Copyright IBM Corporation 2011.