Configuring state attributes

A state attribute allows users to view where an artifact is within its lifecycle and to promote the artifact to a new state. For example, you can configure a state attribute for a Defect artifact type that contains the following values, or states:

• New
• Open
• Fixed
• Verified
• Closed
• Closed-Will Not Fix
• Closed-Duplicate

Each value for a state attribute (each state) has one or more transition rules. Transition rules determine what new state or states a user can assign to an attribute based on the current state. For example, a transition rule can permit users to change the state of a Defect from New to Open, but not from New to Verified.

When users view artifacts that have state attributes, the state attribute is displayed in a drop-down list that shows the current state. The choices in the drop-down list depend on the current state and the user's role. For example, users might work with a Request for Enhancement artifact as follows:

1. Anyone can create a Request for Enhancement.
2. The initial artifact state is New.
3. When a Request for Enhancement is New, only a product manager or development manager can change the state to Scheduled.
4. A developer, a development manager, or a product manager can change the state from Scheduled to Done.

Each state attribute applies to the entire domain. Each state attribute has three components:

• States - The options or values for the attribute.
• State transitions and models - Transitions are rules that describe what states can be chosen based on the current state. State models are collections of transition rules. Each state attribute contains one or more state models.
• Roles - Only one state model can be assigned per user role. You can assign a state model to multiple roles.

You can associate only one state attribute with an artifact type. All artifact types that use the attribute must share the same state models, role associations, active states, and sequence of states.

Note: If you have migrated from artifact transitions (used in pre-3.5 versions of Collabnet), some of the transitions may not adhere to these rules. In this situation, Project Tracker issues a warning when you view or edit the artifact type, "Warning: This artifact type has more than one state attribute. This occurred as a result of the migration from a previous product version. Having multiple state attributes in an artifact type is not a recommended usage and will not be supported in future releases."

About state attributes and user roles

You can configure state attributes so that only certain states are visible to users with a specific role. For example, you can define the following:

• Default state transitions: New to Open, Open to Fixed, Fixed to Verified, Verified to Closed.
• State transitions for a Developer role: New to Open, Open to Fixed.
• State transitions for a Q.A. role: New to Open, Fixed to Verified.

Users with multiple roles inherit all of the role-specific transitions, but not the default transitions.

About state models

You can define different state models for different user roles. A state model consists of one or more transition rules. For example, suppose that you want product developers to be able to re-open defects that require additional work, but you do not want them to verify defects because verification is reserved for Q.A. people. You can assign the following state model to the developer role:

FROM state	New	Open	Fixed	Verified	Closed	Closed - Duplicate	Closed - Will Not Fix	Reopened
Initial state	X
New		X				X	X
Open			X			X	X
Fixed								X
Verified								X
Closed								X
Closed-Duplicate								X
Closed-Will Not Fix								X
Reopened			X			X	X

If you want Q.A. people to be able to originate or verify Defects, but not close them, you can assign the following state model to the Q.A. role:

FROM state	New	Open	Fixed	Verified	Closed	Closed - Duplicate	Closed - Will Not Fix	Reopened
Initial state	X
New		X
Open
Fixed				X				X
Verified								X
Closed								X
Closed-Duplicate								X
Closed-Will Not Fix								X
Reopened

Global and project-level state attributes

Some methods of configuring state attributes from the global level (the Administration tab) are not permitted from the project level (the Projects tab). You can define, activate, and deactivate state attributes only at the global level. At the global level, you can lock the association between a role and a state model to prevent the association from being edited at the project level.

The default state model for a role is the one that you define at the global level. You can override this by associating a project-level state model with the role. You can associate user roles with particular state models at both the global and project levels.

For state attributes that are not locked at the global level, you can do the following at the project level:

• Modify the state attribute.
• Associate different roles with state models.
• Rename a state attribute or a state.

At the project level, you cannot do the following:

• Inactivate a state.
• Change the sequence of states presented to users.

About converting list attributes to state attributes

You can convert single- and multi-select list attributes to state attributes, and you can convert state attributes to single- and multi-select list attributes, as follows:

• When converting a state attribute to a list attribute, the state models and role associations are deleted.
• When converting a list attribute to a state attribute, the new state attribute has only a default state model, and all user roles are mapped to this model.

About state attributes in dependency rules

A state attribute can be a condition in an attribute dependency rule. As a condition, the state attribute value can be used (for example, Open).

A state attribute cannot be the target of an attribute dependency rule.

State attributes cannot be dependent attribute targets of either conditional action rules or option filters. The state attribute specification declares state attributes to be valid rule conditions or sources and excludes them as targets. The reason for this restriction is the lack of guidelines for the correct behavior when the role based state models intersect with the rules from the dependent attributes feature.

About state attributes and artifact transitions

In releases of Collabnet prior to version 3.5, artifact transitions served the purpose of state attributes. If you used artifact transitions, these transitions must be migrated to state attributes when using 3.5 and later versions. A migration process is available for converting data to a form compatible with state attributes.

Adding and changing a state attribute

The following sections describe how to create, modify, copy, lock, and delete state attributes, and how to associate different user roles to different state transition models.

When you create a new state, or edit a state model, the change appears immediately in all artifact types and projects that use the state attribute.

To create a new state attribute

1. Log in to Collabnet as a domain administrator and click the Administration tab.
2. Click Project Tracker > Artifact attributes in the left navigation pane.
3. On the Global Attributes page, click the Create new button at the bottom of the page.
4. On the Create New Global Attribute Page, select State from the Type drop-down list, provide a name and a description, and click Continue.
5. On the Edit Global Attribute Page, scroll to the bottom and add the first state in the State name field.
6. Click Save and continue.
7. Repeat steps 5 and 6 as needed.
   Note: To control the order in which state values appear in a drop-down list on user project pages, select a numeric order using the drop-down numeric lists in the List sequence column to the right of each state.

To create or edit a global state model

1. Click the Administration tab, click Project Tracker > Artifact attributes in the left navigation pane, and click the link for a state attribute.
2. On the Edit Global Attribute Page, click the State transitions tab.
3. To create a new model, scroll to the bottom of the page and click Add New.
   To modify an existing model, select the model from the Select a state model drop-down list.
   If this is the first time you are creating a state model, a default model is created.
4. In the Attribute state transitions table, review the first row and click the options that you want to make available to users when an artifact is newly created.
   To assign a default initial state to a state attribute, choose exactly one state in the Initial Creation row of the attribute state transitions table. You can assign more than one transition state to a preceding state. For example, for a Defect artifact type, you may always want the initial state to be New. From the New state, if you want the user to be able to choose from the Open and Closed-Will Not Fix states, you would check these checkboxes in the row and de-select the other checkboxes.
5. Review the subsequent rows in the table and select the options to be available for the other states in the state model.
6. Click Save changes.

To associate a state attribute with a global artifact type

1. Create a new global state attribute, as described in To create a new state attribute.
2. Click the Administration tab, click Project tracker > Artifact types in the left navigation pane, and click the link for a global artifact type.
3. On the Edit Global Artifact Type page, in the Attribute Groups section, click Add new.
   A link named New Attribute Group appears.
4. Click the link for the new attribute group, provide a name, a description, and click Save.
5. In the Attributes in this Group section, click Add new.
6. Click the checkbox for the state attribute that you want to add to this group and click Add, then click Done.
7. In the Attribute Groups section of the Edit Global Artifact Type page, click Save.
   Note: This change is not automatically propagated to the local (project-level) artifact. To update the artifact at the local level, delete it and re-add it to the project.

To edit the state model project-level state model

1. Click the Projects tab, and click the link for a project that uses Project Tracker.
2. Click Project Tracker > Manage artifact types in the left navigation pane, and click the link for an artifact that contains a state attribute.
3. Click the name of the attribute group that contains the state attribute.
4. Click the link for the state attribute
5. Click the State transitions tab.
6. To create a new model, scroll to the bottom of the page and click Add New.
   To modify an existing model, select the model from the Select a state model drop-down list.
   If this is the first time you are creating a state model, a default model is created.
   Note: If you select a state model from the drop-down that was defined at the global level, it will be read-only.
7. In the Attribute state transitions table, review the first row and click the options that you want to make available to users when an artifact is newly created.
   To assign a default initial state to a state attribute, choose exactly one state in the Initial Creation row of the attribute state transitions table. You can assign more than one transition state to a preceding state. For example, for a Defect artifact type, you may always want the initial state to be New. From the New state, if you want the user to be able to choose from the Open and Closed-Will Not Fix states, you would check these checkboxes in the row and de-select the other checkboxes.
8. Review the subsequent rows in the table and select the options to be available for the other states in the state model.
9. Click Save changes.

To associate a role with a state model at the global level

1. Click the Administation tab, click Project Tracker > Artifact attributes in the left navigation pane, and click the link for a state attribute.
2. On the Edit Global Attribute Page, click the Roles tab.
3. Select a state model that you want to correspond to a particular role from the drop-down list next to the name of the role.
4. Click Save Changes.

Note: locked roles are read-only.

To associate a role with a state model at the project level

1. Click the Projects tab and click the link for a project that uses Project Tracker.
2. Click Project Tracker > Manage artifact types in the left navigation pane, and click the link for an artifact that contains a state attribute.
3. Click the name of the attribute group that contains the state attribute.
4. Click the link for the state attribute
5. Click the Roles tab.
6. Select a state model that you want to correspond to a particular role from the drop-down list next to the name of the role.
7. Click Save Changes.

To copy a state attribute (global level only)

1. Click the Administration tab and click Project Tracker > Artifact attributes in the left navigation pane.
2. Click the checkbox next to the state attribute, scroll to the bottom of the page, and click Copy Selected.

Locking a state attribute

You can lock state attributes, individual states, and role associations from the Administration tab, as follows:

• Locking the attribute - If you lock a state attribute and change the name of one or more states, the changes are propagated to all projects that use this attribute and its associated artifact type.
• Locking the state - If you lock the state, the state name is preserved in projects that use the attribute and its associated artifact type. If you change the name of a locked state, the change propagates to all projects that use the global artifact type assocated with the attribute.
• Locking the role association - If you lock the role, the global association between the role and its state model is preserved in all projects that use that attribute and its associated artifact type.

There is no explicit locking mechanism for state models because it is not possible for projects to modify globally-defined state model. You must create a project-specific state model within the project.

To lock one or more states

1. Click the Administration tab, click Project Tracker > Artifact types, and click the link for an artifact that has the state attribute.
2. Click the link for the attribute group that contains the state attribute.
3. Click the link for the state attribute.
4. In the Artifact Type Attribute Editor page, be sure the States sub-tab is selected.
5. Click the checkbox next to the state that you want to lock.
6. Click Save.

To lock a role associated with a state model

1. Click the Administration tab, click Project Tracker > Artifact types, and click the link for an artifact that has the state attribute.
2. Click the link for the attribute group that contains the state attribute.
3. Click the link for the state attribute.
4. In the Artifact Type Attribute Editor page, be sure the State Transitions sub-tab is selected.
5. Click the checkbox next to the role that you want to lock.
6. Click Save.

Deleting state attributes and state models

You can delete global and project-level state models. If no global state model association has been defined for a role, the role is assigned the default state model for the state attribute. When a state model is deleted, the effects are as follows:

• You can delete a project-level association for a role that was defined at the domain level (for example, the Developer role). People with this role revert to the associations in the global state model for this role.
• You can delete a project-level association for a project-level role. People with this role revert to the associations in the default state model.
• When you delete a global association with a domain-level role, people with this role revert to the associations in the default state model.

To delete a state attribute from its associated artifact type

1. Click the Administration tab, click Project Tracker > Artifact types, and click the link for an artifact that has the state attribute.
2. Click the link for the attribute group that contains the state attribute.
3. From the Global Attribute Group page, click the checkbox in the Select column that corresponds to the state attribute.
4. Click Delete Selected.

To delete a state attribute from the attributes list

1. Click the Administration tab.
2. Click Project Tracker > Artifact attributes.
3. Click the link for a state attribute.
4. From the Global Attribute Group page, in the Attribute Information section, click the Delete checkbox and click Update.

To delete a state from a state attribute

1. Click the Administration tab.
2. Click Project Tracker > Artifact attributes.
3. Click the link for a state attribute.
4. From the Global Attribute Group page, in the Attribute States, click the Delete checkbox that corresponds to a particular state, and click Save changes.

Migrating pre-3.5 attribute transitions

Prior to CollabNet 3.5, Project Tracker enabled administrators to configure single-select, list-type attributes to use transition rules. The transition rules allowed the administrator to do the following:

• Hide one or more attribute options based on the current value of the attribute.
• Require a user to supply a value for an attribute based on the value of another attribute.

In a CollabNet 3.5 installation, attribute transitions no longer work in global or project-level artifact types. Transition rules have been replaced by state attributes and attribute dependencies. A process is available for migrating attribute transitions. Contact your CollabNet support representative for details.

You can only add one state attribute to an artifact type. However, your pre-3.5 data may have more than one attribute transition associated with an artifact. Prior to migration, you should ensure as much as possible that only one attribute transition is associated with an artifact.