Relationships in CMS projects are defined relations or links between issues and/or between issues and a specific type of item. This article describes how to create a relationship type between issues in the same project. For relationships between issues and items, see How to Define a Relationship Between Issues and Items. The relationships must be configured by project, and, you can define multiple relationship types within a project.


  • You must have "Change" access rights to the CMS project.
  • A CMS project exists and has at least one Issue Type configured.

Creating a New Relationship

The first step is to configure a new relationship in the project. For relationships between issues, there are two options - a parent/sub-issue relationship or a custom-defined relationship where a parent/sub-issue relation is not needed. 

  1. In the Setup menu, select Relationships.
  2. Right-click on the Relationships pane and select Add new relationship.

    The New relationship dialog will display. Define the issue relationship using the settings listed below.
  3. Enter a SID for the new relationship type. This cannot be changed after the relationship is created. See Parent/Sub-issue Relationships if that type of relationship is needed. 
  4. Enter a Name for the relationship type. This can be changed at any time.
  5. Enter a Source name. Think of this name as the role the issue will play in the relationship. This can be changed at any time.
  6. Enter a Ref name. This is the designation of the other object in the relationship. Again, this name should identify the role that the issue will play in the relationship. This name will display under Relationships in the issues editor. This can be changed at any time.
  7. Select a Ref multiplicity to indicate the number of occurrences allowed. Possible values are "List" (multiple) or "Single". Note that single relationships will be listed among the attributes of an issue. This cannot be changed after the relationship is created.
  8. Enter a Ref type by clicking on Select issue type. The Select type dialog will display. The Ref type can be changed after the relationship type has been created by changing the issue type to some other issue type. This can be changed at any time. (Floating is not an option for relationships between issues since it has to do with versioning and issues are not versioned.)
  9. Click OK to save the new relationship type.
  10. Repeat the above steps for each desired issue-to-issue relationship type.

 In the above example, users will have an option to link issues as "Tasks".

If you need to make changes or delete the configuration, Edit and Delete options are available if you right-click on the relationship.

Parent/Sub-issue Relationships

Creating parent/sub-issue relationships is done in the same way as described above except that you must use the SID "SI" if you wish to have the issues group properly as parent and sub-issues in configured issue views. 


In the below example, issues of any type can be linked as "Sub Issues" to another issue. 

To have the sub-issues group together in an issue view, use the <SubIssues/> option in the XML configuration of the view.


You can apply the parent/sub-issue relationships to multiple issue types to achieve a multiple level view of the relationships. 

Activating the Relationship Type

Once the relationship type is created, to be able to use it, you must include it in the configuration of the Issue Type(s) for which you want it to apply. When applied, a user will be then be able to choose this type of relationship link between an issue and another issue. 

  1. In the Setup menu, select Issue Types
  2. Select the issue type for which you want the new relationship to be available for use. The Issue Type's configuration will display to the right. 
  3. On the Definition tab, the Included Relationships section will display all available relationship types in the project. Right-click on the relationship type that you want to activate and select Include. You can change this at any time to Exclude.

The relationship type is now available when users link issues of the type selected as Ref type in the relationship configuration. In the below example, an issue has been copied ("Maintain cruise speed") and it is being linked to the "Brake for obstacle" issue as a parent by right-clicking in the Relationships section and selecting Paste "Parents"

The issue editor is accessible both via Projects (as shown above), but also via the Issues view. 

What's Next?

If you are wanting to link an issue in a "main" project with an issue in a "sub" project, see Configuring Relations Between Issues in Different Projects.