Customizing the lifecycle attributes, artifacts, and queries

In all likelihood, if you are able to select a project template at project creation time, the artifacts, attributes, and queries in the template have been modified to meet your requirements. However, you may want to modify some of the defaults. For example, your project may use unique milestone names, and you may want to modify the values of the Target Milestone attribute in various artifact types to reflect these names. Or, you may want to provide a specialized query to show project members information that is not provided on the queries already in the template.

Required customizations of artifact attributes and rules

A domain administrator has probably already made certain required modifications to the artifacts and attributes supplied in the project template. In particular, several attributes should have been assigned sets of values, and two attribute dependency rules will require editing to ensure that they work properly.

You need to provide values for the following attributes:

• CNALM: Category - This attribute appears in the Context and Environment attribute group for CNALM:Defect Report, CNALM:Requirement, and CNALM:Test Case artifacts.
• CNALM: Customer(s) affected - This attribute appears in the Customer Information attribute group for CNALM:Customer Case, CNALM:Defect Report, CNALM:Requirement, and CNALM:Action Item artifacts.
• CNALM: Found in version(s) - This attribute appears in the Context and Environment attribute group for CNALM:Customer Case, CNALM:Defect Report, and CNALM: Requirement artifacts.
• CNALM: Hardware platform - This attribute appears in the Context and Environment attribute group for CNALM:Customer Case and CNALM:Defect Report artifacts.
• CNALM: Operating system - This attribute appears in the Context and Environment attribute group for CNALM:Customer Case and CNALM:Defect Report artifacts.
• CNALM: Source - This attribute appears in the Submission Information attribute group for CNALM:Customer Case, CNALM:Defect Report, CNALM: Requirement,CNALM:Action Item, CNALM: Test Case, and CNALM:Use Case artifacts.
• CNALM: Subcomponent - This attribute appears in the Context and Environment attribute group for CNALM:Customer Case, CNALM:Defect Report, CNALM: Requirement, and CNALM: Test Case artifacts.
• CNALM: Component - This attribute appears in the Context and Environment attribute group for CNALM:Customer Case, CNALM:Defect Report, CNALM: Requirement, and CNALM: Test Case artifacts.
• CNALM: Target milestone - This attribute appears in the Planning and Executino attribute group for CNALM:Customer Case, CNALM:Defect Report, CNALM: Requirement, CNALM:Action Item, CNALM: Test Case, and CNALM:Use Case artifacts.

As provided by CollabNet, the values for these attributes are only place-holders. If your domain administrator has not configured these attributes, you can do so at the project level.

The dependency rules that require modification are the following:

• CNALM-Subcomponent-Filter - This dependency rule must specify particular Subsystem attribute values. If you edit these attribute values, you may need to edit this rule. Note that you must edit each rule definition within each artifact type definition. The following artifact types have this rule:
  • CNALM:Customer Case
  • CNALM:Defect Report
  • CNALM:Requirement
  • CNALM:Test Case.
• CNALM-Category-Filter - This dependency rule specifies particular Category attribute values. If you edit these attribute values, you may need to edit this rule.Note that you must edit each rule definition within each artifact type definition. The following artifact types have this rule:
  • CNALM:Defect Report
  • CNALM:Requirement
  • CNALM:Test Case

Caveats regarding changes to the display names of artifacts and attributes

It is not recommended that you change the names of the provided artifacts or attributes. Also, you should apply caution when thinking about modifying the following:

• The Status attribute - This is a state attribute. Do not modify the Status attribute unless you have read the help on state attributes and feel comfortable with this functionality.
• The Subpage in Lifecycle attribute - Many of the queries supplied with the CollabNet Baseline Project template depend on this attribute and the values that were supplied in the process. If you modify this attribute, you will have to replace many of the queries listed in the activity area on each page. The activity area is either directly below the page navigation toolbar or at the top of the page. It is the area with a light blue background.

Changes to artifact definitions and adding artifact types

If you want to make a change to a subpage or add a new page, in all likelihood this will involve a change to one or more artifacts and queries. These changes can be minor. For example, the following are examples of minor changes you may want to make:

• Adding a query on the Testing page to return all defects of severity S2 or higher.
• Removing some attributes from an artifact type definition because these attributes are not relevant for your organization.
• Adding a query to show all Requirements that have been marked Closed.

Other changes may be extensive. For example, the following are examples of major changes you may want to make:

• Adding a new artifact type.
  For example, you may add a subpage called Qualification between the Testing and Deployment subpages, and you may need an artifact type called Acceptance Test for this subpage.
• Changing the rules by which people can promote an artifact type to a new subpage.
  For example, you may require project members to associate use case documents with each Requirement artifact, and to set the value of an attribute called Use Case Complete before being able to set a value of Yes for the Definition Complete attribute.

Whether the changes are modest or extensive, you will need to follow a basic process for adding or modifying the artifact type, capturing the queries that users will need to view the artifacts of this type, and documenting the correct use of the artifact and the queries.

Task overview: Modifying lifecycle artifacts and queries

1. Edit the relevant artifact type and attribute definitions.
2. Create a custom query that uses the new artifact type definition.
3. Copy the query URL in the browser address bar.
4. Edit the appropriate subpage to display the new query.
5. Remove the domain prefix from the URL.
6. Ensure that special characters in the URL are escaped. For example, replace all instances of ampersand ("&") with the HTML tag "&".

To edit or create an artifact type definition:

1. Click the Administration page.
2. Click Project Tracker > Artifact Types.
3. Follow the online Help to add or modify the appropriate artifact type.
   Note: After adding or modifying the artifact type, a project owner must add it to any existing projects where the artifact type is used.

To create a custom query:

1. Assuming that you have created a project that uses the process that you are modifying, click the Projects page, and click a project that uses this project template.
2. Click Project Tracker > Query Artifacts in the left navigation pane.
3. Click Create New.
4. Click Advanced Query.
5. Define the query criteria.
6. When the query results produce the desired result, copy the query results URL from the browser address bar.
7. Paste the URL into a text file.

To edit the subpage or page to reflect the changes:

1. Navigate to the project template directory.
   For example, you may go to project-templates/trunk/www/templates/My-Process/alm-templates
   Where My-Process is the name of the project template directory.
2. Using Subversion, update the top.html. file in the snippets directory.
3. Edit the top.html file or bottom.html file in the snippets directory for the appropriate subpage or page.
   For example, you would edit project-templates/trunk/www/templates/My-Process/alm-templates/1-Stages/1-Definition/snippets/top.html.
   Where My-Process is the name of the project template directory.
4. Paste the query results URL in the appropriate location in the Activities area or a table.
   For example, to update a URL in the Activities area, find the appropriate list item below the <!-- Start Activity Box --> comment, for example:
   <li><a href="servlets/Scarab/remcurreport/true/template/Search.vm?nextTemplate=IssueList.vm&action= Search&eventSubmit_doSearch=Search& grp=si&si=&qattdelim=true&it=3&mitdelim=true& col=11%2C13%2C2&coldelim=true" title="View all requirements that have been eliminated from consideration">All excluded </a></li>
   Note: The pasted URL will not be pretty.
5. Remove the prefix for the query URL.
   The prefix is http: or https://project.domain, where project is the name of the project where the query was captured and domain is the domain where the project resides. The URLs should begin with "servlets/Scarab".
6. Ensure that special characters in the URL are escaped. For example, replace all instances of ampersand ("&") with the HTML tag "&amp;".
7. Add information in a title attirbute to display a tool tip when the user places the cursor over the activity link.
8. Commit the changes using your version control tool.

The CollabNet Baseline Project template artifact types

The CollabNet Baseline Project template pages contain queries that show artifacts relevant to each subpage. For example, the Definition page displays links to queries in Project Tracker. These queries return requirements that are under development and completed requirements. The Design page has links to queries for completed requirements that are being designed and completed requirements for which design is also complete.

The Requirements artifact type in the CollabNet Baseline Project template allow users to trace requirements from initial definition through design, coding, and testing. For example, a user can promote a requirement from a planning subpage to a design subpage by changing the value of the subpage in Lifecycle attribute from Definition to Design. The Defect artifact type allows a defect to appear in either Testing or Code & Build queries.

The following table summarizes the artifact types used by the CollabNet Baseline Project template, and the activities users can perform with various artifacts at various subpages, and the attribute values that match the query criteria.

Notes: You can modify these artifact types, but if you do so, be aware that you may need to re-enter the query URLs in the corresponding project template subpage pages. See Changes to artifact definitions and adding artifact types for details. Also, if you customize the global default artifact types, the customizations will not apply to already-existing projects. They will only apply to new projects to which the modified artifact types have been added.

Default artifact types in the CollabNet Baseline Project template

The following are artifact types in the CollabNet Baseline Project template.

Artifact type name: CNALM-v1.1: Requirement

Subpages where artifacts of this type appear: Definition, Design, Code & Build, Testing

Description: A requirement defines new functionality for the release.

The View All Active Requirements query link displays artifacts that have not yet been completed. These artifacts contain Status attributes with one of the following values selected: Submitted, Started, On hold, or Reopened.

Requirements that are returned on the Currently in Subpage query have the following attribute values set:

• The value of the Status attribute set to Submitted, Started, On hold, Reopened
• The value of the subpage in Lifecycle attribute set to the name of the current subpage.
• The value of Accepted into Current subpage? is set to Yes.

Requirements that are returned on the Ready for Subpage query differ from the "Currently in" query as follows:

• The value of Accepted into Current subpage? attribute set to No.
• The value of the Previous subpage Complete? attribute should be set to Yes, although this is not required.

When entering a requirement, as distributed by CollabNet, required attributes are Summary, Overview, Justification, Status, and Stage in Lifecycle.

Artifact type name: CNALM-v1.1: Action Item

Subpages where artifacts of this type appear: Action items appear in each subpage.

Description: An activity, for example, handling a customer case or writing the Product Requirements Document.

The View All Active Action Items query link appears on most subpages. Using this query, the user can view all action items that have not yet been completed.

These artifacts contain Status attributes with one of the following values selected: Submitted, Started, On hold, or Reopened.

As distributed by CollabNet, required attributes include Source, Priority, Summary, Overview, Task type, Customer case ID, Customer critical?, Customers affected, Target milestone, Target milestone objective, and Action item type.

Artifact type name: CNALM-v1.1: Defect report

Subpages where artifacts of this type appear: Code & Build, Testing

Description:

The Defect Reports (all active) query link displays all defects that are candidates or are being tested. These artifacts have the value of the Status attribute set to Submitted, Started, On hold, Reopened

By clicking the Defect Reports Currently in Subpage query link, the user can view all defects that are being tested. These artifacts have the following attribute values set:

• The value of the Status attribute set to Submitted, Started, On hold, Reopened
• The value of the Subpage in Lifecycle attribute set to Testing.
• The value of Accepted into Current Subpage? is set to Yes.

By clicking the Defect Reports Flagged for Discussion query link, the user can view all defects that are candidates for being tested. These artifacts have the following attribute values set:

• The value of the Status attribute set to Submitted, Started, On hold, Reopened
• The value of the Flag for Discussion? attribute set to Yes.

Artifact type name: CNALM-v1.1: Customer case

Subpages where this artifact type appears: Support

Description:

A Customer Case describes a customer-reported problem or request for enhancement.

From the Support page, by clicking the All Active query link, the user can view all customer cases that are being worked on. The value of the Status attribute set to Submitted, Started, On hold, Reopened.

By clicking the Customer Cases Flagged for Discussion query link, the user can view all customer cases that have been created but are under discussion. These customer case artifacts have the following attribute values set:

• The value of the Status attribute set to Submitted, Started, On hold, Reopened.
• The value of the Flag for Discussion attribute is set to Yes.

When entering a new customer case, required attributes include Source, Source identifier, Priority, Summary, Overview, Task Type, Customer Case ID, Customer Critical?, Customers affected, Target milestone, Target milestone objective, and Subpage in lifecycle.

Artifact type name: CNALM-v1.1: Use Case

Subpages where artifacts of this type appear: No predefined queries exist in the CollabNet Baseline Project template for a use case..

Description:

A use case describes the real-world task that a user would perform with the new functionality.

When entering a new use case, required attributes include Source, Priority, Summary, Overview, Justification, Requirement ID, Use case type, and Status.

Users can issue ad-hoc queries for use cases based on the Subpage in Lifecycle attribute, the ID of the associated requirement, or on the artifact type. In addition to providing a Use Case artifact type, the CollabNet Baseline Project template provides a document template in Word format in the templates directory. Users would typically upload this template from the Definition or Design page.

Artifact type name: CNALM-v1.1: Test Case

Subpages where artifacts of this type appear:

Description:

A test case describes a scenario that must be tested to ensure that the functionality is free of defects.

When entering a test case, required attributes include Source, Priority, Summary, Overview, System, Subsystem, Category, Subcategory, and Status.

Users can issue ad-hoc queries for test cases based on the Subpage in Lifecycle attribute, the ID of the associated defect, or on the artifact type. In addition to providing a Test Case artifact type, the CollabNet Baseline Project template provides a document template in Word format in the templates directory. Users would typically upload this template from the Testing Subpage.

Artifact type name: CNALM-v1.1: Incident

Subpages where artifacts of this type appear: Deployment

Description: An incident describes an issue that is generated by an automated method.

Artifact type name: CNALM-v1.1: Customer Case

Subpages where artifacts of this type appear: Support

Description: A customer case describes a customer-reported problem or request for enhancement.

When entering a customer case, required attributes include Source, Source identifier, Priority, Summary, Task type, Customer case ID, Customer critical?, Customers affected, Target milestone, Target milestone objective, and Stage in lifecycle.

Artifact type name: CNALM-v1.1: Defect (read-only)

Subpages where artifacts of this type appear: Testing

Description: A read-only defect describes an error in the code, user interface, or documentation as reported in the Test Director product and uploaded to CollabNet.

Transitions for the Status attribute

The Status attribute, used in many of the CollabNet Baseline Project template artifact types, is a state type attribute. See Configuring state attributes for details.

The following table summarizes the valid state transitions for the Status attribute:

If the Status attribute is in this state	The user can select the following as the next state
Initial	Submitted
Submitted	Started, On hold, Will not complete
On hold	Completed, Will not complete
Started	On hold, Will not complete, Completed
Completed	Reopened
Will not complete	Reopened
Reopened	Started, On hold, Will not complete