Defining relationship types

The ability to add relationship types is in beta. Please reach out to Cortex Customer Engineering with any feedback.

Relationship types allow you to define, manage, and visualize relationships between entities within your Cortex workspace, ensuring your organization's structures and dependencies are accurately represented.

Understanding relationship types in Cortex

A relationship type defines how two entities relate to either other, and constrains the types of entities that can be the source and destination entities within the relationship.

Cortex provides multiple options for defining a relationship:

• Entity relationship: As described on this page, you can customize a relationship type (hierarchical or cyclical) between any entity type.

• Team hierarchy: You can define a hierarchical relationship between team entities. Learn more in Add teams.

• Domain hierarchy: You can define a hierarchical relationship between domain entities. You can also configure inheritance; the owner of an entity can be inherited from entities higher in the domain hierarchy. Learn more in Add domains.

• Dependencies: You can define a cyclical relationship between non-team entities. Learn more in Defining dependencies.

View relationship types

View all configured relationship types

To view all relationship types, go to Catalogs > All entities then click the Relationship types tab.

On the Entities page, click the "Relationship types" tab.

To view the details of a specific relationship type, click its name from the list.

View relationships on entity pages

If an entity is part of a relationship, you can view this information on its entity details page. Click Relationships in the left sidebar to see the different relationship types that the entity belongs to.

In the example entity below, there are three destination entities in an "App Components" relationship:

Manage relationship types

Create relationship types and relationship connections

Cortex UI

Create relationship types in the Cortex UI

1. Navigate to Catalogs > All entities then click the Relationship types tab.
2. In the upper right corner, click Create > Create new relationship type.

   
3. Configure the details and entity types:

   1. Name: Enter a name for the relationship type.

   2. Identifier: Enter a unique identifier, used to specify this relationship in YAML definitions for this relationship type.

   3. Description: Add a description of the relationship to help others understand its purpose.

   4. Create relationship type catalog: Enable this option to create a catalog for this relationship type.

   5. Source entity types: Search for and select the entity types which will be the source for this relationship. Selecting no entity type means that all entity types are available as sources.

      • You can also customize the singular and plural wording of the entity types and the cardinality.

   6. Destination entity types: Search for and select the entity types which will be the destination for this relationship. Selecting no entity type means that all entity types are available as destinations.

      • You can also customize the singular and plural wording of the entity types and the cardinality.

4. Configure the relationship constraints:

   1. Architecture: If you are configuring hierarchical data, such as an org chart, we recommend choosing Acyclical. If you are configuring graph-like data, such as dependencies, we recommend choosing Cyclical.

   2. Definition location: Configure where relationships can be defined — from destination entities, from source entities, or from either.

5. Click Create.

Create relationship connections between entities in the UI

After creating the relationship type, you can configure connections between entities in a relationship. You can do this via the entity descriptor or in the UI, as described below:

1. Navigate to an entity details page. In the upper right corner, click Configure entity.
2. Click the Relationships tab.

3. At the top of the Relationship Type section, click the dropdown to select which relationship type you are configuring connections for.
4. After selecting the relationship type, you can search for and select entities in the Sources dropdown and in the Destinations dropdown.
5. At the bottom of the page, click Save changes.

Entity descriptor

Create relationship connections between entities in the entity descriptor

Relationship types must be created in the Cortex UI or via the API. You can configure relationship connections between entities in the entity YAML.

In a source entity's YAML, you can use the x-cortex-relationships tag to define its destination entities.

In the example below, a source entity's YAML has a defined relationship type called app-components and has destination entities production-ui and backend-app.

  x-cortex-relationships:
  - type: app-components
    destinations:
    - tag: production-ui
    - tag: backend-app

The relationship between entities in Cortex is based on the relationship being defined in the entity's YAML file; Cortex does not set hierarchies or relationships based on a YAML file's location in your repository.

API

Create relationship types via the API

Documentation is coming soon for managing relationship types via the Cortex API. Please reach out to your Cortex Customer Success Manager with any questions.

Edit relationship types

To edit an existing relationship type:

1. Navigate to Catalogs > All entities then click the Relationship types tab.
2. In the row containing the relationship type, click the pen icon.
3. Make any necessary changes, then at the bottom of the page, click Save.

Delete relationship types

1. Navigate to Catalogs > All entities then click the Relationship types tab.
2. Click the relationship type name.

3. On its details page, in the upper right corner, click Remove.

Entity relationship CQL

Entity relationship destinations

All recursive destinations an entity for a relationship type, with an optional depth parameter to expand results

Definition: entity.destinations(relationshipType = "my-relationship")

Examples

You could write a Scorecard rule to ensure that an entity has at least one destination with the "my-relationship" type:

entity.destinations(relationshipType = "my-relationship").length > 0

Entity relationship sources

All recursive sources an entity for a relationship type, with an optional depth parameter to expand results

Definition: entity.sources(relationshipType = "my-relationship")

Examples

You could write a Scorecard rule that ensures an entity has at least one source with the "my-relationship" type:

entity.sources(relationshipType = "my-relationship").length > 0