Relationship Fields

You can create relationship fields to link items for reference purposes, such as linking duplicate items, or linking features and their defects. You can also create relationship fields to link items for the purposes of tracking and monitoring. For example, you can create a Sub Features relationship field on a Feature item type to link a master feature to a group of secondary features, which in turn can have relationship fields that link to defect and documentation items. Users can then track the overall development progress for a master feature by reviewing its hierarchy of related items using the Relationships view. For more information on the Relationships view, see the User documentation.

Every relationship consists of a pair of relationship fields: one for the forward relationship and one for the backward relationship. Forward relationships are relationships where the related item is a child of the original item. Backward relationships are relationships where the related item is a parent of the original item. For example, you could create a forward relationship field named Sub Features to link master features to their sub features, and a backward relationship field named Master Feature to link sub features to their master feature. Users can create a relationship from either the child or the parent, and the corresponding field in the related item is updated automatically.

Relationship Fields: Values Tab

Field

Description

Types

Item type that is to use the relationship field

Allowed Types

Item types that can be linked to using the relationship field.

For example, to allow the field to be used to create relationships between documentation items and bugs, select Docs under Available Types and add Bugs to the Allowed Types. Then select Bugs under Available Types, and add Docs to the Allowed Types.

Allowed Types are uneditable for the following fields: Contains, Contained By, Referenced By, Shares, and Shared By.

Repeat the selection process for additional item types.

You can create heterogeneous and homogenous segments using allowed types.

To learn how to create homogeneous subsegments, see Setting Up Documents.

Cycle Detection

To prevent relationship loops from occurring. A relationship loop occurs when an item has both a forward and a backward relationship with another item within the same relationship hierarchy.

Trace

Sets the field as a trace relationship. Trace relationships are defined via field pairs are and presented to the user in domain-specific language, for example, Test and Requirements. To learn more about trace relationships, see the Documents section of the user documentation.

Forward and Backward tabs

The fields used for forward and backward relationships.

For example, if you are defining a relationship field to track defects related to an item, the forward relationship field could be named Defects and the backward relationship field could be named Defects Of.

Name

Name of the relationship field. The name you enter is also used for the backward relationship field and prefixed with the word Backward. You can edit this name.

Once the field is created, changes to the name of the forward relationship field are not carried over to the backward relationship field name.

Multi Valued

Allow links to multiple items. For example, a field used to track defects on an item would need to allow multiple linked items; a field used to identify the documentation item used for documenting the changes made by a change order item would only need to allow a single linked item.

If you want a single-valued relationship field to be able to be changed using drag-and-drop in the Relationships view, you must make it visible on the appropriate item types. For example, if you have Documented By and Documentation For as a set of relationship fields, and the Documented By field is single-valued, if you want users to be able to change the related documentation item for a change order item using drag-and-drop, the Documented By field must be visible on the change order item type.

Wrapped table content

Display wrapped table content for the relationship field when editing the item.

Display Style

Display the relationship field in table format or in a comma-separated values (CSV) format. The table format allows you to sort the linked items and manipulate the columns that display in the table. The CSV format only displays the IDs and relationship flags of the linked items.

If document versioning is enabled, relationship fields configured to display values in CSV format do not support versioned item IDs, for example, 184-1.2.

Display Rows

Number of rows to display for the relationship field when editing the item.

Browsing Style

When adding related items, specifies the browsing style of candidate items. Choices are Query and Finder.

When Query is selected, the following additional options are available:

All Queries: If you select this option, you can see all queries while selecting the related item.
Specific Queries: If you select this option, you can see only queries in the Specific Queries list while browsing the related item. This list contains only Admin queries.
Set Default Browse Query: If you select this option, you set the default Admin query that you want to use when browsing for items to add to the relationship field. Use the data filter to select the desired Admin query. If there are no Admin queries, this option is unavailable.

The list of queries available to the end user while browsing for the related item depends on whether:

Specific Queries list is set.
Default Browse Query is set.

The queries list visible is a combination of the Specific Queries list and Default Browse Query list for the respective relationship field.

If the Specific Queries list is empty and Default Browse Query has been set, only default queries are listed while browsing for related item.
If the Specific Queries list is empty and Default Browse Query is not set, or if the user does not have permission to any of these specified queries, only the last query used by the user is listed while browsing for related item.

When Finder is selected, the following options are used to define the contents of Find Items to Relate window:

Finder Query: The Admin query that is used to populate the left pane of the Find Items to Relate window.
A Finder Query must be provided for the where field filter in the client for the Find Items to Relate window to work.
Outline Format: The way in which to display the outline in the right pane of the Find Items to Relate window. You can select fields from the Fields drop-down box or specify additional fields.
Relationships To Follow: The list of relationships. The specified relationships return the items related to those in the left pane of the Find Items to Relate window and displays them in the right pane.

Set Default Browse Query For Web UI: Sets the default query to use in the Web UI when browsing for items to add to the relationship field that has a Finder browsing style.

The Find Items to Relate window is available only in the client.
If Set Default Browse Query For Web UI is not specified, browsing behavior for adding related items in the Web UI is the same as when All Queries is selected.

For more information about the Find Items to Relate window, see the .

Relationship Flags

Relationship flags are used to indicate when a related item has changed. To add relationship flags for the field click Add.

A user must be licensed for configuration management to be able to use relationship flags in an item.
Relationship flags defined for relationship fields can be set automatically through a field rule.