This article describes how to create a relationship type between issues and an item type. As mentioned in, Understanding Relationships Between Issues and Items, relationships must be configured by project, and, you can define multiple relationship types within a project.


Prerequisites

  • You must have "Change" access rights to the CMS project.
  • A CMS project exists and has at least one Issue Type configured.
  • The item type, to which you want to create relations to, exists.

Creating a New Relationship

The first step is to configure a new relationship in the project.

  1. Open the project, and select the Setup menu. 
  2. Select Relationships.
  3. Right-click on the Relationships pane and select Add new relationship.
    The New relationship dialog will display. All fields are required, except for Floating.
  4. Enter a SID for the new relationship type. This cannot be changed after the relationship is created. It must be unique.
  5. Enter a Name for the relationship type. This can be changed at any time.
  6. 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. 
  7. Enter a Ref name. This is the designation of the other object (in this example, an item type) in the relationship. Again, this name should identify the role that the item will play in the relationship. This name will display under Relationships in the issue view. This can be changed at any time.
  8. Select a Ref multiplicity to indicate the number of object types (in this example, item types). Possible values are "List" (multiple) or "Single". Note that "Single" relationships will be listed in the Attributes section of the issue editor. Ref multiplicity cannot be changed after the relationship is created.
  9. Enter a Ref type by clicking on Select item type. The Select type dialog will display. The Ref type can be changed after the relationship type has been created by changing the item type to some other item type.
  10. Check Floating if you want the relationship to always point to the last version of the item. For example, if an item that has links to issues is released and a new version is created, all of its linked issues will move to the next version of the item. This can be changed at any time. See Understanding Relationships Between Issues and Items for more explanation of this option.
  11. Click OK to save the new relationship type.
  12. Repeat the above steps for each desired relationship type.


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



Configuring Constraints

There is an option to configure constraints for a relationship between issues and items. A constraint limits the relationship to a specific item's parts. To configure, you must first have created the relationship as described above, and it must use Ref multiplicity "Single".



Select the relationship and click Edit Config.


Enter a configuration in the Edit XML dialog: 

The configuration is defined by a required <RelationshipConfig> element.


The optional <Editor> specifies the type of dialog used for selecting the Ref obj objects in the relationship. 

  • The attribute type is required, and indicates the type of dialog used for the selection. Currently supported values are: "dropdown". If the attribute value is blank, a default selection dialog will be used.
  • The optional attribute width indicates the width that should be used for the dialog.

The optional sub-element <VersionInfo> tells that the item version should be indicated in the dialog.


<Constraint> defines the condition that must be fulfilled for a correct relationship. The constraint is further used by the editor to list alternatives that match the constraint.




The sub-element <FromItem> with the mandatory id attribute specifies an item according to its ID, to be used as a base for selecting alternative items to be used in the relationship.


The sub-element <Path> defines the path of the parts to be followed from the <FromItem> item, according to SystemWeaver Path queries.


Example With Constraint Configuration

<RelationshipConfig>
  <Editor type="dropdown" width="200">
    <VersionInfo />
  </Editor>
  <Constraint> 
    <FromItem id="x0400000000000C47">
      <Path>/2IPG</Path>
    </FromItem>
  </Constraint> 
</RelationshipConfig>

Given the above constraint on the "Calibration parameters" relationship called "Parameter", users will be presented with a drop-down list of valid parts to link the issue to. All of the parts meet the definition in the constraint, i.e., they must be a part of the "Component 1", and they can only select a single value.


Result


Example Without Constraint Configuration

Any Parameter in the database can be selected.

Activating the Relationship

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 item and an issue of this type. 

  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, defined relationships in the project. Right-click on the relationship type and select Include. You can change this to Exclude at any time.


The relationship type is now available when users link items of the type selected as Ref type in the relationship configuration.


In the below example, a "Requirement" item has been copied to the clipboard, and can be pasted to issues of type "Issue" as a generic Item Reference, or as a "Requirements" type of Ref multiplicity "List". There is also an item reference called "Parameter" of Ref multiplicity "Single".