Let's assume we have a software development project with three kinds of engineers in the team. Developers write source code, implementing the project and fixing found bugs. Testers test each new version of the project, finding bugs there. Managers control the project, taking care about assigning tasks between team members.

We need a template to track all bugs, found by testers. Its workflow will be the following:

Tester finds new bug and registers it by creating new record, which appears in its initial state 'New'.
Manager reviews new record, chooses corresponding developer, and assigns the record, moving it to 'Assigned' state.
Developer moves the record to 'Opened' state when he starts working on the bug.
When developer fixed the bug, he moves the record to 'Resolved' state.
The tester, who found this bug, verifies that bug is not reproducible with the provided fix. If bug is really fixed, tester moves the record to its final state 'Closed'; otherwise the record is returned to 'New' state.

Quite simple and very popular process among software development teams. The only question you may have is about 'Opened' state. It's a common situation when each of developers has several bugs assigned on him at the moment. And sometimes one developer completes to fix all the bugs were assigned on him, while another developer still has several bugs unresolved (don't blame him − probably his bugs are not so trivial as ones of the first developer). So, managers would like to reassign some of bugs from one developer to another, but what bugs should be reassigned? Currently responsible developer is already working on some of them and it's senseless to reassign a bug, which is probably "half-fixed" already − it will be a waste of developer's effort. So, to show that some bug is already in progress, developer should change its state to 'Opened' as soon as he started to work on the bug.

Well, actually this state is not strictly required, especially in small teams, and I often drop it from workflow in the real life, but I introduced it here in example, because it will help me to illustrate how state's feature, named keep current responsible, does work.

Create new project

I assume that at the moment you have already created all required accounts, or set up LDAP server. It's too simple and generic to dedicate a separated chapter for this. So, log in eTraxis using any account with administration rights, go to 'Projects' page, and create new project.

The only thing which should be clarified is about project status. A status can be one of two following − active or suspended. When project is suspended nobody can create new records in this project and all already existing records can only be read. All suspended projects are displayed in red in the list of registered projects.

Create project groups

Now go to the page with information of newly created project, clicking this project in the list of existing ones. Press 'Groups' button, and create all three groups − 'Developers', 'Managers', and 'Testers'. Then, opening each group one by one and clicking 'Membership' button, add to these groups required accounts (this process is also described in 'LDAP Support' chapter).

Create new template

Go back to the page with information of the project, press 'Templates' button, and create new template. As projects, all templates have status. The status can be one of two possible values − active or locked. When a template is locked nobody can create new records using this template, and all existing records, already created per this template, can only be read. If template is active you cannot modify it (i.e. change its states and fields). All locked templates are displayed in red in the list of project templates. Newly created template is locked by default.

Any template has following attributes, which require additional explanation:

prefix
critical age
frozen time
guest access

Prefix is a short string up to 3 characters length. This prefix will be displayed with unique identifiers of records. It helps to remind what template was used to create the record.

Critical age is an optional integer value of range from 1 to 100 which means amount of days. When record remains opened more than this amount of days it is displayed in red in the list of records. If this value is not specified, the record will never "expire".

Frozen time is an optional integer value of range from 1 to 100 which means amount of days too. When record is closed you cannot change its state anymore, but you still can modify its fields, add comments, and attach files. If frozen time is specified it will be allowed to modify record only this amount of days after its closure, then the record will become "read-only". If this attribute is not specified, record will never become "read-only".

Guest access means that non-authenticated users will be able to read records of this template.

Create states in the template

Now we need to create states of our template. Go to the page with template's information and click 'States' button there. Create new intermediate states as following:

State name	Abbreviation	Responsible
New	N	remove
Assigned	A	assign
Opened	O	remain unchanged
Resolved	R	remove

Also, you have to create one final state, named 'Closed' (let's give it an abbreviation 'C').

Abbreviation is to show in the list of records and its purpose is just to remind you what is the current state of each record. It can be up to 50 characters long, but it's recommended to keep it really short − best abbreviation is about 3-5 characters long.

Responsible attribute is described in 'Responsibles' chapter. I only would like to make one note. According to our workflow you can set 'keep unchanged' for the 'New' state, and it still will work as supposed. But what if later you will be asked to extend the workflow and you will get one more transition from, for example, 'Assigned' to 'New'? In this case after some record is removed from 'Assigned' to 'New', you will get a record which is in 'New' state and still assigned on somebody. My advice is always specify 'remove' in 'responsible' attribute of a state, which is expected to be not assigned under any conditions.

Set transitions between states

At the moment we have all required states created &minus let's specify possible transitions between them.

Click the 'New' state in the list of created states to go to the page with state's information, and use 'Transitions' button there. According to our workflow we have only one possible transition from this state − to 'Assigned' one − and only managers are allowed to move records per this transition. So, choose 'Managers' group at left, put checkmark in 'Assigned' at right, and click 'Save' button. In the same manner grant to 'Developers' group transition from 'Assigned' to 'Opened', and from 'Opened' to 'Resolved'.

At last we have to specify transitions for 'Resolved' state. We have two possible transitions here − to 'New' and to 'Closed' − and both should be permitted to author of a record. So, choose 'Author' role at left, put both checkmarks at right, and save (see screenshot). Now only the tester created this particular record will be able to close it. That's it for transitions − we don't need (and are not able) to specify any transition for 'Closed' state, because it's final one and can't have transitions by its nature.

One important note must be given here. When record is being moved to a state, which has 'assign' in its 'responsible' attribute (i.e. requires the record to be assigned), eTraxis will show you the list of possible users to choose new responsible from it. This list always contains only users, which are allowed to move the record from new state to somewhere further. For our example, when some manager moves a record to 'Assigned' state, the list of possible responsibles will contain only members of 'Developers' group, because only developers will be able to move record to another state from 'Assigned'. It looks reasonable, but we have one more problem here − any developer is allowed to move this record from 'Assigned' state to 'Opened', while we want only currently assigned developer be able to do it. The first thought is to revoke transition "Assigned → Opened" from 'Developers' group and grant this transition to 'Responsible' role, but it's not going to work − eTraxis will not be able to determine, what users should be shown in the list of possible responsibles, when a record is being moved from 'New' state to 'Assigned' one. This is why eTraxis has one more special restriction regarding changing a state − you can move a record to another state if

In other words, when record is assigned on another person you cannot move it to another state even if you have permission to move records from current state to this one. Now everything works as desired − when record is being assigned the list of possible responsibles shows to our manager all developers (and only developers), but only really assigned developer will be able to move the record to 'Opened' state later.

Set template permissions

Now we need to set up permissions to new template. Go to the page with template's information and click 'Permissions' button there. On this page you can specify permissions of all existing local and global groups and system roles. Permissions, applicable to templates, are following:

permission to view records
permission to create records
permission to modify records
permission to postpone records
permission to resume records
permission to reassign assigned records
permission to change state of assigned records
permission to add comments
permission to add/read confidential comments
permission to attach files
permission to remove files
permission to send reminders
permission to delete records
permission to add subrecords
permission to remove subrecords

Permission to view records means that members of a group are allowed to read records. Please note that roles author and responsible always have this permission.

Presence of permission to create records allows group members to create records using this template.

Presence of permission to modify records allows group members to modify records created by this template. Modification of record means changing existing values of its fields; any other operation with a record including changing its state is not a modification.

Permission to postpone records allows group to postpone existing records created by this template. Postponed record can be only commented until it is resumed − all other operations are disabled. All postponed records are displayed in blue in the list of records. Permission to resume records allows group to resume postponed records created by this template.

Permission to reassign assigned records allows to reassign record, which is already assigned, from current person to another. Usually this permission is granted to management and is not required for regular team members.

As it was mentioned above, you cannot move a record to another state (even you have related permission) if the record is assigned on another person. For exceptions of this rule permission to change state of assigned records exists. Usually this permission is granted to management and is not required for regular team members.

Permission to add comments gives an ability to post comments to any record created by this template.

Permission to add/read confidential comments allows to post confidential comments, and read existing confidential ones. Without this permission user can post and read regular comments only (see above).

Permission to attach files gives an ability to attach files to any record created by this template. By default, user can remove only file, that he had attached. Permission to remove files allows to remove any file, even it was attached by another person.

Permission to send reminders allows to create and send reminders about records created by this template. Reminders will be described in details in dedicated chapter later.

Permission to delete records allows to completely erase any existing record created by this template. Software Configuration Management (SCM) standards strongly recommend do not delete any record − it's always better to have some kind of specific final state for such cases (e.g. named "Deleted"). This ability is given for extraordinary special cases only. Please use it with care (and better do not use it at all).

Any record (named parent) can have unlimited number of subrecords. Also, each subrecord can be dependency. Parent record cannot be closed, if it has at least one opened subrecord as dependency. Permissions to add subrecords and to remove subrecords allow to specify subrecords and remove specified ones. Subrecords will be described in details in dedicated chapter later.

After this review of possible template permissions, let's grant required permissions to our groups. First of all choose 'Managers' group at left, click 'Select all' button, then remove checkmark from 'permission to delete records', and click 'Save' − it's normal set of permissions for project management. For 'Developers' and 'Testers' it will be enough to grant 'permission to view records', 'permission to modify records', 'permission to add comments', and 'permission to attach files'. Also, add one more 'permission to create records' for 'Testers' group, otherwise they will not be able to register their found bugs at all.

That's it!

We are almost done. Actually, everything is completed, but our template is still locked, and we didn't mark any state as initial. At first, go to page with information about 'New' state and click 'Make initial' button there. Then go to the page with template's information and press 'Unlock' button. You are all set, just go to 'Records' page and click 'Create'.

Last update: 2009-07-30