Overview

In many projects, artifacts such as User Stories, Test Runs, and Requirements often have relationships with other artifacts. However, identifying and managing these relationships can be challenging and time-consuming. Without a systematic way to link artifacts, you might find yourself manually searching for related artifacts, which can disrupt your workflow and make it difficult to keep track of all connections.

Referential Fields solve this problem by allowing you to create direct links between related artifacts. These special fields within an artifact provide immediate access to other relevant artifacts, streamlining the process of referencing and managing related information.

This document provides a detailed overview of Referential Fields, explaining what they are, when to use them, and how to configure them effectively within your system.

What is a Referential Field

Referential Fields are actual database fields where you can store a reference to an artifact, similar to inserting a link in a rich text field. You can add other relevant artifacts as an attribute of a current artifact. This helps for easy access and understanding of related artifacts or issues. Moreover, Referential Fields can be configured to increment the artifact’s version when modified.

When to use Referential Fields

Use Referential Fields to easily access related information directly from the current artifact. This not only saves time but also provides immediate context about how different artifacts are related.

For example,

• User Story: You can have a field named Stakeholder that provides a contextual reference to an actual stakeholder artifact. This would help you to access stakeholder details directly from the user story.
• Test Run: A Test Configuration field can provide direct access to specific text configuration details for a particular test run.
• User Story or Requirement: A Sprint/Release field can show which sprint or release the story or requirement is associated with.

Benefits

• Customization: Administrators can specify properties for a Referential Field, such as whether the field will contain a reference to single or multiple artifacts, which record types can be selected, and what trace or non-trace links should be created.
• Efficient Navigation: Referential Fields provide direct links to referenced artifacts, making navigation more efficient. You can open the linked artifacts directly from the field.
• Referential fields can be used in various interfaces:
  • List/Tree Editor: View and edit Referential Fields in List and Tree editors. Plus, you can export them to an Excel file.
  • Traceability Coverage Matrix: Referential Fields are visible in Traceability Coverage Matrix.
  • Wiki List Macro: Display Referential Fields in List Macro on a Wiki Page.
  • Mandatory and Read-only Fields: Set Referential Fields as read-only or mandatory for a record type state.
• Bulk Edit Properties: Edit Referential Fields easily in bulk.

Who should read this?

• TopTeam Administrators

Configuration Process Overview

1. Create Referential Field: Navigate to Administration area > Configure System Record Types > Customize Record Type Fields. Create a Referential Field, and define its properties.
2. Add to Record Type: Add the Referential Field to desired record types.
3. Add to User Interface
   • Detail Editor: Customize the screen layout of a record type to add the new field.
   • OneView: Customize the OneView Field Layouts of the OneView sections where you want to display the new field.
   • Document View: Add the field to the Screen Layouts of the Screen Layout Sets in which you want to display the new field.
   • Artifacts Tree/Artifact List: Add the new field as a column in Artifact Tree/Artifact List and save it as a View.

The Referential Field is now ready to be used by the user.

Creating Referential Field

Step 1. Navigate to the Record Types Field administration area

Step 2. Create a new Referential Field

• Select Referential Field (Single Value) if you want this field to have only one value (artifact).
• Select Referential Field (Multi-Value) if you want this field to have multiple values (artifacts).

Step 3. Specify the field properties

Define field properties and click Save to save the settings.

Adding the Field to a Record Type

Once created, the Referential Field can be added to any record type.

We’ve added the Stakeholders field to the User Stories record type. See the image below.

HELP	To learn more about adding fields to record types, click the link below: See step 8 onwards in Defining Custom Fields for a Record Type.

Displaying Referential Field in Different Editors

Detail Editor

To display the field in detail editor, customize the Screen Layouts of the record types and add the new field.

HELP	To learn more about adding fields to the detail editor, click the link below: Customizing a Form Layout of a Record Type

Editing the Field

• Add references to other artifacts using the referential field

HELP	To learn more about adding fields to the detail editor, click the link below: Customizing a Form Layout of a Record Type

• If you have created a multi-value referential field, the users can add one or more artifacts as references from the allowed record types.

• If you have created a single-value referential field, users can add only one artifact as a reference from the allowed record types.

• Remove artifacts from the field

• A traceability link gets created if a traceability rule is defined between related record types.

OneView Document Editor

Customize the OneView Field Layout of the OneView sections where you want to display the new field and add the fields to it. See OneView Field Layouts.

Document View & Focused View

Add the field to the Screen Layouts of the Screen Layout Sets in which you want to display the new field.

HELP	To learn more about adding fields to the Document View and Focused View, click the links below: Customizing Screen Layout for Record Types to display in Document View Creating Layout Sets

Artifacts Tree & Artifacts List

You can add the field as a column in Artifact Tree/Artifact List and save it as a View.

HELP	To learn more about adding fields to the Artifact Tree/Artifact List, click the links below: See the Editing a View topic in Working with Views.

Traceability Coverage Matrix

You can add the field as a column while defining or modifying a query. See Defining Adhoc Query.

Wiki

You can add the field as a column in Macro Record List to show in Wiki pages. See How to Insert a Macro Record List in Wiki to Display Real-Time Data from the Repository.

Conclusion

In conclusion, Referential Fields are a powerful tool for managing and streamlining the relationships between different artifacts in your projects. By providing direct links to related artifacts, they simplify navigation and improve workflow efficiency. Referential Fields help ensure that all relevant information is easily accessible and connected. By integrating them into various interfaces such as OneView, Document View, and Traceability Coverage Matrix, you can significantly enhance your project’s traceability and overall management.

For additional guidance, please refer to the FAQs section or contact support for further assistance.

FAQs

How do Referential Fields differ from Linked Records Fields?

Referential Fields are actual database fields where you can store a direct reference to an artifact, much like inserting a link in a rich text field. This allows you to create permanent, version-specific connections between artifacts. In contrast, Linked Records Fields are pseudo fields that display query results based on traceability links without physically storing references in the database. While Linked Records Fields affect traceability without altering the artifact’s version, Referential Fields can be configured to increment the artifact’s version when modified.

When should I use Referential Fields instead of Linked Records Fields?

Use Referential Fields when you need to store a persistent reference to an artifact within the database, particularly when you want the option to increment the artifact’s version upon any changes. This is useful for maintaining clear, version-specific relationships between artifacts. On the other hand, Linked Records Fields are better suited for managing dynamic traceability without impacting the artifact’s version.

What happens when changes are made to Referential Fields?

When you modify a Referential Field, the changes can be configured to increment the artifact’s version, creating a version-specific reference. This allows you to track changes over time and ensures that the reference is accurately reflected in the artifact’s history. These modifications will also appear in the Compare Versions or Compare Records screens, unlike changes to Linked Records Fields.

Are Referential Fields version-specific?

Yes, Referential Fields can be version-specific. When you modify a Referential Field, the artifact’s version can be incremented, and the changes will be displayed in the Compare Versions screen. This ensures that each version of the artifact maintains accurate references to other artifacts.

How are Referential Fields configured?

Referential Fields are configured by defining their properties during creation, such as whether they will reference single or multiple artifacts and which record types can be selected. You can also specify if the field should increment the artifact’s version upon modification. This configuration process ensures that Referential Fields are tailored to the specific needs of your project.

Revised: August 9^th , 2024