What is a state attribute?

A state attribute is a field that describes the state the artifact is in. It 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:

Anyone can create a Request for Enhancement.
The initial artifact state is New.
When a Request for Enhancement is New, only a product manager or development manager can change the state to Scheduled.
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."

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.

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

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.

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.