Let's get back to our example and extend it. When a tester registers found bug using the template, it's not enough just to create a record. Let's assume that our imaginary team needs the following information about found bug:

Description
Severity
Found in version

'Description' is a block of text where tester describes the bug − what are the steps to reproduce it, what was expected, and what was actually happened. Also, it's very common use case, when you need just to list registered bugs with their descriptions, but such description is usually too big and it's inconvenient to read the list with such descriptions in. So we also need alternative 'Short description' which just repeats first one in several words. Such short description may be not enough to understand the bug, but is enough to recall it if you have read detailed description before.

'Severity' is a simple classification of how bad is the bug's impact. Usually this is a value from list of options. Let's use the following list in our example:

critical (the bug is really bad, and can cause system stop, data loss, etc.)
major (the bug is bad and can block some functionality)
moderate (the bug is still bad and provides wrong results)
minor (it's still a bug, but maybe not so bad, or user has alternative way to use broken functionality)
cosmetic (it's more a misprint than a bug)

'Found in version' is a string with version of product which was being tested. Developer will need this information to check reproducability (the bug may gone already in more recent version just because affected place of code is rewritten), or to analyse when the bug was introduced (if it worked as designed from beginning).

A tester, who submits a bug report, is not the only person who provides additional data. When manager assigns a bug to developer, he may need to specify a deadline, which means a date the bug must be fixed by. In ones turn, the developer, when resolves this record, will specify the version he fixed the bug in (to inform the tester what version should be used to verify the fix), and size of delta in SLOC (it's often required by managers to gather and analyse project metrics, to perform estimates for new projects, etc).

So, let's summarize. We need 'Description', 'Short description', 'Severity', and 'Found in version' for tester when he creates a record. We need 'Deadline' for manager. And finally we need 'Fixed in version' and 'Delta size' for assigned developer. Now let's learn briefly about how fields work and what the abilities they give us. We will get back to our example and create all just enumerated fields by the end of this chapter.

eTraxis allows you to specify in a template what data must be provided for each stage of record's life cycle. Each piece of data is a field, which is linked to particular state. When user creates a record, he is requested for values for all fields linked to initial state. If user moves a record to new state, then he is requested for values for all fields linked to this state. So please note, that if a record never was in some state, then the record doesn't have fields of this state yet. Thus, when user modifies a record, he's able to change current value of any field, which already exists in the record.

Field types

Since the data may vary in their nature, eTraxis provides several predefined types of fields:

number,
string,
multilined text,
check box,
list,
record,
date,
duration.

When you are creating new fields in your template, first of all you are requested for type of field. When type is specified, several additional things are requested, depends on the chosen type as described below. Also most of field types are related to required option and to default value. The required option specifies whether the field can be empty, e.g. has no value at all. When user creates a record, modifies a record, or changes a state, he will be forced to enter value for all fields marked as required. All other fields are optional and their values can be bypassed.

Besides described attributes, you can also specify for any field, whether a separator should be added. Separator is a horizontal line, which will be displayed after the field. It's a cosmetic item, that allows to group fields of the same state when the state has too many fields.

All fields of the same state are displayed in specified order. Each newly created field is put to the end of fields list by default. You can change order of existing fields if you would like.

Default value

When user creates new record, he is requested for all fields of the initial state. If some field has default value specified in its template, then this field is filled in with this value by default, otherwise the field is empty. User can either change the default value, or keep it as provided.

The same situation takes place when user moves a record to new state ‐ he is requested for values for all fields related to new state. A template can be defined in a way when it's able to move a record to some state several times during its life cycle. And default values are used only when a record goes to a state first time. All other times, the record returns to the same state, current field values will be reused instead of default ones.

Number fields

Field of number type can contain only integer values. When creating new field of this type you have to specify range of allowed values. The widest possible range of allowed values is from -1000000000 (a million) to +1000000000. Default value is optional and can be either empty or any integer from specified range.

String fields

Field of string type can contain string of characters. When creating new field you have to specify maximum allowed length of field values, which can be up to to 250. Default value is optional and can be either empty or any string which length is not greater than specified maximum.

For string fields you can also specify following three optional attributes:

PCRE to check field values
search PCRE to transform field values
replace PCRE to transform field values

First PCRE is a Perl-compatible regular expression, that will check values, being entered in the field. Two other PCRE are to update entered values (e.g. format entered phone numbers) and must be used together. Please note that provided PCRE pattern will be put between "/" characters, so you have to escape any "/" character in your pattern. Also i, s, and u modifiers will be automatically applied.

For example, you can specify the following pattern as checking PCRE if you need a field, which will be used to enter a phone numbers in "000-000-0000" format: (\d{3})-(\d{3})-(\d{4})

Another example is for field values transformation. Let's assume, you want to display entered phone numbers from previous example in "(000) 000-0000" format. You can specify the (\d{3})-(\d{3})-(\d{4}) pattern as search PCRE (it contains 3 subpatterns bounded by round brackets), and ($1) $2-$3 pattern as replace PCRE, where $x is a way to address subpattern.

Detailed description of PCRE is out of purpose of this documentation. Please refer to PCRE manuals, or just skip these three PCRE options, keeping them empty.

Multilined text fields

The purpose of multilined text type is clear from its name. When creating new field of this type you have to specify maximum allowed length, which can be up to 4000. Default value is optional and can be either empty or any text which length is not greater than specified maximum. As for string fields described above, you can also specify same three optional PCRE-attributes.

Check box fields

Field of check box type is a "flag" which can have one of two possible values − on or off. You have to specify only default value of field.

List fields

Field of list type is a set of user-defined items. Any list item consists of two parts − number and name. Number is an integer value of range from 1 to 2147483647 (2^31 - 1) and is used to sort and search records. Name is a string up to 50 characters length and is displayed to user when one works with field of this type. To create new field of this type you have to specify set of list items. When enumerating list items please put each item on separated line in format of "number name" (space separated). Default value is optional and can be either empty or number of any specified item.

Record fields

Field of record type can contain only identifier of another existing record. You have to specify only whether the field is required.

Date fields

Field of date type can contain only date values. When creating new field you have to specify range of allowed values. The widest range of allowed values is from -2147483648 (-2^31) to 2147483647 (2^31 - 1). This value means offset in amount of days from current date. For example, having range specified from 0 to 7, user will be able to enter any date between 6/18/2009 and 6/25/2009 if he tries to enter a value on 6/18/2009. Default value is optional and can be either empty or any integer value from the specified range.

Duration fields

Field of duration type can contain only values in format "hh:mm". When creating new field of this type you have to specify range of allowed values. The widest range of allowed values is from 0:00 to 999999:59. Default value is optional and can be either empty or any value from specified range. This type of field doesn't imply time of a day − it's only duration, which can be measured as amount of hours and minutes (e.g. fourty two and half hours can be expressed as "42:30"), or as amount of minutes and seconds (the particular measurement units are completely up to you).

Subject

eTraxis has one predefined field, which is present in every created record − Subject. This is a string field with maximum length of 250 characters. The field is implied as brief description of a record, and displayed in the list of records among other record attributes.

Field permissions

Each field, except built-in 'Subject', has access permissions, which can be specified for existing local and global groups and system roles. Access permissions can be one of following:

none
read-only
read and write

Permission to read-only means that members of a group can view this field and its current value, but cannot change the value when record is being modified. Please note, this restriction is ignored when record is being moved to the state with this field − in this case values of all state's fields will be requested.

Permission to read and write allows to members of a group to change current value of the field when record is being modified.

Permission named 'none' makes the field hidden for members of a group. This restriction is also ignored when record is being moved to the state with this field.

When you created new field all existing local project groups are given permissions to read and write automaticaly, while all existing global groups remain with no permissions to this field.

Example again

Now let's add the fields to our example template, starting with 'New' state. We already have mentioned "short description" as built-in 'Subject' field, and have to create only detailed 'Description', 'Severity', and 'Found in version'.

At first, go to the page with template's information and press 'Lock' button − you will not be able to edit template (including creation of new fields) while the template is not locked. Then go to the page with the 'New' state's information, and use 'Fields' button to get the list of existing fields (currently empty). Now press 'Create' button to create new field, then enter "Description" as 'Field name', choose "multilined text" as 'Field type', and click 'Next'. On the next page you will be prompted for additional attributes, specific to selected field type − just specify "4000" as 'Max.length', put mark in the 'required' check box, and keep the rest attributes unchanged. Click 'OK' to complete.

You will be forwarded to the list of fields again, but this time the list contains newly created field 'Description'. Click 'Create' button again, enter "Severity" as 'Field name', choose "list" as 'Field type', and click 'Next'. Enter into appeared 'List items' attribute the following:

1 critical
2 major
3 moderate
4 minor
5 cosmetic

Then enter "3" as 'Default value', put mark in the 'required' check box, and keep the rest attributes unchanged. Click 'OK' to complete.

Now let's click 'Create' button one more time, entering "Found in version" as 'Field name' and choosing "string" as its type. Let's assume that versions, which our testers will specify in this field, consist of three numbers separated with dot, where each number can contain up to 2 digits (e.g. "2.26.1"). As you can see, the maximum length of such version string is 8, so place "8" in the 'Max.length'. Also, we would want to restrict allowed values, so enter "^(\d{1,2}\.\d{1,2}\.\d{1,2})$" as checking PCRE. That's all for this field, click 'OK' now.

The 'Fixed in version' field of 'Resolved' state is exactly the same as just created 'Found in version'. I would like to let you create two other fields − 'Delta size' and 'Deadline' − by yourself as a homework. When you done, try to create new record and push through its states − if you are still confusing by information from this chapter, everything will become clear as soon as you see how our fields work and look now. And don't forget to unlock the template before.

Last update: 2009-08-09