Managing global elements

Every project that uses Project Tracker contains artifact types. Artifact types are the building blocks of a project. An artifact type is a template for a specific kind of data. For example, CollabNet supplies a default Defect artifact type. A project may require several kinds of artifact types, for example, Defect, Enhancement Request, and Test Plan. An artifact type serves as a template for users who create instances of defect reports, enhancement requests, and so on. Project members who have appropriate permissions can enter instances of each new artifact type in a project.

Artifact types consist of sets of attributes. Attributes describe characteristics of an artifact. For example, a Defect artifact type may have attributes such as Severity and Assigned To. Users enter values for attributes when they create or modify an artifact, search for artifacts, and create reports. User attributes are a specific type of attribute that describe a user's relationship to an artifact. For example, Q.A. Contact and Assigned To are user attributes. Attribute values can be email addresses, integers, single or multiple select lists or short or long text strings.

Domain administrators define global artifact types from the Administration tab. Global artifact types and their associated attributes are available to all projects.

Project owners can add global artifacts and attributes to their projects from the Projects tab. Once an element is associated with a project, the project owner can customize the element for the project. Customizations do not affect the global element. Changes that you make to a global element will not affect the customizations made on a project level. If a project owner needs to incorporate changes made at the global level, the owner must delete and re-add the artifact type to the project.

Defining global artifact types

Artifact types defined at the global level can be altered at the project level.

When a project owner creates a new project in Project Tracker, any artifact types that are marked as default at the global level are displayed in the main list of artifact types for that project. However, the project owner must manually add any artifact types that have not been marked as default at the global level.

Project owners can only add artifact types that have at least one global (non-user) attribute to a project. If you want an artifact type to be available to project owners, you must assign at least one global attribute to it. See About attributes for details.

Guidelines for defining artifact types:

• Artifact types should reflect a wide variety of instances. For example, an artifact type entitled "Unix database errors" will capture information about one process on one operating system, but may be too narrow for your project. An artifact type of "Defect" may be adequate for many projects, but could be too broad for others.
• Users should be able to quickly identify what type of artifact they need to enter. For example, suppose a project has the following artifact types: Defect, Patch, Enhancement, and Feedback. If a project member discovers a bug in the project code, he or she can easily identify the Defect artifact type as the choice for data entry about the bug.
• You can select an "identifier" for an artifact type. The identifier as the link to view the artifact contents, and this value used in email notifications that are sent when the associated artifact is edited. Only text attributes can be used as identifiers.

Project tracker provides several sample global artifact types that you can use directly or as models for building your own global artifact types. The following global artifact types are included:

• CNALM-v1.1:Action Item - This is used to track an activity that is important to the project, for example, handling a Customer Case, writing the Product Requirements Document, or submitting Use Cases. Required attributes include Source, Priority, Summary, Overview, and Action Item type.
• CNALM-v1.1:Customer Case - This is used to track a customer-reported problem or request for enhancement. Required attributes include Source, Source identifier, Priority, Summary, Overview, Action Item Type, Customer Case ID, Customers affected, Target milestone, and Target Milestone.
• CNALM-v1.1:Defect Report - This is used to track an error in the code, user interface, or documentation. Required attributes include Source, Priority, Summary, Overview, Justification, Found in version(s), Reproduceable, Steps to reproduce, and Status.
• CNALM-v1.1:Incident Report - This is used to track an automatically detected problem Required attributes include Source, Source identifier, Priority, Summary, Overview, Action Item Type, Customer Case ID, Customers affected, Target milestone, and Target Milestone objectives.
• CNALM-v1.1:Requirement - This is used to track a new functionality for the release. Required attributes include the Summary, Overview, Justification, Status, and Stage in Lifecycle.
• CNALM-v1.1:TD Defect (Read Only) - This is used to track an error in the code, user interface, or documentation as reported in the Test Director product and uploaded to CollabNet. Required attributes include Source, Priority, Summary, Overview, Justification, Component, Subcomponent, Category, and Subcategory.
• CNALM-v1.1:Test Case - This is used to track a test case for a functionality that must be tested to ensure that the functionality is free of defects. Required attributes include Source, Priority, Summary, Overview, Component, Subcomponent, Category, Subcategory, and Status.
• CNALM-v1.1:Use Case - This is used to track a real-world task that you will perform with the new functionality. Required attributes include Source, Priority, Summary, Overview, Justification, Requirement ID, Use Case Type, and Status.
• Defect: This is the predefined default global artifact type used for tracking defects in existing features.
• Example - document: Used to track documentation processes like document creation, revision and signoff.
• Example - enhancement: Used to track enhancements being made to existing features.
• Example - requirement: Used to track product requirements.
• Example - task: Used to track work done in support of a "task.'
• Issue Tracker Artifact: Used to migrate data from the Issue Tracker tool to Project Tracker. This artifact type cannot be modified.

To define a global artifact type:

1. Click the Administration tab.
2. Click Project Tracker > Artifact Types in the left navigation pane.
3. Click Add new in the Global Artifact Types page.
4. Provide a name and description for your artifact type.
   The artifact type name should be descriptive. Use the description field to describe the type of information to be captured in the artifact type.
5. Select a value from the Namespace drop-down list. You can associate an artifact type to one of the two default Namespace values (Default and IT to PT conversion), or to a Namespace created during an import of a project template archive.
6. If required, select one or more of the following values:
   • Active - Activates the artifact type to be used at the project level.
   • Locked - Prevents the artifact type from being modified at the project level.
     By default, this option is enabled. To avoid the artifact type being set to Locked state, uncheck the checkbox.
   • Default - Adds the artifact type to each new project.
   • Deleted - Prevents the artifact type from being used at the project level.
7. Click Save.
8. Add groups of global attributes as needed.
   Note: If you add a new Attribute group in an artifact type, the Namespace associated to the artifact type will automatically be assigned to the Attribute group.
9. Add user attributes as needed.
   Note: If you add a new User attribute in an artifact type, you can sort the list of attributes associated to different Namespace by using the Filter This List drop-down box in the Select User Attribute page.

Note: If you associate an artifact type belonging to a Namespace, to an existing or deleted project, you cannot reassign that artifact type to another Namespace.

To select an identifier for a global artifact type:

1. Click the Administration tab.
2. Click Project Tracker > Artifact Types in the left navigation pane.
3. Click the link for the artifact type for which you want to set the identifier.
4. Click the link for the attribute group that contains the attribute that will be the identifier.
   The Global Attribute Group page is displayed.
5. Click the Use as Identifier radio button for the attribute.
   Note that this option is only available for text attributes.

About attributes

An artifact is a collection of attributes. For example, a Defect artifact may have attributes such as Summary, Description, Version Found In, and Version to Fix In. Project members supply values for attributes when creating, modifying, or searching for artifacts, and when running reports.

From the Administration tab, you define a pool of attributes that can be used by one or more artifact types. For example, a Priority attribute may be useful for artifact types such as Defect and Request for Enhancement. Each artifact type can have overlapping but unique sets of attributes. For example, a Defect will require a different set of attributes from a Request for Enhancement, however, these two artifact types may also have common attributes, such as the name of a customer who originated the defect report or enhancement request. You can define an unlimited number of attributes, but CollabNet recommends you keep the list of attributes as short as possible for ease of use by project owners.

If you move artifacts between projects, the artifact attributes are mapped between the origin and the destination.

When defining attributes, be sure they are:

• Meaningful and relevant: Attributes should be suited to the project. For instance, a Defect artifact type may need attributes for Version Found In, Version To Fix In, Originator, Assigned To, Component Found In, and other aspects of defect management.
• Understandable: Attribute names should be as simple and obvious as possible.
• Unique: Names must be unique, or you will receive an error. In addition, names should be unique in the minds of your users. Attribute names with similar meanings or that sound the same can cause confusion.

Global attributes

General-purpose attributes (also called global attributes) can be dates, lists, integers, email addresses, or text entry fields:

• Dates require the user to enter a date. If you add a date-type attribute to an artifact, a date field and a calendar icon appears on the artifact entry page. If the user clicks the icon, he or she can select the date from a pop-up calendar. The user can also enter the date directly in the date field in YYYY-MM-DD format.
• Email addresses enable the user to enter an email address.
• Integers require the user to enter an integer value.
• Single and multi-select lists allow the user to select one or more values. For example, an attribute named Operating System may have the following values:
  • Mac
  • Linux
  • UNIX
  • Windows

  Items in a list are referred to as list elements. List elements can have parent and child elements. For example, an element called "Windows" may have child elements of XP, 2000, and so on. When a project member selects the Operating System attribute, he or she can select from the list of defined operating systems. Parent elements appear on creation pages for queries and reports. Choosing a parent element results in the inclusion of the children. Each list element must be assigned a position within the list. See the "About element positioning" section for more details.

• State attributes enable the user to see where an artifact instance is in its lifecycle and to promote it to the next state (for example, from Open to Fixed).
• Text attributes enable the entry of arbitrary text strings.

About element positioning

List attributes element positioning is controlled by the following rules:

• Each element is assigned a position within the list. 
• Only one list element can be assigned per available number of positions. For example, only one element can be assigned the number 1 position, only one element can be assigned the number 2 position, and so on.
• The number of available positions in a list cannot exceed the number of elements in that list. For instance, if you have five elements in your list you have positions 1 through 5 available.
• There can be no empty positions within a list.

Sometimes you may want to rearrange the positions of elements in your list. You can do so by assigning a new position to a list element and saving your changes. For instance, if you had element C assigned to position 3 but want it in the first position you could reassign it to position 1. Moving a list element to a higher position in the list pushes all other elements down one position.

For instance, if you have the following list:

1. = A
2. = B
3. = C
4. = D
5. = E

and you want to put element C in the first position. Assigning C to the first position and saving produces the following list:

1. = C
2. = B
3. = A
4. = D
5. = E

If you attempt to put more than one element in one position the relative order of the elements is maintained. For example, you have a list with elements in the following order:

1. = A
2. = B
3. = C
4. = D
5. = E
6. = F

You move element D to position 2. You also move element E to position 2. In this case D will be assigned to position 2 and E to position 3. All other elements will be moved according to the previous rule. The final order will be:

1. = A
2. = D
3. = E
4. = B
5. = C
6. = F

User attributes

User attributes are used to create a relationship between a user and an artifact. User attributes perform the following functions:

• Identify the originator and establish ownership of an artifact.
• Inform primary stakeholders of progress on the artifact.
• Keep relevant people informed when an artifact is updated.

When you define a user attribute, you also indicate what permissions a project member must have to be able to view or edit the attribute. Optionally, a user attribute can be configured so that a user with this attribute is sent an email notification whenever someone modifies an artifact instance that uses the attribute. User attributes can be associated with the "To" and "CC" actions.

User attributes appear to the user as a list box with choices derived from the list of all users registered with the domain based on the base permission defined for the attribute. Refer to the Project Tracker Roles matrix to determine the value of permissions held by the user in the project.

Configuring an attribute

You can configure attributes from the Administration tab. Attributes can be of several types, including text strings, integers, email and selection lists. If you configure an attribute to be a selection list, you must specify the order in which values are displayed in the list. Note that Project Tracker does not permit you to specify a duplicate option order when configuring the values of List, Single Select, List, Multi Select, and State attributes.

You can configure attribute values in a hierarchy. For example, for an attribute named Components, the parent value of Windows may have child attributes of Windows 2000 and Windows XP. Parent attribute options show up on the creation pages for reports and queries, where if a user selects the parent option, all of the child values are included in the results.

To configure a global attribute:

1. Log in as a domain administrator and click the Administration tab.
2. Click Project Tracker > Artifact Attributes in the left navigation pane.
3. Click the Global Attributes sub-tab.
4. Click Create New.
5. In the Create New Global Attribute page, select the attribute type from the Input Type field.
6. Enter a short name in the Name field.
7. Enter a description in the Description field.
   Note: Users can view descriptions to determine how best to enter information for the attribute. For best result, make your descriptions informative.
8. Select a value from the Namespace drop-down list. You can associate an artifact attribute to one of the two default Namespace values (Default and IT to PT conversion), or to a Namespace created during an import of a project template archive.
9. Click the Continue button.
10. If the attribute is a list-type attribute, in the Attribute Options section enter a name for the first value and click Save.
    To enter additional values, add the value in the New field and enter a unique order for displaying the value to users. Duplicate values for preferred order will generate an error.
11. If the attribute is a list-type attribute, you can choose parent values for each attribute option.
    For example, an attribute option named Operating system can be the parent value for options such as Windows, Linux, UNIX, and Mac.

To modify a global attribute:

1. Log in as a domain administrator and click the Administration tab.
2. Click Project Tracker > Artifact Attributes in the left navigation pane.
3. Click the Global Attributes sub-tab.
4. Click the link of the attribute that you want to modify.
5. If appropriate, change the attribute type from the Input Type field.
6. If appropriate, change the name in the Name field.
7. If appropriate, change the description in the Description field.
   Users can view descriptions to learn how to enter information for the attribute. Make your descriptions informative.
8. If the attribute is a list-type attribute, in the Attribute Options section enter a name for any new value that you want to add, or modify the name for an existing value and click Save.
   To enter additional values, add the value in the New field and enter a unique order for displaying the value to users. Duplicate values for preferred order will generate an error.
9. To delete a value, check the Delete checkbox to the left of the value.
10. If the attribute is a list-type attribute, you can choose parent values for each attribute option.
    For example, an attribute option named Operating system can be the parent value for options such as Windows, Linux, UNIX, and Mac.

Note: You can reassign the Namespace of a global attribute to another value only if the attribute is not associated to an artifact type.

To delete a global attribute:

1. Log in as a Domain Administrator and click the Administration tab.
2. Click Project Tracker > Artifact Attributes in the left navigation pane.
3. Click the Global Attributes sub-tab.
4. Click the link of the attribute that you want to delete.
5. On the edit page for the attribute, click the Deleted checkbox.
6. Click the Update button.

To delete a global attribute option:

1. Click the link of the attribute, whose options you want to delete.
2. In the edit page of the attribute, click the Deleted checkbox of the option you want to delete in the Attribute Options section.
3. Click the Save button.

Warning: Deleting a global attribute or any of its options will remove data from artifacts that use that attribute or the attribute option.

To configure a user attribute:

1. Log in as a domain administrator and click the Administration tab.
2. Click Project Tracker > Artifact Attributes in the left navigation pane.
3. Click the User Attributes sub-tab.
4. Click Create New.
5. In the Create New Global User Attributes page, enter a name in the Name field.
6. Enter a description in the Description field.
   Users read descriptions to learn how to enter information for the attribute. Make your descriptions informative.
7. Select a value from the Namespace drop-down list. You can associate a user attribute to one of the two default Namespace values (Default and IT to PT conversion), or to a Namespace created during an import of a project template archive.
8. In the Email action drop-down, select whether users with this attribute are automatically sent email when an artifact using this attribute is created or modified.
   For instance, a Defect artifact may contain an attribute named CC that indicates that users who are assigned this attribute are copied on emails that are sent when a defect is added or modified.
9. Assign a base permission to a user who has been added to the project.
10. Click Save.
11. Click Done.

To modify a user attribute:

1. Log in as a domain administrator and click the Administration tab.
2. Click Project Tracker > Artifact Attributes in the left navigation pane.
3. Click the User Attributes sub-tab.
4. Click the link for the attribute that you want to modify.
5. Enter an updated name in the Name field, if appropriate.
6. Enter a new description in the Description field. 
7. Change the Email action if appropriate.
   Select whether users with this attribute are automatically sent email when an artifact using this attribute is created or modified. For instance, a Defect artifact may contain an attribute named CC that indicates that users who are assigned this attribute are copied on emails that are sent when a defect is added or modified.
8. Change the base permission that is assigned to a user who has been added to the project, if appropriate.
9. Click Save.
10. Click Done.

Context-sensitive help descriptions on attributes

Domain Administrators can introduce help text descriptions for individual Project Tracker global attributes. If the project level Project Tracker administrator does not override the descriptions then you can see those descriptions provided in the global attribute definition. To enable the context sensitive help functionality:

1. Log in as a Domain Administrator. .
2. Click the Administration tab and the link Project Defaults under Configure in the left navigation pane.
3. Check the checkbox to turn on the attribute descriptions feature under Project Tracker.
4. Click the Projects tab and click Start New Project to create a new project with Project Tracker as the tracking tool.
5. Click the link Enter artifact and click on any artifact type and see that the Hide/Show toggle toolbar appears under the top menu bar.
6. You can also click the link Edit Project on top of the screen and scroll down to the Tool configuration link under the section Project administration and enable the attribute descriptions feature under the section Project Tracker.

This feature is available as tooltips under all attribute fields in all artifact pages. This feature is also available when you create a new query or report, in the attribute columns of the query/report results.

Inactivating Global Artifact types

Global artifact types are set to Locked status by default. The Active status allows the artifact type to be added to specific projects. You can inactivate global artifact types so that they are unavailable for addition to projects.

If you inactivate a global artifact type after it is associated with a project, you can still create artifacts of that type in that project. Being inactive at the global level does not prevent new artifacts from being created using that artifact type if it was active and associated with the project when the project was initiated. An inactive artifact type cannot be associated with new projects.

You cannot delete global artifact types if they are in use by one or more projects.

Note: When you inactivate a global artifact type, the Default checkbox is cleared even if it had been checked. If you re-activate the artifact type, Default checkbox must be checked again if you want this artifact type to be designated a default.

To inactivate an artifact type

1. Log in as a domain administrator.
2. Click the Administration tab.
3. Click Project Tracker > Artifact types in the left navigation pane.
4. Click the link for the artifact type that you want to inactivate.
5. Clear (un-check) the Active checkbox.