Custom Relations

Reference of the custom relations feature in Ketryx

Ketryx provides flexible traceability management through Custom Relations, enabling you to define specialized relationships between configuration items that go beyond the standard relation types.

This feature enables:

• Tailored traceability for your specific product development workflow (e.g., software-hardware dependencies, threat-vulnerability links, feature dependencies)

• Controlled linking with target item KQL filters that prevent invalid (according to your process) connections

• Automatic two-way visibility that displays both forward and reverse relations when you link items

• Integration with the traceability widget for easy link creation directly from item pages

Use custom relations when the default relation types (fulfills, tests, etc.) don't capture the specific dependencies and connections in your system architecture or development process.

This guide explains how to configure and use custom relations in your Ketryx organization.

NOTE:

• Adding custom relations should only be performed by your Ketryx organization owner.

Getting started

The following will explain the full workflow for configuring a custom relation in Ketryx. In this example, we'll create a relation called "uses HW" that allows Software Item Spec items to link to Hardware Item Spec items.

Configuration in Ketryx

1. Navigate to Organization > Advanced

2. Add your custom relation to the Custom Relations setting

{
  "SW_USES_HW": {
    "direction": "downstream",
    "fieldName": "Uses HW component",
    "reverseFieldName": "Is used by SW component",
    "relationName": "uses HW",
    "reverseRelationName": "is used by SW",
    "sourceItemTypes": [
      "Software Item Spec"
    ],
    "targetItemFilter": "type:HW",
    "traceabilityWidgetAddLabel": "Add used HW component"
  }
}

Field Descriptions:

• Key (SW_USES_HW): A unique identifier for this relation. This key must be unique across all custom relations and should be descriptive.

• direction: Either "upstream" or "downstream". Defaults to "downstream".

  • "downstream" means the relation points forward (e.g., Software → Hardware)

  • "upstream" means the relation points backward

• fieldName: The human-readable name shown when viewing the source item (e.g., "Uses HW component")

• reverseFieldName: The human-readable name shown when viewing the target item (e.g., "Is used by SW component")

• relationName: The short name for the relation in the forward direction (e.g., "uses HW")

  • Warning: This value becomes permanent once the relation is used to link items (see Limitations section below).

• reverseRelationName: The short name for the relation in the reverse direction (e.g., "is used by SW")

  • Warning: This value becomes permanent once the relation is used to link items (see Limitations section below).

• sourceItemTypes: An array of item type names that can use this relation. Can include both system item types (e.g., "Software Item Spec", "Requirement") and custom item types (e.g., "Folder")

• targetItemFilter: A KQL filter that defines which items can be targeted by this relation (e.g., "type:HW" for Hardware Item Spec items or "type:FOL" for custom Folder items)

• traceabilityWidgetAddLabel: The label shown on the button in the traceability widget (e.g., "Add used HW component")

1. Click Save changes and confirm

At this point, every project in the Ketryx organization is ready to use the custom relation between Software Item Spec and Hardware Item Spec items.

Limitations

1. Relation Names are Permanent: Once a custom relation is used to link items, relationName and reverseRelationName become permanent. These values are stored in the backend database, and changing them will break existing traceability links.

   1. Best Practice: Choose your relation names carefully the first time. Plan your naming convention before implementation and test with a pilot relation before creating multiple relations.

2. Reverse Relations Cannot Be Created from the Traceability Widget: Relations must always be created from the source item type. For example, for the SW → HW relation above (Software uses Hardware):

   1. You can create the link from the Software Item Spec

   2. You cannot create the link from Hardware Item Spec

The reverse relations ("Is used by SW component") will be visible on Hardware Items, but new links must be created from the Software Item side

Workaround: Always navigate to the source item type to create custom relation links. The reverse relation will automatically appear in the target item's traceability widget once created.