LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • View entity types
  • Create custom entity types
  • JSON schema for custom entity types
  • Create custom entities
  • Managing custom entities
  • Edit custom entities
  • Add custom entities to catalogs
  • Using custom entity types or custom data

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex
  2. Managing Entities
  3. Adding entities

Add custom entity types

Last updated 11 days ago

Was this helpful?

Every entity you add to your workspace is associated with an entity type. Cortex comes with several built-in entity types, but you can to extend your catalogs.

There are two distinct parts of this process: (via the UI or API), then (via the UI, GitOps, or API).

View entity types

To view all entity types, go to Catalogs > All Entities then click the .

A Cortex logo appears next to built-in entity types. When you hover over the logo, you will see a "Powered by Cortex" banner:

The other entity types in the list are custom types.

Create custom entity types

You can create custom entity types:

  • Manually in the Cortex UI

To create, edit, and delete entity types, your user or API key must have the Edit entity types permission.

Create entity types in the Cortex UI

  1. In Cortex, navigate to Catalogs > All entities.

  2. Click the Entity types tab, then click Create entity type.

  3. Configure the form:

    • Name: Enter a human-readable name that will appear in the catalog for this entity type.

    • Type: Enter a unique identifier that corresponds to the entity type. This will be used to specify the type defined in the YAML definitions for imported entities.

    • Description: Optionally, enter a description for the entity type.

    • Display icon: Select an icon to appear alongside the entity type throughout the app.

      • In the example screen shot below, we’ve created a custom entity type called Employee — this is what we’ll use to represent individuals at our organization. In the schema section, you can see that each profile is required to include an employee’s location. This means every time you create an entity of type "Employee," you will define the employee's location.

  4. At the bottom of the page, click Create.

After saving, the entity type will appear in the Entity types tab under Catalogs > All entities, and you are now able to import entities of that type.

Create entity types via the API

JSON schema for custom entity types

Entity type definitions require a JSON schema that outlines the attributes that entities should conform to.

The JSON schema for a custom entity type ensures consistency and validation when creating entities of that type. The attributes listed under required in the schema must be defined for entities of that type according to the outlined properties.

In the example below, location is required when creating this type of entity, but the schema also includes department as a possible property.

{
  "type": "object",
  "required": [
    "location"
  ],
  "properties": {
    "location": {
      "type": "string"
    },
    "department": {
      "type": "string"
    }
  }
}
Field
Definition
Required

type

Type of entity and/or required component: array, boolean, integer, null, number, object, or string

Yes

required

Required specs for the entity type

properties

Properties of the required specs (including type)

Yes only if the required field is not null

Adding an entity schema for new custom entities

When creating a new entity of the custom type, if the entity type's JSON schema requires certain attributes, you must include the metadata for those attributes on that entity.

Add attributes via JSON schema
{
    "location": "San Diego",
    "department": "Engineering"
}
Add attributes via YAML

If you are following a GitOps workflow, or if you are editing the entity's YAML directly in the Cortex UI, you can update the custom entity's metadata in the YAML.

x-cortex-type: org-employees
x-cortex-definition:
   location: San Diego
   department: Engineering

Metadata in the entity details page

In the example below, the entity "Sally S" displays metadata for the property "location."

Create custom entities

  • in the Cortex UI

  • via the Cortex API

To create custom entities, your user or API key must have the Edit entities permission.

Create custom entities in the Cortex UI

  1. In the main nav of Cortex, click Catalogs > All entities.

  2. At the top of the Services page, click +Import entities.

  3. Configure the form:

    • Type: Select your custom entity type.

    • Schema: Enter a JSON schema to define your custom entity.

      • For example, if the entity type's schema requires location and department, your new entity's schema might look like this:

    • Entity name: Enter a human readable name for your entity.

    • Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.

    • Description: Enter a description of the entity to help others understand its purpose.

    • Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.

    • On-call: Configure on-call information.

    • Repository: Select the repository associated with this entity.

  4. When you are finished, click Confirm import at the bottom of the page.

Create custom entities in the entity descriptor

If your entity is of a different type, you must specify x-cortex-type and x-cortex-definition.

Example cortex.yaml

openapi: 3.0.1
info:
  title: Sally S
  description: Technical writer
  x-cortex-tag: employee-sally
  x-cortex-type: org-employees
  x-cortex-definition:
    location: San Diego
    department: Engineering

To delete entities, your API key must have the Delete entities permission.

Managing custom entities

Edit custom entities

It is possible to edit entities after creating them:

  1. Navigate to the entity's page.

  2. In the upper right corner, click Configure entity.

  3. Make any desired changes.

    • Note: The only field you cannot edit is the identifier.

  4. At the bottom of the screen, click Save changes.

Add custom entities to catalogs

Using custom entity types or custom data

In some instances, you may want to use custom data instead of a custom entity type. This is recommended if you need more flexibility for these entity types; they may not always require specific metadata.

It is possible to create an entity type with an empty properties schema:

{
  "type": "object",
    "required": []
    "properties": {}
}

A schema is ideal for enforcing static properties across all entities, while custom data allows users to augment and update attributes.

Via the

When creating an entity type, keep in mind that these will ultimately dictate how you import specific entities later on. After creating the type itself, you will be able to (via the UI, API, or GitOps).

Schema: Define a that will be used to validate the x-cortex-validation block of a given entity’s YAML.

This can be used to enforce certain attributes about entities, such as a region or version number. Attributes defined in the schema will be required when creating an entity of that type, which can then be validated in Scorecards. Learn more under .

If you want entities of the new entity type to automatically belong to a specific catalog, you can configure the catalog's defined entity types while or you can to update the entity types.

You can create, update, and delete entity types using the .

Learn more about the below.

Custom entity type definitions are powered by the open-source project.

While , you can enter JSON for the entity's schema into the Schema field.

Based on the , the entity schema format would look like the following:

Based on the , the entity YAML would look like the following:

When creating a custom entity, the x-cortex-type (the custom entity type) and the x-cortex-definition are required. Learn more under .

Defining a JSON schema enables visibility on an . The schema and the defined properties will appear under the Metadata section on the entity's overview, making it easy for you to identify key specs.

After , you can create entities of that custom type:

in the via

Before creating a custom entity in the UI, make sure you have UI-based editing enabled for this entity type in .

Choose Create entities manually.

See for more information.

Groups: Select your entity.

Owners: Define for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.

Parents: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the .

Dependencies: Select entities that this entity depends on. These can be visualized in the .

Before creating a custom entity via GitOps, make sure you have UI-based editing disabled for this this entity type in .

The x-cortex-definition field is validated against the that you created via the UI or API. If your custom entity type does not have specific requirements, entities of that type still need a non-null definition specified, like x-cortex-definition: {}.

You can create, read, update, and delete entities via the .

After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you , you can set the entity type criteria.

By default, any you create will belong to the Infrastructure catalog. If you do not want the entity type to belong to this catalog, you can add the entity type to a different catalog's definition.

While a custom entity type's metadata will appear on the overview of an , custom data does not appear there. Instead, it appears in the Custom data sidebar of an entity details page.

This entity type will display in the catalogs, but entities of this type won't be validated against certain specs. Such properties can instead be defined using .

API
Cortex API
JSON Schema
entity's detail page
Settings > GitOps
groups to segment
ownership
relationship graph
relationship graph
Settings > GitOps
entity type definition
Cortex API
entity's details page
custom data
create entities of that type
JSON schema
JSON schema for custom entity types
creating a new catalog
edit an existing catalog
JSON schema
creating a custom entity in the Cortex UI
example above
example above
Create custom entities in the entity descriptor
creating your custom entity type
JSON schema for custom entity types
create a custom catalog
custom entity types
create unlimited custom entity types
Entity types tab
Creating the entity type itself
creating entities of that custom type
GitOps
entity descriptor YAML
In the upper right, click "Create entity type."
A custom entity called Employee contains example JSON demonstrating how to configure a required "location" field.
An entity called "Sally S" displays metadata. For a property called "location," the value is "San Diego."
The entity schema includes "location" and "department" metadata