TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Rational Summit/TM Data Structures

Many of Rational Summit/TM's files are located within an Apex or Summit subsystem and view. Thus, these files can be placed under Summit/CM control, if desired.

The following topics are covered in this chapter:


Field-Value File Format

Many of Rational Summit/TM's data files use a field-value format that represents a mapping from field names to field values. In this context, the term "field" has a more general meaning than "task field", and, in fact, all task fields are just examples of fields.

A field-value file can contain zero or more field-value pairs. A field-value pair can take one of two possible forms depending on whether the value is represented as a single line or multiple lines. The single line form looks like this:

Normally, the field_name is any number of alphabetic (upper or lower case), numeric, and underscore ("_") characters. It cannot contain any embedded white space nor can any white space appear between the name and the colon. Sometimes, a field name includes special characters such as "/" or "*".

The field_value includes all characters, after the colon (":") and to the end of the line. Leading and trailing white space is not considered to be part of the field value. A field_value can be empty, but if it is not, there must be at least one white space after the colon.

The multiple line form of a field-value pair looks like this:

The field_name has the same restrictions as before. Now, however, the multi-line value is surrounded by two references to the field_name. The beginning is marked by a line containing the field_name preceded by an opening brace ("{") and followed by a colon (":"). The ending is marked by a line containing the field_name followed by a closing brace ("}"). The value consists of zero or more separate lines of text.

Any line of the value that ends in a closing brace ("}") itself must have an extra trailing closing brace. This allows a value of the form field_name} to be represented.

Anywhere within a field-value file, a line beginning with a sharp-symbol ("#") is regarded as a comment and is ignored by Rational Summit/TM, except a line within a multiple-line field-value pair.

Examples of Field-Values:


Tasks

Tasks are represented as field-value format files which have a .task extension. They must always be stored within some task domain view. The contents of the file just record the current values for each of a task's fields. The fields do not have to be in any particular order. Task field names should be limited to alphanumeric characters and the underscore ("_") to insure greater compatibility with other tools. Normally, task fields which have an empty value are not recorded at all in the task's file. The Kind field must be present in every task to be able to use the full features of Rational Summit/TM.

The purpose of specific task fields and their associated values is described in following sections. In general though, each field of a task is defined by the task's kind giving its field name and field type. If, for some reason, a field of a task is not defined by the task kind, then Rational Summit/TM assumes it to be of type text.

Simple example of a task:


Task Domain

A task domain is implemented as an Apex or Summit subsystem and its associated views. In almost all contexts, a task domain refers to a particular view within the subsystem. That is, each view is usually treated as a separate domain. Some task domain information is common to all views. Most of the time, a task domain's subsystem will contain only a single view. Multiple views could be used for archival purposes or for other task partitioning schemes. In any case, all the tasks in a task domain must have unique task ids across all views in a given task domain subsystem (not counting archived copies used for reference purposes only). A task domain is identified to Rational Summit/TM by its full pathname.

The information in a task domain subsystem can be summed up as follows:

Information

Location

Task Index
.Rational/Taskmgmt/task_index
Task Domain Policy Switches
Policy/Taskmgmt.sw
Task Domain Roles
Policy/Task_Roles
Task Domain Views and Tasks
view/*.task

Task Index

A task index is a sequence number which can be used to generate unique task ids within a given task domain. This number is stored in the task domain's subsystem directory .Rational/Taskmgmt in a file called task_index. It is initialized to zero when a task domain is created and is incremented every time a new task is created within any view of a domain's subsystem. Its value is represented as a simple string of digits.

The task_index file is hidden in the .Rational directory because it should not be changed by users.

Task Domain Policy Switches

Task domain policy information is common to all views in a given task domain subsystem. Therefore, this data is stored in the domain's subsystem Policy directory in a file called Taskmgmt.sw. This file uses the field-value format and contains the following fields.

Prefix Field

The Prefix field defines the task domain prefix for the task id generation policy. It has a string value which cannot include any characters that are inappropriate for a simple file name. The value can be empty.

Suffix Field

The Suffix field defines the task domain suffix for the task id generation policy. It has a string value which cannot include any characters that are inappropriate for a simple file name. The value can be empty.

Width Field

The Width field specifies the minimum width for the task index sequence number used by the task id generation policy. If a sequence number is shorter than this width, it is padded with leading zeros. This field must have a non-negative integer value.

Kind_Path Field

The Kind_Path field identifies the task kinds which can be used to create new tasks within a task domain. It is also used to find the common task kind information for existing tasks within a task domain (such as the state machines and task editors). A Kind_Path value is a list containing the full pathnames of the necessary task kind directories.

Tasks identify their associated task kind with a simple name. If multiple task kind pathnames in the Kind_Path match the same simple name, then the first one found (left-to-right) is the one used.

Task_Customization_Key Field

The Task_Customization_Key field identifies the file containing actions that can be used to customize many Rational Summit/TM commands.

Example of a Task Domain Policy Switch File

Task Domain Roles

A task domain records its task role policy information in a field-value format file, called Task_Roles, located in the domain's subsystem Policy subdirectory. Thus, it applies to all views in a task domain subsystem. The set of roles defined apply to all state machines associated with all tasks located within these task domain views. See State Machines below for more details on how roles are used.

The contents of a Task_Roles file has the following format:

In general, a task_roles_entry maps a role onto a set of zero of more user ids. A role can be any simple identifier or it can be the special role name "*" that is used to represent all (or any) roles. A user_list_spec can either be 1) the special "*" symbol meaning all (or any) users, 2) a list of specific user ids, or 3) the special "@" symbol followed immediately by a pathname. In the latter case, pathname identifies a text file whose contents contains the list of specific user ids that are to be assigned to the given role. The entire contents of the file are "tokenized" so that there can be multiple user ids on one line and multiple lines of user ids. The pathname can either be a full pathname or a pathname relative to the task domain subsystem directory.

If a particular role name is not mentioned anywhere in a Task_Roles file, it means that no user is allowed to be in that role. If the same role name appears in more than one entry, then only the last one is used. If the Task_Roles file is missing altogether, it means that any user can be in any role (that is, equivalent to "*: *").

Example of a Task Domain Roles File

Task Domain Views and Tasks

As was mentioned previously, under most circumstances, a task domain is an Apex or Summit view within a subsystem, specially prepared for use by Rational Summit/TM. All task files are stored within such a view. These task files must be in the view's directory, itself, and not in a subdirectory of the view.

Other than the normal directories and files that Apex or Summit places in a view, and the task files themselves, there are no other files or directories in a task domain view that are of interest to Rational Summit/TM. Note that task domain views can be created with no model.


Task Kind

All the information for a particular task kind is stored in a single directory containing a number of files. This directory must be located within an Apex or Summit view. Multiple task kind directories can be created within the same view.

The information in a task kind directory can be summed up as follows:

Information

Files

Task Kind Policy Switches
Taskmgmt_Kind.sw
Task Fields and Types
Fields
State Machines
*.sm
Actions
*.actions
Task Templates
*.task
Task Editors
*.dgen, *.dlisp, *.fm

Task Kind Policy Switches

The task kind policy information is stored in the field-value format file Taskmgmt_Kind.sw. This file contains the following fields.

Prefix Field

The Prefix field defines the task kind prefix for the task id generation policy. It has a string value which cannot include any characters that are inappropriate for a simple file name. The value can be empty, but it usually contains a string that helps identify the task kind from which a task is created.

Suffix Field

The Suffix field defines the task kind suffix for the task id generation policy. It has a string value which cannot include any characters that are inappropriate for a simple file name. The value can be empty.

Id_Format Field

The Id_Format field defines the task id generation policy. The field consists of a sequence of elements (described below) which are evaluated whenever a new id is created. The resulting values are concatenated to form the new id.

Any combination of the following elements, in any order, may be specified:

Except for <index>, any of these elements may have an empty value.

When the Id_Format field is omitted, the following default id generation policy is assumed:

The <user_id> element inserts a component into the new task id which is specified by the user when the task is created. When multiple tasks are created in one operation (using related templates) it is generally necessary to include the <index> element as well to ensure each task is assigned a unique id. In addition, all of the task ids generated (in a single operation) must include the <user_id> if the –name option (or Name field) is specified.

Tasks will not be created unless the ids generated are unique.

Examples:

Template_Path Field

The Template_Path field identifies the task templates that can be used to initialize new tasks of the given task kind. It has a value of type string which can consist of zero or more task template file names separated by white space. The template file names can be full or relative pathnames. Relative pathnames are resolved with respect to the task kind directory. Wildcard characters can also be used in template file names. The first task template file on the list is the default one used by the create task commands. If the Template_Path field does not exist, or if its value is empty, then the value "*.task" is assumed.

Default_Field_List Field

The Default_Field_List field defines a default list of fields to be displayed for tasks of the task kind. This list is used by commands that display tasks whenever no explicit list of fields is provided as a command option and no applicable entry for the task kind exists in the user's Task_Field_List file in the ~/.Rational directory (see User Default Fields). The switch value must be a list of fields defined for the task kind. Alternatively, an asterisk "*" may be used to indicate that all fields of the task kind are default fields.

If the absence of a default fields specification for a task kind in both the Task_Field_List file and the DEFAULT_FIELD_LIST switch, the default fields are Id, State, Priority, Assigned, and Summary.

Default_Gui Field

The Default_Gui field specifies the default task editor that will be used to present a task's data via the graphical user interface. The value is of type string and identifies the associated task editor files (without any extension). A full or relative pathname is permitted. A relative pathname must be resolvable within the task kind directory. If the Default_Gui field does not exist, or if its value is empty, then Rational Summit/TM will pick the first task editor from within the task kind directory that it finds (if any).

Example of a Task Kind Policy Switches File

Task Fields and Types

The legal task fields for a task are defined by its associated task kind's Fields file. The Fields file is a field-value format file containing an unlimited number of field-value pairs. The field name of each pair specifies a user-defined task field name. Its associated value is a string that provides the task type for the task field.

Only the following predefined task types are recognized:

A task type can also be followed by an optional "*" character to indicate a list of zero or more elements of the simple type.

The enum task type must be followed by the legal values of the enumeration separated by white space.

The state task type must be followed by the name of the associated state machine description file. This file must be located within the task kind directory. Normally, the name of this file (without its extension) is the same as the name of the task field.

Fields of type task_path designate tasks by their full pathnames. They are used to represent relationships with other tasks, such as Parent/Children relationships. Relationships are bidirectional. The reverse_field is the name of the field which represents the corresponding reverse relationship in the related task. This field must also be a task_path field which designates the original field as its reverse_field.

Rational Summit/TM checks that the values of fields conform to their type definitions when they are initialized or modified. Any field (excepting certain predefined fields) may have an empty value, indicating that no value is specified.

The correct forms for values of each type are described in the subsections which follow. The syntax notation used is the following:

name

The name of a syntactic construct.

name: expression

The construct name has the syntax given by the expression.

expression_1 | expression_2

Either the syntax specified by expression_1 or by expression_2 is allowed.

expression...

The expression may be repeated.

[expression]

The expression is optional.

{text}

An construct described by text.

The following specific syntactic constructs are used below:

Type date

A value of type date represents a time and date. Date values are ordered. Later dates are larger than earlier dates.

The time part of a date value is optional. When omitted, 00:00:00 is assumed. When the century is omitted in the yy form of the year, 19 is assumed. The month is not case-sensitive.

Examples:

12/24/74
December 24 1995 13:00
12:00 AM Dec 24 1995
Dec 24 1996 12:00:59 AM

Type enum

An enum type is an enumeration of a fixed set of named values. The enumeration literals specified in the type are the only legal values. These values must be identifiers. They are case-sensitive. The values are ordered; the smallest value is the first and successive values are larger.

Examples:

Medium, Critical, resolved, RESOLVED.

Types fixed and float

These types represent fixed or floating numeric values. The syntax is:

Spaces are not allowed. Signs, the fraction part, and the exponent part are optional.

Examples: 3.14159, 0.05E-6, -5.0

Type int

A value of type int is an integer - a positive or negative whole number.

Spaces are not allowed.

Examples:

5, 0, -40, +10

Type path

A value of type path is the pathname of a file or directory. The required syntax is that of an absolute pathname. The referenced file or directory need not exist.

Examples:

/bin/rm
/ned/sierra/taskmgmt/taskmgmt.ss

Type state

Values are the named states of a state machine. They are case-sensitive identifiers. The states are defined in the file referenced by state_machine in the field type specification. State field values are ordered. The first state specified is the smallest.

Examples:

Assigned, Pending, Completed, Canceled.

Type string

A value of type string is a string (a character sequence) containing no newline characters.

Examples:

"a string value"
" ".

Note: The string value does not include the quotes.

Type task_path

A value of type task_path is the absolute pathname of a task. The .task extension must be included. The referenced task may or may not exist.

With the exception of the predefined Name field, fields of type task_path are used to represent relationships between tasks. These relationships are bidirectional. The name of the field that contains the reverse relationship is specified in the type definition (by reverse_field). The reverse field may be defined in other task kinds and the related tasks may be in other domains. However, the field type of the reverse_field must also be task_path and must name the original field as its reverse_field.

If a field represents relationships to more than one other task, the task_path* form is used, indicating a list of task pathnames. (See Task Relationships).

Example:

/project/task_domain.ss/all.wrk/C00351.task

Type text

The text type is equivalent to type string. However, see the section below on "List Types" for a subtle distinction.

Type version

A value of type version references a specific version of a controlled object. It is a string consisting of three parts separated by spaces: the absolute pathname of the object (including a view), the name of a version history, and a version number. The version referenced may or may not exist.

Example:

List Types

A field can be defined as a list of any of the above base types. A list value is a string containing simple values separated by newline characters.

Each simple value must conform to the base type of the list.

The type text* is, for the most part, the same as string*. However, text* should be used in situations where the breakdown of words into multiple lines is basically arbitrary (as in a paragraph of a document) whereas string* should be used in cases where each individual string value (or line) is "complete" and independent of the others (as in a list of cities). This distinction may be used in future versions of Rational Summit/TM to imply what kind of editing facilities will be made available to modify the values of these lists. For example, a list box widget might be used to edit a string* value while a text widget might be used for a text* value.

Predefined Fields

The following task fields with their respective task types are predefined by Rational Summit/TM for every task:

Id
string
Name
task_path
Domain
path
Kind_Path
path
Kind
string
Children
task_path* Parent
Parent
task_path Children
CmvcVersions
version*

The predefined fields are described in the Rational Summit/TM User's Guide.

The fields, Id, Name, Domain, and Kind_Path are implicit fields. Their values are not actually stored in the task's field-file but are computed automatically by Rational Summit/TM when the fields are referenced.

Any task field found in a task which is not defined in the task kind's Field file is assumed to be of type text.

Example of a Task Kind Fields File

Task Relationships

As already mentioned. fields of type task_path are used to represent relationships between tasks. Each relationship is bidirectional such that each related task has a task_path or task_path* field that contains the full pathname of the other task.

The type definitions of the fields representing a relationship also refer to one another. For example, the predefined Children and Parent fields together specify a bidirectional parent/child relationship between tasks as follows:

The general form of a relationship field type is

Where field is the field name and reverse_field is the name of the corresponding field that contains the reverse relationship. The reverse_field may be defined in the same task kind and/or in other task kinds.

The cardinality of a relationship field is either "to-one" or "to-many". It is "to-many" if the field is declared as task_path* indicating a list of destinations. For example, the parent-to-child relationship is a "one-to-many" relationship because the Children field (of the parent task) is a list and can refer to many tasks while the Parent field (of each child task) can refer only to a single parent task. In this way, relationships can be defined which are one-to-one, one-to-many (many-to-one in the reverse direction), or many-to-many.

When the modify_task command is used to modify the value of a given task_path or task_path* field, the corresponding reverse field in the related task is updated automatically. For, example, if a new pathname is assigned to a task_path field (or added to a task_path* field), a corresponding reverse pathname is also added to the reverse field in the task identified by that new pathname. An error results from an attempt to create more than one reverse relationship in a reverse field if the cardinality of the reverse field is "to-one".

Relationships can be also be created when tasks are created (see Task Templates).

State Machines

Each state machine description is stored in a separate field-value format file with the .sm extension. The name of the file is communicated to Summit/TM via the definition of the associated state field in the task kind's Fields file. A state machine description file contains the following three fields.

States Field

The States field has a value of type string which represents a list of state names separated by white space. Each state name is a simple name containing only letters, numbers and the underscore character ("_").

Default_State Field

The Default_State field has the default value for the state field. This is the initial value of the state field when not explicitly specified.

Transitions Field

The Transitions field applies preconditions and post-actions to state changes. When the field is absent, no actions are applied. In this context, a precondition is always an action that returns a result. Do not confuse them here with role-based preconditions.

The Transitions field value is in a 3-dimensional set format (that is, a set of sets of sets), each set being bounded by curled braces and their members (or subsets) being separated by commas. Single member sets need no enclosing braces, but empty sets must be denoted with braces as "{}". The sets are structured as follows:

1 . A single master set of arbitrarily ordered transitions:

2 . A state transition rule containing exactly five (5) subsets in the following order:

3 . A set of predecessor state names

4 . A set of successor state names

5 . A set of roles

6 . A set of preconditions

7 . A set of post-actions

Here is a simple example of a state transition rule:

This indicates that a transition from predecessor state A to successor state B is permitted only if the person requesting the transition is a member of the MANAGER task role and the precondition COND returns a successful result. If these tests pass, the state transition is completed and then post-action ACT is executed.

The precondition is not performed unless the role condition is satisfied. A precondition is deemed successful only if it returns the value 0 as its status. All other values are treated as failures.

Multiple predecessor states, as in

imply that a transition is allowed from either of the predecessor states to the successor state. Likewise, multiple successor states permit a transition to either of the successors. If more than one task role is given, then the transition can be performed by anyone in any of the listed roles. Multiple preconditions mean that all preconditions are executed in order (from left to right) either until all preconditions have been performed successfully, or until a precondition returns failure in which case no remaining preconditions are tested. If more than one post-action is provided, then all of them are executed in left to right order if the previous tests have succeeded.

A special symbol, "*" (including the double quotes), can be used for the set of predecessor states or successor states. The "*" indicates all states for which a transition is not explicitly defined. For example, the rule

allows anyone in the MANAGER role to perform a transition to state B from any state (which is not explicitly a predecessor of B in another rule).

For any allowed state transition, there must be only one applicable rule. The "*" symbol is interpreted consistently with this requirement. In the case of two rules, such as

the rule in which the predecessor state is explicit has precedence. Hence, the first rule above applies to the transition from A to B. A rule of the form

applies only to transitions for which no other rule is applicable.

The symbol "*" may also be used as the role set to indicate that the transition is permitted regardless of role. For example, the following rule allows anyone to perform a transition from A to B:

Note that some states may appear only as predecessor states and never as successor states. These states are known as start states and can be set when a task is created. Likewise, states that only appear as successors are known as stop states.

Example of a Task Kind State Machine Description File

Actions

The actions of a state machine are stored in a menu action clause file, whose name is the name of the state machine file, with the extension .actions rather than the extension .sm. For every precondition and post-action referred to in a state machine description file, there should be a corresponding action clause in the actions file. The name of a precondition or post-action must be an identifier (starts with a letter plus zero or more letters, digits or underscore characters).

Both precondition actions and post-actions for a given state machine are stored in the same action file. All action clauses are executed within the context of the task kind directory, so any relative pathnames referred to in the action clause must be resolvable with respect to that directory.

Please see Menu Files - Action Clauses for more information about action clause files.

Success or Failure of an Action

During an attempted state transition, if all the role preconditions are satisfied, then any modified, non-state task fields are permanently stored in the task. Then the action preconditions are performed. If any action precondition "fails", the state transition is immediately terminated (no remaining actions are evaluated) and the state field is left unchanged. If all action preconditions "succeed", then the state field is permanently updated and the post actions are executed. If any post action "fails", then no remaining post actions are performed, but the state transition still takes place.

Note that precondition actions cannot attempt to modify the fields of the task involved in the state transition.

An action shell script indicates its success or failure via the exit status code (an integer) that it returns. A status code value of zero (0) indicates successful completion of an action. All other values imply failure. Normally, status codes are returned explicitly using the shell's exit command as in these examples:

The shell will prematurely terminate an action script and implicitly return a failed status code if it detects an error before it actually executes a command. This is typically due to a syntax error, such as forgetting a quote character:

Note that some types of "errors" will not cause the shell to abort an action script. For example, if an action attempts to execute a non-existent command, the shell will display an error message, but it will continue to execute the rest of the action script. Of course, these types of errors can be detected by the script itself and then it can decide what to do about them.

If a state transition is attempted via the graphical user interface (that is, with a task editor), then any time an action fails, a general failure message appears in a pop up window identifying the name of the action. If the failure was explicitly detected by the action, then the action script should display the exact reason for the failure in the Message Window using the echo command.

Action Substitution Prompts

Rational Summit/TM supports the following substitution prompts which may be referred to by the commands in an action clause:

Prompt

Meaning

<task>
The canonical (full) name of the task
<task.field>
The value of the specified task field
<old_state>
The value of the state before the transition
<new_state>
The value of the state after the transition
<kind_dir>
The canonical (full) name of the task kind directory
<roles>
The user's current role(s), in quotes if there is more than one. The role "*" is represented by the string ALL_ROLES in this prompt.

In dlisp code, the construct <parent>*<child>, such as <field name>*value (or more generally, such as, assigned*value), is not a "field attribute" or a "prompt". Rather, it is a reference to a child widget of a parent widget. Information about what child widgets are supported for the various widget types (in the previous example "assigned" is an instance of the "text_alt" widget type) can be found in Basic Widget Children and Attributes. For a given task field, the associated widget type can only be determined by examining the .dgen file.

Debugging Action Scripts

As an aid in debugging shell scripts used for state transition actions, the shell interpreter can be directed to display commands as they are encountered. To do so, certain special shell commands must be included in the action script.

To display commands as they are read (that is, before variable substitutions are performed), the following special shell commands should be inserted:

For csh: set verbose = 1
For sh: set -v

To display commands as they are executed (that is, after variable substitutions are performed), use these special shell commands:

For csh: set echo = 1
For sh: set -x

Example of a Precondition Action Clause

Example of a Post-Action Action Clause

Task Templates

A task template file is a field-value format file containing the initial task field values for a new task. In fact, it looks identical to an actual task file and even uses the same .task file extension. This makes it easy to create a new task template out of a copy of an existing task.

A given template may be related to other task templates through fields of type task_path or task_path*, in exactly the same manner that tasks can be related to one another through these fields. In templates, such relationships define prototypes of relationships to be created when a task is created. When a task is created using a given template, additional tasks are also created corresponding to each of the related templates (transitively). The created tasks are initialized to have the same relationships among one another as the corresponding templates. Thus, it is possible to define a network of templates that instantiates a network of tasks. The capability can be used, for example, to automatically create certain children whenever a certain type of parent task is created.

In related templates, the task_path fields must contain the full pathnames of the related template files. These relationships must be bidirectional, that is, there must be a reverse field in the related template.

Non-editable Fields

Control over which task fields may be modified by users within a task editor dialog can be obtained by providing an APEX_SHELL script called Field_Edit.ash in the task kind directory. See the Apex Scripting Language Guide for a detailed description of the APEX_SHELL language.

The Field_Edit.ash script is called by a task editor dialog whenever it reads (or rereads) a task's field values either initially or after application of the Reset or Apply buttons. The script simply returns (using the APEX_SHELL return statement) a list of task field names that may not be modified by the user. A task editor dialog disables non-editable fields so that the user cannot change their values. The script cannot enable (by omission) the editing of task fields that are implicitly non-editable, such as the Kind and CmvcVersions fields. Also, note that the modify_task command is not affected by this feature.

For example, to indicate that the Priority and Assigned fields are non-editable, the Field_Edit.ash script could do this:

The current values of task fields and other task information may be accessed by the script. For example, the current state of a task or the roles of the current user may be considered in determining the non-editable fields.The full pathname of the task is passed as an argument and may be referenced as $1 in the script. The current value of a task field may be accessed in the script by defining a task type variable and then calling the field function. For example, the following code retrieves the current value of the field call state:

Assuming task t has been declared as above, the current effective roles of the user can be tested as follows in the script:

Dynamic Field Value Checking

Normally, the legal values for a task field are statically determined by the definition of the field as found in the task kind's Fields file. For example, a field of type date can only be assigned a value that satisfies the proper date syntax. Likewise, the value for an enum field must be one of the legal enumeration values defined in the Fields file. Dynamic field value checking is also supported through the use of special APEX_SHELL scripts. Given a task field called field_name, if an APEX_SHELL script file called alt_field_name.ash exists in the task's associated task kind directory, then this script is executed to determine the legal values for the field. These values are specified in the script by assigning them to the APEX_SHELL variable called alt_items. Thus, this variable itemizes all the acceptable field values. For example, to restrict a field of type string called Levels to the values "High", "Medium", and "Low", an APEX_SHELL script called alt_levels.ash could be defined containing the following:

The full pathname of the task is passed as an argument and may be referenced as $1 in the script. Thus, the values of the task and the roles of the current user can be used to determine what values are permitted. However, when a task is in the process of being created, the script will be executed with a null string ("") as the task name argument in $1, if the associated field is initialized by a task template.

Note that the values returned by the script must still satisfy the static field value checking rules. For example, a value for a date field must still have the proper syntax for a date even if the script indicates that the value is legal. Likewise, an enum value "approved" by the script must also be a member of the field's enumeration list as defined in the Fields file in order for it to be accepted. In other words, the dynamic field value checking rules can only further refine or restrict the set of values that are allowed by the static field value checking rules.

The field value checking provided by this feature can also be implemented using the pre_modify_task customization action. However, using this feature, the same APEX_SHELL script can also be used to provide dynamic alternative popup lists for task editor dialogs as well.

Task Editors

A task editor is defined by three files all having the same root name but with the extensions .dgen, .dlisp and .fm. For example, the task editor changeEditor has the files changeEditor.dgen, changeEditor.dlisp and changeEditor.fm. These files describe the dialog box that Rational Summit/TM uses to present the information in a task via the graphical user interface. The .dlisp and .fm files are actually generated from the .dgen file by a special program. It is very useful, however, to treat these files as a unit so that they are always kept together.

A .dgen file defines what task fields to display, and where and how to display them. It also defines what actions to perform when various buttons are pressed. This information can be customized. See Customizing Task Editors with Apex_guigen for detailed information on defining dialogs through .dgen files.

Dlisp, the language used to define dialog actions in a .dgen file, is described in the chapter Customizing Task Editor Actions using Dlisp.

When a user visits a task, Rational Summit/TM uses the following scheme to choose the task editor dialog box that will be displayed:

1 . See if the user has requested a particular task editor for this task kind. If so, use that one. (See User Task Editors for details.)

2 . Determine what role the user is in and see if there is a task editor with the same name as the role in the task kind's directory. For example, if the user is in the "manager" role, then look for the files manager.dlisp and manager.fm. If they exist, use them.

3 . Check if the task kind's policy switches file contains a non-empty Default_Gui field. If it does, then use the task editor named there.

4 . Otherwise, look in the task kind directory for any task editor files. If any are found, just pick one of those to use.


User Environment

The user environment contains all the Rational Summit/TM information that is specific to a given user. All of the files for recording this data are located in the user's ~/.Rational home directory. All sessions of Apex or Summit that a particular user has running share this information.

The information in a user environment can be summed up as follows:

Information

Location

User Roles
~/.Rational/Task_Roles
User Task Editors
~/.Rational/Task_Gui
User Default Fields
~/.Rational/Task_Field_List
Task Lists
~/.Rational/*.tasklist
Current Task List
~/.Rational/current.tasklist
To Do Task List
~/.Rational/todo.tasklist

User Roles

A user roles file indicates which roles the user wishes to be in when working on tasks within specified task domains. This information is provided in a field-value format file called Task_Roles in the user's Rational home directory (~/.Rational).

A field name in this file represents a user-defined task role name. Its corresponding field value is of type string and represents a list of zero or more task domain pathnames separated by white space. The special symbol "*" can be used as a field name to represent any and all roles. When used as a field value, the "*" symbol means any and all task domains. The task domain pathnames can contain wildcard characters.

If no Task_Roles file exists, then this is equivalent to a Task_Roles file with the single entry "*: *" meaning let the user be in whatever roles each task domain permits him or her to be in. If the Task_Roles file does exist, then only the roles asked for in the file will be granted (assuming the task domain permits it). If the same role name appears in more than one field-value pair, then only the last one is used.

When Rational Summit/TM needs to determine (for state machine transitions) which roles a user is legally entitled to be in for a given task domain, it computes the intersection of the set of roles that the user has requested for that domain with the set of roles that the domain has allowed for that user. See the Task Domain Roles for how the task domain defines its role policy.

Example of a User Task Roles File

User Task Editors

A user task editors file indicates which task editor the user wants to use when visiting tasks of specific task kinds. This information is provided in a field-value format file called Task_Gui in the user's Rational home directory (~/.Rational).

A field name in this file represents the pathname of an existing task kind directory. Its corresponding field value is of type string and represents the pathname of the task editor file (without the extension) to be used for tasks of that kind.

Example of a User Task Editors File

User Default Fields

A user default field list file indicates which fields the user wants Summit/TM commands to display (by default) for tasks of specific task kinds. This information is provided in a field-value format file called Task_Field_List in the user's Rational home directory (~/.Rational).The file must contain entries of the form:

The kind_path is the pathname of a task kind; the specified field names are the default fields to be displayed for that kind.

The kind_path can also be an asterisk ("*") which indicates all task kinds; in this case, there must be only one entry in the file. Similarly, an asterisk ("*") can be given for the list of field names to indicate that all fields of the kind are included.

The Task_Field_List file (if any) is examined whenever a command that displays tasks is used without an option specifying which fields are to be displayed. When there is no entry in the user's Task_Field_List file for a task kind, the Taskmgmt_Kind.sw switch file in the task kind directory is examined to see if it contains the DEFAULT_FIELD_LIST switch. If so, the value of this switch determines the default fields for the task kind (see Default_Field_List Field).

If the DEFAULT_FIELD_LIST switch is not defined, then the default fields are Id, State, Priority, Assigned, and Summary.

mykindpath: field1 field2

Means field1 and field2 are the default fields for the kind defined by mykindpath.

*: *

Means all fields are default fields for all kinds.

*: field1 field2 field3

Means field1, field2, and field3 are the default fields for all task kinds.

mykindpath: *

Means all fields of the kind mykindpath are default fields for that kind.

Task Lists

A task list is just a simple text file containing zero or more full pathnames of tasks, one per line. These files have the extension .tasklist. The tasks in a task list file can belong to any task domain. Task list files can be stored anywhere, but are typically found in the user's Rational home directory, (~/.Rational).

Example of a Task List File

It is possible to edit a task list directly as text using the command

where name.tasklist is the pathname of the tasklist. The current task list and the "to do" task list described below can be edited via the Set Current and Set ToDo commands on the Tasks menu.

Task lists can also be created and modified using the Tasks > Query command which searches domains for tasks that satisfy specified conditions.

Current Task List

The current task list is a very special case of a task list file. It is stored in user's Rational home directory, (~/.Rational), in the file current.tasklist. The contents of this file are used to provide default values for many graphical user interface commands that call for a task argument.

To Do Task List

The "to do" task list is the only other predefined task list file and is located in your Rational home directory, (~/.Rational), in the file todo.tasklist. This list is displayed by the Alternatives icons for task id entry fields in the graphical user interface. The Summary field of each task is also displayed.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS