# REST API operations
Source: https://docs.cortex.io/api

Programmatic access to your entities, Scorecards, Workflows, and more

## Cortex API

The Cortex REST API provides programmatic access to your entities, Scorecards, Workflows, and more.

### Base URL

Send API requests to the base URL for the region or deployment where your Cortex workspace is hosted:

| Deployment | Base URL |
| - | - |
| US | `https://api.getcortexapp.com` |
| EU | `https://api.eu.cortex.io` |
| Self-managed | Your Cortex backend URL (for example, `https://cortex-api.yourdomain.example`) |

If you're not sure which region your workspace is in, check the URL you use to log in. If it starts with `app.eu.cortex.io`, use the EU base URL. If it starts with `app.getcortexapp.com`, use the US base URL.

For self-managed Cortex, use the hostname you set as `app.hostnames.backend` in your Helm chart values.

### Authentication

All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.

| Security Scheme Type: | http |
| - | - |
| HTTP Authorization Scheme | bearer |
| Bearer format: | JWT |

### Operations

See the sub-pages in this section for all available operations. Throughout these documentation pages, click **Try it** under an operation to send a request directly from the documentation page. Before you send it, click the base URL next to the endpoint path and select the one that matches your workspace. For self-managed Cortex, select `{baseUrl}`, then enter your backend URL in the **baseUrl** field under **Server**.

![The selector icon in the base URL.](https://mintcdn.com/cortex-290c0c42/KuOyXNHfLFf7MXsJ/images/api-selector.png?fit=max\&auto=format\&n=KuOyXNHfLFf7MXsJ\&q=85\&s=21e5efd6e3dd652c456784fd62327c9b)

![A list of the available base URLs for the API.](https://mintcdn.com/cortex-290c0c42/KuOyXNHfLFf7MXsJ/images/api-selector-urls.png?fit=max\&auto=format\&n=KuOyXNHfLFf7MXsJ\&q=85\&s=761f59ea067e2052b6b169723da61e40)

### Rate limiting

The Cortex API limits requests to 1000 per minute per client. The body size of any given request has a maximum of 2MB.
If you attempt too many requests in a short period, a `429` error will be returned with a `Retry-After` header. If you are hitting rate limits frequently, please contact your Cortex Customer Success Manager to discuss your use case.

> [!NOTE]
>
> API rate limits are subject to change. Customers will be notified of any changes made to the rate limits.


# Add a single configuration
Source: https://docs.cortex.io/api/rest/anthropic-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/anthropic/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/anthropic-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/anthropic/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/anthropic-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/anthropic/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/anthropic-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/anthropic/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/anthropic-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/anthropic/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/anthropic-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/anthropic/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/anthropic-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/anthropic/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/anthropic-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/anthropic/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/anthropic-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/anthropic/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/anthropic-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/anthropic/configuration/validate



# API Keys
Source: https://docs.cortex.io/api/rest/api-keys



Use these operations to interact with [API keys](/configure/settings/api-keys) in Cortex.

### Required permissions

Your API token must have the `Edit API keys` permission.

### Roles

When creating an API key, you must specify roles. Each role requires a `type` field set to `DEFAULT` or `CUSTOM`. You can assign multiple roles (both default and custom) to a single API key.

**Default roles** use the `role` field to specify the permission level. Allowed values: `READ_ONLY`, `USER`, `ADMIN`.

```json theme={null}
{
  "type": "DEFAULT",
  "role": "READ_ONLY"
}
```

**Custom roles** use the `tag` field (not `role`) to reference a [custom role](/configure/settings/managing-users/permissioning/custom-roles) by its unique tag:

```json theme={null}
{
  "type": "CUSTOM",
  "tag": "custom-role-tag"
}
```

**Example payload with multiple roles:**

```json theme={null}
{
  "name": "Entities scanner",
  "roles": [
    { "type": "DEFAULT", "role": "ADMIN" },
    { "type": "CUSTOM", "tag": "custom-role-tag" }
  ]
}
```

> [!NOTE]
>
> Note: Users with custom roles can only create API keys assigned to roles with equal or fewer permissions than their own.

## Operations

> **[List API keys](/api/rest/api-keys/list-api-keys)**
>
> `GET /api/v1/auth/key`

> **[Get API key](/api/rest/api-keys/get-api-key)**
>
> `GET /api/v1/auth/key/{cid}`

> **[Create API key](/api/rest/api-keys/create-api-key)**
>
> `POST /api/v1/auth/key`

> **[Update API key](/api/rest/api-keys/update-api-key)**
>
> `PUT /api/v1/auth/key/{cid}`

> **[Delete API key](/api/rest/api-keys/delete-api-key)**
>
> `DELETE /api/v1/auth/key/{cid}`


# Create API key
Source: https://docs.cortex.io/api/rest/api-keys/create-api-key

/openapi/cortex_swagger.json post /api/v1/auth/key
Create new API key.

The API key used to make the request must have the `Edit API keys` permission



# Delete API key
Source: https://docs.cortex.io/api/rest/api-keys/delete-api-key

/openapi/cortex_swagger.json delete /api/v1/auth/key/{cid}
Delete API key

The API key used to make the request must have the `Edit API keys` permission



# Get API key
Source: https://docs.cortex.io/api/rest/api-keys/get-api-key

/openapi/cortex_swagger.json get /api/v1/auth/key/{cid}
Get API key



# List API keys
Source: https://docs.cortex.io/api/rest/api-keys/list-api-keys

/openapi/cortex_swagger.json get /api/v1/auth/key
List API keys

The API key used to make the request must have the `Edit API keys` permission



# Update API key
Source: https://docs.cortex.io/api/rest/api-keys/update-api-key

/openapi/cortex_swagger.json put /api/v1/auth/key/{cid}
Update API key

The API key used to make the request must have the `Edit API keys` permission



# Add a single configuration
Source: https://docs.cortex.io/api/rest/apiiro-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/apiiro/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/apiiro-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/apiiro/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/apiiro-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/apiiro/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/apiiro-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/apiiro/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/apiiro-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/apiiro/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/apiiro-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/apiiro/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/apiiro-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/apiiro/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/apiiro-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/apiiro/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/apiiro-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/apiiro/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/apiiro-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/apiiro/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/argocd-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/argocd/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/argocd-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/argocd/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/argocd-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/argocd/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/argocd-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/argocd/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/argocd-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/argocd/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/argocd-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/argocd/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/argocd-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/argocd/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/argocd-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/argocd/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/argocd-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/argocd/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/argocd-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/argocd/configuration/validate



# Audit Logs
Source: https://docs.cortex.io/api/rest/audit-logs



Use these operations to interact with [audit logs](/configure/settings/audit-logs) in Cortex.

### Required permissions

Your API token must have the `View audit logs` permission.

> **[Retrieve audit logs](/api/rest/audit-logs/retrieve-audit-logs)**
>
> `GET /api/v1/audit-logs`


# Retrieve audit logs
Source: https://docs.cortex.io/api/rest/audit-logs/retrieve-audit-logs

/openapi/cortex_swagger.json get /api/v1/audit-logs
Note: To see the complete list of possible values, please reference the available filter options for [audit logs under Settings in the app](https://app.getcortexapp.com/admin/settings/audit-logs).  API key must have the `View audit logs` permission.



# Add a single configuration
Source: https://docs.cortex.io/api/rest/aws-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/aws/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/aws-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/aws/configurations/{accountId}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/aws-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/aws/configurations



# Get AWS resource details for an entity
Source: https://docs.cortex.io/api/rest/aws-api/get-aws-resource-details-for-an-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/aws

            Returns all cached AWS resource details for the specified entity.
            This endpoint serves cached data only and does not make live AWS API calls.
        



# List AWS types
Source: https://docs.cortex.io/api/rest/aws-api/list-aws-types

/openapi/cortex_swagger.json get /api/v1/aws/types



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/aws-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/aws/configurations/{accountId}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/aws-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/aws/configurations



# Update configurations
Source: https://docs.cortex.io/api/rest/aws-api/update-configurations

/openapi/cortex_swagger.json put /api/v1/aws/configurations



# Update configured AWS types
Source: https://docs.cortex.io/api/rest/aws-api/update-configured-aws-types

/openapi/cortex_swagger.json put /api/v1/aws/types



# Validate a configuration
Source: https://docs.cortex.io/api/rest/aws-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/aws/configurations/validate/{accountId}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/aws-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/aws/configurations/all/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/azure-active-directory-entra-id-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/active-directory/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/azure-active-directory-entra-id-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/active-directory/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/azure-active-directory-entra-id-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/active-directory/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/azure-active-directory-entra-id-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/active-directory/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/azure-active-directory-entra-id-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/active-directory/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/azure-devops-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/azure-devops/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/azure-devops-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/azure-devops/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/azure-devops-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/azure-devops/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/azure-devops-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/azure-devops/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/azure-devops-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/azure-devops/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/azure-devops-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/azure-devops/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/azure-devops-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/azure-devops/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/azure-devops-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/azure-devops/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/azure-devops-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/azure-devops/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/azure-devops-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/azure-devops/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/azure-resources-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/azure-resources/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/azure-resources-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/azure-resources/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/azure-resources-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/azure-resources/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/azure-resources-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/azure-resources/configurations



# List Azure Resources types
Source: https://docs.cortex.io/api/rest/azure-resources-api/list-azure-resources-types

/openapi/cortex_swagger.json get /api/v1/azure-resources/types



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/azure-resources-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/azure-resources/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/azure-resources-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/azure-resources/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/azure-resources-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/azure-resources/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/azure-resources-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/azure-resources/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Update configured Azure Resources types
Source: https://docs.cortex.io/api/rest/azure-resources-api/update-configured-azure-resources-types

/openapi/cortex_swagger.json put /api/v1/azure-resources/types



# Validate a configuration
Source: https://docs.cortex.io/api/rest/azure-resources-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/azure-resources/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/azure-resources-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/azure-resources/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/bamboohr-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/bamboohr/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/bamboohr-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/bamboohr/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/bamboohr-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/bamboohr/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/bamboohr-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/bamboohr/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/bamboohr-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/bamboohr/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/bitbucket-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/bitbucket/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/bitbucket-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/bitbucket/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/bitbucket-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/bitbucket/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/bitbucket-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/bitbucket/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/bitbucket-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/bitbucket/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/bitbucket-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/bitbucket/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/bitbucket-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/bitbucket/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/bitbucket-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/bitbucket/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/bitbucket-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/bitbucket/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/bitbucket-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/bitbucket/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/bugsnag-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/bugsnag/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/bugsnag-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/bugsnag/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/bugsnag-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/bugsnag/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/bugsnag-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/bugsnag/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/bugsnag-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/bugsnag/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/buildkite-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/buildkite/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/buildkite-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/buildkite/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/buildkite-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/buildkite/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/buildkite-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/buildkite/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/buildkite-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/buildkite/configuration/validate



# Catalog Entities
Source: https://docs.cortex.io/api/rest/catalog-entities



Use these operations to interact with [entities](/ingesting-data-into-cortex/entities-overview/entities) in Cortex.

To see additional API operations specific to team entities, see the [Teams API page](/api/rest/teams).

### Required permissions

* Edit entities: Your API key must have the `Edit entities` permission.
* Archive entities: Your API key must have the `Archive entities` permission.
* Delete entities: Your API key must have `Delete entities` permission.

## Operations

> **[List entities](/api/rest/catalog-entities/list-entities)**
>
> `GET /api/v1/catalog`

> **[Search entities](/api/rest/catalog-entities/search-entities)**
>
> `GET /api/v1/catalog/search`

> **[List entity descriptors](/api/rest/catalog-entities/list-entity-descriptors)**
>
> `GET /api/v1/catalog/descriptors`

> **[Retrieve entity details](/api/rest/catalog-entities/retrieve-entity-details)**
>
> `GET /api/v1/catalog/{tagOrId}`

> **[Retrieve most recent GitOps log for entity](/api/rest/catalog-entities/retrieve-most-recent-gitops-log-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/gitops-logs`

> **[Retrieve entity descriptor](/api/rest/catalog-entities/retrieve-entity-descriptor)**
>
> `GET /api/v1/catalog/{tagOrId}/openapi`

> **[Retrieve entity Scorecard scores](/api/rest/catalog-entities/retrieve-entity-scorecard-scores)**
>
> `GET /api/v1/catalog/{tagOrId}/scorecards`

> **[Create or update entity](/api/rest/catalog-entities/create-or-update-entity)**
>
> `POST /api/v1/open-api`

> **[Archive an entity](/api/rest/catalog-entities/archive-an-entity)**
>
> `PUT /api/v1/catalog/{tagOrId}/archive`

> **[Unarchive an entity](/api/rest/catalog-entities/unarchive-an-entity)**
>
> `PUT /api/v1/catalog/{tagOrId}/unarchive`

> **[Create or patch entity](/api/rest/catalog-entities/create-or-patch-entity)**
>
> `PATCH /api/v1/open-api`

> **[Delete entity](/api/rest/catalog-entities/delete-entity)**
>
> `DELETE /api/v1/catalog/{tagOrId}`

> **[Delete entities by ID](/api/rest/catalog-entities/delete-entities-by-id)**
>
> `DELETE /api/v1/catalog`

> **[Get Kubernetes resource details for an entity](/api/rest/kubernetes-api/get-kubernetes-resource-details-for-an-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/k8s`


# Archive an entity
Source: https://docs.cortex.io/api/rest/catalog-entities/archive-an-entity

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/archive



# Create or patch entity
Source: https://docs.cortex.io/api/rest/catalog-entities/create-or-patch-entity

/openapi/cortex_swagger.json patch /api/v1/open-api
Creates or updates an entity using OpenAPI. If the YAML refers to an entity that already exists (as referenced by the `x-cortex-tag`), this API will merge the specified changes into the existing entity.



# Create or update entity
Source: https://docs.cortex.io/api/rest/catalog-entities/create-or-update-entity

/openapi/cortex_swagger.json post /api/v1/open-api
Create a catalog entity using a descriptor YAML. By default (UPSERT mode), if the entity already exists (as referenced by the `x-cortex-tag`), this API will update the existing entity. In CREATE mode, the API will fail if the entity already exists.



# Delete entities by ID
Source: https://docs.cortex.io/api/rest/catalog-entities/delete-entities-by-id

/openapi/cortex_swagger.json delete /api/v1/catalog
Deletes the entities with the given IDs.



# Delete entity
Source: https://docs.cortex.io/api/rest/catalog-entities/delete-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}



# List entities
Source: https://docs.cortex.io/api/rest/catalog-entities/list-entities

/openapi/cortex_swagger.json get /api/v1/catalog
List all entities across the Service, Resource and Domain Catalogs.

This API returns summary data for each entity, so refer to the retrieve entity method to lookup more details for a single entity.



# List entity descriptors
Source: https://docs.cortex.io/api/rest/catalog-entities/list-entity-descriptors

/openapi/cortex_swagger.json get /api/v1/catalog/descriptors
List entity descriptors

The descriptors do not include objects (e.g. custom data, dependencies, etc) defined via the API



# Retrieve entity descriptor
Source: https://docs.cortex.io/api/rest/catalog-entities/retrieve-entity-descriptor

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/openapi
Retrieve entity descriptor

The descriptor does not include objects (e.g. custom data, dependencies, etc) defined via the API



# Retrieve entity details
Source: https://docs.cortex.io/api/rest/catalog-entities/retrieve-entity-details

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}



# Retrieve entity Scorecard scores
Source: https://docs.cortex.io/api/rest/catalog-entities/retrieve-entity-scorecard-scores

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/scorecards



# Retrieve entity verifications
Source: https://docs.cortex.io/api/rest/catalog-entities/retrieve-entity-verifications

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/verifications
Returns one entry per verification period the entity is in scope for, including periods the entity has not been verified for yet.



# Retrieve most recent GitOps log for entity
Source: https://docs.cortex.io/api/rest/catalog-entities/retrieve-most-recent-gitops-log-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/gitops-logs



# Search entities
Source: https://docs.cortex.io/api/rest/catalog-entities/search-entities

/openapi/cortex_swagger.json get /api/v1/catalog/search
Relevance-ranked catalog search. Returns a lean, hydrated result set scoped by query and/or filters.



# Unarchive an entity
Source: https://docs.cortex.io/api/rest/catalog-entities/unarchive-an-entity

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/unarchive



# Verify an entity for a verification period
Source: https://docs.cortex.io/api/rest/catalog-entities/verify-an-entity-for-a-verification-period

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/verifications/{periodCid}
Records the caller's answer for one entity in one verification period. The period must be open, and the caller must own the entity -- unless it is a global API key granted the "Verify any entity" permission, for which ownership is waived.



# Catalogs
Source: https://docs.cortex.io/api/rest/catalogs



Use these operations to interact with [catalogs](/ingesting-data-into-cortex/catalogs/viewing-catalogs) in Cortex.

### Required permissions

* View catalogs: Your API key must have the `View catalogs` permission.
* Edit catalogs: Your API key must have the `Edit catalogs` permission.

## Operations

> **[List catalogs](/api/rest/catalogs/list-catalogs)**
>
> `GET /api/v1/catalog-pages`

> **[Create or replace a catalog](/api/rest/catalogs/create-or-replace-a-catalog)**
>
> `POST /api/v1/catalog-pages`

> **[Get catalog](/api/rest/catalogs/get-catalog)**
>
> `GET /api/v1/catalog-pages/{slug}`

> **[Delete catalog](/api/rest/catalogs/delete-catalog)**
>
> `DELETE /api/v1/catalog-pages/{slug}`


# Create or replace a catalog
Source: https://docs.cortex.io/api/rest/catalogs/create-or-replace-a-catalog

/openapi/cortex_swagger.json post /api/v1/catalog-pages
Creates a catalog, or replaces the existing one with the same slug.

API key must have the `Edit catalogs` permission.



# Delete catalog
Source: https://docs.cortex.io/api/rest/catalogs/delete-catalog

/openapi/cortex_swagger.json delete /api/v1/catalog-pages/{slug}



# Get catalog
Source: https://docs.cortex.io/api/rest/catalogs/get-catalog

/openapi/cortex_swagger.json get /api/v1/catalog-pages/{slug}
Retrieves a single catalog by slug.

API key must have the `View catalogs` permission.



# List catalogs
Source: https://docs.cortex.io/api/rest/catalogs/list-catalogs

/openapi/cortex_swagger.json get /api/v1/catalog-pages
Retrieves a list of catalogs.

API key must have the `View catalogs` permission.



# Add a configuration
Source: https://docs.cortex.io/api/rest/checkmarx-sast-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/checkmarx/sast/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/checkmarx-sast-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/checkmarx/sast/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/checkmarx-sast-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/checkmarx/sast/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/checkmarx-sast-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/checkmarx/sast/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/checkmarx-sast-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/checkmarx/sast/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/circleci-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/circleci/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/circleci-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/circleci/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/circleci-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/circleci/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/circleci-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/circleci/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/circleci-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/circleci/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/circleci-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/circleci/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/circleci-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/circleci/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/circleci-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/circleci/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/circleci-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/circleci/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/circleci-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/circleci/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/clickup-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/clickup/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/clickup-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/clickup/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/clickup-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/clickup/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/clickup-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/clickup/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/clickup-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/clickup/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/codecov-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/codecov/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/codecov-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/codecov/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/codecov-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/codecov/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/codecov-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/codecov/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/codecov-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/codecov/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/coralogix-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/coralogix/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/coralogix-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/coralogix/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/coralogix-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/coralogix/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/coralogix-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/coralogix/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/coralogix-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/coralogix/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/coralogix-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/coralogix/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/coralogix-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/coralogix/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/coralogix-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/coralogix/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/coralogix-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/coralogix/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/coralogix-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/coralogix/configuration/validate



# Custom Data
Source: https://docs.cortex.io/api/rest/custom-data



Use these operations to interact with [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data) in Cortex.

### Required permissions

Edit entities: Your API key must have the `Edit entities` permission.

## Operations

> **[List custom data for entity](/api/rest/custom-data/list-custom-data-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/custom-data`

> **[Retrieve custom data for entity](/api/rest/custom-data-advanced/retrieve-custom-data-for-entity)**
>
> `GET /api/v1/catalog/custom-data`

> **[Retrieve custom data for entity by key](/api/rest/custom-data/retrieve-custom-data-for-entity-by-key)**
>
> `GET /api/v1/catalog/{tagOrId}/custom-data/{key}`

> **[Add custom data for entity](/api/rest/custom-data/add-custom-data-for-entity)**
>
> `POST /api/v1/catalog/{tagOrId}/custom-data`

> **[Add custom data via webhook](/api/rest/custom-data/add-custom-data-via-webhook)**
>
> `POST /api/v1/custom-integrations/data/{uuid}`

> **[Add custom data in bulk](/api/rest/custom-data/add-custom-data-in-bulk)**
>
> `PUT /api/v1/catalog/custom-data`

> **[Delete custom data for entity](/api/rest/custom-data/delete-custom-data-for-entity)**
>
> `DELETE /api/v1/catalog/{tagOrId}/custom-data`

> **[Delete custom data by key for entity](/api/rest/custom-data-advanced/delete-custom-data-by-key-for-entity)**
>
> `DELETE /api/v1/catalog/custom-data`


# Add custom data for entity (advanced)
Source: https://docs.cortex.io/api/rest/custom-data-advanced/add-custom-data-for-entity-advanced

/openapi/cortex_swagger.json post /api/v1/catalog/custom-data



# Delete custom data by key for entity
Source: https://docs.cortex.io/api/rest/custom-data-advanced/delete-custom-data-by-key-for-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/custom-data
Use this endpoint when attempting to delete custom data where the key contains non-alphanumeric characters. Otherwise, use the standard API under `Custom Data`.



# Retrieve custom data for entity
Source: https://docs.cortex.io/api/rest/custom-data-advanced/retrieve-custom-data-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/custom-data
Use this endpoint when attempting to delete custom data where the key contains non-alphanumeric characters. Otherwise, use the standard API under `Custom Data`.



# Add custom data for entity
Source: https://docs.cortex.io/api/rest/custom-data/add-custom-data-for-entity

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/custom-data



# Add custom data in bulk
Source: https://docs.cortex.io/api/rest/custom-data/add-custom-data-in-bulk

/openapi/cortex_swagger.json put /api/v1/catalog/custom-data
Add multiple key/values of custom data to multiple entities



# Add custom data via webhook
Source: https://docs.cortex.io/api/rest/custom-data/add-custom-data-via-webhook

/openapi/cortex_swagger.json post /api/v1/custom-integrations/data/{uuid}
Refer to the [Webhook section](/docs/reference/basics/custom-data#webhook) of the Custom Data docs for more information. This API is preconfigured in your workspace settings under Custom Integrations. The UUID corresponds to a custom data key, as well as a `jq` command that maps the data in this payload to an entity in your workspace.



# Custom Data (Advanced)
Source: https://docs.cortex.io/api/rest/custom-data/custom-data-advanced



> **[Retrieve custom data for entity](/api/rest/custom-data-advanced/retrieve-custom-data-for-entity)**
>
> `GET /api/v1/catalog/custom-data`

> **[Add custom data for entity (advanced)](/api/rest/custom-data-advanced/add-custom-data-for-entity-advanced)**
>
> `POST /api/v1/catalog/custom-data`

> **[Delete custom data by key for entity](/api/rest/custom-data-advanced/delete-custom-data-by-key-for-entity)**
>
> `DELETE /api/v1/catalog/custom-data`


# Delete custom data for entity
Source: https://docs.cortex.io/api/rest/custom-data/delete-custom-data-for-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/custom-data



# List custom data for entity
Source: https://docs.cortex.io/api/rest/custom-data/list-custom-data-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/custom-data



# Retrieve custom data for entity by key
Source: https://docs.cortex.io/api/rest/custom-data/retrieve-custom-data-for-entity-by-key

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/custom-data/{key}



# Custom Events
Source: https://docs.cortex.io/api/rest/custom-events



Use these operations to interact with custom events in Cortex.

### Required permissions

Edit entities: Your API key must have the `Edit entities` permission.

## Operations

> **[List custom events for entity](/api/rest/custom-events/list-custom-events-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/custom-events`

> **[Retrieve custom event by UUID](/api/rest/custom-events/retrieve-custom-event-by-uuid)**
>
> `GET /api/v1/catalog/{tagOrId}/custom-events/{uuid}`

> **[Create custom event for entity](/api/rest/custom-events/create-custom-event-for-entity)**
>
> `POST /api/v1/catalog/{tagOrId}/custom-events`

> **[Update custom event by UUID](/api/rest/custom-events/update-custom-event-by-uuid)**
>
> `PUT /api/v1/catalog/{tagOrId}/custom-events/{uuid}`

> **[Delete ALL custom events for an entity](/api/rest/custom-events/delete-all-custom-events-for-an-entity)**
>
> `DELETE /api/v1/catalog/{tagOrId}/custom-events`

> **[Delete custom events by UUID](/api/rest/custom-events/delete-custom-events-by-uuid)**
>
> `DELETE /api/v1/catalog/{tagOrId}/custom-events/{uuid}`


# Create custom event for entity
Source: https://docs.cortex.io/api/rest/custom-events/create-custom-event-for-entity

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/custom-events



# Delete ALL custom events for an entity
Source: https://docs.cortex.io/api/rest/custom-events/delete-all-custom-events-for-an-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/custom-events



# Delete custom events by UUID
Source: https://docs.cortex.io/api/rest/custom-events/delete-custom-events-by-uuid

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/custom-events/{uuid}



# List custom events for entity
Source: https://docs.cortex.io/api/rest/custom-events/list-custom-events-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/custom-events



# Retrieve custom event by UUID
Source: https://docs.cortex.io/api/rest/custom-events/retrieve-custom-event-by-uuid

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/custom-events/{uuid}



# Update custom event by UUID
Source: https://docs.cortex.io/api/rest/custom-events/update-custom-event-by-uuid

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/custom-events/{uuid}



# Custom Metrics
Source: https://docs.cortex.io/api/rest/custom-metrics



Use these operations to interact with [custom metrics](/improve/eng-intelligence/custom-metrics) in Cortex Eng Intelligence.

### Required permissions

The permission your API key needs depends on the operation:

* To list or retrieve custom metric definitions, your API key must have the `View Eng Intelligence` permission. Draft metrics also require the `Configure Eng Intelligence custom metrics` permission.
* To create, update, or delete custom metric definitions, your API key must have the `Configure Eng Intelligence custom metrics` permission.
* To retrieve, add, or delete data points, your API key must have the `Manage Eng Intelligence custom metrics data via API` permission.

## Operations

> **[List custom metric definitions](/api/rest/custom-metrics/list-custom-metric-definitions)**
>
> `GET /api/v1/eng-intel/custom-metrics`

> **[Retrieve a custom metric definition](/api/rest/custom-metrics/retrieve-a-custom-metric-definition)**
>
> `GET /api/v1/eng-intel/custom-metrics/{customMetricKey}`

> **[Create a custom metric definition](/api/rest/custom-metrics/create-a-custom-metric-definition)**
>
> `POST /api/v1/eng-intel/custom-metrics`

> **[Update a custom metric definition](/api/rest/custom-metrics/update-a-custom-metric-definition)**
>
> `PUT /api/v1/eng-intel/custom-metrics/{customMetricKey}`

> **[Delete a custom metric definition](/api/rest/custom-metrics/delete-a-custom-metric-definition)**
>
> `DELETE /api/v1/eng-intel/custom-metrics/{customMetricKey}`

> **[Retrieve custom metrics data points](/api/rest/custom-metrics/retrieve-custom-metrics-data-points)**
>
> `GET /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}`

> **[Add custom metrics data point](/api/rest/custom-metrics/add-custom-metrics-data-point)**
>
> `POST /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}`

> **[Add custom metrics data points in bulk](/api/rest/custom-metrics/add-custom-metrics-data-points-in-bulk)**
>
> `POST /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}/bulk`

> **[Delete custom metrics data points](/api/rest/custom-metrics/delete-custom-metrics-data-points)**
>
> `DELETE /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}`


# Add custom metrics data point
Source: https://docs.cortex.io/api/rest/custom-metrics/add-custom-metrics-data-point

/openapi/cortex_swagger.json post /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}
Adds a single custom metric data point for entity.



# Add custom metrics data points in bulk
Source: https://docs.cortex.io/api/rest/custom-metrics/add-custom-metrics-data-points-in-bulk

/openapi/cortex_swagger.json post /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}/bulk
Adds multiple custom metric data points for entity.



# Create a custom metric definition
Source: https://docs.cortex.io/api/rest/custom-metrics/create-a-custom-metric-definition

/openapi/cortex_swagger.json post /api/v1/eng-intel/custom-metrics
Defines a custom metric of type `PUBLIC_API`, which you then record data points against. The key cannot change after creation. API key must have the `Configure Eng Intelligence custom metrics` permission.



# Delete a custom metric definition
Source: https://docs.cortex.io/api/rest/custom-metrics/delete-a-custom-metric-definition

/openapi/cortex_swagger.json delete /api/v1/eng-intel/custom-metrics/{customMetricKey}
Removes the metric from Eng Intelligence. Its recorded data points stay out of reach, and creating the key again starts with no data. Only `PUBLIC_API` metrics can be deleted through the API. API key must have the `Configure Eng Intelligence custom metrics` permission.



# Delete custom metrics data points
Source: https://docs.cortex.io/api/rest/custom-metrics/delete-custom-metrics-data-points

/openapi/cortex_swagger.json delete /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}
Deletes custom metric data points for entity.



# List custom metric definitions
Source: https://docs.cortex.io/api/rest/custom-metrics/list-custom-metric-definitions

/openapi/cortex_swagger.json get /api/v1/eng-intel/custom-metrics
Returns every custom metric defined in the workspace, sorted by key. API key must have the `View Eng Intelligence` permission. Draft metrics are included only when the key also has the `Configure Eng Intelligence custom metrics` permission.



# Retrieve a custom metric definition
Source: https://docs.cortex.io/api/rest/custom-metrics/retrieve-a-custom-metric-definition

/openapi/cortex_swagger.json get /api/v1/eng-intel/custom-metrics/{customMetricKey}
API key must have the `View Eng Intelligence` permission. A draft metric returns 404 unless the key also has the `Configure Eng Intelligence custom metrics` permission.



# Retrieve custom metrics data points
Source: https://docs.cortex.io/api/rest/custom-metrics/retrieve-custom-metrics-data-points

/openapi/cortex_swagger.json get /api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}
Lists all custom metrics data points for an entity



# Update a custom metric definition
Source: https://docs.cortex.io/api/rest/custom-metrics/update-a-custom-metric-definition

/openapi/cortex_swagger.json put /api/v1/eng-intel/custom-metrics/{customMetricKey}
Replaces the definition in full, so an omitted optional field is cleared. Only `PUBLIC_API` metrics can be updated through the API. API key must have the `Configure Eng Intelligence custom metrics` permission.



# Add a single configuration
Source: https://docs.cortex.io/api/rest/datadog-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/datadog/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/datadog-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/datadog/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/datadog-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/datadog/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/datadog-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/datadog/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/datadog-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/datadog/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/datadog-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/datadog/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/datadog-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/datadog/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/datadog-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/datadog/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/datadog-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/datadog/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/datadog-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/datadog/configuration/validate



# Dependencies
Source: https://docs.cortex.io/api/rest/dependencies



Use these operations to interact with [dependencies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies) in Cortex.

### Required permissions

Your API key must have the `Edit entities` permission.

## Operations

> **[Retrieve all dependencies for an entity](/api/rest/dependencies/retrieve-all-dependencies-for-an-entity)**
>
> `GET /api/v1/catalog/{callerTag}/dependencies`

> **[Retrieve dependency between entities](/api/rest/dependencies/retrieve-dependency-between-entities)**
>
> `GET /api/v1/catalog/{callerTag}/dependencies/{calleeTag}`

> **[Create dependency from entity](/api/rest/dependencies/create-dependency-from-entity)**
>
> `POST /api/v1/catalog/{callerTag}/dependencies/{calleeTag}`

> **[Create or update dependencies in bulk](/api/rest/dependencies/create-or-update-dependencies-in-bulk)**
>
> `PUT /api/v1/catalog/dependencies`

> **[Update dependency between entities](/api/rest/dependencies/update-dependency-between-entities)**
>
> `PUT /api/v1/catalog/{callerTag}/dependencies/{calleeTag}`

> **[Delete dependency](/api/rest/dependencies/delete-dependency)**
>
> `DELETE /api/v1/catalog/{callerTag}/dependencies/{calleeTag}`

> **[Delete dependencies from entity](/api/rest/dependencies/delete-dependencies-from-entity)**
>
> `DELETE /api/v1/catalog/{callerTag}/dependencies`

> **[Delete dependencies in bulk](/api/rest/dependencies/delete-dependencies-in-bulk)**
>
> `DELETE /api/v1/catalog/dependencies`


# Create dependency from entity
Source: https://docs.cortex.io/api/rest/dependencies/create-dependency-from-entity

/openapi/cortex_swagger.json post /api/v1/catalog/{callerTag}/dependencies/{calleeTag}



# Create or update dependencies in bulk
Source: https://docs.cortex.io/api/rest/dependencies/create-or-update-dependencies-in-bulk

/openapi/cortex_swagger.json put /api/v1/catalog/dependencies
This API allows you to create multiple dependencies for multiple entities at once.



# Delete dependencies from entity
Source: https://docs.cortex.io/api/rest/dependencies/delete-dependencies-from-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/{callerTag}/dependencies
Deletes any outgoing dependencies from the entity. Note: this only deletes dependencies that were created via the API.



# Delete dependencies in bulk
Source: https://docs.cortex.io/api/rest/dependencies/delete-dependencies-in-bulk

/openapi/cortex_swagger.json delete /api/v1/catalog/dependencies



# Delete dependency
Source: https://docs.cortex.io/api/rest/dependencies/delete-dependency

/openapi/cortex_swagger.json delete /api/v1/catalog/{callerTag}/dependencies/{calleeTag}
Deletes a single dependency edge between the `caller` and the `callee`. 
Note: This is only supported for edges created via the API.



# Retrieve all dependencies for an entity
Source: https://docs.cortex.io/api/rest/dependencies/retrieve-all-dependencies-for-an-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{callerTag}/dependencies



# Retrieve dependency between entities
Source: https://docs.cortex.io/api/rest/dependencies/retrieve-dependency-between-entities

/openapi/cortex_swagger.json get /api/v1/catalog/{callerTag}/dependencies/{calleeTag}
If a dependency exists between the `callee` and the `caller`, returns metadata about the edge.



# Update dependency between entities
Source: https://docs.cortex.io/api/rest/dependencies/update-dependency-between-entities

/openapi/cortex_swagger.json put /api/v1/catalog/{callerTag}/dependencies/{calleeTag}
If a dependency exists between two entities, replace the metadata with the payload. 
Note: This only supports dependencies created via the API.



# Deploys
Source: https://docs.cortex.io/api/rest/deploys



Use these operations to interact with [deploys](/ingesting-data-into-cortex/entities-overview/entities/deploys) in Cortex.

### Required permissions

Edit entities: Your API key must have the `Edit entities` permission.

## Operations

> **[List deployments for entity](/api/rest/deploys/list-deployments-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/deploys`

> **[Add deployment for entity](/api/rest/deploys/add-deployment-for-entity)**
>
> `POST /api/v1/catalog/{tagOrId}/deploys`

> **[Update deployment by UUID](/api/rest/deploys/update-deployment-by-uuid)**
>
> `PUT /api/v1/catalog/{tagOrId}/deploys/{uuid}`

> **[Delete all deployments for all entities](/api/rest/deploys/delete-all-deployments-for-all-entities)**
>
> `DELETE /api/v1/catalog/deploys/all`

> **[Delete deployments for entity](/api/rest/deploys/delete-deployments-for-entity)**
>
> `DELETE /api/v1/catalog/{tagOrId}/deploys`

> **[Delete deployment by UUID](/api/rest/deploys/delete-deployment-by-uuid)**
>
> `DELETE /api/v1/catalog/{tagOrId}/deploys/{uuid}`

> **[Delete deploys by filter](/api/rest/deploys/delete-deploys-by-filter)**
>
> `DELETE /api/v1/catalog/deploys`

> **[List all distinct deploy environments for this tenant](/api/rest/deploys/list-all-distinct-deploy-environments-for-this-tenant)**
>
> `GET /api/v1/deploys/environments`

> **[Search deployments across the tenant](/api/rest/deploys/search-deployments-across-the-tenant)**
>
> `GET /api/v1/deploys/search`


# Add deployment for entity
Source: https://docs.cortex.io/api/rest/deploys/add-deployment-for-entity

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/deploys



# Delete all deployments for all entities
Source: https://docs.cortex.io/api/rest/deploys/delete-all-deployments-for-all-entities

/openapi/cortex_swagger.json delete /api/v1/catalog/deploys/all
Dangerous endpoint that blows away deploys for all entities



# Delete deployment by UUID
Source: https://docs.cortex.io/api/rest/deploys/delete-deployment-by-uuid

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/deploys/{uuid}



# Delete deployments for entity
Source: https://docs.cortex.io/api/rest/deploys/delete-deployments-for-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/deploys



# Delete deploys by filter
Source: https://docs.cortex.io/api/rest/deploys/delete-deploys-by-filter

/openapi/cortex_swagger.json delete /api/v1/catalog/deploys
Filter and delete deploys by SHA hash, environment, or type. Note that at least one of the filters need to be set.
If looking to delete all deployments for an entity, use the `Delete all deploys for entity` endpoint instead.



# List all distinct deploy environments for this tenant
Source: https://docs.cortex.io/api/rest/deploys/list-all-distinct-deploy-environments-for-this-tenant

/openapi/cortex_swagger.json get /api/v1/deploys/environments



# List deployments for entity
Source: https://docs.cortex.io/api/rest/deploys/list-deployments-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/deploys



# Search deployments across the tenant
Source: https://docs.cortex.io/api/rest/deploys/search-deployments-across-the-tenant

/openapi/cortex_swagger.json get /api/v1/deploys/search



# Update deployment by UUID
Source: https://docs.cortex.io/api/rest/deploys/update-deployment-by-uuid

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/deploys/{uuid}



# Discovery Audit
Source: https://docs.cortex.io/api/rest/discovery-audit



Use these operations to interact with the [discovered entities list](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit) in Cortex.

### Required permissions

Your API key must have the `Configure discovery audit events` permission.

## Operations

> **[Retrieve discovery audit report](/api/rest/discovery-audit/retrieve-discovery-audit-report)**
>
> `GET /api/v1/discovery-audit`


# Retrieve discovery audit report
Source: https://docs.cortex.io/api/rest/discovery-audit/retrieve-discovery-audit-report

/openapi/cortex_swagger.json get /api/v1/discovery-audit
This report shows you recent changes in your environment that aren't reflected in Cortex, including newly created repositories, services, and resources that we discover from your integrations or which were deleted in the environment but corresponding Cortex entities are still present.



# Docs
Source: https://docs.cortex.io/api/rest/docs



Use these operations to interact with [external docs on entities](/ingesting-data-into-cortex/entities-overview/entities/external-docs) in Cortex.

### Required permissions

Your API key must have the `Edit entities` permission.

## Operations

> **[Retrieve OpenAPI docs for entity](/api/rest/docs/retrieve-openapi-docs-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/documentation/openapi`

> **[Update OpenAPI docs for entity](/api/rest/docs/update-openapi-docs-for-entity)**
>
> `PUT /api/v1/catalog/{tagOrId}/documentation/openapi`

> **[Delete OpenAPI docs for entity](/api/rest/docs/delete-openapi-docs-for-entity)**
>
> `DELETE /api/v1/catalog/{tagOrId}/documentation/openapi`


# Delete OpenAPI docs for entity
Source: https://docs.cortex.io/api/rest/docs/delete-openapi-docs-for-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/documentation/openapi



# Retrieve OpenAPI docs for entity
Source: https://docs.cortex.io/api/rest/docs/retrieve-openapi-docs-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/documentation/openapi



# Update OpenAPI docs for entity
Source: https://docs.cortex.io/api/rest/docs/update-openapi-docs-for-entity

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/documentation/openapi



# Add a configuration
Source: https://docs.cortex.io/api/rest/dynatrace-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/dynatrace/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/dynatrace-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/dynatrace/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/dynatrace-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/dynatrace/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/dynatrace-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/dynatrace/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/dynatrace-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/dynatrace/configuration/validate



# Eng Intelligence: Metrics
Source: https://docs.cortex.io/api/rest/eng-intel-metrics



Use these operations to query aggregated metric data from [Eng Intelligence](/improve/eng-intelligence/eng-intelligence). You can group results and compare them across time periods.

### Required permissions

Your API key must have the `View Dev Metrics` permission, and your workspace must have Eng Intelligence enabled.

### Query workflow

1. Call **List available engineering metric definitions** first. It returns the metric keys, data sources, and the `groupBy`, filter, and aggregation options that each metric supports. Use the exact keys from that response when you build a query.
2. Call **Execute point-in-time engineering metrics queries** to get aggregated metric values. You can group the results and compare them against a prior period.
3. To see the individual event records behind those values (pull requests, deployments, and so on), use the [Eng Intelligence: Trace operation](/api/rest/eng-intel-trace).

Query results come back as `metadata` plus `rows`. Rows are positional, not keyed: the value at index `i` of each row corresponds to `metadata.columns[i]`. Queries are capped at a six-month date range, and trace queries at 500 rows per page.

## Operations

> **[List available engineering metric definitions](/api/rest/eng-intel-metrics/list-available-engineering-metric-definitions)**
>
> `GET /api/v1/eng-intel/registry/metrics/definitions`

> **[Execute point-in-time engineering metrics queries](/api/rest/eng-intel-metrics/execute-point-in-time-engineering-metrics-queries)**
>
> `POST /api/v1/eng-intel/metrics/point-in-time`


# Execute point-in-time engineering metrics queries
Source: https://docs.cortex.io/api/rest/eng-intel-metrics/execute-point-in-time-engineering-metrics-queries

/openapi/cortex_swagger.json post /api/v1/eng-intel/metrics/point-in-time
Query current metric values with optional period comparisons and flexible grouping. Supports batch queries for multiple metrics efficiently.



# List available engineering metric definitions
Source: https://docs.cortex.io/api/rest/eng-intel-metrics/list-available-engineering-metric-definitions

/openapi/cortex_swagger.json get /api/v1/eng-intel/registry/metrics/definitions
Discover all available engineering metrics and their metadata. Use this before querying metrics to understand what data is available and how to query it effectively.



# Eng Intelligence: Trace
Source: https://docs.cortex.io/api/rest/eng-intel-trace



Use this operation to query individual event records from the engineering data sources behind [Eng Intelligence](/improve/eng-intelligence/eng-intelligence). You can filter, sort, and paginate the results.

### Required permissions

Your API key must have the `View Dev Metrics` permission.

## Operations

> **[Query raw trace events from engineering data sources](/api/rest/eng-intel-trace/query-raw-trace-events-from-engineering-data-sources)**
>
> `POST /api/v1/eng-intel/trace`


# Query raw trace events from engineering data sources
Source: https://docs.cortex.io/api/rest/eng-intel-trace/query-raw-trace-events-from-engineering-data-sources

/openapi/cortex_swagger.json post /api/v1/eng-intel/trace
Retrieve individual event records with flexible filtering, ordering, and pagination. Supports any engineering data source registered in the registry.



# Eng Intelligence: User Labels
Source: https://docs.cortex.io/api/rest/eng-intel-user-labels



Use these operations to interact with [user labels](/improve/eng-intelligence/eng-intelligence#group-by-user-label) in Cortex Eng Intelligence.

### Required permissions

Your API key must have the `Configure user labels` permission.

## Operations

> **[List user labels](/api/rest/eng-intel-user-labels/list-user-labels)**
>
> `GET /api/v1/eng-intel/labels`

> **[Retrieve user label](/api/rest/eng-intel-user-labels/retrieve-user-label)**
>
> `GET /api/v1/eng-intel/labels/{id}`

> **[Update user label assignments](/api/rest/eng-intel-user-labels/update-user-label-assignments)**
>
> `POST /api/v1/eng-intel/labels/users`


# List user labels
Source: https://docs.cortex.io/api/rest/eng-intel-user-labels/list-user-labels

/openapi/cortex_swagger.json get /api/v1/eng-intel/labels
Retrieves a list of all available user labels.

API key must have the `View Eng Intelligence` permission.



# Retrieve user label
Source: https://docs.cortex.io/api/rest/eng-intel-user-labels/retrieve-user-label

/openapi/cortex_swagger.json get /api/v1/eng-intel/labels/{id}
Get user label.

API key must have the `View Eng Intelligence` permission.



# Update user label assignments
Source: https://docs.cortex.io/api/rest/eng-intel-user-labels/update-user-label-assignments

/openapi/cortex_swagger.json post /api/v1/eng-intel/labels/users
Assign user label values to user emails in bulk.

API key must have the `Edit user labels` permission.



# Get entity archival configuration
Source: https://docs.cortex.io/api/rest/entity-archival/get-entity-archival-configuration

/openapi/cortex_swagger.json get /api/v1/entity-archival-config
Retrieve the workspace's archival settings: auto-archival from integrations and from GitOps, auto-archival of monorepo entities, and how many days an archived entity is kept before it is deleted.



# Update entity archival configuration
Source: https://docs.cortex.io/api/rest/entity-archival/update-entity-archival-configuration

/openapi/cortex_swagger.json patch /api/v1/entity-archival-config
Change the workspace's archival settings. Only the fields in the request change. Setting retentionDays requires automatic deletion to be enabled for the workspace. Requires the Edit Settings permission.



# Entity Relationship Types
Source: https://docs.cortex.io/api/rest/entity-relationship-types



Use these operations to interact with [entity relationship types](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types) in Cortex.

### Required permissions

Create and Update Relationship Types: Your API key must have the `Edit entities` permission.\

Your tenant must also have the `Entity relationships` feature enabled.

### Operations

> **[List relationship types](/api/rest/entity-relationship-types/list-relationship-types)**
>
> `GET /api/v1/relationship-types`

> **[Create relationship type](/api/rest/entity-relationship-types/create-relationship-type)**
>
> `POST /api/v1/relationship-types`

> **[Get a relationship type](/api/rest/entity-relationship-types/get-a-relationship-type)**
>
> `GET /api/v1/relationship-types/{relationshipTypeTag}`

> **[Update relationship type](/api/rest/entity-relationship-types/update-relationship-type)**
>
> `PUT /api/v1/relationship-types/{relationshipTypeTag}`

> **[Delete a relationship type](/api/rest/entity-relationship-types/delete-a-relationship-type)**
>
> `DELETE /api/v1/relationship-types/{relationshipTypeTag}`


# Create relationship type
Source: https://docs.cortex.io/api/rest/entity-relationship-types/create-relationship-type

/openapi/cortex_swagger.json post /api/v1/relationship-types
Create a relationship type



# Delete a relationship type
Source: https://docs.cortex.io/api/rest/entity-relationship-types/delete-a-relationship-type

/openapi/cortex_swagger.json delete /api/v1/relationship-types/{relationshipTypeTag}
Delete a relationship type



# Get a relationship type
Source: https://docs.cortex.io/api/rest/entity-relationship-types/get-a-relationship-type

/openapi/cortex_swagger.json get /api/v1/relationship-types/{relationshipTypeTag}
List details for a relationship type



# List relationship types
Source: https://docs.cortex.io/api/rest/entity-relationship-types/list-relationship-types

/openapi/cortex_swagger.json get /api/v1/relationship-types
List paginated relationship types



# Update relationship type
Source: https://docs.cortex.io/api/rest/entity-relationship-types/update-relationship-type

/openapi/cortex_swagger.json put /api/v1/relationship-types/{relationshipTypeTag}
Update relationship type



# Entity Relationships
Source: https://docs.cortex.io/api/rest/entity-relationships



Use these operations to interact with [entity relationships](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types) in Cortex.

### Required permissions

Create and Update Relationships: Your API key must have the `Edit entities` permission.\

Your tenant must also have the `Entity relationships` feature enabled.

### Operations

> **[List entity destinations for a relationship type](/api/rest/entity-relationships/list-entity-destinations-for-a-relationship-type)**
>
> `GET /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/destinations`

> **[Update direct entity destinations for a given entity](/api/rest/entity-relationships/update-direct-entity-destinations-for-a-given-entity)**
>
> `PUT /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/destinations`

> **[Add direct entity destinations for a given entity](/api/rest/entity-relationships/add-direct-entity-destinations-for-a-given-entity)**
>
> `POST /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/destinations`

> **[List entity sources for a relationship type](/api/rest/entity-relationships/list-entity-sources-for-a-relationship-type)**
>
> `GET /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/sources`

> **[Update direct entity sources for a given entity](/api/rest/entity-relationships/update-direct-entity-sources-for-a-given-entity)**
>
> `PUT /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/sources`

> **[Add direct entity sources for a given entity](/api/rest/entity-relationships/add-direct-entity-sources-for-a-given-entity)**
>
> `POST /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/sources`

> **[List entity relationships for a relationship type](/api/rest/entity-relationships/list-entity-relationships-for-a-relationship-type)**
>
> `GET /api/v1/relationships/{relationshipTypeTag}`

> **[Update entity relationships for a relationship type](/api/rest/entity-relationships/update-entity-relationships-for-a-relationship-type)**
>
> `PUT /api/v1/relationships/{relationshipTypeTag}`

> **[Add entity relationships for a relationship type](/api/rest/entity-relationships/add-entity-relationships-for-a-relationship-type)**
>
> `POST /api/v1/relationships/{relationshipTypeTag}`


# Add direct entity destinations for a given entity
Source: https://docs.cortex.io/api/rest/entity-relationships/add-direct-entity-destinations-for-a-given-entity

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/destinations
Add direct destinations for a given entity and entity relationship type



# Add direct entity sources for a given entity
Source: https://docs.cortex.io/api/rest/entity-relationships/add-direct-entity-sources-for-a-given-entity

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/sources
Add direct sources for a given entity and entity relationship type



# Add entity relationships for a relationship type
Source: https://docs.cortex.io/api/rest/entity-relationships/add-entity-relationships-for-a-relationship-type

/openapi/cortex_swagger.json post /api/v1/relationships/{relationshipTypeTag}
Add all entity relationships for a certain relationship type.



# List entity destinations for a relationship type
Source: https://docs.cortex.io/api/rest/entity-relationships/list-entity-destinations-for-a-relationship-type

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/destinations
List all entity destinations for a certain relationship type. Optional depth parameter to limit the depth of the relationship tree.



# List entity relationships for a relationship type
Source: https://docs.cortex.io/api/rest/entity-relationships/list-entity-relationships-for-a-relationship-type

/openapi/cortex_swagger.json get /api/v1/relationships/{relationshipTypeTag}
List all entity relationships for a certain relationship type.



# List entity sources for a relationship type
Source: https://docs.cortex.io/api/rest/entity-relationships/list-entity-sources-for-a-relationship-type

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/sources
List all entity sources for a certain relationship type. Optional depth parameter to limit the depth of the relationship tree.



# Update direct entity destinations for a given entity
Source: https://docs.cortex.io/api/rest/entity-relationships/update-direct-entity-destinations-for-a-given-entity

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/destinations
Update all direct destinations for a given entity and entity relationship type



# Update direct entity sources for a given entity
Source: https://docs.cortex.io/api/rest/entity-relationships/update-direct-entity-sources-for-a-given-entity

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/relationships/{relationshipTypeTag}/sources
Update all direct sources for a given entity and entity relationship type



# Update entity relationships for a relationship type
Source: https://docs.cortex.io/api/rest/entity-relationships/update-entity-relationships-for-a-relationship-type

/openapi/cortex_swagger.json put /api/v1/relationships/{relationshipTypeTag}
Update all entity relationships for a certain relationship type.



# Entity Types
Source: https://docs.cortex.io/api/rest/entity-types



Use these operations to interact with [entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types) in Cortex.

### Required permissions

Your API key must have the `Edit entity types` permission.

## Operations

> **[List entity types](/api/rest/entity-types/list-entity-types)**
>
> `GET /api/v1/catalog/definitions`

> **[Retrieve entity type](/api/rest/entity-types/retrieve-entity-type)**
>
> `GET /api/v1/catalog/definitions/{type}`

> **[Create entity type](/api/rest/entity-types/create-entity-type)**
>
> `POST /api/v1/catalog/definitions`

> **[Update entity type](/api/rest/entity-types/update-entity-type)**
>
> `PUT /api/v1/catalog/definitions/{type}`

> **[Delete entity type](/api/rest/entity-types/delete-entity-type)**
>
> `DELETE /api/v1/catalog/definitions/{type}`


# Create entity type
Source: https://docs.cortex.io/api/rest/entity-types/create-entity-type

/openapi/cortex_swagger.json post /api/v1/catalog/definitions



# Delete entity type
Source: https://docs.cortex.io/api/rest/entity-types/delete-entity-type

/openapi/cortex_swagger.json delete /api/v1/catalog/definitions/{type}



# List entity types
Source: https://docs.cortex.io/api/rest/entity-types/list-entity-types

/openapi/cortex_swagger.json get /api/v1/catalog/definitions
List entity types

Response excludes Cortex default types of service, domain, and team.



# Retrieve entity type
Source: https://docs.cortex.io/api/rest/entity-types/retrieve-entity-type

/openapi/cortex_swagger.json get /api/v1/catalog/definitions/{type}



# Update entity type
Source: https://docs.cortex.io/api/rest/entity-types/update-entity-type

/openapi/cortex_swagger.json put /api/v1/catalog/definitions/{type}



# Add a configuration
Source: https://docs.cortex.io/api/rest/firehydrant-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/firehydrant/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/firehydrant-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/firehydrant/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/firehydrant-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/firehydrant/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/firehydrant-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/firehydrant/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/firehydrant-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/firehydrant/configuration/validate



# Add a single app configuration
Source: https://docs.cortex.io/api/rest/github-api/add-a-single-app-configuration

/openapi/cortex_swagger.json post /api/v1/github/configurations/app



# Add a single personal configuration
Source: https://docs.cortex.io/api/rest/github-api/add-a-single-personal-configuration

/openapi/cortex_swagger.json post /api/v1/github/configurations/personal



# Delete a personal configuration
Source: https://docs.cortex.io/api/rest/github-api/delete-a-personal-configuration

/openapi/cortex_swagger.json delete /api/v1/github/configurations/personal/{alias}



# Delete a single app configuration
Source: https://docs.cortex.io/api/rest/github-api/delete-a-single-app-configuration

/openapi/cortex_swagger.json delete /api/v1/github/configurations/app/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/github-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/github/configurations



# Retrieve a single app configuration
Source: https://docs.cortex.io/api/rest/github-api/retrieve-a-single-app-configuration

/openapi/cortex_swagger.json get /api/v1/github/configurations/app/{alias}



# Retrieve a single personal configuration
Source: https://docs.cortex.io/api/rest/github-api/retrieve-a-single-personal-configuration

/openapi/cortex_swagger.json get /api/v1/github/configurations/personal/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/github-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/github/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/github-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/github/default-configuration



# Update a single app configuration
Source: https://docs.cortex.io/api/rest/github-api/update-a-single-app-configuration

/openapi/cortex_swagger.json put /api/v1/github/configurations/app/{alias}



# Update a single personal configuration
Source: https://docs.cortex.io/api/rest/github-api/update-a-single-personal-configuration

/openapi/cortex_swagger.json put /api/v1/github/configurations/personal/{alias}



# Validate a configuration
Source: https://docs.cortex.io/api/rest/github-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/github/configurations/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/github-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/github/configurations/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/gitlab-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/gitlab/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/gitlab-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/gitlab/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/gitlab-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/gitlab/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/gitlab-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/gitlab/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/gitlab-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/gitlab/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/gitlab-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/gitlab/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/gitlab-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/gitlab/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/gitlab-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/gitlab/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/gitlab-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/gitlab/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/gitlab-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/gitlab/configuration/validate



# GitOps Logs
Source: https://docs.cortex.io/api/rest/gitops-logs



Use these operations to interact with [GitOps logs](/configure/gitops/gitops-logs) in Cortex.

### Required permissions

Your API key must have the `View GitOps logs` permission.

## Operations

> **[Retrieve GitOps logs](/api/rest/gitops-logs/retrieve-gitops-logs)**
>
> `GET /api/v1/gitops-logs`


# Retrieve GitOps logs
Source: https://docs.cortex.io/api/rest/gitops-logs/retrieve-gitops-logs

/openapi/cortex_swagger.json get /api/v1/gitops-logs
API key must have the `View GitOps logs` permission.



# Groups
Source: https://docs.cortex.io/api/rest/groups



Use these operations to interact with [groups](/ingesting-data-into-cortex/entities-overview/entities/groups) on entities in Cortex.

### Required permissions

Your API key must have the `Edit entities` permission.

## Operations

> **[Retrieve groups for entity](/api/rest/groups/retrieve-groups-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/groups`

> **[Add groups to entity](/api/rest/groups/add-groups-to-entity)**
>
> `PUT /api/v1/catalog/{tagOrId}/groups`

> **[Delete groups from entity](/api/rest/groups/delete-groups-from-entity)**
>
> `DELETE /api/v1/catalog/{tagOrId}/groups`


# Add groups to entity
Source: https://docs.cortex.io/api/rest/groups/add-groups-to-entity

/openapi/cortex_swagger.json put /api/v1/catalog/{tagOrId}/groups



# Delete groups from entity
Source: https://docs.cortex.io/api/rest/groups/delete-groups-from-entity

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/groups



# Retrieve groups for entity
Source: https://docs.cortex.io/api/rest/groups/retrieve-groups-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/groups



# Add a single configuration
Source: https://docs.cortex.io/api/rest/incidentio-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/incidentio/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/incidentio-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/incidentio/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/incidentio-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/incidentio/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/incidentio-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/incidentio/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/incidentio-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/incidentio/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/incidentio-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/incidentio/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/incidentio-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/incidentio/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/incidentio-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/incidentio/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/incidentio-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/incidentio/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/incidentio-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/incidentio/configuration/validate



# Initiatives
Source: https://docs.cortex.io/api/rest/initiatives



Use these operations to interact with [Initiatives](/improve/initiatives) in Cortex.

### Required permissions

* Create, read, update, or delete Initiatives: Your API key must have the `Edit Initiatives` permission.
* View Initiatives: Your API key must have the `View Initiatives` permission.

## Operations

> **[List Initiatives](/api/rest/initiatives/list-initiatives)**
>
> `GET /api/v1/initiatives`

> **[Get Initiative](/api/rest/initiatives/get-initiative)**
>
> `GET /api/v1/initiatives/{cid}`

> **[Create an Initiative](/api/rest/initiatives/create-an-initiative)**
>
> `POST /api/v1/initiatives`

> **[Update an Initiative](/api/rest/initiatives/update-an-initiative)**
>
> `PUT /api/v1/initiatives/{cid}`

> **[Delete Initiative](/api/rest/initiatives/delete-initiative)**
>
> `DELETE /api/v1/initiatives/{cid}`


# Create an Initiative
Source: https://docs.cortex.io/api/rest/initiatives/create-an-initiative

/openapi/cortex_swagger.json post /api/v1/initiatives
Create an Initiative.

API key must have the `Edit Initiative` permission.



# Delete Initiative
Source: https://docs.cortex.io/api/rest/initiatives/delete-initiative

/openapi/cortex_swagger.json delete /api/v1/initiatives/{cid}



# Get Initiative
Source: https://docs.cortex.io/api/rest/initiatives/get-initiative

/openapi/cortex_swagger.json get /api/v1/initiatives/{cid}
Get Initiative.

API key must have the `View Initiatives` permission.



# List Initiatives
Source: https://docs.cortex.io/api/rest/initiatives/list-initiatives

/openapi/cortex_swagger.json get /api/v1/initiatives
Retrieves a list of Initiatives.

API key must have the `View Initiatives` permission.



# Update an Initiative
Source: https://docs.cortex.io/api/rest/initiatives/update-an-initiative

/openapi/cortex_swagger.json put /api/v1/initiatives/{cid}
Update an Initiative.

API key must have the `Edit Initiative` permission.



# Add a configuration
Source: https://docs.cortex.io/api/rest/instana-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/instana/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/instana-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/instana/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/instana-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/instana/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/instana-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/instana/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/instana-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/instana/configuration/validate



# List installed integrations and their status
Source: https://docs.cortex.io/api/rest/integration-status/list-installed-integrations-and-their-status

/openapi/cortex_swagger.json get /api/v1/integrations/status

            Returns every installed integration configuration with the result of its most recent
            connection check. Serves stored results only and never contacts the third-party service.
            The timestamp is when the connection was last checked, not when data was last synced.
        



# Integrations APIs
Source: https://docs.cortex.io/api/rest/integrations





# Anthropic API
Source: https://docs.cortex.io/api/rest/integrations/anthropic



Use these operations to interact with the Anthropic integration in Cortex.

### Required permissions

Your API key must have the `Configure Integrations` permission.

## Operations

> **[Add a single configuration](/api/rest/anthropic-api/add-a-single-configuration)**
>
> `POST /api/v1/anthropic/configuration`

> **[Validate all configurations](/api/rest/anthropic-api/validate-all-configurations)**
>
> `POST /api/v1/anthropic/configuration/validate`

> **[Validate a configuration](/api/rest/anthropic-api/validate-a-configuration)**
>
> `POST /api/v1/anthropic/configuration/validate/{alias}`

> **[Retrieve a configuration](/api/rest/anthropic-api/retrieve-a-configuration)**
>
> `GET /api/v1/anthropic/configuration/{alias}`

> **[Update a configuration](/api/rest/anthropic-api/update-a-configuration)**
>
> `PUT /api/v1/anthropic/configuration/{alias}`

> **[Delete a configuration](/api/rest/anthropic-api/delete-a-configuration)**
>
> `DELETE /api/v1/anthropic/configuration/{alias}`

> **[Retrieve configurations](/api/rest/anthropic-api/retrieve-configurations)**
>
> `GET /api/v1/anthropic/configurations`

> **[Add multiple configurations](/api/rest/anthropic-api/add-multiple-configurations)**
>
> `POST /api/v1/anthropic/configurations`

> **[Delete all configurations](/api/rest/anthropic-api/delete-all-configurations)**
>
> `DELETE /api/v1/anthropic/configurations`

> **[Retrieve default configuration](/api/rest/anthropic-api/retrieve-default-configuration)**
>
> `GET /api/v1/anthropic/default-configuration`


# Apiiro API
Source: https://docs.cortex.io/api/rest/integrations/apiiro



Use these operations to interact with the [Apiiro integration](/ingesting-data-into-cortex/integrations/apiiro) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve default configuration](/api/rest/apiiro-api/retrieve-default-configuration)**
>
> `GET /api/v1/apiiro/default-configuration`

> **[Add a single configuration](/api/rest/apiiro-api/add-a-single-configuration)**
>
> `POST /api/v1/apiiro/configuration`

> **[Add multiple configurations](/api/rest/apiiro-api/add-multiple-configurations)**
>
> `POST /api/v1/apiiro/configurations`

> **[Retrieve configurations](/api/rest/apiiro-api/retrieve-configurations)**
>
> `GET /api/v1/apiiro/configurations`

> **[Retrieve a configuration](/api/rest/apiiro-api/retrieve-a-configuration)**
>
> `GET /api/v1/apiiro/configuration/{alias}`

> **[Update a configuration](/api/rest/apiiro-api/update-a-configuration)**
>
> `PUT /api/v1/apiiro/configuration/{alias}`

> **[Delete a configuration](/api/rest/apiiro-api/delete-a-configuration)**
>
> `DELETE /api/v1/apiiro/configuration/{alias}`

> **[Delete all configurations](/api/rest/apiiro-api/delete-all-configurations)**
>
> `DELETE /api/v1/apiiro/configurations`

> **[Validate all configurations](/api/rest/apiiro-api/validate-all-configurations)**
>
> `POST /api/v1/apiiro/configuration/validate`

> **[Validate a configuration](/api/rest/apiiro-api/validate-a-configuration)**
>
> `POST /api/v1/apiiro/configuration/validate/{alias}`


# ArgoCD API
Source: https://docs.cortex.io/api/rest/integrations/argocd



Use these operations to interact with the [ArgoCD integration](/ingesting-data-into-cortex/integrations/argocd) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve default configuration](/api/rest/argocd-api/retrieve-default-configuration)**
>
> `GET /api/v1/argocd/default-configuration`

> **[Add a single configuration](/api/rest/argocd-api/add-a-single-configuration)**
>
> `POST /api/v1/argocd/configuration`

> **[Add multiple configurations](/api/rest/argocd-api/add-multiple-configurations)**
>
> `POST /api/v1/argocd/configurations`

> **[Retrieve configurations](/api/rest/argocd-api/retrieve-configurations)**
>
> `GET /api/v1/argocd/configurations`

> **[Retrieve a configuration](/api/rest/argocd-api/retrieve-a-configuration)**
>
> `GET /api/v1/argocd/configuration/{alias}`

> **[Update a configuration](/api/rest/argocd-api/update-a-configuration)**
>
> `PUT /api/v1/argocd/configuration/{alias}`

> **[Delete a configuration](/api/rest/argocd-api/delete-a-configuration)**
>
> `DELETE /api/v1/argocd/configuration/{alias}`

> **[Delete all configurations](/api/rest/argocd-api/delete-all-configurations)**
>
> `DELETE /api/v1/argocd/configurations`

> **[Validate all configurations](/api/rest/argocd-api/validate-all-configurations)**
>
> `POST /api/v1/argocd/configuration/validate`

> **[Validate a configuration](/api/rest/argocd-api/validate-a-configuration)**
>
> `POST /api/v1/argocd/configuration/validate/{alias}`


# AWS API
Source: https://docs.cortex.io/api/rest/integrations/aws



Use these operations to interact with the [AWS integration](/ingesting-data-into-cortex/integrations/aws) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[List AWS types](/api/rest/aws-api/list-aws-types)**
>
> `GET /api/v1/aws/types`

> **[Retrieve a configuration](/api/rest/aws-api/retrieve-a-configuration)**
>
> `GET /api/v1/aws/configurations/{accountId}`

> **[Retrieve configurations](/api/rest/aws-api/retrieve-configurations)**
>
> `GET /api/v1/aws/configurations`

> **[Add a single configuration](/api/rest/aws-api/add-a-single-configuration)**
>
> `POST /api/v1/aws/configurations`

> **[Validate all configurations](/api/rest/aws-api/validate-all-configurations)**
>
> `POST /api/v1/aws/configurations/all/validate`

> **[Validate a configuration](/api/rest/aws-api/validate-a-configuration)**
>
> `POST /api/v1/aws/configurations/validate/{accountId}`

> **[Update configurations](/api/rest/aws-api/update-configurations)**
>
> `PUT /api/v1/aws/configurations`

> **[Update configured AWS types](/api/rest/aws-api/update-configured-aws-types)**
>
> `PUT /api/v1/aws/types`

> **[Delete all configurations](/api/rest/aws-api/delete-all-configurations)**
>
> `DELETE /api/v1/aws/configurations`

> **[Delete a configuration](/api/rest/aws-api/delete-a-configuration)**
>
> `DELETE /api/v1/aws/configurations/{accountId}`

> **[Get AWS resource details for an entity](/api/rest/aws-api/get-aws-resource-details-for-an-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/aws`


# Azure Active Directory (Entra ID) API
Source: https://docs.cortex.io/api/rest/integrations/azure-active-directory



Use these operations to interact with the [Azure Active Directory (Entra ID) integration](/ingesting-data-into-cortex/integrations/entraid) in Cortex.

## Operations

> **[Retrieve a configuration](/api/rest/azure-active-directory-entra-id-api/retrieve-a-configuration)**
>
> `GET /api/v1/active-directory/default-configuration`

> **[Add a configuration](/api/rest/azure-active-directory-entra-id-api/add-a-configuration)**
>
> `POST /api/v1/active-directory/configuration`

> **[Update the existing configuration](/api/rest/azure-active-directory-entra-id-api/update-the-existing-configuration)**
>
> `PUT /api/v1/active-directory/configuration`

> **[Validate a configuration](/api/rest/azure-active-directory-entra-id-api/validate-a-configuration)**
>
> `POST /api/v1/active-directory/configuration/validate`

> **[Delete a configuration](/api/rest/azure-active-directory-entra-id-api/delete-a-configuration)**
>
> `DELETE /api/v1/active-directory/configurations`


# Azure DevOps API
Source: https://docs.cortex.io/api/rest/integrations/azure-devops



Use these operations to interact with the [Azure DevOps integration](/ingesting-data-into-cortex/integrations/azuredevops) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/azure-devops-api/retrieve-configurations)**
>
> `GET /api/v1/azure-devops/configurations`

> **[Retrieve default configuration](/api/rest/azure-devops-api/retrieve-default-configuration)**
>
> `GET /api/v1/azure-devops/default-configuration`

> **[Retrieve a configuration](/api/rest/azure-devops-api/retrieve-a-configuration)**
>
> `GET /api/v1/azure-devops/configuration/{alias}`

> **[Add a single configuration](/api/rest/azure-devops-api/add-a-single-configuration)**
>
> `POST /api/v1/azure-devops/configuration`

> **[Validate all configurations](/api/rest/azure-devops-api/validate-all-configurations)**
>
> `POST /api/v1/azure-devops/configuration/validate`

> **[Add multiple configurations](/api/rest/azure-devops-api/add-multiple-configurations)**
>
> `POST /api/v1/azure-devops/configurations`

> **[Validate a configuration](/api/rest/azure-devops-api/validate-a-configuration)**
>
> `POST /api/v1/azure-devops/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/azure-devops-api/update-a-configuration)**
>
> `PUT /api/v1/azure-devops/configuration/{alias}`

> **[Delete a configuration](/api/rest/azure-devops-api/delete-a-configuration)**
>
> `DELETE /api/v1/azure-devops/configuration/{alias}`

> **[Delete all configurations](/api/rest/azure-devops-api/delete-all-configurations)**
>
> `DELETE /api/v1/azure-devops/configurations`


# Azure Resources API
Source: https://docs.cortex.io/api/rest/integrations/azure-resources



Use these operations to interact with the [Azure Resources integration](/ingesting-data-into-cortex/integrations/azureresources) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[List Azure Resources types](/api/rest/azure-resources-api/list-azure-resources-types)**
>
> `GET /api/v1/azure-resources/types`

> **[Retrieve configurations](/api/rest/azure-resources-api/retrieve-configurations)**
>
> `GET /api/v1/azure-resources/configurations`

> **[Retrieve default configuration](/api/rest/azure-resources-api/retrieve-default-configuration)**
>
> `GET /api/v1/azure-resources/default-configuration`

> **[Retrieve a configuration](/api/rest/azure-resources-api/retrieve-a-configuration)**
>
> `GET /api/v1/azure-resources/configuration/{alias}`

> **[Add a single configuration](/api/rest/azure-resources-api/add-a-single-configuration)**
>
> `POST /api/v1/azure-resources/configuration`

> **[Validate all configurations](/api/rest/azure-resources-api/validate-all-configurations)**
>
> `POST /api/v1/azure-resources/configuration/validate`

> **[Validate a configuration](/api/rest/azure-resources-api/validate-a-configuration)**
>
> `POST /api/v1/azure-resources/configuration/validate/{alias}`

> **[Add multiple configurations](/api/rest/azure-resources-api/add-multiple-configurations)**
>
> `POST /api/v1/azure-resources/configurations`

> **[Update configured Azure Resources types](/api/rest/azure-resources-api/update-configured-azure-resources-types)**
>
> `PUT /api/v1/azure-resources/types`

> **[Update a configuration](/api/rest/azure-resources-api/update-a-configuration)**
>
> `PUT /api/v1/azure-resources/configuration/{alias}`

> **[Delete all configurations](/api/rest/azure-resources-api/delete-all-configurations)**
>
> `DELETE /api/v1/azure-resources/configurations`

> **[Delete a configuration](/api/rest/azure-resources-api/delete-a-configuration)**
>
> `DELETE /api/v1/azure-resources/configuration/{alias}`


# BambooHR API
Source: https://docs.cortex.io/api/rest/integrations/bamboohr



Use these operations to interact with the [BambooHR integration](/ingesting-data-into-cortex/integrations/bamboohr) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/bamboohr-api/retrieve-a-configuration)**
>
> `GET /api/v1/bamboohr/default-configuration`

> **[Add a configuration](/api/rest/bamboohr-api/add-a-configuration)**
>
> `POST /api/v1/bamboohr/configuration`

> **[Update the existing configuration](/api/rest/bamboohr-api/update-the-existing-configuration)**
>
> `PUT /api/v1/bamboohr/configuration`

> **[Validate a configuration](/api/rest/bamboohr-api/validate-a-configuration)**
>
> `POST /api/v1/bamboohr/configuration/validate`

> **[Delete a configuration](/api/rest/bamboohr-api/delete-a-configuration)**
>
> `DELETE /api/v1/bamboohr/configurations`


# Bitbucket API
Source: https://docs.cortex.io/api/rest/integrations/bitbucket



Use these operations to interact with the [Bitbucket integration](/ingesting-data-into-cortex/integrations/bitbucket) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/bitbucket-api/retrieve-configurations)**
>
> `GET /api/v1/bitbucket/configurations`

> **[Retrieve default configuration](/api/rest/bitbucket-api/retrieve-default-configuration)**
>
> `GET /api/v1/bitbucket/default-configuration`

> **[Retrieve a configuration](/api/rest/bitbucket-api/retrieve-a-configuration)**
>
> `GET /api/v1/bitbucket/configuration/{alias}`

> **[Add multiple configurations](/api/rest/bitbucket-api/add-multiple-configurations)**
>
> `POST /api/v1/bitbucket/configurations`

> **[Add a single configuration](/api/rest/bitbucket-api/add-a-single-configuration)**
>
> `POST /api/v1/bitbucket/configuration`

> **[Validate all configurations](/api/rest/bitbucket-api/validate-all-configurations)**
>
> `POST /api/v1/bitbucket/configuration/validate`

> **[Validate a configuration](/api/rest/bitbucket-api/validate-a-configuration)**
>
> `POST /api/v1/bitbucket/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/bitbucket-api/update-a-configuration)**
>
> `PUT /api/v1/bitbucket/configuration/{alias}`

> **[Delete a configuration](/api/rest/bitbucket-api/delete-a-configuration)**
>
> `DELETE /api/v1/bitbucket/configuration/{alias}`

> **[Delete all configurations](/api/rest/bitbucket-api/delete-all-configurations)**
>
> `DELETE /api/v1/bitbucket/configurations`


# Bugsnag API
Source: https://docs.cortex.io/api/rest/integrations/bugsnag



Use these operations to interact with the [Bugsnag integration](/ingesting-data-into-cortex/integrations/bugsnag) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/bugsnag-api/retrieve-a-configuration)**
>
> `GET /api/v1/bugsnag/default-configuration`

> **[Add a configuration](/api/rest/bugsnag-api/add-a-configuration)**
>
> `POST /api/v1/bugsnag/configuration`

> **[Update the existing configuration](/api/rest/bugsnag-api/update-the-existing-configuration)**
>
> `PUT /api/v1/bugsnag/configuration`

> **[Validate a configuration](/api/rest/bugsnag-api/validate-a-configuration)**
>
> `POST /api/v1/bugsnag/configuration/validate`

> **[Delete a configuration](/api/rest/bugsnag-api/delete-a-configuration)**
>
> `DELETE /api/v1/bugsnag/configurations`


# Buildkite API
Source: https://docs.cortex.io/api/rest/integrations/buildkite



Use these operations to interact with the [Buildkite integration](/ingesting-data-into-cortex/integrations/buildkite) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/buildkite-api/retrieve-a-configuration)**
>
> `GET /api/v1/buildkite/default-configuration`

> **[Add a configuration](/api/rest/buildkite-api/add-a-configuration)**
>
> `POST /api/v1/buildkite/configuration`

> **[Update the existing configuration](/api/rest/buildkite-api/update-the-existing-configuration)**
>
> `PUT /api/v1/buildkite/configuration`

> **[Validate a configuration](/api/rest/buildkite-api/validate-a-configuration)**
>
> `POST /api/v1/buildkite/configuration/validate`

> **[Delete a configuration](/api/rest/buildkite-api/delete-a-configuration)**
>
> `DELETE /api/v1/buildkite/configurations`


# Checkmarx SAST API
Source: https://docs.cortex.io/api/rest/integrations/checkmarx-sast



Use these operations to interact with the [Checkmarx SAST integration](/api/rest/integrations/checkmarx-sast) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/checkmarx-sast-api/retrieve-a-configuration)**
>
> `GET /api/v1/checkmarx/sast/default-configuration`

> **[Add a configuration](/api/rest/checkmarx-sast-api/add-a-configuration)**
>
> `POST /api/v1/checkmarx/sast/configuration`

> **[Update the existing configuration](/api/rest/checkmarx-sast-api/update-the-existing-configuration)**
>
> `PUT /api/v1/checkmarx/sast/configuration`

> **[Validate a configuration](/api/rest/checkmarx-sast-api/validate-a-configuration)**
>
> `POST /api/v1/checkmarx/sast/configuration/validate`

> **[Delete a configuration](/api/rest/checkmarx-sast-api/delete-a-configuration)**
>
> `DELETE /api/v1/checkmarx/sast/configurations`


# CircleCI API
Source: https://docs.cortex.io/api/rest/integrations/circleci



Use these operations to interact with the [CircleCI integration](/ingesting-data-into-cortex/integrations/circleci) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/circleci-api/retrieve-configurations)**
>
> `GET /api/v1/circleci/configurations`

> **[Retrieve default configuration](/api/rest/circleci-api/retrieve-default-configuration)**
>
> `GET /api/v1/circleci/default-configuration`

> **[Retrieve a configuration](/api/rest/circleci-api/retrieve-a-configuration)**
>
> `GET /api/v1/circleci/configuration/{alias}`

> **[Add a single configuration](/api/rest/circleci-api/add-a-single-configuration)**
>
> `POST /api/v1/circleci/configuration`

> **[Validate all configurations](/api/rest/circleci-api/validate-all-configurations)**
>
> `POST /api/v1/circleci/configuration/validate`

> **[Add multiple configurations](/api/rest/circleci-api/add-multiple-configurations)**
>
> `POST /api/v1/circleci/configurations`

> **[Validate a configuration](/api/rest/circleci-api/validate-a-configuration)**
>
> `POST /api/v1/circleci/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/circleci-api/update-a-configuration)**
>
> `PUT /api/v1/circleci/configuration/{alias}`

> **[Delete all configurations](/api/rest/circleci-api/delete-all-configurations)**
>
> `DELETE /api/v1/circleci/configurations`

> **[Delete a configuration](/api/rest/circleci-api/delete-a-configuration)**
>
> `DELETE /api/v1/circleci/configuration/{alias}`


# ClickUp API
Source: https://docs.cortex.io/api/rest/integrations/clickup



Use these operations to interact with the [ClickUp integration](/ingesting-data-into-cortex/integrations/clickup) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/clickup-api/retrieve-a-configuration)**
>
> `GET /api/v1/clickup/default-configuration`

> **[Add a configuration](/api/rest/clickup-api/add-a-configuration)**
>
> `POST /api/v1/clickup/configuration`

> **[Update the existing configuration](/api/rest/clickup-api/update-the-existing-configuration)**
>
> `PUT /api/v1/clickup/configuration`

> **[Validate a configuration](/api/rest/clickup-api/validate-a-configuration)**
>
> `POST /api/v1/clickup/configuration/validate`

> **[Delete a configuration](/api/rest/clickup-api/delete-a-configuration)**
>
> `DELETE /api/v1/clickup/configurations`


# Codecov API
Source: https://docs.cortex.io/api/rest/integrations/codecov



Use these operations to interact with the [Codecov integration](/ingesting-data-into-cortex/integrations/codecov) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/codecov-api/retrieve-a-configuration)**
>
> `GET /api/v1/codecov/default-configuration`

> **[Add a configuration](/api/rest/codecov-api/add-a-configuration)**
>
> `POST /api/v1/codecov/configuration`

> **[Update the existing configuration](/api/rest/codecov-api/update-the-existing-configuration)**
>
> `PUT /api/v1/codecov/configuration`

> **[Validate a configuration](/api/rest/codecov-api/validate-a-configuration)**
>
> `POST /api/v1/codecov/configuration/validate`

> **[Delete a configuration](/api/rest/codecov-api/delete-a-configuration)**
>
> `DELETE /api/v1/codecov/configurations`


# Coralogix API
Source: https://docs.cortex.io/api/rest/integrations/coralogix



Use these operations to interact with the [Coralogix integration](/ingesting-data-into-cortex/integrations/coralogix) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/coralogix-api/retrieve-configurations)**
>
> `GET /api/v1/coralogix/configurations`

> **[Retrieve default configuration](/api/rest/coralogix-api/retrieve-default-configuration)**
>
> `GET /api/v1/coralogix/default-configuration`

> **[Retrieve a configuration](/api/rest/coralogix-api/retrieve-a-configuration)**
>
> `GET /api/v1/coralogix/configuration/{alias}`

> **[Validate all configurations](/api/rest/coralogix-api/validate-all-configurations)**
>
> `POST /api/v1/coralogix/configuration/validate`

> **[Add multiple configurations](/api/rest/coralogix-api/add-multiple-configurations)**
>
> `POST /api/v1/coralogix/configurations`

> **[Add a single configuration](/api/rest/coralogix-api/add-a-single-configuration)**
>
> `POST /api/v1/coralogix/configuration`

> **[Validate a configuration](/api/rest/coralogix-api/validate-a-configuration)**
>
> `POST /api/v1/coralogix/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/coralogix-api/update-a-configuration)**
>
> `PUT /api/v1/coralogix/configuration/{alias}`

> **[Delete all configurations](/api/rest/coralogix-api/delete-all-configurations)**
>
> `DELETE /api/v1/coralogix/configurations`

> **[Delete a configuration](/api/rest/coralogix-api/delete-a-configuration)**
>
> `DELETE /api/v1/coralogix/configuration/{alias}`


# Datadog API
Source: https://docs.cortex.io/api/rest/integrations/datadog



Use these operations to interact with the [Datadog integration](/ingesting-data-into-cortex/integrations/datadog) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/datadog-api/retrieve-configurations)**
>
> `GET /api/v1/datadog/configurations`

> **[Retrieve default configuration](/api/rest/datadog-api/retrieve-default-configuration)**
>
> `GET /api/v1/datadog/default-configuration`

> **[Retrieve a configuration](/api/rest/datadog-api/retrieve-a-configuration)**
>
> `GET /api/v1/datadog/configuration/{alias}`

> **[Add multiple configurations](/api/rest/datadog-api/add-multiple-configurations)**
>
> `POST /api/v1/datadog/configurations`

> **[Add a single configuration](/api/rest/datadog-api/add-a-single-configuration)**
>
> `POST /api/v1/datadog/configuration`

> **[Validate all configurations](/api/rest/datadog-api/validate-all-configurations)**
>
> `POST /api/v1/datadog/configuration/validate`

> **[Validate a configuration](/api/rest/datadog-api/validate-a-configuration)**
>
> `POST /api/v1/datadog/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/datadog-api/update-a-configuration)**
>
> `PUT /api/v1/datadog/configuration/{alias}`

> **[Delete a configuration](/api/rest/datadog-api/delete-a-configuration)**
>
> `DELETE /api/v1/datadog/configuration/{alias}`

> **[Delete all configurations](/api/rest/datadog-api/delete-all-configurations)**
>
> `DELETE /api/v1/datadog/configurations`


# Dynatrace API
Source: https://docs.cortex.io/api/rest/integrations/dynatrace



Use these operations to interact with the [Dynatrace integration](/ingesting-data-into-cortex/integrations/dynatrace) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/dynatrace-api/retrieve-a-configuration)**
>
> `GET /api/v1/dynatrace/default-configuration`

> **[Add a configuration](/api/rest/dynatrace-api/add-a-configuration)**
>
> `POST /api/v1/dynatrace/configuration`

> **[Update the existing configuration](/api/rest/dynatrace-api/update-the-existing-configuration)**
>
> `PUT /api/v1/dynatrace/configuration`

> **[Validate a configuration](/api/rest/dynatrace-api/validate-a-configuration)**
>
> `POST /api/v1/dynatrace/configuration/validate`

> **[Delete a configuration](/api/rest/dynatrace-api/delete-a-configuration)**
>
> `DELETE /api/v1/dynatrace/configurations`


# Firehydrant API
Source: https://docs.cortex.io/api/rest/integrations/firehydrant



Use these operations to interact with the [Firehydrant integration](/ingesting-data-into-cortex/integrations/firehydrant) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/firehydrant-api/retrieve-a-configuration)**
>
> `GET /api/v1/firehydrant/default-configuration`

> **[Add a configuration](/api/rest/firehydrant-api/add-a-configuration)**
>
> `POST /api/v1/firehydrant/configuration`

> **[Update the existing configuration](/api/rest/firehydrant-api/update-the-existing-configuration)**
>
> `PUT /api/v1/firehydrant/configuration`

> **[Validate a configuration](/api/rest/firehydrant-api/validate-a-configuration)**
>
> `POST /api/v1/firehydrant/configuration/validate`

> **[Delete a configuration](/api/rest/firehydrant-api/delete-a-configuration)**
>
> `DELETE /api/v1/firehydrant/configurations`


# GitHub API
Source: https://docs.cortex.io/api/rest/integrations/github



Use these operations to interact with the [GitHub integration](/ingesting-data-into-cortex/integrations/github) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/github-api/retrieve-configurations)**
>
> `GET /api/v1/github/configurations`

> **[Retrieve default configuration](/api/rest/github-api/retrieve-default-configuration)**
>
> `GET /api/v1/github/default-configuration`

> **[Retrieve a single personal configuration](/api/rest/github-api/retrieve-a-single-personal-configuration)**
>
> `GET /api/v1/github/configurations/personal/{alias}`

> **[Retrieve a single app configuration](/api/rest/github-api/retrieve-a-single-app-configuration)**
>
> `GET /api/v1/github/configurations/app/{alias}`

> **[Validate all configurations](/api/rest/github-api/validate-all-configurations)**
>
> `POST /api/v1/github/configurations/validate`

> **[Add a single app configuration](/api/rest/github-api/add-a-single-app-configuration)**
>
> `POST /api/v1/github/configurations/app`

> **[Validate a configuration](/api/rest/github-api/validate-a-configuration)**
>
> `POST /api/v1/github/configurations/validate/{alias}`

> **[Add a single personal configuration](/api/rest/github-api/add-a-single-personal-configuration)**
>
> `POST /api/v1/github/configurations/personal`

> **[Update a single app configuration](/api/rest/github-api/update-a-single-app-configuration)**
>
> `PUT /api/v1/github/configurations/app/{alias}`

> **[Delete a personal configuration](/api/rest/github-api/delete-a-personal-configuration)**
>
> `DELETE /api/v1/github/configurations/personal/{alias}`

> **[Update a single personal configuration](/api/rest/github-api/update-a-single-personal-configuration)**
>
> `PUT /api/v1/github/configurations/personal/{alias}`

> **[Delete all configurations](/api/rest/github-api/delete-all-configurations)**
>
> `DELETE /api/v1/github/configurations`

> **[Delete a single app configuration](/api/rest/github-api/delete-a-single-app-configuration)**
>
> `DELETE /api/v1/github/configurations/app/{alias}`


# GitLab API
Source: https://docs.cortex.io/api/rest/integrations/gitlab



Use these operations to interact with the [GitLab integration](/ingesting-data-into-cortex/integrations/gitlab) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/gitlab-api/retrieve-configurations)**
>
> `GET /api/v1/gitlab/configurations`

> **[Retrieve default configuration](/api/rest/gitlab-api/retrieve-default-configuration)**
>
> `GET /api/v1/gitlab/default-configuration`

> **[Retrieve a configuration](/api/rest/gitlab-api/retrieve-a-configuration)**
>
> `GET /api/v1/gitlab/configuration/{alias}`

> **[Add a single configuration](/api/rest/gitlab-api/add-a-single-configuration)**
>
> `POST /api/v1/gitlab/configuration`

> **[Validate all configurations](/api/rest/gitlab-api/validate-all-configurations)**
>
> `POST /api/v1/gitlab/configuration/validate`

> **[Validate a configuration](/api/rest/gitlab-api/validate-a-configuration)**
>
> `POST /api/v1/gitlab/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/gitlab-api/update-a-configuration)**
>
> `PUT /api/v1/gitlab/configuration/{alias}`

> **[Add multiple configurations](/api/rest/gitlab-api/add-multiple-configurations)**
>
> `POST /api/v1/gitlab/configurations`

> **[Delete all configurations](/api/rest/gitlab-api/delete-all-configurations)**
>
> `DELETE /api/v1/gitlab/configurations`

> **[Delete a configuration](/api/rest/gitlab-api/delete-a-configuration)**
>
> `DELETE /api/v1/gitlab/configuration/{alias}`


# incident.io API
Source: https://docs.cortex.io/api/rest/integrations/incidentio



Use these operations to interact with the [incident.io integration](/ingesting-data-into-cortex/integrations/incidentio) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/incidentio-api/retrieve-configurations)**
>
> `GET /api/v1/incidentio/configurations`

> **[Retrieve default configuration](/api/rest/incidentio-api/retrieve-default-configuration)**
>
> `GET /api/v1/incidentio/default-configuration`

> **[Retrieve a configuration](/api/rest/incidentio-api/retrieve-a-configuration)**
>
> `GET /api/v1/incidentio/configuration/{alias}`

> **[Add multiple configurations](/api/rest/incidentio-api/add-multiple-configurations)**
>
> `POST /api/v1/incidentio/configurations`

> **[Add a single configuration](/api/rest/incidentio-api/add-a-single-configuration)**
>
> `POST /api/v1/incidentio/configuration`

> **[Validate all configurations](/api/rest/incidentio-api/validate-all-configurations)**
>
> `POST /api/v1/incidentio/configuration/validate`

> **[Validate a configuration](/api/rest/incidentio-api/validate-a-configuration)**
>
> `POST /api/v1/incidentio/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/incidentio-api/update-a-configuration)**
>
> `PUT /api/v1/incidentio/configuration/{alias}`

> **[Delete all configurations](/api/rest/incidentio-api/delete-all-configurations)**
>
> `DELETE /api/v1/incidentio/configurations`

> **[Delete a configuration](/api/rest/incidentio-api/delete-a-configuration)**
>
> `DELETE /api/v1/incidentio/configuration/{alias}`


# Instana API
Source: https://docs.cortex.io/api/rest/integrations/instana



Use these operations to interact with the [Instana integration](/ingesting-data-into-cortex/integrations/instana) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/instana-api/retrieve-a-configuration)**
>
> `GET /api/v1/instana/default-configuration`

> **[Add a configuration](/api/rest/instana-api/add-a-configuration)**
>
> `POST /api/v1/instana/configuration`

> **[Update the existing configuration](/api/rest/instana-api/update-the-existing-configuration)**
>
> `PUT /api/v1/instana/configuration`

> **[Validate a configuration](/api/rest/instana-api/validate-a-configuration)**
>
> `POST /api/v1/instana/configuration/validate`

> **[Delete a configuration](/api/rest/instana-api/delete-a-configuration)**
>
> `DELETE /api/v1/instana/configurations`


# Jenkins API
Source: https://docs.cortex.io/api/rest/integrations/jenkins



Use these operations to interact with the [Jenkins integration](/ingesting-data-into-cortex/integrations/jenkins) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve default configuration](/api/rest/jenkins-api/retrieve-default-configuration)**
>
> `GET /api/v1/jenkins/default-configuration`

> **[Add a single configuration](/api/rest/jenkins-api/add-a-single-configuration)**
>
> `POST /api/v1/jenkins/configuration`

> **[Add multiple configurations](/api/rest/jenkins-api/add-multiple-configurations)**
>
> `POST /api/v1/jenkins/configurations`

> **[Retrieve configurations](/api/rest/jenkins-api/retrieve-configurations)**
>
> `GET /api/v1/jenkins/configurations`

> **[Retrieve a configuration](/api/rest/jenkins-api/retrieve-a-configuration)**
>
> `GET /api/v1/jenkins/configuration/{alias}`

> **[Update a configuration](/api/rest/jenkins-api/update-a-configuration)**
>
> `PUT /api/v1/jenkins/configuration/{alias}`

> **[Delete a configuration](/api/rest/jenkins-api/delete-a-configuration)**
>
> `DELETE /api/v1/jenkins/configuration/{alias}`

> **[Delete all configurations](/api/rest/jenkins-api/delete-all-configurations)**
>
> `DELETE /api/v1/jenkins/configurations`

> **[Validate all configurations](/api/rest/jenkins-api/validate-all-configurations)**
>
> `POST /api/v1/jenkins/configuration/validate`

> **[Validate a configuration](/api/rest/jenkins-api/validate-a-configuration)**
>
> `POST /api/v1/jenkins/configuration/validate/{alias}`


# Jira API
Source: https://docs.cortex.io/api/rest/integrations/jira



Use these operations to interact with the [Jira integration](/ingesting-data-into-cortex/integrations/jira) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/jira-api/retrieve-configurations)**
>
> `GET /api/v1/jira/configurations`

> **[Retrieve default configuration](/api/rest/jira-api/retrieve-default-configuration)**
>
> `GET /api/v1/jira/default-configuration`

> **[Retrieve a configuration](/api/rest/jira-api/retrieve-a-configuration)**
>
> `GET /api/v1/jira/configuration/{alias}`

> **[Add multiple configurations](/api/rest/jira-api/add-multiple-configurations)**
>
> `POST /api/v1/jira/configurations`

> **[Add a single configuration](/api/rest/jira-api/add-a-single-configuration)**
>
> `POST /api/v1/jira/configuration`

> **[Validate all configurations](/api/rest/jira-api/validate-all-configurations)**
>
> `POST /api/v1/jira/configuration/validate`

> **[Validate a configuration](/api/rest/jira-api/validate-a-configuration)**
>
> `POST /api/v1/jira/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/jira-api/update-a-configuration)**
>
> `PUT /api/v1/jira/configuration/{alias}`

> **[Delete a configuration](/api/rest/jira-api/delete-a-configuration)**
>
> `DELETE /api/v1/jira/configuration/{alias}`

> **[Delete all configurations](/api/rest/jira-api/delete-all-configurations)**
>
> `DELETE /api/v1/jira/configurations`


# LaunchDarkly API
Source: https://docs.cortex.io/api/rest/integrations/launchdarkly



Use these operations to interact with the [LaunchDarkly integration](/ingesting-data-into-cortex/integrations/launchdarkly) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/launchdarkly-api/retrieve-configurations)**
>
> `GET /api/v1/launchdarkly/configurations`

> **[Retrieve default configuration](/api/rest/launchdarkly-api/retrieve-default-configuration)**
>
> `GET /api/v1/launchdarkly/default-configuration`

> **[Retrieve a configuration](/api/rest/launchdarkly-api/retrieve-a-configuration)**
>
> `GET /api/v1/launchdarkly/configuration/{alias}`

> **[Add multiple configurations](/api/rest/launchdarkly-api/add-multiple-configurations)**
>
> `POST /api/v1/launchdarkly/configurations`

> **[Add a single configuration](/api/rest/launchdarkly-api/add-a-single-configuration)**
>
> `POST /api/v1/launchdarkly/configuration`

> **[Validate all configurations](/api/rest/launchdarkly-api/validate-all-configurations)**
>
> `POST /api/v1/launchdarkly/configuration/validate`

> **[Validate a configuration](/api/rest/launchdarkly-api/validate-a-configuration)**
>
> `POST /api/v1/launchdarkly/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/launchdarkly-api/update-a-configuration)**
>
> `PUT /api/v1/launchdarkly/configuration/{alias}`

> **[Delete a configuration](/api/rest/launchdarkly-api/delete-a-configuration)**
>
> `DELETE /api/v1/launchdarkly/configuration/{alias}`

> **[Delete all configurations](/api/rest/launchdarkly-api/delete-all-configurations)**
>
> `DELETE /api/v1/launchdarkly/configurations`


# Mend API
Source: https://docs.cortex.io/api/rest/integrations/mend



Use these operations to interact with the [Mend integration](/ingesting-data-into-cortex/integrations/mend) in Cortex. Mend provides two separate products — SAST and SCA — each configured independently.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Mend SAST operations

> **[Retrieve a configuration](/api/rest/mend-sast-api/retrieve-a-configuration)**
>
> `GET /api/v1/mend/sast/default-configuration`

> **[Add a configuration](/api/rest/mend-sast-api/add-a-configuration)**
>
> `POST /api/v1/mend/sast/configuration`

> **[Update the existing configuration](/api/rest/mend-sast-api/update-the-existing-configuration)**
>
> `PUT /api/v1/mend/sast/configuration`

> **[Validate a configuration](/api/rest/mend-sast-api/validate-a-configuration)**
>
> `POST /api/v1/mend/sast/configuration/validate`

> **[Delete a configuration](/api/rest/mend-sast-api/delete-a-configuration)**
>
> `DELETE /api/v1/mend/sast/configurations`

## Mend SCA operations

> **[Retrieve a configuration](/api/rest/mend-sca-api/retrieve-a-configuration)**
>
> `GET /api/v1/mend/sca/default-configuration`

> **[Add a configuration](/api/rest/mend-sca-api/add-a-configuration)**
>
> `POST /api/v1/mend/sca/configuration`

> **[Update the existing configuration](/api/rest/mend-sca-api/update-the-existing-configuration)**
>
> `PUT /api/v1/mend/sca/configuration`

> **[Validate a configuration](/api/rest/mend-sca-api/validate-a-configuration)**
>
> `POST /api/v1/mend/sca/configuration/validate`

> **[Delete a configuration](/api/rest/mend-sca-api/delete-a-configuration)**
>
> `DELETE /api/v1/mend/sca/configurations`


# New Relic API
Source: https://docs.cortex.io/api/rest/integrations/new-relic



Use these operations to interact with the [New Relic integration](/ingesting-data-into-cortex/integrations/newrelic) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/new-relic-api/retrieve-configurations)**
>
> `GET /api/v1/newrelic/configurations`

> **[Retrieve default configuration](/api/rest/new-relic-api/retrieve-default-configuration)**
>
> `GET /api/v1/newrelic/default-configuration`

> **[Retrieve a configuration](/api/rest/new-relic-api/retrieve-a-configuration)**
>
> `GET /api/v1/newrelic/configuration/{alias}`

> **[Add multiple configurations](/api/rest/new-relic-api/add-multiple-configurations)**
>
> `POST /api/v1/newrelic/configurations`

> **[Add a single configuration](/api/rest/new-relic-api/add-a-single-configuration)**
>
> `POST /api/v1/newrelic/configuration`

> **[Validate all configurations](/api/rest/new-relic-api/validate-all-configurations)**
>
> `POST /api/v1/newrelic/configuration/validate`

> **[Validate a configuration](/api/rest/new-relic-api/validate-a-configuration)**
>
> `POST /api/v1/newrelic/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/new-relic-api/update-a-configuration)**
>
> `PUT /api/v1/newrelic/configuration/{alias}`

> **[Delete all configurations](/api/rest/new-relic-api/delete-all-configurations)**
>
> `DELETE /api/v1/newrelic/configurations`

> **[Delete a configuration](/api/rest/new-relic-api/delete-a-configuration)**
>
> `DELETE /api/v1/newrelic/configuration/{alias}`


# Okta API
Source: https://docs.cortex.io/api/rest/integrations/okta



Use these operations to interact with the [Okta integration](/ingesting-data-into-cortex/integrations/okta) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/okta-api/retrieve-a-configuration)**
>
> `GET /api/v1/okta/default-configuration`

> **[Add a configuration](/api/rest/okta-api/add-a-configuration)**
>
> `POST /api/v1/okta/configuration`

> **[Update the existing configuration](/api/rest/okta-api/update-the-existing-configuration)**
>
> `PUT /api/v1/okta/configuration`

> **[Validate a configuration](/api/rest/okta-api/validate-a-configuration)**
>
> `POST /api/v1/okta/configuration/validate`

> **[Delete a configuration](/api/rest/okta-api/delete-a-configuration)**
>
> `DELETE /api/v1/okta/configurations`


# Opsgenie API
Source: https://docs.cortex.io/api/rest/integrations/opsgenie



Use these operations to interact with the [Opsgenie integration](/ingesting-data-into-cortex/integrations/opsgenie) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/opsgenie-api/retrieve-a-configuration)**
>
> `GET /api/v1/opsgenie/default-configuration`

> **[Add a configuration](/api/rest/opsgenie-api/add-a-configuration)**
>
> `POST /api/v1/opsgenie/configuration`

> **[Update the existing configuration](/api/rest/opsgenie-api/update-the-existing-configuration)**
>
> `PUT /api/v1/opsgenie/configuration`

> **[Validate a configuration](/api/rest/opsgenie-api/validate-a-configuration)**
>
> `POST /api/v1/opsgenie/configuration/validate`

> **[Delete a configuration](/api/rest/opsgenie-api/delete-a-configuration)**
>
> `DELETE /api/v1/opsgenie/configurations`


# PagerDuty API
Source: https://docs.cortex.io/api/rest/integrations/pagerduty



Use these operations to interact with the [PagerDuty integration](/ingesting-data-into-cortex/integrations/pagerduty) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/pagerduty-api/retrieve-a-configuration)**
>
> `GET /api/v1/pagerduty/default-configuration`

> **[Add a configuration](/api/rest/pagerduty-api/add-a-configuration)**
>
> `POST /api/v1/pagerduty/configuration`

> **[Update the existing configuration](/api/rest/pagerduty-api/update-the-existing-configuration)**
>
> `PUT /api/v1/pagerduty/configuration`

> **[Validate a configuration](/api/rest/pagerduty-api/validate-a-configuration)**
>
> `POST /api/v1/pagerduty/configuration/validate`

> **[Delete a configuration](/api/rest/pagerduty-api/delete-a-configuration)**
>
> `DELETE /api/v1/pagerduty/configurations`


# Prometheus API
Source: https://docs.cortex.io/api/rest/integrations/prometheus



Use these operations to interact with the [Prometheus integration](/ingesting-data-into-cortex/integrations/prometheus) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/prometheus-api/retrieve-configurations)**
>
> `GET /api/v1/prometheus/configurations`

> **[Retrieve default configuration](/api/rest/prometheus-api/retrieve-default-configuration)**
>
> `GET /api/v1/prometheus/default-configuration`

> **[Retrieve a configuration](/api/rest/prometheus-api/retrieve-a-configuration)**
>
> `GET /api/v1/prometheus/configuration/{alias}`

> **[Add multiple configurations](/api/rest/prometheus-api/add-multiple-configurations)**
>
> `POST /api/v1/prometheus/configurations`

> **[Add a single configuration](/api/rest/prometheus-api/add-a-single-configuration)**
>
> `POST /api/v1/prometheus/configuration`

> **[Validate all configurations](/api/rest/prometheus-api/validate-all-configurations)**
>
> `POST /api/v1/prometheus/configuration/validate`

> **[Validate a configuration](/api/rest/prometheus-api/validate-a-configuration)**
>
> `POST /api/v1/prometheus/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/prometheus-api/update-a-configuration)**
>
> `PUT /api/v1/prometheus/configuration/{alias}`

> **[Delete a configuration](/api/rest/prometheus-api/delete-a-configuration)**
>
> `DELETE /api/v1/prometheus/configuration/{alias}`

> **[Delete all configurations](/api/rest/prometheus-api/delete-all-configurations)**
>
> `DELETE /api/v1/prometheus/configurations`


# Rollbar API
Source: https://docs.cortex.io/api/rest/integrations/rollbar



Use these operations to interact with the [Rollbar integration](/ingesting-data-into-cortex/integrations/rollbar) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/rollbar-api/retrieve-a-configuration)**
>
> `GET /api/v1/rollbar/default-configuration`

> **[Add a configuration](/api/rest/rollbar-api/add-a-configuration)**
>
> `POST /api/v1/rollbar/configuration`

> **[Update the existing configuration](/api/rest/rollbar-api/update-the-existing-configuration)**
>
> `PUT /api/v1/rollbar/configuration`

> **[Validate a configuration](/api/rest/rollbar-api/validate-a-configuration)**
>
> `POST /api/v1/rollbar/configuration/validate`

> **[Delete a configuration](/api/rest/rollbar-api/delete-a-configuration)**
>
> `DELETE /api/v1/rollbar/configurations`


# Rootly API
Source: https://docs.cortex.io/api/rest/integrations/rootly



Use these operations to interact with the [Rootly integration](/ingesting-data-into-cortex/integrations/rootly) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve default configuration](/api/rest/rootly-api/retrieve-default-configuration)**
>
> `GET /api/v1/rootly/default-configuration`

> **[Add a configuration](/api/rest/rootly-api/add-a-configuration)**
>
> `POST /api/v1/rootly/configuration`

> **[Retrieve all configurations](/api/rest/rootly-api/retrieve-all-configurations)**
>
> `GET /api/v1/rootly/configurations`

> **[Retrieve a configuration by alias](/api/rest/rootly-api/retrieve-a-configuration-by-alias)**
>
> `GET /api/v1/rootly/configuration/{alias}`

> **[Update a configuration](/api/rest/rootly-api/update-a-configuration)**
>
> `PUT /api/v1/rootly/configuration/{alias}`

> **[Delete a configuration by alias](/api/rest/rootly-api/delete-a-configuration-by-alias)**
>
> `DELETE /api/v1/rootly/configuration/{alias}`


# Semgrep API
Source: https://docs.cortex.io/api/rest/integrations/semgrep



Use these operations to interact with the [Semgrep integration](/ingesting-data-into-cortex/integrations/semgrep) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/semgrep-api/retrieve-configurations)**
>
> `GET /api/v1/semgrep/configurations`

> **[Retrieve default configuration](/api/rest/semgrep-api/retrieve-default-configuration)**
>
> `GET /api/v1/semgrep/default-configuration`

> **[Retrieve a configuration](/api/rest/semgrep-api/retrieve-a-configuration)**
>
> `GET /api/v1/semgrep/configuration/{alias}`

> **[Add multiple configurations](/api/rest/semgrep-api/add-multiple-configurations)**
>
> `POST /api/v1/semgrep/configurations`

> **[Add a single configuration](/api/rest/semgrep-api/add-a-single-configuration)**
>
> `POST /api/v1/semgrep/configuration`

> **[Validate all configurations](/api/rest/semgrep-api/validate-all-configurations)**
>
> `POST /api/v1/semgrep/configuration/validate`

> **[Validate a configuration](/api/rest/semgrep-api/validate-a-configuration)**
>
> `POST /api/v1/semgrep/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/semgrep-api/update-a-configuration)**
>
> `PUT /api/v1/semgrep/configuration/{alias}`

> **[Delete a configuration](/api/rest/semgrep-api/delete-a-configuration)**
>
> `DELETE /api/v1/semgrep/configuration/{alias}`

> **[Delete all configurations](/api/rest/semgrep-api/delete-all-configurations)**
>
> `DELETE /api/v1/semgrep/configurations`


# Sentry API
Source: https://docs.cortex.io/api/rest/integrations/sentry



Use these operations to interact with the [Sentry integration](/ingesting-data-into-cortex/integrations/sentry) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/sentry-api/retrieve-a-configuration)**
>
> `GET /api/v1/sentry/default-configuration`

> **[Add a configuration](/api/rest/sentry-api/add-a-configuration)**
>
> `POST /api/v1/sentry/configuration`

> **[Update the existing configuration](/api/rest/sentry-api/update-the-existing-configuration)**
>
> `PUT /api/v1/sentry/configuration`

> **[Validate a configuration](/api/rest/sentry-api/validate-a-configuration)**
>
> `POST /api/v1/sentry/configuration/validate`

> **[Delete a configuration](/api/rest/sentry-api/delete-a-configuration)**
>
> `DELETE /api/v1/sentry/configurations`


# ServiceNow API
Source: https://docs.cortex.io/api/rest/integrations/servicenow



Use these operations to interact with the [ServiceNow integration](/ingesting-data-into-cortex/integrations/servicenow) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/servicenow-api/retrieve-a-configuration)**
>
> `GET /api/v1/servicenow/default-configuration`

> **[Add a configuration](/api/rest/servicenow-api/add-a-configuration)**
>
> `POST /api/v1/servicenow/configuration`

> **[Update the existing configuration](/api/rest/servicenow-api/update-the-existing-configuration)**
>
> `PUT /api/v1/servicenow/configuration`

> **[Validate a configuration](/api/rest/servicenow-api/validate-a-configuration)**
>
> `POST /api/v1/servicenow/configuration/validate`

> **[Delete a configuration](/api/rest/servicenow-api/delete-a-configuration)**
>
> `DELETE /api/v1/servicenow/configurations`


# ServiceNow Cloud Observability API
Source: https://docs.cortex.io/api/rest/integrations/servicenow-cloud-observability



Use these operations to interact with the [ServiceNow Cloud Observability integration](/api/rest/integrations/servicenow-cloud-observability) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/servicenow-cloud-observability-api/retrieve-a-configuration)**
>
> `GET /api/v1/lightstep/default-configuration`

> **[Add a configuration](/api/rest/servicenow-cloud-observability-api/add-a-configuration)**
>
> `POST /api/v1/lightstep/configuration`

> **[Update the existing configuration](/api/rest/servicenow-cloud-observability-api/update-the-existing-configuration)**
>
> `PUT /api/v1/lightstep/configuration`

> **[Validate a configuration](/api/rest/servicenow-cloud-observability-api/validate-a-configuration)**
>
> `POST /api/v1/lightstep/configuration/validate`

> **[Delete a configuration](/api/rest/servicenow-cloud-observability-api/delete-a-configuration)**
>
> `DELETE /api/v1/lightstep/configurations`


# Snyk API
Source: https://docs.cortex.io/api/rest/integrations/snyk



Use these operations to interact with the [Snyk integration](/ingesting-data-into-cortex/integrations/snyk) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/snyk-api/retrieve-a-configuration)**
>
> `GET /api/v1/snyk/default-configuration`

> **[Add a configuration](/api/rest/snyk-api/add-a-configuration)**
>
> `POST /api/v1/snyk/configuration`

> **[Update the existing configuration](/api/rest/snyk-api/update-the-existing-configuration)**
>
> `PUT /api/v1/snyk/configuration`

> **[Validate a configuration](/api/rest/snyk-api/validate-a-configuration)**
>
> `POST /api/v1/snyk/configuration/validate`

> **[Delete a configuration](/api/rest/snyk-api/delete-a-configuration)**
>
> `DELETE /api/v1/snyk/configurations`


# SonarQube API
Source: https://docs.cortex.io/api/rest/integrations/sonarqube



Use these operations to interact with the [SonarQube integration](/ingesting-data-into-cortex/integrations/sonarqube) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve configurations](/api/rest/sonarqube-api/retrieve-configurations)**
>
> `GET /api/v1/sonarqube/configurations`

> **[Retrieve default configuration](/api/rest/sonarqube-api/retrieve-default-configuration)**
>
> `GET /api/v1/sonarqube/default-configuration`

> **[Retrieve a configuration](/api/rest/sonarqube-api/retrieve-a-configuration)**
>
> `GET /api/v1/sonarqube/configuration/{alias}`

> **[Add multiple configurations](/api/rest/sonarqube-api/add-multiple-configurations)**
>
> `POST /api/v1/sonarqube/configurations`

> **[Add a single configuration](/api/rest/sonarqube-api/add-a-single-configuration)**
>
> `POST /api/v1/sonarqube/configuration`

> **[Validate all configurations](/api/rest/sonarqube-api/validate-all-configurations)**
>
> `POST /api/v1/sonarqube/configuration/validate`

> **[Validate a configuration](/api/rest/sonarqube-api/validate-a-configuration)**
>
> `POST /api/v1/sonarqube/configuration/validate/{alias}`

> **[Update a configuration](/api/rest/sonarqube-api/update-a-configuration)**
>
> `PUT /api/v1/sonarqube/configuration/{alias}`

> **[Delete a configuration](/api/rest/sonarqube-api/delete-a-configuration)**
>
> `DELETE /api/v1/sonarqube/configuration/{alias}`

> **[Delete all configurations](/api/rest/sonarqube-api/delete-all-configurations)**
>
> `DELETE /api/v1/sonarqube/configurations`


# Splunk Observability Cloud API
Source: https://docs.cortex.io/api/rest/integrations/splunk-observability-cloud



Use these operations to interact with the [Splunk Observability Cloud integration](/api/rest/integrations/splunk-observability-cloud) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/splunk-observability-cloud-api/retrieve-a-configuration)**
>
> `GET /api/v1/signalfx/default-configuration`

> **[Add a configuration](/api/rest/splunk-observability-cloud-api/add-a-configuration)**
>
> `POST /api/v1/signalfx/configuration`

> **[Update the existing configuration](/api/rest/splunk-observability-cloud-api/update-the-existing-configuration)**
>
> `PUT /api/v1/signalfx/configuration`

> **[Validate a configuration](/api/rest/splunk-observability-cloud-api/validate-a-configuration)**
>
> `POST /api/v1/signalfx/configuration/validate`

> **[Delete a configuration](/api/rest/splunk-observability-cloud-api/delete-a-configuration)**
>
> `DELETE /api/v1/signalfx/configurations`


# Splunk On Call API
Source: https://docs.cortex.io/api/rest/integrations/splunk-on-call



Use these operations to interact with the [Splunk On Call integration](/api/rest/integrations/splunk-on-call) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/splunk-on-call-api/retrieve-a-configuration)**
>
> `GET /api/v1/victorops/default-configuration`

> **[Add a configuration](/api/rest/splunk-on-call-api/add-a-configuration)**
>
> `POST /api/v1/victorops/configuration`

> **[Update the existing configuration](/api/rest/splunk-on-call-api/update-the-existing-configuration)**
>
> `PUT /api/v1/victorops/configuration`

> **[Validate a configuration](/api/rest/splunk-on-call-api/validate-a-configuration)**
>
> `POST /api/v1/victorops/configuration/validate`

> **[Delete a configuration](/api/rest/splunk-on-call-api/delete-a-configuration)**
>
> `DELETE /api/v1/victorops/configurations`


# Sumo Logic API
Source: https://docs.cortex.io/api/rest/integrations/sumologic



Use these operations to interact with the [Sumo Logic integration](/ingesting-data-into-cortex/integrations/sumologic) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/sumo-logic-api/retrieve-a-configuration)**
>
> `GET /api/v1/sumologic/default-configuration`

> **[Add a configuration](/api/rest/sumo-logic-api/add-a-configuration)**
>
> `POST /api/v1/sumologic/configuration`

> **[Update the existing configuration](/api/rest/sumo-logic-api/update-the-existing-configuration)**
>
> `PUT /api/v1/sumologic/configuration`

> **[Validate a configuration](/api/rest/sumo-logic-api/validate-a-configuration)**
>
> `POST /api/v1/sumologic/configuration/validate`

> **[Delete a configuration](/api/rest/sumo-logic-api/delete-a-configuration)**
>
> `DELETE /api/v1/sumologic/configurations`


# Veracode API
Source: https://docs.cortex.io/api/rest/integrations/veracode



Use these operations to interact with the [Veracode integration](/ingesting-data-into-cortex/integrations/veracode) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/veracode-api/retrieve-a-configuration)**
>
> `GET /api/v1/veracode/default-configuration`

> **[Add a configuration](/api/rest/veracode-api/add-a-configuration)**
>
> `POST /api/v1/veracode/configuration`

> **[Update the existing configuration](/api/rest/veracode-api/update-the-existing-configuration)**
>
> `PUT /api/v1/veracode/configuration`

> **[Validate a configuration](/api/rest/veracode-api/validate-a-configuration)**
>
> `POST /api/v1/veracode/configuration/validate`

> **[Delete a configuration](/api/rest/veracode-api/delete-a-configuration)**
>
> `DELETE /api/v1/veracode/configurations`


# Wiz API
Source: https://docs.cortex.io/api/rest/integrations/wiz



Use these operations to interact with the [Wiz integration](/ingesting-data-into-cortex/integrations/wiz) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/wiz-api/retrieve-a-configuration)**
>
> `GET /api/v1/wiz/default-configuration`

> **[Add a configuration](/api/rest/wiz-api/add-a-configuration)**
>
> `POST /api/v1/wiz/configuration`

> **[Update the existing configuration](/api/rest/wiz-api/update-the-existing-configuration)**
>
> `PUT /api/v1/wiz/configuration`

> **[Validate a configuration](/api/rest/wiz-api/validate-a-configuration)**
>
> `POST /api/v1/wiz/configuration/validate`

> **[Delete a configuration](/api/rest/wiz-api/delete-a-configuration)**
>
> `DELETE /api/v1/wiz/configurations`


# Workday API
Source: https://docs.cortex.io/api/rest/integrations/workday



Use these operations to interact with the [Workday integration](/ingesting-data-into-cortex/integrations/workday) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/workday-api/retrieve-a-configuration)**
>
> `GET /api/v1/workday/default-configuration`

> **[Add a configuration](/api/rest/workday-api/add-a-configuration)**
>
> `POST /api/v1/workday/configuration`

> **[Update the existing configuration](/api/rest/workday-api/update-the-existing-configuration)**
>
> `PUT /api/v1/workday/configuration`

> **[Validate a configuration](/api/rest/workday-api/validate-a-configuration)**
>
> `POST /api/v1/workday/configuration/validate`

> **[Delete a configuration](/api/rest/workday-api/delete-a-configuration)**
>
> `DELETE /api/v1/workday/configurations`


# xMatters API
Source: https://docs.cortex.io/api/rest/integrations/xmatters



Use these operations to interact with the [xMatters integration](/ingesting-data-into-cortex/integrations/xmatters) in Cortex.

### Required permissions

Your API key must have the `Configure integrations` permission.

## Operations

> **[Retrieve a configuration](/api/rest/xmatters-api/retrieve-a-configuration)**
>
> `GET /api/v1/xmatters/default-configuration`

> **[Add a configuration](/api/rest/xmatters-api/add-a-configuration)**
>
> `POST /api/v1/xmatters/configuration`

> **[Update the existing configuration](/api/rest/xmatters-api/update-the-existing-configuration)**
>
> `PUT /api/v1/xmatters/configuration`

> **[Validate a configuration](/api/rest/xmatters-api/validate-a-configuration)**
>
> `POST /api/v1/xmatters/configuration/validate`

> **[Delete a configuration](/api/rest/xmatters-api/delete-a-configuration)**
>
> `DELETE /api/v1/xmatters/configurations`


# IP Allowlist
Source: https://docs.cortex.io/api/rest/ip-allowlist



Use these operations to interact with the [IP allowlist](/configure/settings/ip-allowlist) in Cortex.

### Required permissions

Your API key must have the `Configure IP allowlist` permission.

## Operations

> **[Gets allowlist of IP addresses & ranges](/api/rest/ip-allowlist/gets-allowlist-of-ip-addresses-&-ranges)**
>
> `GET /api/v1/ip-allowlist`

> **[Validates allowlist of IP addresses & ranges](/api/rest/ip-allowlist/validates-allowlist-of-ip-addresses-&-ranges)**
>
> `POST /api/v1/ip-allowlist/validate`

> **[Replace existing allowlist with provided list of IP addresses & ranges](/api/rest/ip-allowlist/replace-existing-allowlist-with-provided-list-of-ip-addresses-&-ranges)**
>
> `PUT /api/v1/ip-allowlist`


# Gets allowlist of IP addresses & ranges
Source: https://docs.cortex.io/api/rest/ip-allowlist/gets-allowlist-of-ip-addresses-&-ranges

/openapi/cortex_swagger.json get /api/v1/ip-allowlist



# Replace existing allowlist with provided list of IP addresses & ranges
Source: https://docs.cortex.io/api/rest/ip-allowlist/replace-existing-allowlist-with-provided-list-of-ip-addresses-&-ranges

/openapi/cortex_swagger.json put /api/v1/ip-allowlist



# Validates allowlist of IP addresses & ranges
Source: https://docs.cortex.io/api/rest/ip-allowlist/validates-allowlist-of-ip-addresses-&-ranges

/openapi/cortex_swagger.json post /api/v1/ip-allowlist/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/jenkins-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/jenkins/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/jenkins-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/jenkins/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/jenkins-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/jenkins/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/jenkins-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/jenkins/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/jenkins-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/jenkins/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/jenkins-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/jenkins/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/jenkins-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/jenkins/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/jenkins-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/jenkins/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/jenkins-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/jenkins/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/jenkins-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/jenkins/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/jira-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/jira/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/jira-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/jira/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/jira-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/jira/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/jira-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/jira/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/jira-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/jira/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/jira-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/jira/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/jira-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/jira/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/jira-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/jira/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/jira-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/jira/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/jira-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/jira/configuration/validate



# Get Kubernetes resource details for an entity
Source: https://docs.cortex.io/api/rest/kubernetes-api/get-kubernetes-resource-details-for-an-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/k8s

            Returns cached Kubernetes resource details for the specified entity.
            This endpoint serves cached data only and does not make live Kubernetes API calls.
        



# Add a single configuration
Source: https://docs.cortex.io/api/rest/launchdarkly-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/launchdarkly/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/launchdarkly-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/launchdarkly/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/launchdarkly-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/launchdarkly/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/launchdarkly-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/launchdarkly/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/launchdarkly-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/launchdarkly/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/launchdarkly-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/launchdarkly/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/launchdarkly-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/launchdarkly/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/launchdarkly-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/launchdarkly/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/launchdarkly-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/launchdarkly/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/launchdarkly-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/launchdarkly/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/mend-sast-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/mend/sast/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/mend-sast-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/mend/sast/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/mend-sast-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/mend/sast/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/mend-sast-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/mend/sast/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/mend-sast-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/mend/sast/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/mend-sca-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/mend/sca/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/mend-sca-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/mend/sca/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/mend-sca-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/mend/sca/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/mend-sca-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/mend/sca/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/mend-sca-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/mend/sca/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/new-relic-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/newrelic/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/new-relic-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/newrelic/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/new-relic-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/newrelic/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/new-relic-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/newrelic/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/new-relic-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/newrelic/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/new-relic-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/newrelic/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/new-relic-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/newrelic/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/new-relic-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/newrelic/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/new-relic-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/newrelic/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/new-relic-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/newrelic/configuration/validate



# Notification Logs
Source: https://docs.cortex.io/api/rest/notification-logs



Use these operations to interact with [notification logs](/configure/settings/notifications/logs) in Cortex.

### Required permissions

Your API key must have the `View notification logs` permission.

## Operations

> **[Retrieve notification logs](/api/rest/notification-logs/retrieve-notification-logs)**
>
> `GET /api/v1/notifications/logs`

> **[Retrieve notification runs](/api/rest/notification-logs/retrieve-notification-runs)**
>
> `GET /api/v1/notifications/logs/run`


# Retrieve notification logs
Source: https://docs.cortex.io/api/rest/notification-logs/retrieve-notification-logs

/openapi/cortex_swagger.json get /api/v1/notifications/logs
Retrieve notification logs based on the provided filters. API key must have the `View Notification logs` permission.



# Retrieve notification runs
Source: https://docs.cortex.io/api/rest/notification-logs/retrieve-notification-runs

/openapi/cortex_swagger.json get /api/v1/notifications/logs/run
Retrieve notification runs based on the provided filters. API key must have the `View Notification logs` permission.



# Add a configuration
Source: https://docs.cortex.io/api/rest/okta-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/okta/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/okta-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/okta/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/okta-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/okta/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/okta-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/okta/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/okta-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/okta/configuration/validate



# On call
Source: https://docs.cortex.io/api/rest/on-call



Use these operations to interact with on-call information on [entities](/ingesting-data-into-cortex/entities-overview/entities) in Cortex.

### Required permissions

* Your API key must have the `Edit entities` permission.

## Operations

> **[Retrieve current on-call for entity](/api/rest/on-call/retrieve-current-on-call-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/integrations/oncall/current`

> **[Retrieve on-call registration for entity](/api/rest/on-call/retrieve-on-call-registration-for-entity)**
>
> `GET /api/v1/catalog/{tagOrId}/integrations/oncall/registration`


# Retrieve current on-call for entity
Source: https://docs.cortex.io/api/rest/on-call/retrieve-current-on-call-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/integrations/oncall/current



# Retrieve on-call registration for entity
Source: https://docs.cortex.io/api/rest/on-call/retrieve-on-call-registration-for-entity

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/integrations/oncall/registration



# Add a configuration
Source: https://docs.cortex.io/api/rest/opsgenie-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/opsgenie/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/opsgenie-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/opsgenie/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/opsgenie-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/opsgenie/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/opsgenie-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/opsgenie/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/opsgenie-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/opsgenie/configuration/validate



# Packages
Source: https://docs.cortex.io/api/rest/packages



Use these operations to interact with packages in Cortex.

### Required permissions

Your API key must have the `Edit entities` permission.

## Operations

> **[List packages](/api/rest/packages/list-packages)**
>
> `GET /api/v1/catalog/{tagOrId}/packages`

> **[\[csharp\] Upload Nuget csproj](/api/rest/packages/\[csharp]-upload-nuget-csproj)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/dotnet/nuget/csproj`

> **[\[csharp\] Upload Nuget packages.lock.json](/api/rest/packages/\[csharp]-upload-nuget-packageslockjson)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/dotnet/nuget/packages-lock`

> **[\[csharp\] Delete Nuget package](/api/rest/packages/\[csharp]-delete-nuget-package)**
>
> `DELETE /api/v1/catalog/{tagOrId}/packages/dotnet/nuget`

> **[\[golang\] Upload go.sum](/api/rest/packages/\[golang]-upload-gosum)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/go/gosum`

> **[\[go\] Delete Go package](/api/rest/packages/\[go]-delete-go-package)**
>
> `DELETE /api/v1/catalog/{tagOrId}/packages/go`

> **[\[java\] Upload single Java package](/api/rest/packages/\[java]-upload-single-java-package)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/java`

> **[\[java\] Upload multiple Java packages](/api/rest/packages/\[java]-upload-multiple-java-packages)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/java/bulk`

> **[\[java\] Upload maven pom.xml](/api/rest/packages/\[java]-upload-maven-pomxml)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/java/maven-pom`

> **[\[java\] Delete Java package](/api/rest/packages/\[java]-delete-java-package)**
>
> `DELETE /api/v1/catalog/{tagOrId}/packages/java`

> **[\[js\] Upload NPM/Yarn/PNPM package.json](/api/rest/packages/\[js]-upload-npmyarnpnpm-packagejson)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/node/package-json`

> **[\[js\] Upload NPM package-lock.json](/api/rest/packages/\[js]-upload-npm-package-lockjson)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/node/package-lock`

> **[\[node\] Delete Node package](/api/rest/packages/\[node]-delete-node-package)**
>
> `DELETE /api/v1/catalog/{tagOrId}/packages/node`

> **[\[js\] Upload pnpm-lock.yaml](/api/rest/packages/\[js]-upload-pnpm-lockyaml)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/node/pnpm-lock`

> **[\[js\] Upload yarn.lock](/api/rest/packages/\[js]-upload-yarnlock)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/node/yarn-lock`

> **[\[python\] Upload pipfile.lock](/api/rest/packages/\[python]-upload-pipfilelock)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/python/pipfile`

> **[\[python\] Upload requirements.txt](/api/rest/packages/\[python]-upload-requirementstxt)**
>
> `POST /api/v1/catalog/{tagOrId}/packages/python/requirements`

> [!WARNING]
>
> Only exact version specifiers (`==`) are supported in `requirements.txt` files. Other version specifiers such as `>=`, `<=`, `~=`, and `!=` are ignored when parsing the file. Packages specified without an exact version will be ingested without a version value.

> **[\[python\] Delete Python package](/api/rest/packages/\[python]-delete-python-package)**
>
> `DELETE /api/v1/catalog/{tagOrId}/packages/python`


# [csharp] Delete Nuget package
Source: https://docs.cortex.io/api/rest/packages/[csharp]-delete-nuget-package

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/packages/dotnet/nuget



# [csharp] Upload Nuget csproj
Source: https://docs.cortex.io/api/rest/packages/[csharp]-upload-nuget-csproj

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/dotnet/nuget/csproj



# [csharp] Upload Nuget packages.lock.json
Source: https://docs.cortex.io/api/rest/packages/[csharp]-upload-nuget-packageslockjson

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/dotnet/nuget/packages-lock



# [go] Delete Go package
Source: https://docs.cortex.io/api/rest/packages/[go]-delete-go-package

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/packages/go



# [golang] Upload go.sum
Source: https://docs.cortex.io/api/rest/packages/[golang]-upload-gosum

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/go/gosum



# [java] Delete Java package
Source: https://docs.cortex.io/api/rest/packages/[java]-delete-java-package

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/packages/java



# [java] Upload maven pom.xml
Source: https://docs.cortex.io/api/rest/packages/[java]-upload-maven-pomxml

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/java/maven-pom



# [java] Upload multiple Java packages
Source: https://docs.cortex.io/api/rest/packages/[java]-upload-multiple-java-packages

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/java/bulk



# [java] Upload single Java package
Source: https://docs.cortex.io/api/rest/packages/[java]-upload-single-java-package

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/java



# [js] Upload NPM package-lock.json
Source: https://docs.cortex.io/api/rest/packages/[js]-upload-npm-package-lockjson

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/node/package-lock



# [js] Upload NPM/Yarn/PNPM package.json
Source: https://docs.cortex.io/api/rest/packages/[js]-upload-npmyarnpnpm-packagejson

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/node/package-json



# [js] Upload pnpm-lock.yaml
Source: https://docs.cortex.io/api/rest/packages/[js]-upload-pnpm-lockyaml

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/node/pnpm-lock



# [js] Upload yarn.lock
Source: https://docs.cortex.io/api/rest/packages/[js]-upload-yarnlock

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/node/yarn-lock



# [node] Delete Node package
Source: https://docs.cortex.io/api/rest/packages/[node]-delete-node-package

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/packages/node



# [python] Delete Python package
Source: https://docs.cortex.io/api/rest/packages/[python]-delete-python-package

/openapi/cortex_swagger.json delete /api/v1/catalog/{tagOrId}/packages/python



# [python] Upload pipfile.lock
Source: https://docs.cortex.io/api/rest/packages/[python]-upload-pipfilelock

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/python/pipfile



# [python] Upload requirements.txt
Source: https://docs.cortex.io/api/rest/packages/[python]-upload-requirementstxt

/openapi/cortex_swagger.json post /api/v1/catalog/{tagOrId}/packages/python/requirements



# List packages
Source: https://docs.cortex.io/api/rest/packages/list-packages

/openapi/cortex_swagger.json get /api/v1/catalog/{tagOrId}/packages



# Add a configuration
Source: https://docs.cortex.io/api/rest/pagerduty-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/pagerduty/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/pagerduty-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/pagerduty/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/pagerduty-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/pagerduty/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/pagerduty-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/pagerduty/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/pagerduty-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/pagerduty/configuration/validate



# Plugins
Source: https://docs.cortex.io/api/rest/plugins



Use these operations to interact with [plugins](/streamline/plugins) in Cortex.

### Required permissions

Your API key must have the `Edit plugins` permission for write operations (create, update, and delete). For read endpoints, your API key's effective role must be greater than or equal to the plugin's `minimumRoleRequired` setting — if it is not, read endpoints will return `403 Forbidden` for existing plugins or an empty result set.

## Operations

> **[Get all plugins](/api/rest/plugins/get-all-plugins)**
>
> `GET /api/v1/plugins`

> **[Get plugin by tag](/api/rest/plugins/get-plugin-by-tag)**
>
> `GET /api/v1/plugins/{tag}`

> **[Create a plugin](/api/rest/plugins/create-a-plugin)**
>
> `POST /api/v1/plugins`

> **[Replace a plugin](/api/rest/plugins/replace-a-plugin)**
>
> `PUT /api/v1/plugins/{tag}`

> **[Delete a plugin](/api/rest/plugins/delete-a-plugin)**
>
> `DELETE /api/v1/plugins/{tag}`


# Create a plugin
Source: https://docs.cortex.io/api/rest/plugins/create-a-plugin

/openapi/cortex_swagger.json post /api/v1/plugins
Create a new plugin



# Delete a plugin
Source: https://docs.cortex.io/api/rest/plugins/delete-a-plugin

/openapi/cortex_swagger.json delete /api/v1/plugins/{tag}
Delete a plugin by tag



# Get all plugins
Source: https://docs.cortex.io/api/rest/plugins/get-all-plugins

/openapi/cortex_swagger.json get /api/v1/plugins
Retrieve a list of all plugins, excluding drafts



# Get plugin by tag
Source: https://docs.cortex.io/api/rest/plugins/get-plugin-by-tag

/openapi/cortex_swagger.json get /api/v1/plugins/{tag}
Retrieve the metadata of a plugin by tag



# Replace a plugin
Source: https://docs.cortex.io/api/rest/plugins/replace-a-plugin

/openapi/cortex_swagger.json put /api/v1/plugins/{tag}
Replace an existing plugin by tag



# Add a single configuration
Source: https://docs.cortex.io/api/rest/prometheus-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/prometheus/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/prometheus-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/prometheus/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/prometheus-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/prometheus/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/prometheus-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/prometheus/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/prometheus-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/prometheus/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/prometheus-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/prometheus/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/prometheus-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/prometheus/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/prometheus-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/prometheus/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/prometheus-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/prometheus/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/prometheus-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/prometheus/configuration/validate



# Queries
Source: https://docs.cortex.io/api/rest/queries



Use these operations to interact with [CQL queries](/standardize/cql) in Cortex.

> [!WARNING]
>
> Starting November 10, 2026, `POST /api/v1/queries` no longer runs a query against every entity in your catalog. Pass up to 100 tags or Cortex IDs in `entities`, or page through the catalog with `pageSize` and `pageToken`. A request without `entities` runs against the first page of up to 1,000 entities, and its `nextPageToken` reads the next page.

### Required permissions

Edit entities: Your API key must have the `Enable Query builder` permission.

## Operations

> **[Retrieve query results](/api/rest/queries/retrieve-query-results)**
>
> `GET /api/v1/queries/{jobId}`

> **[Run query](/api/rest/queries/run-query)**
>
> `POST /api/v1/queries`


# Retrieve query results
Source: https://docs.cortex.io/api/rest/queries/retrieve-query-results

/openapi/cortex_swagger.json get /api/v1/queries/{jobId}
Retrieve the status and results of a CQL query



# Run query
Source: https://docs.cortex.io/api/rest/queries/run-query

/openapi/cortex_swagger.json post /api/v1/queries
Run a CQL query against up to 100 `entities`, or against one page of the catalog with `pageSize` and `pageToken`. A request with neither runs against every entity in the catalog. Starting November 10, 2026, it runs against the first page only, and the response's `nextPageToken` reads the next page. For more information about the types of queries you can run, take a look at our CQL Explorer in the app.



# Recommendations
Source: https://docs.cortex.io/api/rest/recommendations



PRIVATE BETA

Use these operations to review [ownership recommendations](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations) in Cortex. Ownership recommendations are in [private beta](/resources/beta#ownership-recommendations-private-beta).

### Required permissions

To accept, reject, or restore a recommendation, your API key must be able to edit the recommendation's entity.

## Operations

> **[List ownership recommendations](/api/rest/recommendations/list-ownership-recommendations)**
>
> `GET /api/v1/recommendations/ownership`

> **[List entities with ownership recommendations](/api/rest/recommendations/list-entities-with-ownership-recommendations)**
>
> `GET /api/v1/recommendations/ownership/entities`

> **[Accept an ownership recommendation](/api/rest/recommendations/accept-an-ownership-recommendation)**
>
> `POST /api/v1/recommendations/ownership/{id}/accept`

> **[Accept many ownership recommendations](/api/rest/recommendations/accept-many-ownership-recommendations)**
>
> `POST /api/v1/recommendations/ownership/accept/batch`

> **[Reject an ownership recommendation](/api/rest/recommendations/reject-an-ownership-recommendation)**
>
> `PUT /api/v1/recommendations/ownership/{id}/rejection`

> **[Reject many ownership recommendations](/api/rest/recommendations/reject-many-ownership-recommendations)**
>
> `PUT /api/v1/recommendations/ownership/rejections/batch`

> **[Restore an ownership recommendation](/api/rest/recommendations/restore-an-ownership-recommendation)**
>
> `DELETE /api/v1/recommendations/ownership/{id}/rejection`

> **[Restore many ownership recommendations](/api/rest/recommendations/restore-many-ownership-recommendations)**
>
> `DELETE /api/v1/recommendations/ownership/rejections/batch`


# Accept an ownership recommendation
Source: https://docs.cortex.io/api/rest/recommendations/accept-an-ownership-recommendation

/openapi/cortex_swagger.json post /api/v1/recommendations/ownership/{id}/accept
Adds the recommended team as a direct owner of the entity, and records that the recommendation was accepted. When the entity's owners are managed in Git, a pull request adding the team is queued instead, and the result is PENDING until it merges.



# Accept many ownership recommendations
Source: https://docs.cortex.io/api/rest/recommendations/accept-many-ownership-recommendations

/openapi/cortex_swagger.json post /api/v1/recommendations/ownership/accept/batch
Accepts each recommendation as acceptOwnershipRecommendation does. Each one succeeds or fails on its own, and the results come back in request order. A GitOps pull request is queued (PENDING) only when every recommendation in the request is for the same entity; in a request spanning several entities, those whose owners are managed in Git fail with GITOPS_MANAGED.



# List entities with ownership recommendations
Source: https://docs.cortex.io/api/rest/recommendations/list-entities-with-ownership-recommendations

/openapi/cortex_swagger.json get /api/v1/recommendations/ownership/entities
One row for each entity that has ownership recommendations, with how many are open and the highest confidence among them, strongest first.



# List ownership recommendations
Source: https://docs.cortex.io/api/rest/recommendations/list-ownership-recommendations

/openapi/cortex_swagger.json get /api/v1/recommendations/ownership
Lists the team ownership recommendations you can see, strongest first. By default it lists open ones: not rejected, and the team does not already own the entity. Archived entities and teams never appear.



# Reject an ownership recommendation
Source: https://docs.cortex.io/api/rest/recommendations/reject-an-ownership-recommendation

/openapi/cortex_swagger.json put /api/v1/recommendations/ownership/{id}/rejection
Hides the recommendation from the open list. Owners do not change. Rejecting a recommendation that is already rejected does nothing.



# Reject many ownership recommendations
Source: https://docs.cortex.io/api/rest/recommendations/reject-many-ownership-recommendations

/openapi/cortex_swagger.json put /api/v1/recommendations/ownership/rejections/batch
Rejects each recommendation in the request. Each one succeeds or fails on its own, and the results come back in request order. Owners do not change.



# Restore an ownership recommendation
Source: https://docs.cortex.io/api/rest/recommendations/restore-an-ownership-recommendation

/openapi/cortex_swagger.json delete /api/v1/recommendations/ownership/{id}/rejection
Removes the rejection, or withdraws an accept still PENDING on a GitOps pull request, so the recommendation is open again. Owners do not change, and an open pull request is left as it is. Restoring an open recommendation does nothing.



# Restore many ownership recommendations
Source: https://docs.cortex.io/api/rest/recommendations/restore-many-ownership-recommendations

/openapi/cortex_swagger.json delete /api/v1/recommendations/ownership/rejections/batch
Removes the rejection, or withdraws a PENDING accept, from each recommendation in the request, as batchRejectOwnershipRecommendations does. Owners do not change.



# Add a configuration
Source: https://docs.cortex.io/api/rest/rollbar-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/rollbar/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/rollbar-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/rollbar/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/rollbar-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/rollbar/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/rollbar-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/rollbar/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/rollbar-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/rollbar/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/rootly-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/rootly/configuration



# Delete a configuration by alias
Source: https://docs.cortex.io/api/rest/rootly-api/delete-a-configuration-by-alias

/openapi/cortex_swagger.json delete /api/v1/rootly/configuration/{alias}



# Retrieve a configuration by alias
Source: https://docs.cortex.io/api/rest/rootly-api/retrieve-a-configuration-by-alias

/openapi/cortex_swagger.json get /api/v1/rootly/configuration/{alias}



# Retrieve all configurations
Source: https://docs.cortex.io/api/rest/rootly-api/retrieve-all-configurations

/openapi/cortex_swagger.json get /api/v1/rootly/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/rootly-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/rootly/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/rootly-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/rootly/configuration/{alias}



# Create or update Scaffolder template
Source: https://docs.cortex.io/api/rest/scaffolder/create-or-update-scaffolder-template

/openapi/cortex_swagger.json post /api/v1/scaffolders
Create or update a Scaffolder template.

API key must have the `Configure Scaffolder` permission.

**Note:** If a Scaffolder template with the same tag already exists, it will be updated.



# Delete Scaffolder template
Source: https://docs.cortex.io/api/rest/scaffolder/delete-scaffolder-template

/openapi/cortex_swagger.json delete /api/v1/scaffolders/{tagOrId}
Delete a Scaffolder template by tag or Cortex ID.

API key must have the `Configure Scaffolder` permission.



# List Scaffolder templates
Source: https://docs.cortex.io/api/rest/scaffolder/list-scaffolder-templates

/openapi/cortex_swagger.json get /api/v1/scaffolders
List Scaffolder templates.



# Retrieve Scaffolder template
Source: https://docs.cortex.io/api/rest/scaffolder/retrieve-scaffolder-template

/openapi/cortex_swagger.json get /api/v1/scaffolders/{tagOrId}
Retrieve a Scaffolder template by tag or Cortex ID.



# Update Scaffolder template
Source: https://docs.cortex.io/api/rest/scaffolder/update-scaffolder-template

/openapi/cortex_swagger.json put /api/v1/scaffolders/{tagOrId}
Update a Scaffolder template by tag or Cortex ID.

API key must have the `Configure Scaffolder` permission.



# Scaffolder
Source: https://docs.cortex.io/api/rest/scaffolders



Use these operations to interact with [Scaffolder templates](/streamline/workflows/scaffolder) in Cortex.

### Required permissions

* List or retrieve Scaffolder templates: no additional permission is required.
* Create, update, or delete Scaffolder templates: your API key must have the `Configure Scaffolder` permission.

### Identifying a template

Every Scaffolder template has a `tag`: a stable, human-readable identifier that is unique within your workspace. Tags may contain lowercase letters, numbers, and dashes, and may not start or end with a dash. If you omit the tag when creating a template, Cortex derives one from the template's name. An existing template keeps its tag unless you supply a new one.

Operations that take a `tagOrId` path parameter accept either the tag or the unique, auto-generated Cortex ID. Prefer the tag: it is the identifier you choose, so it stays readable and portable across workspaces.

### Creating and updating

`POST /api/v1/scaffolders` is an upsert. If a template with the same tag already exists, that template is updated instead of a new one being created. Use `PUT /api/v1/scaffolders/{tagOrId}` when you want to update a specific template and have the request fail if it does not exist.

## Operations

> **[List Scaffolder templates](/api/rest/scaffolder/list-scaffolder-templates)**
>
> `GET /api/v1/scaffolders`

> **[Retrieve Scaffolder template](/api/rest/scaffolder/retrieve-scaffolder-template)**
>
> `GET /api/v1/scaffolders/{tagOrId}`

> **[Create or update Scaffolder template](/api/rest/scaffolder/create-or-update-scaffolder-template)**
>
> `POST /api/v1/scaffolders`

> **[Update Scaffolder template](/api/rest/scaffolder/update-scaffolder-template)**
>
> `PUT /api/v1/scaffolders/{tagOrId}`

> **[Delete Scaffolder template](/api/rest/scaffolder/delete-scaffolder-template)**
>
> `DELETE /api/v1/scaffolders/{tagOrId}`


# SCIM
Source: https://docs.cortex.io/api/rest/scim



Use these operations to interact with [SCIM-provisioned users](/configure/settings/managing-users/scim/okta-scim) in Cortex.

### Required permissions

* Your API key must have the `Configure Open ID Connector & SCIM` permission.

### Required SCIM toggles

Each operation is gated on the matching SCIM toggle in your [workspace settings](https://app.getcortexapp.com/settings/scim). A request whose required toggle is off is rejected without taking effect:

| Operation | Required toggle | Response when the toggle is off |
| - | - | - |
| Create user (`POST /scim/v2/Users`) | Enable automatic provisioning of users | `403` |
| Delete user (`DELETE /scim/v2/Users/{id}`) | Enable automatic deprovisioning of users | `403` |
| Get user, Find users (`GET`) | Any SCIM toggle enabled | `403` |
| Update or patch that deactivates a user (`active: false`) | Enable automatic deprovisioning of users | `400` |
| Update or patch that reactivates a user (`active: true`) | Enable automatic provisioning of users | `400` |
| Update or patch of other user attributes | Any SCIM toggle enabled | `400` |

A user created or reactivated while automatic provisioning is enabled is always assigned your workspace's default role.

## Operations

> [!NOTE]
>
> For the filter string in the `Find users` operation, use a value of `userName eq "<email>"` to return a result based on an email value.

> **[Find users](/api/rest/scim/find-users)**
>
> `GET /scim/v2/Users`

> **[Gets a user by id](/api/rest/scim/gets-a-user-by-id)**
>
> `GET /scim/v2/Users/{id}`

> **[Creates a user](/api/rest/scim/creates-a-user)**
>
> `POST /scim/v2/Users`

> **[Updates a user](/api/rest/scim/updates-a-user)**
>
> `PUT /scim/v2/Users/{id}`

> **[Patches a user](/api/rest/scim/patches-a-user)**
>
> `PATCH /scim/v2/Users/{id}`

> **[Deletes a user](/api/rest/scim/deletes-a-user)**
>
> `DELETE /scim/v2/Users/{id}`


# Creates a user
Source: https://docs.cortex.io/api/rest/scim/creates-a-user

/openapi/cortex_swagger.json post /scim/v2/Users
Creates a user based on provided data.



# Deletes a user
Source: https://docs.cortex.io/api/rest/scim/deletes-a-user

/openapi/cortex_swagger.json delete /scim/v2/Users/{id}
Deletes a user based on provided id



# Find users
Source: https://docs.cortex.io/api/rest/scim/find-users

/openapi/cortex_swagger.json get /scim/v2/Users
Fetches users based on provided criteria



# Gets a user by id
Source: https://docs.cortex.io/api/rest/scim/gets-a-user-by-id

/openapi/cortex_swagger.json get /scim/v2/Users/{id}
Gets a user based on provided id



# Patches a user
Source: https://docs.cortex.io/api/rest/scim/patches-a-user

/openapi/cortex_swagger.json patch /scim/v2/Users/{id}
Replaces user details based on provided id and data



# Updates a user
Source: https://docs.cortex.io/api/rest/scim/updates-a-user

/openapi/cortex_swagger.json put /scim/v2/Users/{id}
Updates a user based on provided id and data



# Scorecards
Source: https://docs.cortex.io/api/rest/scorecards



Use these operations to interact with [Scorecards](/standardize/scorecards) in Cortex.

### Required permissions

* Create, read, update, or delete Scorecards: Your API key must have the `Edit Scorecards` permission.
* View Scorecards: Your API key must have the `View Scorecards` permission.
* Approve or revoke Scorecard exemptions: Your API key must have the `Configure Scorecard exemptions` permission.
* List Scorecard exemptions: API keys with the `View Scorecard Exemptions` permission see every exemption. A personal API key without that permission sees only exemptions its user requested in the Cortex UI; exemptions requested through the API are attributed to the API key, not the user.

## Operations

> **[List Scorecards](/api/rest/scorecards/list-scorecards)**
>
> `GET /api/v1/scorecards`

> **[List Scorecard rule exemptions](/api/rest/scorecards/list-scorecard-rule-exemptions)**
>
> `GET /api/v1/scorecards/exemptions`

> **[Retrieve Scorecard scores](/api/rest/scorecards/retrieve-scorecard-scores)**
>
> `GET /api/v1/scorecards/{tag}/scores`

> **[Retrieve entity Scorecard scores](/api/rest/catalog-entities/retrieve-entity-scorecard-scores)**
>
> `GET /api/v1/catalog/{tagOrId}/scorecards`

> **[Retrieve Scorecard](/api/rest/scorecards/retrieve-scorecard)**
>
> `GET /api/v1/scorecards/{tag}`

> **[Retrieve Scorecard descriptor](/api/rest/scorecards/retrieve-scorecard-descriptor)**
>
> `GET /api/v1/scorecards/{tag}/descriptor`

> **[Retrieve Scorecard shields.io badge](/api/rest/scorecards/retrieve-scorecard-shieldsio-badge)**
>
> `GET /api/v1/scorecards/{scorecardTag}/entity/{tagOrId}/badge`

> **[Retrieve next steps for entity in Scorecard](/api/rest/scorecards/retrieve-next-steps-for-entity-in-scorecard)**
>
> `GET /api/v1/scorecards/{tag}/next-steps`

> **[Create or update Scorecard](/api/rest/scorecards/create-or-update-scorecard)**
>
> `POST /api/v1/scorecards/descriptor`

> **[Request Scorecard rule exemption](/api/rest/scorecards/request-scorecard-rule-exemption)**
>
> `POST /api/v1/scorecards/{tag}/entity/{entityTag}/exemption`

> **[Evaluate entity scorecard score](/api/rest/scorecards/evaluate-entity-scorecard-score)**
>
> `POST /api/v1/scorecards/{tag}/entity/{entityTag}/scores`

> **[Revoke Scorecard rule exemption](/api/rest/scorecards/revoke-scorecard-rule-exemption)**
>
> `PUT /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/revoke`

> **[Approve Scorecard rule exemption](/api/rest/scorecards/approve-scorecard-rule-exemption)**
>
> `PUT /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/approve`

> **[Deny Scorecard rule exemption](/api/rest/scorecards/deny-scorecard-rule-exemption)**
>
> `PUT /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/deny`

> **[Delete Scorecard](/api/rest/scorecards/delete-scorecard)**
>
> `DELETE /api/v1/scorecards/{tag}`


# Approve Scorecard rule exemption
Source: https://docs.cortex.io/api/rest/scorecards/approve-scorecard-rule-exemption

/openapi/cortex_swagger.json put /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/approve
Approve Scorecard rule exemption



# Create or update Scorecard
Source: https://docs.cortex.io/api/rest/scorecards/create-or-update-scorecard

/openapi/cortex_swagger.json post /api/v1/scorecards/descriptor
Create or update a Scorecard using the descriptor YAML. The operation is determined by the existence of a Scorecard with the same `tag` as passed in the descriptor.



# Delete Scorecard
Source: https://docs.cortex.io/api/rest/scorecards/delete-scorecard

/openapi/cortex_swagger.json delete /api/v1/scorecards/{tag}



# Deny Scorecard rule exemption
Source: https://docs.cortex.io/api/rest/scorecards/deny-scorecard-rule-exemption

/openapi/cortex_swagger.json put /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/deny
Deny Scorecard rule exemption



# Evaluate entity scorecard score
Source: https://docs.cortex.io/api/rest/scorecards/evaluate-entity-scorecard-score

/openapi/cortex_swagger.json post /api/v1/scorecards/{tag}/entity/{entityTag}/scores
Triggers score evaluation for entity scorecard



# List Scorecard rule exemptions
Source: https://docs.cortex.io/api/rest/scorecards/list-scorecard-rule-exemptions

/openapi/cortex_swagger.json get /api/v1/scorecards/exemptions
List rule exemptions across Scorecards, newest first. Callers with permission to view Scorecard exemptions see every exemption; other users see only the exemptions they requested.



# List Scorecards
Source: https://docs.cortex.io/api/rest/scorecards/list-scorecards

/openapi/cortex_swagger.json get /api/v1/scorecards
Returns scorecards matching optional search criteria. If search criteria is specified we will use search logic, which will not find Scorecards that have yet to be evaluated



# Request Scorecard rule exemption
Source: https://docs.cortex.io/api/rest/scorecards/request-scorecard-rule-exemption

/openapi/cortex_swagger.json post /api/v1/scorecards/{tag}/entity/{entityTag}/exemption
Request Scorecard rule exemption



# Retrieve next steps for entity in Scorecard
Source: https://docs.cortex.io/api/rest/scorecards/retrieve-next-steps-for-entity-in-scorecard

/openapi/cortex_swagger.json get /api/v1/scorecards/{tag}/next-steps



# Retrieve Scorecard
Source: https://docs.cortex.io/api/rest/scorecards/retrieve-scorecard

/openapi/cortex_swagger.json get /api/v1/scorecards/{tag}



# Retrieve Scorecard descriptor
Source: https://docs.cortex.io/api/rest/scorecards/retrieve-scorecard-descriptor

/openapi/cortex_swagger.json get /api/v1/scorecards/{tag}/descriptor



# Retrieve Scorecard scores
Source: https://docs.cortex.io/api/rest/scorecards/retrieve-scorecard-scores

/openapi/cortex_swagger.json get /api/v1/scorecards/{tag}/scores
Returns latest scores for all entities in the Scorecard



# Retrieve Scorecard shields.io badge
Source: https://docs.cortex.io/api/rest/scorecards/retrieve-scorecard-shieldsio-badge

/openapi/cortex_swagger.json get /api/v1/scorecards/{scorecardTag}/entity/{tagOrId}/badge



# Revoke Scorecard rule exemption
Source: https://docs.cortex.io/api/rest/scorecards/revoke-scorecard-rule-exemption

/openapi/cortex_swagger.json put /api/v1/scorecards/{tag}/entity/{entityTag}/exemption/revoke
Revoke Scorecard rule exemption



# Secrets
Source: https://docs.cortex.io/api/rest/secrets



Use these operations to interact with [secrets](/configure/settings/api-keys/secrets) in Cortex.

### Required permissions

* Your API key must have the `Create secrets` permission.

> **[List secrets](/api/rest/secrets/list-secrets)**
>
> `GET /api/v1/secrets`

> **[Retrieve secret](/api/rest/secrets/retrieve-secret)**
>
> `GET /api/v1/secrets/{tagOrId}`

> **[Create secret](/api/rest/secrets/create-secret)**
>
> `POST /api/v1/secrets`

> **[Update secret](/api/rest/secrets/update-secret)**
>
> `PUT /api/v1/secrets/{tagOrId}`

> **[Delete secret](/api/rest/secrets/delete-secret)**
>
> `DELETE /api/v1/secrets/{tagOrId}`


# Create secret
Source: https://docs.cortex.io/api/rest/secrets/create-secret

/openapi/cortex_swagger.json post /api/v1/secrets
API key must have the `Create secrets` permission.



# Delete secret
Source: https://docs.cortex.io/api/rest/secrets/delete-secret

/openapi/cortex_swagger.json delete /api/v1/secrets/{tagOrId}
API key must have the `Create secrets` permission.



# List secrets
Source: https://docs.cortex.io/api/rest/secrets/list-secrets

/openapi/cortex_swagger.json get /api/v1/secrets
API key must have the `Create secrets` permission.



# Retrieve secret
Source: https://docs.cortex.io/api/rest/secrets/retrieve-secret

/openapi/cortex_swagger.json get /api/v1/secrets/{tagOrId}
API key must have the `Create secrets` permission.



# Update secret
Source: https://docs.cortex.io/api/rest/secrets/update-secret

/openapi/cortex_swagger.json put /api/v1/secrets/{tagOrId}
API key must have the `Create secrets` permission.



# Add a single configuration
Source: https://docs.cortex.io/api/rest/semgrep-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/semgrep/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/semgrep-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/semgrep/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/semgrep-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/semgrep/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/semgrep-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/semgrep/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/semgrep-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/semgrep/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/semgrep-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/semgrep/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/semgrep-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/semgrep/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/semgrep-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/semgrep/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/semgrep-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/semgrep/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/semgrep-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/semgrep/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/sentry-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/sentry/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/sentry-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/sentry/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/sentry-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/sentry/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/sentry-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/sentry/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/sentry-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/sentry/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/servicenow-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/servicenow/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/servicenow-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/servicenow/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/servicenow-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/servicenow/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/servicenow-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/servicenow/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/servicenow-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/servicenow/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/servicenow-cloud-observability-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/lightstep/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/servicenow-cloud-observability-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/lightstep/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/servicenow-cloud-observability-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/lightstep/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/servicenow-cloud-observability-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/lightstep/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/servicenow-cloud-observability-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/lightstep/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/snyk-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/snyk/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/snyk-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/snyk/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/snyk-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/snyk/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/snyk-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/snyk/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/snyk-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/snyk/configuration/validate



# Add a single configuration
Source: https://docs.cortex.io/api/rest/sonarqube-api/add-a-single-configuration

/openapi/cortex_swagger.json post /api/v1/sonarqube/configuration



# Add multiple configurations
Source: https://docs.cortex.io/api/rest/sonarqube-api/add-multiple-configurations

/openapi/cortex_swagger.json post /api/v1/sonarqube/configurations



# Delete a configuration
Source: https://docs.cortex.io/api/rest/sonarqube-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/sonarqube/configuration/{alias}



# Delete all configurations
Source: https://docs.cortex.io/api/rest/sonarqube-api/delete-all-configurations

/openapi/cortex_swagger.json delete /api/v1/sonarqube/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/sonarqube-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/sonarqube/configuration/{alias}



# Retrieve configurations
Source: https://docs.cortex.io/api/rest/sonarqube-api/retrieve-configurations

/openapi/cortex_swagger.json get /api/v1/sonarqube/configurations



# Retrieve default configuration
Source: https://docs.cortex.io/api/rest/sonarqube-api/retrieve-default-configuration

/openapi/cortex_swagger.json get /api/v1/sonarqube/default-configuration



# Update a configuration
Source: https://docs.cortex.io/api/rest/sonarqube-api/update-a-configuration

/openapi/cortex_swagger.json put /api/v1/sonarqube/configuration/{alias}
WARNING: Updating aliases for configurations or changing the default configuration could cause entity YAMLs that use this integration to break.



# Validate a configuration
Source: https://docs.cortex.io/api/rest/sonarqube-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/sonarqube/configuration/validate/{alias}



# Validate all configurations
Source: https://docs.cortex.io/api/rest/sonarqube-api/validate-all-configurations

/openapi/cortex_swagger.json post /api/v1/sonarqube/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/splunk-observability-cloud-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/signalfx/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/splunk-observability-cloud-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/signalfx/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/splunk-observability-cloud-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/signalfx/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/splunk-observability-cloud-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/signalfx/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/splunk-observability-cloud-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/signalfx/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/splunk-on-call-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/victorops/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/splunk-on-call-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/victorops/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/splunk-on-call-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/victorops/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/splunk-on-call-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/victorops/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/splunk-on-call-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/victorops/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/sumo-logic-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/sumologic/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/sumo-logic-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/sumologic/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/sumo-logic-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/sumologic/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/sumo-logic-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/sumologic/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/sumo-logic-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/sumologic/configuration/validate



# Team Hierarchies
Source: https://docs.cortex.io/api/rest/team-hierarchies



Use these operations to interact with [team hierarchies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#understanding-hierarchies) in Cortex.

### Required permissions

Your API key must have the `Edit entities` permission.

## Operations

> **[Retrieve team relationships](/api/rest/team-hierarchies/retrieve-team-relationships)**
>
> `GET /api/v1/teams/relationships`

> **[Replace all relationships](/api/rest/team-hierarchies/replace-all-relationships)**
>
> `PUT /api/v1/teams/relationships`


# Replace all relationships
Source: https://docs.cortex.io/api/rest/team-hierarchies/replace-all-relationships

/openapi/cortex_swagger.json put /api/v1/teams/relationships



# Retrieve team relationships
Source: https://docs.cortex.io/api/rest/team-hierarchies/retrieve-team-relationships

/openapi/cortex_swagger.json get /api/v1/teams/relationships



# Teams
Source: https://docs.cortex.io/api/rest/teams



Use these operations to interact with [teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams) in Cortex.

This page lists operations specific to team entities. See [Catalog entities](/api/rest/catalog-entities) for API operations relating to all entity types (including teams).

### Required permissions

Your API key must have the `Edit entities` permission.

## Operations

> **[Retrieve list of teams or team details](/api/rest/teams/retrieve-list-of-teams-or-team-details)**
>
> `GET /api/v1/teams`

> **[Retrieve team details](/api/rest/teams/retrieve-team-details)**
>
> `GET /api/v1/teams/{tagOrId}`

> **[Create a team](/api/rest/teams/create-a-team)**
>
> `POST /api/v1/teams`

> **[\[Cortex managed teams\] Update members in team](/api/rest/teams/\[cortex-managed-teams]-update-members-in-team)**
>
> `PUT /api/v1/teams/{tagOrId}/members`

> **[\[Cortex managed teams\] Update members in team](/api/rest/teams-advanced/\[cortex-managed-teams]-update-members-in-team)**
>
> `PUT /api/v1/teams/members`

> **[Update team metadata](/api/rest/teams-advanced/update-team-metadata)**
>
> `PUT /api/v1/teams`

> **[Update team metadata](/api/rest/teams/update-team-metadata)**
>
> `PUT /api/v1/teams/{tagOrId}`

> **[Archive team](/api/rest/teams/archive-team)**
>
> `PUT /api/v1/teams/{tagOrId}/archive`

> **[Unarchive team](/api/rest/teams/unarchive-team)**
>
> `PUT /api/v1/teams/{tagOrId}/unarchive`

> **[Delete team](/api/rest/teams/delete-team)**
>
> `DELETE /api/v1/teams`

> **[Delete team by tag or ID](/api/rest/teams/delete-team-by-tag-or-id)**
>
> `DELETE /api/v1/teams/{tagOrId}`


# [Cortex managed teams] Update members in team
Source: https://docs.cortex.io/api/rest/teams-advanced/[cortex-managed-teams]-update-members-in-team

/openapi/cortex_swagger.json put /api/v1/teams/members
For teams whose members are not backed by an IdP, use this API to update the team members. Note that it will replace the members in the team with the members defined in this request. 
*Warning:* This API should only be used if your team identifier contains non-alphanumeric characters. Otherwise, use the standard API under `Teams`.



# Update team metadata
Source: https://docs.cortex.io/api/rest/teams-advanced/update-team-metadata

/openapi/cortex_swagger.json put /api/v1/teams
*Warning:* This API should only be used if your team identifier contains non-alphanumeric characters. Otherwise, use the standard API under `Teams`.



# [Cortex managed teams] Update members in team
Source: https://docs.cortex.io/api/rest/teams/[cortex-managed-teams]-update-members-in-team

/openapi/cortex_swagger.json put /api/v1/teams/{tagOrId}/members
For teams whose members are not backed by an IdP, use this API to update the team members. Note that it will replace the members in the team with the members defined in this request.



# Archive team
Source: https://docs.cortex.io/api/rest/teams/archive-team

/openapi/cortex_swagger.json put /api/v1/teams/{tagOrId}/archive



# Create a team
Source: https://docs.cortex.io/api/rest/teams/create-a-team

/openapi/cortex_swagger.json post /api/v1/teams
Team memberships can be backed by an IdP group (from Okta, Azure AD, Google Groups, etc), or can be managed directly through Cortex. Each has a separate request shape, so make sure to select the correct example.



# Delete team
Source: https://docs.cortex.io/api/rest/teams/delete-team

/openapi/cortex_swagger.json delete /api/v1/teams



# Delete team by tag or ID
Source: https://docs.cortex.io/api/rest/teams/delete-team-by-tag-or-id

/openapi/cortex_swagger.json delete /api/v1/teams/{tagOrId}



# Retrieve list of teams or team details
Source: https://docs.cortex.io/api/rest/teams/retrieve-list-of-teams-or-team-details

/openapi/cortex_swagger.json get /api/v1/teams
*Warning:* This API can return team details if you pass in a teamTag query parameter. However, this should only be used to retrieve team details if your team identifier contains non-alphanumeric characters. Otherwise, use the standard API under `Teams` -> `Retrieve team details`. When retrieving team details, the response will be a single team entity instead of a list.

Note: the response objects can also include an `idpGroup` or `cortexTeam` field depending on whether the team contains a `group` or only consists of individually defined `members`.



# Retrieve team details
Source: https://docs.cortex.io/api/rest/teams/retrieve-team-details

/openapi/cortex_swagger.json get /api/v1/teams/{tagOrId}



# Unarchive team
Source: https://docs.cortex.io/api/rest/teams/unarchive-team

/openapi/cortex_swagger.json put /api/v1/teams/{tagOrId}/unarchive



# Update team metadata
Source: https://docs.cortex.io/api/rest/teams/update-team-metadata

/openapi/cortex_swagger.json put /api/v1/teams/{tagOrId}



# Users
Source: https://docs.cortex.io/api/rest/users



Use these operations to list users in your Cortex workspace along with their profile metadata, and to retrieve their role assignments.

### Required permissions

Your API token must have the `View Roles` permission.

> [!NOTE]
>
> Some built-in API key roles (`VIWER`, `USER`, and `MANAGER`) do not include `View Roles`. To call this endpoint with an API key, use an `ADMIN` key or create a new one and assign it a [custom role](/configure/settings/managing-users/permissioning/custom-roles) that grants `View Roles`.

## Operations

> **[List users](/api/rest/users/list-users)**
>
> `GET /api/v1/users`

> **[List user role assignments](/api/rest/users/list-user-role-assignments)**
>
> `GET /api/v1/users/roles`


# List user role assignments
Source: https://docs.cortex.io/api/rest/users/list-user-role-assignments

/openapi/cortex_swagger.json get /api/v1/users/roles
Returns the role assignments for every user in your Cortex tenant, intended for access reviews and access governance reporting. Each entry lists the user along with their assigned built-in (BASIC) and CUSTOM roles. Requires the View Roles permission; assign it to a custom role to issue a least-privilege API key for automated reporting.



# List users
Source: https://docs.cortex.io/api/rest/users/list-users

/openapi/cortex_swagger.json get /api/v1/users
Returns every user in your Cortex tenant along with their profile metadata: name, email, join date, and last active timestamp. Intended for access reviews, compliance, and auditing. Role assignments are available from the separate GET /api/v1/users/roles endpoint. Requires the View Roles permission; assign it to a custom role to issue a least-privilege API key for automated reporting.



# Add a configuration
Source: https://docs.cortex.io/api/rest/veracode-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/veracode/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/veracode-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/veracode/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/veracode-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/veracode/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/veracode-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/veracode/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/veracode-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/veracode/configuration/validate



# Verifications
Source: https://docs.cortex.io/api/rest/verifications



Use these operations to manage [data verification](/configure/settings/entity-settings/verification) in Cortex. A verification period asks entity owners to confirm that their entities' information is accurate.

To see or answer verifications for a single entity, use the verification operations under [Catalog Entities](/api/rest/catalog-entities).

### Required permissions

Your API key must have the `Configure Verification Periods` permission.

To answer verifications for entities you don't own, your API key must have the `Verify any entity` permission.

## Operations

> **[Retrieve verification periods](/api/rest/verifications/retrieve-verification-periods)**
>
> `GET /api/v1/verification-periods`

> **[Create a verification period](/api/rest/verifications/create-a-verification-period)**
>
> `POST /api/v1/verification-periods`

> **[Retrieve a verification period](/api/rest/verifications/retrieve-a-verification-period)**
>
> `GET /api/v1/verification-periods/{periodCid}`

> **[Update a verification period](/api/rest/verifications/update-a-verification-period)**
>
> `PUT /api/v1/verification-periods/{periodCid}`

> **[Delete a verification period](/api/rest/verifications/delete-a-verification-period)**
>
> `DELETE /api/v1/verification-periods/{periodCid}`

> **[Retrieve verifications](/api/rest/verifications/retrieve-verifications)**
>
> `GET /api/v1/verifications`

> **[Verify entities in bulk](/api/rest/verifications/verify-entities-in-bulk)**
>
> `PUT /api/v1/verifications`


# Create a verification period
Source: https://docs.cortex.io/api/rest/verifications/create-a-verification-period

/openapi/cortex_swagger.json post /api/v1/verification-periods
Opens a verification campaign over the entities its scope selects. Every selected entity gets a PENDING verification immediately, except under a cqlQuery scope, which is evaluated in the background, so the counts read zero until it finishes.



# Delete a verification period
Source: https://docs.cortex.io/api/rest/verifications/delete-a-verification-period

/openapi/cortex_swagger.json delete /api/v1/verification-periods/{periodCid}
Closes the period and stops it appearing in reads, along with the verifications recorded against it. The CID is not reissued, so the period cannot be restored through this API.



# Retrieve a verification period
Source: https://docs.cortex.io/api/rest/verifications/retrieve-a-verification-period

/openapi/cortex_swagger.json get /api/v1/verification-periods/{periodCid}



# Retrieve verification periods
Source: https://docs.cortex.io/api/rest/verifications/retrieve-verification-periods

/openapi/cortex_swagger.json get /api/v1/verification-periods
Returns every verification period in the workspace, open or closed, with a count of how many entities are outstanding.



# Retrieve verifications
Source: https://docs.cortex.io/api/rest/verifications/retrieve-verifications

/openapi/cortex_swagger.json get /api/v1/verifications
Returns every verification in the workspace, one entry per entity and verification period, including entities that have not been verified yet. Each entry names the entity it belongs to, and who verified it once someone has.



# Update a verification period
Source: https://docs.cortex.io/api/rest/verifications/update-a-verification-period

/openapi/cortex_swagger.json put /api/v1/verification-periods/{periodCid}
Replaces the period in full; omitted optional fields are cleared rather than left alone. Changing the scope changes who owes a verification: widening it adds PENDING entries, and narrowing it removes entries along with any answer already recorded for them.



# Verify entities in bulk
Source: https://docs.cortex.io/api/rest/verifications/verify-entities-in-bulk

/openapi/cortex_swagger.json put /api/v1/verifications
Answers many entity-and-period pairs in one call. Each entry is answered on its own merits: an entity the caller may not verify is returned under `errors` while the rest are still recorded, because eligibility depends on who owns each entity. Read `errors` on every response -- a 200 does not mean every entry was recorded.



# Add a configuration
Source: https://docs.cortex.io/api/rest/wiz-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/wiz/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/wiz-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/wiz/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/wiz-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/wiz/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/wiz-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/wiz/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/wiz-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/wiz/configuration/validate



# Add a configuration
Source: https://docs.cortex.io/api/rest/workday-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/workday/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/workday-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/workday/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/workday-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/workday/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/workday-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/workday/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/workday-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/workday/configuration/validate



# Workflows
Source: https://docs.cortex.io/api/rest/workflows



Use these operations to interact with [Workflows](/streamline/workflows) in Cortex.

### Required permissions

* View Workflows: Your API key must have the `View Workflows` permission.
* Create or update Workflows: Your API key must have the `Edit Workflows` permission.
* Callback a paused async HTTP block: Your API key must have the `Execute Workflow Runs` permission.
* Run a workflow: Your API key must have the `Execute Workflow Runs` permission.
* View or list workflow runs: Your API key must have the `View workflow runs` permission.

## Operations

> **[List workflows](/api/rest/workflows/list-workflows)**
>
> `GET /api/v1/workflows`

> **[Retrieve workflow](/api/rest/workflows/retrieve-workflow)**
>
> `GET /api/v1/workflows/{tagOrId}`

> **[Create or update workflow](/api/rest/workflows/create-or-update-workflow)**
>
> `POST /api/v1/workflows`

> **[Validates YAML descriptor](/api/rest/workflows/validates-yaml-descriptor)**
>
> `POST /api/v1/workflows/validate`

> **[Update asynchronous HTTP request Workflow block](/api/rest/workflows/update-asynchronous-http-request-workflow-block)**
>
> `POST /api/v1/workflows/{tagOrId}/callback/{callbackId}`

> **[Delete workflow](/api/rest/workflows/delete-workflow)**
>
> `DELETE /api/v1/workflows/{tagOrId}`

> **[Run a workflow](/api/rest/workflows/run-a-workflow)**
>
> `POST /api/v1/workflows/{tagOrId}/runs`

> **[Get workflow run details](/api/rest/workflows/get-workflow-run-details)**
>
> `GET /api/v1/workflows/{tagOrId}/runs/{runId}`

> **[List workflow runs](/api/rest/workflows/list-workflow-runs)**
>
> `GET /api/v1/workflows/runs`


# Create or update workflow
Source: https://docs.cortex.io/api/rest/workflows/create-or-update-workflow

/openapi/cortex_swagger.json post /api/v1/workflows
Create or update new workflow.

API key must have the `Edit workflows` permission.

**Note:** If a workflow with the same tag already exists, it will be updated.



# Delete workflow
Source: https://docs.cortex.io/api/rest/workflows/delete-workflow

/openapi/cortex_swagger.json delete /api/v1/workflows/{tagOrId}
Delete workflow by tag or ID.

API key must have the `Edit workflows` permission.



# Get workflow run details
Source: https://docs.cortex.io/api/rest/workflows/get-workflow-run-details

/openapi/cortex_swagger.json get /api/v1/workflows/{tagOrId}/runs/{runId}
Retrieve details of a specific workflow run.

API key must have the `View workflow runs` permission.



# List workflow runs
Source: https://docs.cortex.io/api/rest/workflows/list-workflow-runs

/openapi/cortex_swagger.json get /api/v1/workflows/runs
List workflow runs based on filters.

API key must have the `View workflow runs` permission.



# List workflows
Source: https://docs.cortex.io/api/rest/workflows/list-workflows

/openapi/cortex_swagger.json get /api/v1/workflows
List workflows.

API key must have the `View workflows` permission.



# Retrieve workflow
Source: https://docs.cortex.io/api/rest/workflows/retrieve-workflow

/openapi/cortex_swagger.json get /api/v1/workflows/{tagOrId}
Retrieve workflow by tag or ID.

API key must have the `View workflows` permission.



# Run a workflow
Source: https://docs.cortex.io/api/rest/workflows/run-a-workflow

/openapi/cortex_swagger.json post /api/v1/workflows/{tagOrId}/runs
Start a new run for a workflow.

API key must have the `Run workflows` permission and the workflow must be runnable via API



# Update asynchronous HTTP request Workflow block
Source: https://docs.cortex.io/api/rest/workflows/update-asynchronous-http-request-workflow-block

/openapi/cortex_swagger.json post /api/v1/workflows/{tagOrId}/callback/{callbackId}
Updates an asynchronous HTTP request Workflow block.

API key must have the `Edit workflow runs` permission.



# Validates YAML descriptor
Source: https://docs.cortex.io/api/rest/workflows/validates-yaml-descriptor

/openapi/cortex_swagger.json post /api/v1/workflows/validate
Validates YAML descriptor.



# Add a configuration
Source: https://docs.cortex.io/api/rest/xmatters-api/add-a-configuration

/openapi/cortex_swagger.json post /api/v1/xmatters/configuration



# Delete a configuration
Source: https://docs.cortex.io/api/rest/xmatters-api/delete-a-configuration

/openapi/cortex_swagger.json delete /api/v1/xmatters/configurations



# Retrieve a configuration
Source: https://docs.cortex.io/api/rest/xmatters-api/retrieve-a-configuration

/openapi/cortex_swagger.json get /api/v1/xmatters/default-configuration



# Update the existing configuration
Source: https://docs.cortex.io/api/rest/xmatters-api/update-the-existing-configuration

/openapi/cortex_swagger.json put /api/v1/xmatters/configuration



# Validate a configuration
Source: https://docs.cortex.io/api/rest/xmatters-api/validate-a-configuration

/openapi/cortex_swagger.json post /api/v1/xmatters/configuration/validate



# Cortex Command Line Interface
Source: https://docs.cortex.io/configure/cortex-command-line-interface



The Cortex Command Line Interface (CLI) is an open‑source, Python‑based command‑line tool for interacting with the [Cortex API](/api). It’s published as the `cortexapps-cli` package on PyPI and maintained in the public [`cortexapps/cli` GitHub repository](https://github.com/cortexapps/cli).

You can use it to call Cortex APIs from scripts (for example, managing catalog entities and performing bulk operations).

### Installation

For installation, usage, and examples, see the [Cortex CLI project in PyPi](https://pypi.org/project/cortexapps-cli/).

### Contributions

For bug reports or other issues, customers are encouraged to open GitHub issues in the [Cortex CLI GitHub repository](https://github.com/cortexapps/cli).


# GitOps for Cortex overview
Source: https://docs.cortex.io/configure/gitops



Cortex supports a [GitOps approach](https://about.gitlab.com/topics/gitops/): instead of managing your catalog in the Cortex UI, you define it in code. Entities, Scorecards, and Workflows are described in descriptor files that live in your Git repository, and Cortex treats those files as the source of truth. This keeps the definition of a system in the same place as the system itself, so your catalog can evolve alongside the code it describes.

The GitOps model offers several benefits:

* Your metadata is version-controlled.
* The repository where your code lives is also the source of truth for information about it.
* You always own the data.
* You can track GitOps changes in GitOps logs.
  * Users must have the `View GitOps Logs` permission.

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy course on [using GitOps](https://academy.cortex.io/courses/gitops-dq31).

## How GitOps works in Cortex

With GitOps, you manage entities, Scorecards, and Workflows with descriptor files that live in your Git repository. An entity descriptor, also called a Cortex YAML, describes an entity in your catalogs. You can keep each entity's descriptor in the repository it describes, or keep all of your definitions together in a single repository.

For Bitbucket, GitHub, and GitLab, Cortex checks for a `cortex.yaml` or `cortex.yml` file anywhere in the default branch, and processes any changes you push to that branch. If you keep all of your definitions in a single repository, Cortex checks for YAML files in the `.cortex` directory.

Cortex finds Scorecards and Workflows by location rather than by filename. Scorecard definitions are read from the `.cortex/scorecards` directory, and Workflow definitions from `.cortex/workflows`. For more information, refer to [Scorecards as code](/standardize/scorecards/scorecards-as-code) and [Workflows as code](/streamline/workflows/workflows-as-code).

> [!TIP]
>
> Cortex recommends storing `cortex.yaml` in the repository root or `basePath`.

If you turn on GitOps-based auto-archival, Cortex archives an entity when its descriptor file is deleted from the repository. Cortex checks for deleted files only, so moving a file doesn't archive the entity. For more information, refer to [Archiving entities automatically](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive).

### **GitOps repository structure**

There are two ways to structure descriptor files in your Git repository.

**Option 1: One `cortex.yaml` per repository**

Each repository contains a `cortex.yaml` file, stored anywhere in the default branch. This is commonly used for a one-to-one mapping, where the repository represents its Cortex entity. It's supported for Bitbucket, GitHub, and GitLab.

For Azure DevOps, the `cortex.yaml` file must be stored at the root of the default branch. To work around this in unique cases, refer to [Using multiple source directories](/configure/gitops/using-gitops-for-cortex#using-multiple-source-directories).

**Option 2: A single repository for all descriptors**

All descriptor YAMLs are stored in one repository, under a `.cortex` directory, in the subdirectories `catalog`, `domains`, `teams`, `scorecards`, and `workflows`. This is supported for all Git providers.

* The `catalog` subdirectory contains services and custom entities.
* The `domains` subdirectory contains domains.
* The `teams` subdirectory contains teams.
* The `scorecards` subdirectory contains Scorecards as code.
* The `workflows` subdirectory contains Workflows as code.

The following example shows a single repository structure. Entity descriptor files are listed under subdirectories for `catalog`, `domains`, `teams`, `scorecards`, and `workflows`:

```
.
└── .cortex
    ├── catalog
    │   ├── database.yml
    │   ├── s3-bucket.yml
    │   ├── auth-service.yml
    │   ├── my-custom-entity.yml
    │   ├── events
    │   │   ├── event-router.yml
    │   │   └── event-archiver.yml
    │   └── payments
    │       ├── payment-api.yml
    │       └── payment-worker.yml
    ├── domains
    │   ├── billing-domain.yml
    │   └── health-domain.yml
    ├── teams
    │   ├── eng-team.yml
    │   └── platform
    │       └── sre-team.yml
    ├── scorecards
    │   ├── production-readiness.yml
    │   └── security.yml
    └── workflows
        ├── onboarding.yml
        └── incident-response.yml
```

Note the following:

* Catalogs cannot be created via GitOps—they can only be defined in the Cortex UI.
* The `catalog` subdirectory contains the YAML files for services and custom entities, regardless of which catalogs the services and custom entities are organized into.
  * For example, you might have created catalogs for `API` and `Library`, and those catalogs might contain services or custom entities. In your Git repository, those entities will appear in the `catalog` subdirectory.
* You can organize YAML files into subdirectories nested under any of the `catalog`, `domains`, `teams`, `scorecards`, and `workflows` subdirectories. Cortex searches each of these recursively, so it finds YAML files at any depth.
  * For example, Cortex finds both `.cortex/catalog/payment-api.yaml` and `.cortex/catalog/events/payment-api.yaml`. Each of these directories must be directly inside `.cortex`, so Cortex doesn't find `.cortex/internal/catalog/payment-api.yaml`.
* Directory names must match exactly. Cortex only searches the `catalog`, `domains`, `teams`, `scorecards`, and `workflows` subdirectories, so similarly named directories such as `.cortex/catalog-pilot/` or `.cortex/catalog_audit/` are ignored.

### Switching from the Cortex UI to GitOps

Cortex's Git integrations parse entity descriptor files automatically, so switching to GitOps is straightforward.

Cortex recommends switching after Cortex has been broadly rolled out to your organization. Give developers a chance to explore Cortex in the UI first, and set a threshold for when your organization is ready to cut over. You don't have to move everything at once, since you can [enable GitOps for each entity type](/configure/gitops/using-gitops-for-cortex#step-1-disable-ui-editing) separately.

### Using both the UI and GitOps

You can mix UI and GitOps management, but the details differ depending on what you're managing.

**Entities**

You can combine the two approaches for an entity type by enabling UI editing and disabling UI importing. New entities are then created through GitOps, but you edit them in the Cortex UI. Cortex doesn't process edits you make through GitOps, so the UI becomes the source of truth for changes:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. In Settings menu, locate the **Workspace** section, then select **GitOps**.
4. From the **Entities** tab, scroll to the **Options by type** section.
5. Toggle on **Enable UI editing for new entity types**.
6. Ensure that **Enable UI importing for new entity types** is toggled off.

**Workflows**

GitOps editing applies only to Workflows that are backed by a YAML file, so you can manage some Workflows through GitOps and others through the UI at the same time. You can still create and delete Workflows in the UI, and you can still edit any Workflow that isn't managed through GitOps.

**Scorecards**

When you enable GitOps editing for Scorecards, you can't edit any Scorecard in the UI, including Scorecards you originally created there. All edits must happen in the YAML file in your Git repository. You can still create and delete Scorecards in the UI.


# GitOps logs
Source: https://docs.cortex.io/configure/gitops/gitops-logs



GitOps logs serve as a valuable tool to understand and monitor changes made specifically through GitOps within your workspace. This feature provides a comprehensive record of changes made via GitOps. This record includes, but is not limited to, which repository a change was made in, the commit details, the number of commits made, the entities affected, and any validation errors that occurred during the change process.

GitOps logs are a great way for you to track changes, identify discrepancies, and gain a holistic view of changes that have been made in your workspace. You can access the GitOps log through the Cortex UI or the public API endpoint.

## Accessing GitOps logs through the Cortex UI

To view GitOps logs, navigate to [**Settings > GitOps** **logs**](https://app.getcortexapp.com/admin/settings/gitops-logs).

![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/gitops-logs.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=5edc4a8e852067b713f6008ae198e2c5)

The GitOps logs page lists events and associated details. Click into a log to view a side panel with more information:

* **Repo:** Name of the repository a change was made in.
* **Timestamp**: When the change was made.
* **Commit sha:** Record of the changes made in associated repository.
* **Branch**: Which branch the change was made in.
* **# of commits:** Total number of commits.
* Under the **Changes** tab, a list of the affected files.
  * You can toggle on **Show only with impacted entities** to view changes that impacted entities.
* Under the **Omitted files** tab, a list of files that were omitted during the commit.
* Under the **Event processing tab**, a list of related events.

![A GitOps log displays relevant information about the activity.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/gitops-log-example.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=afe348d8487a6dbfcc6e457707821dc7)

### Accessing Audit logs through the public API endpoint

GitOps logs can also be accessed through the public API endpoint. Please refer to our [GitOps logs API documentation](/api/rest/gitops-logs) to learn how to retrieve GitOps logs.


# Using GitOps for Cortex
Source: https://docs.cortex.io/configure/gitops/using-gitops-for-cortex



### GitOps considerations

Before getting started, note the following:

* Cortex will only check for files in the repository's default branch, unless [otherwise specified](/configure/gitops/using-gitops-for-cortex#additional-configuration-options-for-gitops). Cortex defaults to `main` if there is no default branch defined.
* Cortex does not delete Scorecards if a corresponding Scorecard YAML is deleted. You can enable automatic archival of entities through GitOps by toggling on **"Enable auto archiving of services"** in [the Entities settings page](https://app.getcortexapp.com/settings/entities). Read more in the [auto-archival docs](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive).
* Domain, team, and Scorecard definitions must be in the `.cortex/domains`, `.cortex/teams`, and `.cortex/scorecards` folders, respectively, or in any subdirectory beneath them.
* The hierarchy of entities in Cortex is based on that hierarchy being defined in the entity's YAML file; Cortex does not set hierarchies or entity relationships based on a YAML file's location in your repository.
  * Learn more about defining a hierarchy in the YAML in the [Team docs](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#adding-a-team-in-yaml-via-gitops), [Domain docs](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains#adding-a-domain-in-yaml-via-gitops), and the [Entity relationship docs](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types/managing-relationships#creating-relationship-connections-via-an-entity-descriptor).
* You can define any number of entities within the same repository.
* GitOps is not designed for high-volume or bulk updates. We recommend keeping batch sizes under 1,000 updates per hour to avoid hitting your Git provider's rate limits. For large-scale entity updates, we recommend using the [Cortex API](/api/rest/catalog-entities).
* The recommended placement for entity descriptor files is in the root of the repository, or in the appropriate `.cortex/catalog` folder.
  * For Bitbucket, Bitbucket Server, GitHub, or GitLab, the descriptor can be located anywhere in the repository as long as the file is named `cortex.yaml` or `cortex.yml`. You can also use a single repository and place descriptor files in the appropriate `.cortex` subdirectory.
  * For Azure DevOps, the `cortex.yaml` file must be stored at the root of the repository of the default branch. It is possible to [work around this](/configure/gitops/using-gitops-for-cortex#using-multiple-source-directories) for unique cases. You can also use a single repository and place descriptor files in the appropriate `.cortex` subdirectory.
  * When using a single repository structure, [as described in this example](/configure/gitops#gitops-repository-structure), the `.cortex` subdirectory only respects `catalog`, `scorecards`, `domains`, `workflows`, and `teams` subdirectories. Do not place an entity's YAML file in the `.cortex` directory unless it is in one of the supported subdirectories.

For additional information on using GitOps to manage Scorecards and Workflows, see [Scorecards as code](/standardize/scorecards/scorecards-as-code) and [Workflows as code](/streamline/workflows/workflows-as-code).

### Step 1: Disable UI editing

When following a GitOps approach, you make changes to entities via their entity descriptor file and sync the changes using a Cortex git integration or programmatically using the [Cortex API](/api/rest/catalog-entities). You must disable UI editing to ensure consistency. If the UI editor is enabled, then changes made via git will not be processed in Cortex.

Confirm that the Cortex UI editor is **disabled** for each entity type you want to use a GitOps approach for:

1. Navigate to the [**GitOps** page in Settings](https://app.getcortexapp.com/settings/gitops).
2. Disable the toggles for UI editing next to services, domains, teams, and other entity types.

To learn about other GitOps settings, see the [GitOps settings documentation](/configure/settings/gitops-settings).

### Step 2: Configure a Git integration

Before you can move to a GitOps approach, Cortex must be integrated with GitHub, GitLab, Azure DevOps, or Bitbucket.

Expand the tabs below for instructions on each provider.

> **Azure DevOps**
>
> **Azure DevOps**
>
> 1. Follow the instructions to [integrate Cortex with Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops).
> 2. Add a webhook for Azure DevOps:
>    1. In Cortex, navigate to [Settings > Azure DevOps](https://app.getcortexapp.com/settings/azuredevops) and validate your Azure DevOps integration.
>    2. Click **Create a new webhook** and copy the unique webhook URL.
>    3. Follow the instructions from Azure on [adding a webhook](https://docs.microsoft.com/en-us/azure/devops/service-hooks/services/webhooks?view=azure-devops).
>       * Set the event type to `Code pushed` and use the URL from the previous step.

> **Bitbucket**
>
> The Bitbucket integration is pre-configured with the ability to use the GitOps approach in Cortex. If you are using Bitbucket Server, you will also need to add a webhook.
>
> 1. In Bitbucket, enable development mode.
>    * You can find this setting in your Bitbucket instance at `https://bitbucket.org//workspace/settings/addon-management/`.
> 2. Follow the instructions to integrate Cortex with Bitbucket.
>    * If you are not using Bitbucket Server, then your integration is complete and you are ready to use GitOps.
> 3. If you are using Bitbucket Server, add a webhook for Bitbucket:
>    1. Navigate to [Settings > Bitbucket](https://app.getcortexapp.com/settings/bitbucket) and validate your configuration.
>    2. Enter a secret token for your Bitbucket Server webhook.
>    3. Click **Create a new webhook** and copy the unique webhook URL.
>    4. Follow the [Bitbucket Server instructions](https://confluence.atlassian.com/bitbucketserver/manage-webhooks-938025878.html) for adding a project-level or repository-level webhook.
>       * Set the event type to `repository push`. Use the secret and the URL from the previous steps.
>
> If you're using a monorepo, see the section below: [Using GitOps for a monorepo in Bitbucket](/configure/gitops/using-gitops-for-cortex#using-gitops-for-a-monorepo-in-bitbucket).

> **GitHub**
>
> The [Cortex app for GitHub](https://github.com/apps/cortex-app) is pre-configured with the ability to use the GitOps approach in Cortex. If you configure the integration using a personal access token, you will also need to add a webhook.
>
> 1. Follow the instructions to [integrate Cortex with GitHub](/ingesting-data-into-cortex/integrations/github).
>    * If you integrated using the Cortex app, then your integration is complete and you are ready to use GitOps.
> 2. If you configured your GitHub integration using a personal access token, create a webhook:
>    1. Enter a secret passphrase for your GitHub webhook in the **Secret** field.
>    2. After saving the passphrase, a unique webhook URL is displayed.
>       * The URL will end with `{alias}` - make sure to replace this with the alias you used when configuring your GitHub integration.
>    3. Follow the instructions from GitHub on [creating a webhook](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks). Cortex recommends adding an [organization webhook](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks#creating-an-organization-webhook), but you can also define the webhook for a [repository in the org](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks#creating-a-repository-webhook).
>       * Set the content type to `application/json`. Use the secret passphrase and the URL from the previous steps.

> **GitLab**
>
> 1. Follow the instructions to [integrate Cortex with GitLab](/ingesting-data-into-cortex/integrations/gitlab).
> 2. Create a webhook:
>    1. In the [GitLab settings](https://app.getcortexapp.com/settings/gitlab) in Cortex, click **Create a new token**.
>       * The token and the webhook URL will be displayed.
>    2. In GitLab, [create a system hook](https://docs.gitlab.com/ee/administration/system_hooks.html#create-a-system-hook)(recommended) or a [project hook](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#configure-a-webhook).
>       * Enable `Push events` for the webhook. Use the token and the webhook URL from the previous steps.

Once GitOps is enabled, Cortex will detect push events in your repositories. For the first webhook for a given repository, Cortex looks for the `cortex.yaml` files and processes them. For subsequent webhooks, Cortex only processes files with a change in the webhook event. A maximum of 3,000 changed files will be reported per commit.

**Additional configuration**

Cortex's out-of-the-box GitOps configuration suits most common use cases, but you may have a scenario that requires additional configuration, such as a monorepo in Bitbucket, a repository with different projects in multiple branches, a need to restrict which repositories to import from, and more. See [Additional configuration options for GitOps](/configure/gitops/using-gitops-for-cortex#additional-configuration-options-for-gitops) below for more information.

**Multi-account configuration**

It is possible to configure multiple account integrations with Cortex for each of the git integrations. If you're creating or editing a `cortex.yaml` in the non-default configuration, you must reference the alias you used for that integration when you configured it.

For example, if you added a second GitHub configuration called `non-default-example`, you would define the following block in the entity descriptor:

```yaml theme={null}
x-cortex-git:
  repository: organization/non-default-example-repo
  alias: non-default-example
```

> [!WARNING]
>
> If you do not define the `alias`, Cortex will use the default configuration when processing changes made to the `cortex.yaml` file. If a repository is not included in the default configuration, changes will not be processed via GitOps.

### Step 3: Get started with managing entities

After completing your GitOps configuration, you can start managing entities via GitOps.

Before following these steps:

* We recommend reviewing the [Entities documentation](/ingesting-data-into-cortex/entities-overview/entities) to understand the basics about working with entities in Cortex.

> **Create an entity**
>
> **Create an entity**
>
> To create a new entity from a new repository:
>
> 1. Create a repository in your git account.
> 2. Create a new `cortex.yaml` or `cortex.yml` file in the repo you just created, including the entity's details.
> 3. Commit and push your changes.
>
> The entity will now exist in your repository and in the Cortex UI.
>
> For example:
>
> ```yaml theme={null}
> openapi: 3.0.1
> info:
>   title: Example Entity
>   x-cortex-git:
>     github:
>       repository: org/repo
>   x-cortex-tag: example-entity
>   x-cortex-owners:
>     - name: test-team
>       type: group
>       provider: CORTEX
>   x-cortex-type: service
>   x-cortex-custom-metadata:
>     test: 123
> ```
>
> > [!TIP]
> >
> > The GitHub app has a built-in linter, so if an entity descriptor file is invalid, the GitHub app will comment on the pull request with outstanding issues.
>
> Learn more about creating entity YAMLs in [Defining entities via YAML file](/ingesting-data-into-cortex/entities-overview/entities/yaml).
>
> **Verify that your entity was created**
>
> To verify that the new entity was created:
>
> * View the [GitOps logs page in Cortex](https://app.getcortexapp.com/settings/gitops-logs), which displays all changes made in your Cortex workspace. If your entity creation was successful, you should expect to see it at the top of the list.
>   * You must have the `View GitOps logs` permission to view this page.
>
> * Search the [**Catalogs > All entities** page](https://app.getcortexapp.com/admin/entities) for the new entity's name or tag. If your creation was successful, it will appear in the search results.
>
> > [!NOTE]
> >
> > If you do not see your changes, refresh the browser window where you are logged in to Cortex.

> **Edit an entity**
>
> **Edit an entity**
>
> Any changes you commit to an entity will appear under **Recent activity** on the entity page overview.
>
> 1. Navigate to the YAML file for an entity.
> 2. Add data to the entity
> 3. Commit and push your changes.
>
> The edits now exist in your repository and on the entity in the Cortex UI. On the entity details page, the update will appear under **Recent activity**.
>
> > [!WARNING]
> >
> > If UI editing is **enabled** for an entity type, any changes you commit to that entity will **not** be reflected in Cortex.
>
> **Verify that an entity was edited**
>
> To verify that an entity was edited:
>
> * View the [GitOps logs page in Cortex](https://app.getcortexapp.com/settings/gitops-logs), which displays all changes made in your Cortex workspace. If your entity edit was successful, you should expect to see it at the top of the list.
>   * You must have the `View GitOps logs` permission to view this page.
> * Search the [**Catalogs > All entities** page](https://app.getcortexapp.com/admin/entities) for the entity's name or tag. If your edit was successful, it will appear in the search results.
>
> If UI editing is enabled and UI importing is disabled, changes will display in GitOps logs and under an entity's recent activity, but those changes will not process. The **Entities** column in GitOps logs will show `0 entities` if this is the case. When you open the commit, the panel will show **No changes processed**, and the `cortex.yaml` file will appear under **Omitted files**.

> [!TIP]
>
> In the Cortex UI on an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details), entities created or updated via GitOps will display the file path of the entity's YAML file and a preview of the last GitOps log. You must have the `View GitOps logs` permission.

## Additional configuration options for GitOps

Cortex's standard GitOps configuration suits most common use cases:

* Single or many projects per repo
* Only one branch needs to be processed for `cortex.yaml`
* The `cortex.yaml` file is in the default or `main` branch

However, there may be scenarios that require special setups, such as the following examples:

* **Monorepos in Bitbucket:** Multiple projects in a single repo, split into subfolders.
* **Branches:** Non-main or non-default branches, or different projects in multiple branches.

See the sections below for more information about special configurations.

### Restrict which repositories to import from

By default, Cortex will check all repositories for services, domains, teams, and other entity types. It is possible to restrict which repositories entities are imported from:

1. Navigate to the [**Settings > GitOps**](https://app.getcortexapp.com/settings/gitops).
2. Under **Options by entity type**, find the dropdown labeled **Entity GitOps repository allowlist for new entity types**.
3. Select the repositories you want to import from.

When one or more repositories are selected for a given entity type, Cortex will only check those repos for changes to the `cortex.yaml` file.

> [!WARNING]
>
> If you make changes in a repo that is not designated on the allowlist, Cortex will not process those changes.

### Using GitOps for a monorepo in Bitbucket

Using GitOps with a monorepo - one Git repository with multiple entities - is supported out-of-the-box for Azure DevOps, GitHub, and GitLab when you use the `basepath` field to specify the subdirectory in the entity descriptor (see an example of this in the docs for [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops#editing-the-entity-descriptor), [GitHub](/ingesting-data-into-cortex/integrations/github#entity-descriptor), and [GitLab](/ingesting-data-into-cortex/integrations/gitlab#editing-the-entity-descriptor)).

When using a monorepo with Bitbucket, you must use the `cortex-properties.yaml` file:

* The file is automatically processed, just like the entity descriptor.
* It should live in the `default` branch for the repo, **regardless of which branches it states Cortex should use to find entity descriptor files**.
* When using the `cortex-properties.yaml file`, the `basePath` may not function as expected if you have service code elsewhere in your repository.

Note that this file should only be used for custom workflows, such as using monorepos in Bitbucket or using a non-default branch as the home for your entity descriptor files.

### Using GitOps in a non-default branch

You can configure Cortex to automatically process `cortex.yaml` files in non-standard branches, multiple branches, or both.

Consider the following example scenario:

* You have a project where `main` is protected and is the default branch.
* You want to include `cortex.yaml` in the `develop` branch.
* You also have a separate project version in a `staging` branch with its own `cortex.yaml` file.

To represent this:

* Add a `cortex-properties.yaml` file in the default branch of your repo
* Define the `branches` field with a list of branches to process.
  * The default branch **must** be explicitly defined if you are using an advanced configuration and you want Cortex to search for a `cortex.yaml` file in the default branch.

```yaml theme={null}
branches:
  - main
  - develop
  - staging
```

If your `cortex-properties.yaml` file does not contain a `branches` field, Cortex will continue to process the `default` branch.

Cortex will process the most recently modified `cortex.yaml` file across all branches listed in the `cortex-properties.yaml` file.

> [!NOTE]
>
> When using the `branches` field in your `cortex-properties.yaml` file, make sure to include the default branch if you want Cortex to continue looking for a `cortex.yaml` file in the default branch.

### Using multiple source directories

When using Azure DevOps for GitOps, you can configure Cortex to look for `cortex.yaml` files in multiple subdirectories.

Consider the following example scenario:

* You have a monorepo structure where all projects live in a single repository.
* Each project lives in a subdirectory in the main repository (`project1/`, `project2/`, etc.).
* Each project has its own `cortex.yaml` file.

To represent this:

* Add a `src-dirs` field in a `cortex-properties.yaml` file at the root of the repository, containing a list of directories to process.

```yaml theme={null}
src-dirs:
  - project1
  - project2
```

Cortex will still process any `cortex.yaml` file found in the root of the repository.

## Troubleshooting and FAQ

See frequently asked questions below.

> **Conflicts between UI editing, GitOps, and the Cortex API**
>
> If GitOps has previously been enabled, but UI editing is temporarily turned on, any changes made in Cortex to applicable entities will not be reflected in Git. When the file is next changed through your Git provider, it will override changes made in the UI.
>
> The last received change in a `cortex.yaml` file will override previous changes, whether it originated from the create/update entity API or a push from your Git provider. Changes are not appended and the last submitted entire file takes precedence, so fields omitted in `cortex.yaml` will be removed.

> **Will my cortex.yaml file be picked up immediately?**
>
> If you already have a `cortex.yaml` file when you set up GitOps, Cortex will automatically process it. However, the file **will not** be processed until UI editing is **disabled**.

> **The entity I created appears in GitOps logs, but displays 0 entities 0 scorecards in the Entities column.**
>
> First, use the [YAML linter](https://app.getcortexapp.com/admin/yaml-linter) to validate your `cortex.yaml` file. Then, confirm GitOps settings are configured correctly:
>
> * Make sure [UI editing is **disabled**](/configure/gitops/using-gitops-for-cortex#step-1-disable-ui-editing) for the entity type that you're trying to create.
> * Check repositories in the GitOps [repository allowlist](/configure/gitops/using-gitops-for-cortex#restrict-which-repositories-to-import-from). If there are repositories selected for the entity type you're working with, confirm that you're working from an allowed repo.

> **My entities were syncing from a directory under .cortex, and now they aren't.**
>
> Cortex matches directory names exactly. It doesn't scan similarly named directories such as `.cortex/catalog-pilot/`, `.cortex/catalog_v2/`, or `.cortex/teams-old/`.
>
> If files in one of these directories were being discovered before, move them into `catalog`, `domains`, `teams`, `scorecards`, or `workflows`, or into a subdirectory beneath one of them. Cortex doesn't remove entities that were already created from those directories. They stop receiving updates, and you can archive or delete them when you're ready.


# Workspace Settings
Source: https://docs.cortex.io/configure/settings



Customize your Cortex workspace, [manage users](/configure/settings/managing-users), view [audit logs](/configure/settings/audit-logs), and more in Settings.

To access Settings, click your avatar in the lower left corner, then click **Settings**.

* If you have the `Edit settings` permission, you will see the general settings configuration page. If you do not have this permission, you will see your notification subscriptions page.

![Click your avatar, then click Settings.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/settings-link.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=bb7bf20004405a5cf176a55ca60eb977)

## Types of workspace settings

In Cortex, you can configure personal preferences, workspace look and feel, entity and feature settings, authentication and access, identity mappings, and integrations. The required permissions differ depending on which settings you need to access. See the [permissions included in default roles](/configure/settings/managing-users/permissioning#default-roles) and the [permissions you can add to custom roles](/configure/settings/managing-users/permissioning/custom-roles#available-permissions-for-custom-roles).

### Personal preferences

Configure your own access tokens, group subscriptions, identity mappings, and notifications.

![Access personal preferences in the Settings.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/personal-preferences.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=0aab18f322c3b3fac2b8901e7db6e4e3)

### Workspace

* View billing information
* Configure the [look and feel for the workspace](/configure/settings/workspace-customization), plugins, and Eng Intelligence
* Configure Eng Intelligence [custom metrics](/improve/eng-intelligence/custom-metrics#define-custom-metrics-and-add-metric-data), [issue groupings for Jira metrics](/improve/eng-intelligence/eng-intelligence#issues-completed), and [user labeling](/improve/eng-intelligence#create-and-manage-user-labels-for-grouping)
* Configure entity settings, including auto import (for [AWS](/ingesting-data-into-cortex/integrations/aws#enable-automatic-import-of-aws-entities), [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources#enable-automatic-discovery-of-azure-resource-entities), and [Google](/ingesting-data-into-cortex/integrations/google#enable-automatic-import-of-google-entities)), [auto-archival](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive), team member role sync, and [data verification](/configure/settings/entity-settings/verification)
* Configure [GitOps settings](/configure/gitops), including processing, linter checks, and whether to enable or disable UI editing per entity type
* Adjust [notification](/configure/settings/notifications) options for the workspace
* Change the default [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph#adjust-appearance-settings) view
* Configure [Scorecard](/standardize/scorecards) preferences and evaluation window, review rule exemptions, and see all outdated CQL expressions being used
*

```
<div align="left"><figure><img src="../../.gitbook/assets/workspace-settings.jpg" alt="Manage workspace customization in Workspace settings." width="563"><figcaption></figcaption></figure></div>
```

### Authentication and access

* View a list of [API keys](/configure/settings/api-keys) and [secrets](/configure/settings/api-keys/secrets), create API keys and secrets
* View Cortex workspace [audit logs](/configure/settings/audit-logs), [GitOps audit logs](/configure/gitops/gitops-logs), and [notification logs](/configure/settings/notifications/logs) from the last 30 days
* View breaking API change notifications
  * This feature is available in beta. Please contact your Cortex Customer Success Manager for access.
* Configure the [IP allowlist](/configure/settings/ip-allowlist)
* Configure [OpenID Connect applications](/configure/settings/managing-users/configuring-sso) and [SCIM settings](/configure/settings/managing-users/scim/okta-scim)
* Configure [roles and permissions](/configure/settings/managing-users/permissioning)

![Access authentication settings in the Settings page.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/auth-settings.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=ac8b0e7c0e6041cd01aa3d967a101602)

### Identity mappings

Configure [identity mappings](/configure/settings/managing-users/identity-mapping) for your configured integrations.

![Configure identity mappings in the Settings page.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/identity-mappings-settings.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=9de7a2ca838b6419dfd271914c131764)

### Integrations

Configure your [third-party integrations](/ingesting-data-into-cortex/integrations).

![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/integration-settings-page.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=01a7463b557388b90fc56883332116dd)


# API keys, secrets, and tokens
Source: https://docs.cortex.io/configure/settings/api-keys



Cortex provides three credential types to help you manage authentication and access securely. API keys grant programmatic access to Cortex data and integrations, [secrets](/configure/settings/api-keys/secrets) store sensitive credentials for use across your configurations, and [personal access tokens](/configure/settings/api-keys/personal-tokens) allow individual users to interact with the Cortex API under their own permissions. Using the right credential type for each use case helps minimize risk and maintain the principle of least privilege.

## Managing API keys

API keys enable programmatic access to your Cortex data, from high-level Scorecard stats to detailed information about specific entities in your catalogs. You can manage API keys through the Cortex UI or via the API. Both require the `Edit API keys` permission.

For a full reference of available API key endpoints, see [API Keys](/api/rest/api-keys).

## Creating an API key in Cortex

Follow the steps below to create an API key in Cortex. Note that you must have the `Edit API keys` permission to create or delete API keys, or to edit their name or description.

> [!NOTE]
>
> Assign only the permissions necessary for the API key's intended purpose. API keys support the same [default permissions](/configure/settings/managing-users/permissioning) and [custom roles](/configure/settings/managing-users/permissioning/custom-roles) available to individual users.

There is no limit to the number of API keys you can create!

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the *Security and access* section, then select **API keys**.
4. Click **Create new key** in the upper-right corner.
5. Do the following:

   1. Below **Name**, enter a name for the key (required).
   2. Below **Description**, enter a brief overview of the key.

   > [!NOTE]
   >
   > As a best practice, include details about what the API key is used for. This helps ensure that other users do not accidentally delete an important API key.

   3. From the *Role* drop-down menu, select the permissions level for the key (required).
   4. Below **Expiration date**, set an expiration date for the key. The key automatically expires at the end of the chosen day based on the current time zone.
6. Click **Create API key**. The key is created and displayed. Copy the key and store it in a secure location, as it will not be displayed again after you refresh or navigate away from the page.

   > [!NOTE]
   >
   > The key is only displayed once! Copy it and store it in a secure location before navigating away from this page. Cortex only retains the last 4 digits of the key for reference; the remainder is encrypted and cannot be recovered.

## Modifying an API key

You can update the name and description of an API key after it has been created.

> [!NOTE]
>
> The key value itself cannot be modified. To change it, delete the existing key and create a new one. Learn more about [best practices for API key rotation below](/configure/settings/api-keys#best-practices-for-api-key-rotation).

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the *Security and access* section, then select **API keys**.
4. Locate the API key you want to edit, then click the **pencil icon** next to that key.
5. Do any or all of the following:
   * Below **Name**, enter a new name.
   * Below **Description**, enter a new or updated overview of the key.
   * Below **Expiration date**, enter a new or updated expiration date.
6. Click **Save**. The key is updated.

## Requiring an expiration date for API keys

Cortex requires all new API keys to have an expiration date. For existing keys, an expiration date is optional.

> [!NOTE]
>
> API key expiration is enforced globally. Once enabled, all newly created API keys in your Cortex workspace are subject to the specified maximum lifetime.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the *Security and access* section, then select **Security policy**.
4. Toggle on **Require API token expiration**.
5. Below *Maximum lifetime for new tokens*, enter the number of days after which new tokens will expire.

   > [!NOTE]
   >
   > Maximum lifetime cannot exceed 400 days.
6. Click **Save**. API keys created going forward will expire after the maximum lifetime you specified in step 5.

## API key and personal access token expiration notifications

Keys and tokens with an expiration date trigger notifications before they expire. Recipients receive a reminder seven (7) days before the expiration date, followed by a second reminder the day before, giving time to rotate or renew before it becomes invalid.

Who receives these notifications depends on the type of credential:

* **API keys:** Notifications go to all workspace users with the `Edit settings` permission (effectively, workspace admins). The notification states that one or more API keys will expire and links to the API keys settings page.
* **Personal access tokens:** Notifications go only to the individual user who owns the token. The notification states that one or more personal access tokens will expire and links to the personal access tokens settings page.

Both notification types follow the same timing: 7 days before expiration, and 1 day before expiration.


# Personal tokens
Source: https://docs.cortex.io/configure/settings/api-keys/personal-tokens



Personal access tokens provide Cortex users with a way to access data and edit entities and Scorecards.

Similar to API keys, you can use personal tokens to make calls through API endpoints. **Permissions for personal tokens directly mirror your own user** [**permissions**](/configure/settings/managing-users/permissioning).
All users, including users with the `Viewer` role, can create a personal token.

> [!WARNING]
>
> If you attempt to make a call through endpoints not within your user permissions, this will result in a 403 error.

**To create a personal access token**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the *Preferences* section, then select **My access tokens**.
4. In the upper-right corner, click **Create new token**.
5. Do the following:

   1. Below **Name**, enter a name for the token (required).
   2. Below **Description**, enter a brief overview of the token.

   > [!NOTE]
   >
   > As a best practice, include details about what the token is used for. If you add multiple tokens, the description can help clearly identify and differentiate between the tokens listed on this page.

   3\. Below **Expiration date**, set an expiration date for the token. The key automatically expires at the end of the chosen day based on the current time zone.
6. Click **Create token**.

   The personal access token is created.


# Secrets
Source: https://docs.cortex.io/configure/settings/api-keys/secrets



[Secrets](https://app.getcortexapp.com/admin/settings/secrets) are encrypted variables you can store in Cortex for your workspace environment. They can be accessed for use in various Cortex features, such as:

* [Plugin proxies](/streamline/plugins/creating-plugins/plugin-proxy), to allow secure authenticated access to various third-party APIs.
* [Workflows](/streamline/workflows), when configuring an HTTP Request action.

Secrets are securely encrypted and stored in Cortex’s database, and the secret values are not accessible via public or private APIs once saved.

### Accessing secrets

Secrets can only be accessed programmatically through features in Cortex. Secrets are generally referenced by configuration of the relevant feature through a templated string that uses Mustache-like syntax to reference the secret by tag. For instance, a plugin proxy header can reference a secret similar to the following example:

```json theme={null}
{
  "name": "Authorization",
  "value": "Bearer {{ secrets.my_secret }}"
}
```

## Managing secrets

### Create a secret

Secrets can be created in the Cortex UI or via the Cortex API. Your user or API token must have the `Create secrets` permission.

> **Cortex UI**
>
> For convenience, secrets can be optionally named in a human-friendly manner. For programmatic access, secrets must have a unique tag that contains only alphanumeric characters and dashes.
>
> To create a secret:
>
> 1. Go to [**Settings > Secrets**](https://app.getcortexapp.com/admin/settings/secrets) then click **Add secret**.
>
>    ![](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/add-secret.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=d628de9c5eef35ba98b57496e5690ea6)
>
> 2. In the modal, configure your secret:
>
> * **Name**: Enter a user-friendly name.
> * **Identifier**: Enter a unique identifier for the secret, made of letters, digits, and underscores.
>   * Note that tags cannot be edited after they are created.
> * **Secret value**: Enter your secret value.
>   * This is usually the value of an API token or some other value from a third-party integration.
>
> 3. Click **Add secret**.

> **API**
>
> It is possible to create, read, update, and delete secrets via the Cortex API. See the [API documentation](/api/rest/secrets) for more information.

### Edit secrets in the Cortex UI

You must have the `Create secrets` permission to edit secrets.

To edit a secret:

1. Go to [**Settings > Secrets**](https://app.getcortexapp.com/admin/settings/secrets) then click the pencil icon next to the secret you want to edit.
2. In the modal, edit the secret name.
   * We recommend creating a user-friendly name for the secret.
3. Click **Save**.


# Audit logs
Source: https://docs.cortex.io/configure/settings/audit-logs



Audit logs document a detailed record of actions taken in your workspace, letting you track who made a change, when it happened, and what was altered. This includes entity edits, integration configuration changes, API key activity, and updates to custom roles and their assigned permissions.

Use audit logs to investigate changes, identify discrepancies, and get a holistic view of activity across your workspace. You can access them through the Cortex UI or the [public API](/api/rest/audit-logs).

## Viewing audit logs in the Cortex UI

Users with the `View Audit Logs` permission can view audit logs via the Cortex UI.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Logging** section, then click **Audit logs**.\


   ![The audit logs page in the Cortex UI.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/audit-logs.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=0973330cc48f47099f91be4ff22fe1ff)

The audit logs page displays a list of user activities. Each log entry includes the following columns:

* **Actor** - Who or what performed the action:
  * **A user** - The user who made the change in Cortex.
  * **An API key** - The change was made with an API key. The entry shows the name of the key.
  * **Cortex** - Cortex made the change automatically on your behalf, such as syncing data from an integration or applying an update through GitOps. See [Cortex-initiated actions](#cortex-initiated-actions) for details.
* **Action type** - The action performed (created, deleted, or updated).
* **Object type** - The type of object that changed. See the full list of object types below.
* **Object identifier** - The unique identifier of the object.
* **Date** - When the action occurred.

> [!WARNING]
>
> Note: Audit log entries only capture successful, applied changes. If an action fails, is denied by authorization, or doesn't result in an actual change (before and after states match), no entry is created.

To view more information about a particular action, click its row:

![A highlighted action on the audit logs page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/audit-logs-row.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=401d99eff632f7bb7847af1baeb13160)

A side panel opens with details about the action, including diff changes and the date and time of the action:

![The side panel provides further information about the action.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202026-05-22%20at%2010.13.17%E2%80%AFAM.png)

### Filtering audit logs

On the audit logs page, you can narrow your search by using the filter and date range options.

![The filter icons on the audit logs page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/audit-logs-filters.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=a127d4beddaca28811529db1603cccea)

To narrow the scope of your search, click **Filter**. You can filter by:

* API key identifier
* Action type
* Actor IP address
* Actor email
* Actor type
* Anonymous request type
* Entity
* Object type

To change the date range, click **Last 7 days**. You can filter by:

* Last 7 days
* Last 14 days
* Last 30 days
* Custom date range

#### How filters work

You can apply multiple filters at once, and select one or more criteria within each filter.

Within a single filter, multiple selections are combined with `OR`. Across different filters, selections are combined with `AND`.

**Example**

* Selecting `CREATE` for 'action type' and `SCORECARD` for 'object type' produces the query `create AND scorecard`.
* Selecting both `CREATE` and `DELETE` for 'action type' and `SCORECARD` for 'object type' produces `(create OR delete) AND scorecard`, which returns all Scorecards created or deleted within the selected timeframe.

## **Audit log reference**

### **Object types**

The following object types are included in audit logs:

| Object type | Notes |
| - | - |
| `ACCOUNT_FLAG` | |
| `ALLOW_LIST_ENTRY` | |
| `API_KEY` | |
| `CATALOG` | |
| `CATALOG_FILTER` | |
| `CORTEX_USER` | |
| `CUSTOM_ROLE` | Covers changes to the role itself (name, description) |
| `CUSTOM_ROLE_PERMISSIONS` |  • Covers changes to the permissions granted by that role • Re-saving a custom role with no effective permission change does not produce a `CUSTOM_ROLE_PERMISSIONS` entry |
| `DOMAIN` | |
| `ENTITY_TYPE_DEFINITION` | |
| `INITIATIVE` | |
| `OAUTH_CONFIGURATION` | |
| `OPENAPI_DEFINITION` | |
| `PERSONAL_API_KEY` | |
| `RESOURCE` | |
| `SCORECARD` | |
| `SECRET` | |
| `SECRET_GROUP` | |
| `SERVICE` | |
| `TEAM` | |
| `WORKFLOW` | |
| Integrations |  • Configuration, e.g. `OKTA_CONFIGURATION` • OAuth configuration, e.g. `BITBUCKET_OAUTH_CONFIGURATION` • OAuth registration, e.g. `JIRA_OAUTH_REGISTRATION` • On-prem configuration, e.g. `JIRA_ONPREM_CONFIGURATION` • On-prem webhook secret, e.g. `BITBUCKET_ONPREM_WEBHOOK_SECRET` • Personal configuration, e.g. `BITBUCKET_PERSONAL_CONFIGURATION` • SAST configuration, e.g. `MEND_SAST_CONFIGURATION`Unique GitHub types: • `GITHUB_APP_CONFIGURATION` • `GITHUB_APP_INSTALLATION` • `GITHUB_PERSONAL_TOKEN` • `GITHUB_WEBHOOK_SECRET` |

### **Actors**

The following actor identifiers are included in audit logs:

| Identifier | Notes |
| - | - |
| **Actor Types** |  • `ANONYMOUS` • `API_KEY` • `BACKSTAGE` • `OAUTH2` • `PERSONAL_API_KEY` |
| **API Key Identifiers** | When filtering by this field, enter API key names or the last 4 characters of an API key. |
| **Emails** | When filtering by this field, the email address must be an exact match to the user's email. |
| **IP Addresses** | |
| **Anonymous Request Types** |  • `API_KEY_ENTITY` • `BRAIN_AI` • `CUSTOM_INTEGRATION` • `SCORECARD_BADGES` • `SLACK_COMMAND` • Integration webhooks, e.g. `ATLASSION_WEBHOOK` |

#### Cortex-initiated actions

When Cortex makes a change automatically, the **Actor** column shows **Cortex** on the first line and the source of the change on the second line. Each source maps to something configured in your workspace, so you can tell why the change happened.

* **Integration sync** - Cortex refreshed data from an integration you connected. This includes discovering cloud resources from Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP), discovering entities from Git and observability providers, and mapping identities from a connected user directory.
* **GitOps** - Cortex applied an entity descriptor from your repository.
* **Workflow** - A Workflow that Cortex ran on your behalf made the change.
* **Scaffolder** - A Scaffolder template run created or changed the entity.
* **System** - A change Cortex made that doesn't fall under one of the categories above.

To see what kind of object changed (for example, a cloud resource or an incident), check the **Object type** column.


# Entity settings
Source: https://docs.cortex.io/configure/settings/entity-settings



Admins, or users with the `Configure settings` permission, can adjust system-wide settings for entities under [**Settings > Entities**](https://app.getcortexapp.com/admin/settings/entities/general). There are general settings that apply to all entity types, and settings specific to teams and domains.

![](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/entity-settings-page.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=1851be882e93bd0b61ee34331ff7aee2)

## General entity settings

* **Enable changing entity type**
  * Allow whether or not existing entities can change their type. For example, changing the type of an entity from service to domain. Note that this could result in broken YAMLs with dependencies and hierarchies and can only be updated via the entity YAML.
* **Auto import from AWS, Azure, and Google Cloud**
  * Enable automatic import of discovered entities of known types from [AWS](/ingesting-data-into-cortex/integrations/aws), [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources), and [Google](/ingesting-data-into-cortex/integrations/google). This will import all Lambda functions and ECS services as distinct entity types.
* **Always append suffixed to resource discovery**
  * Appends the type to the auto-generated tag for imported entities
* **Auto-archiving entities by type**
  * Configure automatic archival for entities that are no longer detected in your integrations or whose YAML files have been deleted. Learn more in [Auto archiving entities](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive).
* **Data verification**
  * Set data verification policies in Cortex to make sure that entities in your Cortex workspace are accurate. Learn more in [Data verification](/configure/settings/entity-settings/verification).

## Team entity settings

* **Enabled identity providers**
  * In this section, you can select which identity providers will be used to sync team and team memberships into Cortex.
  * When [importing teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#importing-teams-from-an-integration), you will see the option to import from the enabled IdPs listed on this page.
* **Auto import teams**
  * When enabled, any discovered teams and team relationships from [Workday ](/ingesting-data-into-cortex/integrations/workday)are automatically imported.
  * In order for teams to be imported, Workday needs to be enabled under the **Enabled identity providers** section on this settings page. The Workday report must include the `managerEmail` field in order for team relationships to be auto imported.
* **Team ownership entity editing**
  * When enabled, entities can only be edited by the team that own them. You can also configure entity edit access for specific individuals on a team. Read more about this feature in [Team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing).
* **Give edit access to all team members**
  * When enabled, all team members will be granted edit access to the entities owned by their team. You will not be able to turn off edit access for individual members in your teams configuration when this is enabled.

### Team member roles tab

* **Sync team roles from identity providers**
  * When enabled, Cortex will automatically assign roles to team members based on your enabled identity providers. Leave this option disabled to assign team roles manually.
* **Roles**
  * You can define the set of roles that can be assigned to team members. Learn more in [Adding team member roles](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles#adding-team-member-roles).

## Domain entity settings

* **Enable auto import of domains**
  * Automatically import any discovered domains and domain relationships from [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow).
  * You must have the ServiceNow integration configured.


# Data verification
Source: https://docs.cortex.io/configure/settings/entity-settings/verification



You can set data verification policies in Cortex to make sure that entities in your Cortex workspace are accurate. Verifications prompt owners and responsible users to check certain information, as determined by the person who created the verification period.

You can [launch a Scorecard](/configure/settings/entity-settings/viewing-and-verifying-data-verifications#flagging-unverified-entities-via-a-scorecard) to streamline the process of flagging entities that haven't yet been verified, and you can [create a CQL report](/configure/settings/entity-settings/viewing-and-verifying-data-verifications#viewing-incorrect-entities-via-cql-report) to view a list of all entities that have been verified as incorrect.

# Adding a verification period

Users with the `Configure Verification Periods` permission can add a verification period.

Optionally, but highly recommended, [configure notifications](/configure/settings/entity-settings/verification#configuring-notifications-for-data-verification) to ensure users are notified when a verification period starts and to ensure they receive reminders for entities they own that haven't yet been verified.

**To add a verification period**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Data verification**.

   ![Data Verification](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-verification.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=064de4315aea0100b4186b89418d2de2)
5. On the **Data verification** page, click **+Add verification period**.\
   The **Data verification** side panel opens.
6. In the side panel, enter the following:

   1. **Start date** - Enter the start date for the verification period (required). This date cannot be in the past.
   2. **End date** - Enter the end date for the verification period (required). This date must be at least one day after the start date.
   3. **Name** - Enter a descriptive name for the data verification (required).
   4. **Verification instructions** - Enter clear and concise instructions that will appear on the entity's details page.
   5. **Require reason for verification** - Select this checkbox to require a reason when users mark an entity's data as invalid.
   6. **Team member roles responsible for verification** - Select the Cortex users responsible for verifying data.
      * If you select multiple roles, any team member with one of those roles can verify data.
      * If you do not select a team member role, any direct member of the entity's owning team can verify data.
      * This setting matches against a user's [team member role](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles.md) in Cortex, not their job title or their role in an external system. If your team members don't have Cortex team roles assigned, restricting verification to a role means no one can verify. See [Verifying an entity](/configure/settings/entity-settings/viewing-and-verifying-data-verifications#verifying-an-entity).
   7. **Entity types** - From the dropdown, select the entities to which the verification policy applies.
      * Alternatively, use this dropdown to exclude specific entity types from data verification. Turn on **Exclude**, then select the types you want to leave out.
   8. **Advanced options** - Expand this option to further refine your selection by including or excluding groups, or defining a CQL expression.
7. Click **Create verification period**.\
   After you save a verification period, it appears in the list on the **Data verification** page within a few minutes.

# Configuring notifications for data verification

You can configure two notifications for entity owners: one when a verification period starts, and one that repeats while it's running.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then select **Notifications**.
4. From the **Users** tab, scroll to the **Data verification** section.

   ![Data Ver Notifications](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-ver-notifications.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=ef967e1caa3824a7b241d43c83a2de3c)
5. Toggle on the following:

   * **Verification period reminder** - Owners receive a notification every Monday during an active verification period, reminding them which of their entities still need to be verified.
   * **Verification period started** - Owners receive a notification when a verification period starts for an entity they own.

For more information about notifications, refer to [Notifications](/configure/settings/notifications).

# Editing or deleting a verification period

Data verification periods can be edited or deleted on the **Data verification** page.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Data verification**.
5. On the **Data verification** page, locate the verification you want to edit or delete.
6. Do one of the following:

   1. To edit a verification, click the **pencil icon**.

      ![Data Ver Edit](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-ver-edit.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=4e1c8036fe4d6d278a5d6868a201ec00)
      1. In the **Data verification** side panel, edit any necessary information, then click **Update verification period**.
         > [!NOTE]
         >
         > The pencil icon is greyed out for verifications that are completed or expired.
   2. To delete a verification, click the **trash icon**.

      ![Data Ver Trash](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-ver-trash.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=d2627bfd6fc08d8465478934235aaec2)
      1. The **Delete verification period** modal opens. Click **Delete**.


# Viewing and verifying data verifications
Source: https://docs.cortex.io/configure/settings/entity-settings/viewing-and-verifying-data-verifications



Data verification periods are viewable at any time on the **Data verification** page. At a glance, see the status, time period, and progress for each verification.

**To access the Data verification page**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Data verification**.

# Viewing all entities associated with a verification

You can view a list of all entities associated with a particular verification on the **Data verification** page.

**To view entities associated with a verification period**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Data verification**.
5. Click into a row. \
   The **Verification details** side panel opens.\
   In the side panel, you can also see at a glance which entities have been verified, which user verified them, and the date of the verification. Click an entity to view its entity details page.

   ![Data Ver All Entities](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-ver-all-entities.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=b44f2c39da86b5a0a5627fa343ca9a07)

# Viewing your assigned verifications

Your [Engineering homepage](/streamline/homepage) shows everything you're responsible for verifying. If you own entities that need verifying, a **Pending verifications** tab appears there.

If notifications are enabled, you'll also hear about a verification period when it begins and get weekly reminders while it's open.

# Verifying an entity

To verify an entity, you must be a direct member of a team that owns it. A few things to keep in mind:

* Ownership alone isn't enough if it's indirect. If your team owns the entity through [ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance.md), or you're a member of a parent team rather than the owning team itself, you can't verify the entity.
* There's no global verifier role. Workspace-level permissions, including `Configure Verification Periods`, let you set up and manage verification periods, but they don't let you verify an entity you don't own.
* If the verification period specifies **Team member roles responsible for verification**, you also need one of those roles on the owning team. Without a matching role, you can't verify the entity even if you're a direct member.

If you don't meet these requirements, the **Verify entity** button doesn't appear on the entity's details page.

## Verification and externally synced teams

If you sync team membership from an identity provider such as Workday, GitHub, or Datadog, the sync brings in who belongs to each team, but it doesn't always bring in each member's role. Members imported without a role have no Cortex team member role at all.

This matters when a verification period restricts verification to specific roles. If no one on the owning team has a matching role, no one can verify the entity, and no error is shown.

To verify entities on externally synced teams, do one of the following:

* Enable **Sync team roles from identity providers** under **Settings > Entities > Teams** so Cortex assigns roles based on your enabled identity providers. See [Team roles](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles.md) for more information.

  ![Data Ver Sync Team Roles](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-ver-sync-team-roles.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=6a87f1a7f5772e53a827ec790395cafb)
* Leave **Team member roles responsible for verification** empty when you create the verification period, so any direct member of the owning team can verify.

## How to verify an entity

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner of the page, click **Verify entity**. If the button isn't showing, refer to [The 'Verify entity' button isn't showing](/configure/settings/entity-settings/viewing-and-verifying-data-verifications#the-verify-entity-button-isnt-showing) below.

   ![Data Ver Verify Entity](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-ver-verify-entity.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=7019f5cad0c222ed68b6e963e59f46f3)
3. Click the down arrow to the right of the **days left** tag.

   ![Data Ver Arrow](https://mintcdn.com/cortex-290c0c42/2s8kQpg4kevldgO6/images/data-ver-arrow.png?fit=max\&auto=format\&n=2s8kQpg4kevldgO6\&q=85\&s=f9e2e7db3ccaf2f361ccf943bc75da6d)
4. Review the verification instructions. Do one of the following:

   1. If the entity data is correct, select **Data is correct**, then click **Submit**. When prompted to confirm again, click **Yes**.
   2. If the data is incorrect, select **Data is incorrect**. Enter the reason, then click **Submit**.

> [!TIP]
>
> If there is more than one outstanding verification, they'll be listed sequentially by due date.

Once all data verifications have been processed, the entity will display a `Verified` badge.

### The 'Verify entity' button isn't showing

The **Verify entity** button only appears when you're eligible to verify that entity, and there's no tooltip or message when you aren't. If you expect to see it but don't, check the following:

1. The entity is in scope of a verification period. Confirm the entity matches the verification's **Entities to verify** settings on the **Entity verification settings** page.
2. The verification period is active. The button doesn't appear before the start date or after the end date.
3. You're a direct member of a team that owns the entity. Membership in a parent team, or ownership that reaches the entity through inheritance, doesn't make you eligible.
4. You have a required role, if the verification specifies one. Check **Team member roles responsible for verification** on the verification period, then confirm you hold that role on the owning team.
5. Your team's roles are populated. If team membership syncs from an identity provider, members may have no role assigned. See Verification and externally synced teams.

## Viewing verification statuses

Entities that have been labeled as correct, incorrect, or are still pending review are listed on the **Data verification** page. Click into a verification to view its details.

## Flagging unverified entities via a Scorecard

You can launch a Scorecard to automatically flag entities that have not been verified:

1. From the main sidebar, expand **Scorecards**, then expand **Scorecards**.
2. In the upper-right corner of the page, click **+Create Scorecard**.
3. Locate the **Entity Verification** template, then click **+Use**.
4. Make edits to the templated configuration if necessary, then click **Create Scorecard**.

The Scorecard automatically evaluates your entities. If an entity has not been verified, the entity's owner will see a task appear on their Engineering homepage to let them know.

## Viewing incorrect entities via CQL report

You can create a CQL report to view all entities that have been verified as incorrect through data verification.

1. From the main sidebar, expand **Tools**, then select **CQL reports**.
2. Locate the **Entity Verification Report** template, then click **+Use**.
3. Modify the report template as needed, then click **Create**.


# GitOps settings
Source: https://docs.cortex.io/configure/settings/gitops-settings



Admins, or users with the `Configure settings` permission, can adjust system-wide settings for GitOps under [**Settings > GitOps**](https://app.getcortexapp.com/admin/settings/gitops). On this page, adjust settings that apply to entities, to [Scorecards](/standardize/scorecards), and to [Workflows](/streamline/workflows).

To learn more about using a GitOps workflow for Cortex, see [Using GitOps for Cortex](/configure/gitops).

![See the GitOps settings under Settings > GitOps.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/gitops-settings.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=2b7109e2c04877d3387badc70c08b99b)

## GitOps entities settings

In the **Entities** tab of the GitOps Settings page, you can adjust settings that affect entities.

### Processing

These settings allow you to control how Cortex processes and validates your GitOps-managed configuration, helping you ensure that only the desired files and changes are ingested and that errors are surfaced appropriately.

* **Cortex YAML processing**: This setting enables or disables the processing of cortex.yaml files. If disabled, Cortex will not process these files for entity updates, but package and OpenAPI breaking change detections will still process.
* **Process Cortex properties**: This setting controls whether Cortex processes the cortex-properties.yaml file after GitOps processing. If disabled, Cortex will ignore cortex-properties.yaml files.
* **Package parsing during GitOps processing**: This setting determines if Cortex will parse package information (such as dependencies) during GitOps processing. If disabled, package parsing is skipped.
* **OpenAPI detection**: This setting determines whether Cortex checks for breaking changes in API specs defined in cortex.yaml files. If disabled, Cortex does not check for these.

### Linter checks

These options help you control the strictness and visibility of validation checks during your GitOps workflows, making it easier to catch and address configuration issues earlier. Note that these settings only apply if you are using GitHub in your GitOps workflow.

* **Linter check on non-parsable files**: When disabled, GitOps processing will skip non-parsable entity YAML files in the repository. If you have errors in the processed YAMLs, the linter will fail regardless of this setting.
  * For example, if a YAML file is missing its `x-cortex-type` to define the entity type, that file would be considered non-parsable.
* **GitOps linter check repository allowlist**: Choose which repositories to run the linter check on. If none are selected, the check will run on all repositories.
* **Pull requests linter result for warning violations**: This option lets you choose whether the linter result for warning violations should result in success, neutral, or failure. This helps teams decide how strictly to enforce warnings in their CI/CD workflows. By default, if there are any errors in your YAML file, the linter will result with a failure.

![Adjust the linter check settings in Cortex.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/linter-check.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=89d8cf3942f54a3306e1a9194dc63afc)

### Options by entity type

These settings allow you to control whether each type of entity can be created or edited via the UI or whether they must be managed exclusively through GitOps.

* **Enable UI editing for new entity types**: When enabled, entity editing can be done through the Cortex UI. When disabled, entities can only be edited through GitOps.
* **Enable UI importing for new entity types**: When enabled, entities can be imported through the Cortex UI. When disabled, entities can only be created through GitOps.
* **Entity GitOps repository allowlist for new entity types**: Choose which repositories to search for new entity types. If none are selected, Cortex will search all repositories.

Below these toggle settings, you can choose to enable UI editing and UI importing per entity type, and you can select which repositories to search for each entity type.

![Adjust UI editing settings for entity types.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/entity-gitops-options.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=3ff3abe13aad6762ec1a9785f1a4f950)

## GitOps Scorecard settings

The GitOps Scorecard settings control how Scorecards are managed and edited in your workspace, allowing you to enforce a single source of truth and auditability for Scorecard changes.

Learn more about GitOps for Scorecards in [Scorecards as code](/standardize/scorecards/scorecards-as-code).

* **Enable GitOps for Scorecard editing**: When enabled, you can only edit Scorecards via GitOps, reagrdless of whether the Scorecard was originally created in the UI.
* **Scorecard GitOps repository allowlist**: Choose which repositories to search for new Scorecard YAML files. If none are selected, Cortex will search all repositories.

![Choose whether to manage Scorecards in the UI or via GitOps.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scorecard-gitops-settings.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=4e38e552ccaf4c8b9104fde01b401bc9)

## GitOps Workflow settings

The GitOps Workflow settings control how Workflows are managed and edited in your workspace, allowing you to enforce a single source of truth and auditability for Workflow changes.

Learn more about GitOps for Workflows in [Workflows as code](/streamline/workflows/workflows-as-code).

* **Enable GitOps for Workflows editing**: When enabled, you can only edit Workflows via GitOps. You can still create and delete Workflows in the Cortex UI.
* **Workflow GitOps repository allowlist**: Choose which repositories to search for new Workflow YAML files. If none are selected, Cortex will search all repositories.

![Adjust settings to manage Workflows in the UI or via GitOps.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/workflow-settings-gitops.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=038af391f148f5a8aa41f3c962c96317)


# Adding an IP allowlist
Source: https://docs.cortex.io/configure/settings/ip-allowlist



An IP allowlist is a network security control that restricts access to your Cortex workspace based on the originating IP address of incoming requests. When enabled, only requests coming from IP addresses you've explicitly approved can reach your workspace; all others are blocked before they can authenticate. This adds a layer of defense beyond user credentials, ensuring that even if a password or session token is compromised, an attacker still cannot access your workspace from an unapproved network.

IP allowlists are particularly useful for organizations that want to limit workspace access to trusted networks, such as a corporate office, a VPN, or a specific set of remote locations. You can specify individual IP addresses or entire ranges using [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing), giving you flexibility to cover anything from a single machine to an entire subnet.

By default, the allowlist is empty and all IP addresses are permitted access. As soon as you add your first entry, the workspace automatically switches to a deny-by-default posture: only the addresses on the allowlist can connect, and all others are rejected. There's no separate toggle to enable enforcement, as the presence of any entry activates the restriction.

**Before you begin**

A few things to keep in mind before configuring your allowlist:

* **Add your own IP address first.** The allowlist activates the moment you save your first entry, so omitting your current IP will lock you out of the workspace. Cortex warns you before this happens, but as a best practice, add your own IP to the list before saving.
* **Account for all trusted networks.** Make sure you've identified every network your users connect from, including corporate offices, VPN exit nodes, remote workers' home networks, and any third-party services or integrations that make requests to your workspace.
* **Plan for dynamic IPs.** Home internet connections and some cloud services use IP addresses that change over time. For these, use a CIDR range that covers the expected pool, or require users to connect through a VPN with a static egress IP.
* **Include the remote MCP server if you use it.** If you use the [remote Cortex MCP](/get-started/cortex-ai-assistant/mcp/configuring-cortex-mcp#hosting-the-cortex-mcp-server-remotely), add the IP addresses the MCP server sends requests from, not the MCP server's own address. See [Allowlisting the remote MCP server](/get-started/cortex-ai-assistant/mcp/configuring-cortex-mcp#allowlisting-the-remote-mcp-server) for the addresses in each region.

You can configure an IP allowlist in the Cortex UI or via the Cortex API. Your user or API key must have the `Configure IP Allowlist` permission to perform these steps.

## Configuring an IP allowlist via the Cortex UI

Follow the steps below to configure an IP allowlist in Cortex.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Security and access** section, then click **IP allowlist**.
4. In the upper-right corner, click **Add IP addresses**.
5. In the **Add IP addresses to allowlist side** panel, do one of the following:
   * Enter a single IP address
     1. Under IP addresses, enter a single IP address.
     2. Optionally, enter a description of the IP address.
     3. Optionally, click **Add more** to add another IP address.
     4. Click **Add addresses**.
   * Enter multiple IP addresses
     1. Toggle on **Bulk edit**.
     2. In the Entries field, enter or paste a list of IP addresses (and optional descriptions).
     3. Click **Add addresses**.

> [!WARNING]
>
> When you save the allowlist, Cortex checks whether your current IP is included. If it isn't, a warning appears before the change takes effect. This prevents you from accidentally locking yourself out of the workspace.

## Configuring an IP allowlist via the API

See the [IP allowlist API documentation](/api/rest/ip-allowlist) to learn more about creating an allowlist through the API. You can retrieve a range of addresses, update existing addresses, and validate your IP addresses.
Note that Cortex checks whether your IP address is included in the allowlist to prevent you from losing access to your workspace.

## Troubleshooting and FAQ

**Why do I see a** `403 Forbidden IP address` **error when running a Workflow?**

Workflow steps that call the Cortex API fail if the request originates from an IP that isn't on your allowlist. Send a message to [help@cortex.io](mailto:help@cortex.io) if you need further assistance.


# Managing users and roles
Source: https://docs.cortex.io/configure/settings/managing-users



> **[Roles and permissions](/configure/settings/managing-users/permissioning)**

> **[Configuring SSO for Cortex workspace logins](/configure/settings/managing-users/configuring-sso)**

> **[Provisioning users with SCIM](/configure/settings/managing-users/scim/provisioning-users-with-scim)**

> **[Configuring identity mappings](/configure/settings/managing-users/identity-mapping)**

> **[Onboarding management](/configure/settings/managing-users/onboarding-mgmt)**


# Configuring SSO for Cortex workspace logins
Source: https://docs.cortex.io/configure/settings/managing-users/configuring-sso



Cortex always maintains a strong security posture. Aside from being SOC 2 Type 2 certified and protecting your data through strict process and standards, Cortex supports SSO through most major vendors. SSO is supported through any OIDC provider. The scopes Cortex requires for OIDC to function are: `openid`, `email`, and `profile`, and the only data Cortex stores from the OIDC flow is the user's `name` and `email`.

### SSO integrations

Cortex offers native integrations for:

* [Entra ID](/configure/settings/managing-users/configuring-sso/entraid) (including [Entra ID SCIM](/configure/settings/managing-users/scim/entraid-scim))
* [Google](/configure/settings/managing-users/configuring-sso/google)
* [Okta](/configure/settings/managing-users/configuring-sso/okta) (including [Okta SCIM](/configure/settings/managing-users/scim/okta-scim))

You can also configure other OIDC providers via the [Generic OIDC providers](/configure/settings/managing-users/configuring-sso/oidc) documentation.


# Entra ID SSO
Source: https://docs.cortex.io/configure/settings/managing-users/configuring-sso/entraid



Cortex supports configuring Single Sign-On (SSO) with Microsoft Entra ID (formerly known as Azure Active Directory) with OpenID Connect for protecting access to your Cortex workspace.

Cortex also supports an integration to track Entra ID teams and team members as entity owners as well as create Scorecards involving your Entra ID teams. See the [Entra ID integration page](/ingesting-data-into-cortex/integrations/entraid) for more information.

## Configuring Entra ID SSO for Cortex

Users who have the `Configure OpenID Connector & SCIM` permission can configure Entra ID SSO for Cortex.

### Step 1: Setting up a new Entra ID application

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com/).
2. From the left menu, select **Overview**.
3. Click **Add**, then select **App registration**.
4. In the **Name** field, enter a descriptive name for the application, e.g. `Cortex login`.
5. From the **Supported account types** drop-down menu, select **Single tenant only** / **Accounts in this organizational directory only.** Selecting this option means the SSO will only work for the given Entra ID instance—not for other organizations.
6. From the **Redirect URI (optional)** drop-down menu, select **Web**.
7. In the **Authorized redirect URI** field, enter `https://cortexapp.auth0.com/login/callback` .
8. Click **Register**.

   The app's overview page is displayed.
9. Copy the **Application (client) ID** value and store it in a secure location, as you will need this in the next steps.

> [!NOTE]
>
> Refer to the Microsoft [quickstart guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application) for more detailed instructions on setting up an Entra ID app.

### Step 2: Creating a client secret in Entra ID

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com/).
2. From the left menu, select **App registrations**.
3. Select the **All applications** tab, then select your app.
4. Click **Add a certificate or secret.**
5. Select the **Client secrets** tab.
6. Click **New client secret**.
7. In the **Description** field, enter a description for the secret.
8. From the **Expires** drop-down menu, select an expiration.

   SSO stops working when the secret expires. Set an expiration that makes sense for your process. If you regularly rotate secrets, a shorter expiration period might make more sense. If you don't, a longer duration ensures that SSO continues to function without interruption.
9. Click **Add**.
10. Copy the value of the secret and store it in a secure location, as you will need this in the next steps.

### Step 3: Obtaining the metadata document endpoint in Entra ID

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com/).
2. From the left menu, select **App registrations**.
3. Select the **All applications** tab, then select your app.
4. Select the **Endpoints** tab.
5. Copy the **OpenID Connect metadata document** up to `/v2.0` . It should be in the format `https://login.microsoftonline.com/<uuid>/v2.0`.

### Step 4: Configuring SSO in Cortex

1. Log in to Cortex.
2. From the main sidebar, click your avatar in the bottom-left corner.
3. Click **Settings**.
4. From the **Settings** menu, scroll to the **Security and access** section, then select **OpenID connector**.
5. Configure the form:
   * From the **Type** drop-down men&#x75;**,**  select **Azure**.
   * Below **Identifier**, **e**nter your client ID.
   * Below **Secret**, enter your client secret.
   * Below **Issuer**, enter the issuer URI.
     * Do **not** include a backslash after `v2.0` in the issuer URI! This will process as an invalid configuration for the URI.
6. Click **Save**.

Once saved, users will only be able to sign in to Cortex using their Entra ID account.


# Google SSO
Source: https://docs.cortex.io/configure/settings/managing-users/configuring-sso/google



By default, Cortex uses Google as the Single Sign-On (SSO) authentication provider. Follow the instructions on this page to configure your own Google Cloud app for SSO to your Cortex workspace.

Cortex also supports an integration to track Google teams and team members as entity owners, pull in Service Level Objectives (SLOs) from Google Cloud Observability, and create Scorecards involving your Google resources and teams. See the [Google integration page](/ingesting-data-into-cortex/integrations/google) for more information.

## How to configure Google SSO for Cortex

You must have the `Configure OpenID Connector & SCIM` permission.

### Step 1: Set up a Google OAuth app

To set up a new Google OAuth app, follow [Google's OpenID Connect instructions](https://developers.google.com/identity/openid-connect/openid-connect).

### Step 2: Create an OAuth client ID in Google Cloud

1. In your Google Cloud instance, navigate to **APIs & Services**.
2. Click **Create Credentials**. Under Application type, select **Web application**
3. In the **Authorized redirect URI section**, add `https://cortexapp.auth0.com/login/callback` as an authorized [redirect URI](https://developers.google.com/identity/openid-connect/openid-connect#setredirecturi).
4. Click **Create**.
   * You will be redirected to the APIs & Services page. A modal will open with the client ID and secret.
5. Copy the client ID and client secret. Store these in a secure location, as you will need them in the next steps.

### Step 3: Configure SSO in Cortex

1. In your Cortex workspace, navigate to [**Settings > OpenID Connector**](https://app.getcortexapp.com/admin/settings/oidc).
2. Configure the form:
   * **Type**: Select `Google`.
   * **Identifier:** Enter the client ID from Step 2.
   * **Secret:** Enter the client secret from Step 2.
   * **Issuer:** Enter `https://accounts.google.com`.
3. At the bottom of the page, click **Save**.

After saving your configuration, users will only have the option to sign in to your Cortex workspace via your Google Cloud account.


# Other OIDC SSO providers
Source: https://docs.cortex.io/configure/settings/managing-users/configuring-sso/oidc



This guide explains how to configure Single Sign-On (SSO) for your Cortex instance with OpenID Connect (OIDC) providers that are not available as native integrations.

You must have the `Configure OpenID Connector & SCIM` permission.

### Step 1: Configure your provider

In your OIDC provider, before setting up SSO with a third-party application, you will need to configure:

* An application and permissions
* The Cortex redirect URI: `https://cortexapp.auth0.com/login/callback`
* A client ID and client secret

See your provider's documentation for instructions.

### Step 2: Configure SSO in Cortex

1. In Cortex, navigate to the [OIDC settings page](https://app.getcortexapp.com/admin/settings/oidc).
2. Configure the OIDC settings:
   * **Type**: Click the dropdown and type in the name of the OIDC provider. In the dropdown, click **+Add**.
   * **Identifier**: Enter your OIDC provider client ID.
   * **Secret**: Enter your OIDC provider client secret.
   * **Issuer**: Enter the auth URL from your SSO provider, e.g., `https://oauth.id.jumpcloud.com/`
3. Click **Save**.

### Troubleshooting and FAQ

See frequently asked questions below.

> **I'm receiving a 'No verified email found' error.**
>
> This error occurs when Cortex cannot find a valid email address in the ID token returned by your OIDC provider. To resolve:
>
> 1. Ensure the `email` scope is requested. Your OIDC application must include the `email` scope (in addition to `openid` and `profile`) so the provider includes email claims in the token.
> 2. Ensure the `email` claim is mapped. In your OIDC provider's attribute/claim mappings, verify that the `email` claim is included in the ID token. Some providers do not include it by default.
> 3. Include `email_verified`. Some providers omit the `email_verified` claim, which can cause Cortex to reject the email. Add `email_verified` (set to `true`) as a claim in your provider's token configuration.


# Okta SSO
Source: https://docs.cortex.io/configure/settings/managing-users/configuring-sso/okta



Cortex supports configuring Single Sign-On (SSO) with Okta to protect access to your Cortex workspace. Additionally, you can configure [Okta SCIM with Cortex](/configure/settings/managing-users/scim/okta-scim).

Cortex also supports an integration to track Okta teams and team members as entity owners as well as create Scorecards involving your Okta teams. See the [Okta integration page](/ingesting-data-into-cortex/integrations/okta) for more information.

## Configuring Okta SSO for Cortex

Users with the `Configure OpenID Connector & SCIM` permission can configure Okta SSO in Cortex.

There are two options to configure Okta SSO:

* Installing the [Cortex app in the Okta Integration Network (OIN)](https://www.okta.com/integrations/cortex/)
  * This option provides a simplified setup for most standard use cases. It's compatible with [Okta SCIM](/configure/settings/managing-users/scim/okta-scim) provisioning features.
* Creating your own app
  * This option is best if you need more flexibility in configuring redirect behavior, want to configure automatic sign-on, or if you require multiple or advanced configurations.

### Configuring Okta SSO via the Cortex OIN app

#### Step 1: Installing the Cortex OIN app

Cortex's OIN app configures the initial steps for Okta SSO.

1. Install the Cortex app from the [Okta OIN](https://www.okta.com/integrations/cortex/).

> [!NOTE]
>
> You can also access the Cortex app from your Okta instance by navigating to **Applications** and selecting Cortex from the *App Integration Catalog*.

#### Step 2: Copying the client ID and client secret

1. In Okta, navigate to the **Applications** page and select the Cortex app from your list of applications.
2. Click the **Sign On** tab.
3. Copy the values of the client ID and client secret. Store them in a secure location, as you will need these in the next steps.

   > [!NOTE]
   >
   > Be sure to copy the client ID and the client secret and save them for later. Do not skip this step—you can only view these values once!

#### Step 3: Obtaining the issuer URI

In Okta, each authorization server has a unique issuer URI. See [Okta's instructions](https://developer.okta.com/docs/concepts/auth-servers/) for information on finding your Okta issuer URI. It should look like `https://{okta-domain}.okta.com`.

#### Step 4: Configuring SSO in Cortex

1. Log in to Cortex.
2. From the main sidebar, click your avatar in the bottom-left corner.
3. Click **Settings**.
4. From the **Settings** menu, scroll to the **Security and access** section, then select **OpenID connector**. The **OpenID connector** page is displayed.
5. Enter the following values:
   * From the **Type** drop-down menu, select **Okta**.
   * In the **Identifier** field, enter your client ID.
   * In the **Secret** field, enter your client secret.
   * In the **Issuer** field, enter the issuer URI.
6. Click **Save**.

Once saved, users will only be able to sign in to Cortex using their Okta account.

### Configuring Okta SSO via your own app

#### Step 1: Creating an Okta app integration

1. Log in to the Okta admin console.
2. Navigate to **Applications**, then select **Create App Integration**.
3. In the modal under the sign-in methods, select **OIDC - Open ID Connect**. Under **Application type**, select **Web Application**.
4. On the next page, enter a name, logo, and grant type for the app.
   * To bypass the login screen and enable automatic sign on, see [Auto sign-on](/configure/settings/managing-users/configuring-sso/okta#auto-sign-on) below.
5. Click **Save**.
   * You will be redirected to the app's overview page.
6. From the app's overview, click the **General** tab. Copy the values of the client ID and client secret. Store these in a secure location, as you will need them in the next steps.

**Auto sign-on**

You can bypass the login screen and enable automatic sign-on with the following configurations for your Okta app:

* **Grant type** - Authorization Code
* **Initiate login URI** - `https://app.getcortexapp.com/login?tenantCode=TENANT_CODE` (replace `TENANT_CODE` with your Cortex tenant code. This is what triggers auto sign-on directly into your workspace)
* **Sign-in redirect URIs** - Add all of the following:
  * `https://cortexapp.auth0.com/login/callback` (required for all configurations; this is the redirect URI the Auth0 OAuth flow uses)
  * `https://api.getcortexapp.com/login/oauth2/code/okta` (required for the standard SSO login flow)
  * `https://app.getcortexapp.com/login?tenantCode=TENANT_CODE` (replace `TENANT_CODE` with your Cortex tenant code)

#### Step 2: Configuring SSO in Cortex

1. Log in to Cortex.
2. From the main sidebar, click your avatar in the bottom-left corner.
3. Click **Settings**.
4. From the **Settings** menu, scroll to the **Security and access** section, then select **OpenID connector**. The **OpenID connector** page is displayed.
5. Enter the following values:
   * From the **Type** drop-down menu, select **Okta**.
   * In the **Identifier** field, enter your client ID.
   * In the **Secret** field, enter your client secret.
   * In the **Issuer** field, enter your Okta account domain, e.g. `https://{okta-domain}.okta.com`.
6. Click **Save**.

Once saved, users will only be able to sign in to Cortex using their Okta account.

## Troubleshooting and FAQ

See frequently asked questions below.

> **I see authentication failures and/or can't to connect to Okta**
>
> Follow these steps:
>
> 1. Check your network connectivity from Cortex to Okta endpoints.
> 2. Verify no firewall rules or network changes are blocking outbound traffic.
> 3. Confirm required Okta domains/endpoints are reachable.

> **I see TLS handshake failures in the logs / The TLS handshake could not complete, blocking the authentication flow**
>
> Follow these steps:
>
> 1. Validate that outbound HTTPS (port 443) is allowed.
> 2. Check for SSL/TLS inspection or proxy interference.
> 3. Confirm certificates are not blocked or altered.


# Configuring identity mappings
Source: https://docs.cortex.io/configure/settings/managing-users/identity-mapping



The identity mappings feature allows you to map accounts from different integrations to Cortex accounts, based on name or email address. With identity mapping, you can not only make sure that integrations are working properly for your team members, but you can also ensure that the [Developer Homepage](/streamline/homepage) and [Eng Intelligence](/improve/eng-intelligence) features are working as intended with their mappings.

In most cases, Cortex can automatically match user identities across systems with no setup required. When account details differ across tools, Cortex Admins can manually review and map users in **Settings > Identity mappings**.

Identity mapping is available for:

* [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
* [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket)
* [ClickUp](/ingesting-data-into-cortex/integrations/clickup)
* [GitHub](/ingesting-data-into-cortex/integrations/github)
* [GitLab](/ingesting-data-into-cortex/integrations/gitlab)
* [Jira](/ingesting-data-into-cortex/integrations/jira)
* [Microsoft Teams](/ingesting-data-into-cortex/integrations/microsoftteams)
* [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie)
* [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty)
* [Slack](/ingesting-data-into-cortex/integrations/slack)

Git providers and Jira support [multiple mappings per user](/configure/settings/managing-users/identity-mapping#mapping-multiple-identities-to-users).

## View your personal identity mappings

All of your personal mappings for your established integrations are listed in Cortex under [**Settings > My identity mapping**](https://app.getcortexapp.com/admin/settings/my-integration-accounts).

From this page, you can directly add your OAuth user for GitHub cloud if there’s no mapping. For other integrations, a user with the `Configure identity mappings` permission must configure the identity mappings.

> [!WARNING]
>
> OAuth mapping is only valid for GitHub cloud and not for GitHub Enterprise server.

## Viewing and managing all identity mappings

Users with the `Configure Identity Mappings` permission can review all user mappings specific to each configured integration. Every integration you've set up appears on this page, whether or not you've mapped users to it yet.

**To access**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. Scroll to the **Identity mappings section**.\


   ![](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/identity-mappings.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=6c5ca30de2388dcc397531ec0aeb7439)

### Reviewing mapped and unmapped users

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. Scroll to the **Identity mappings section**.
4. Select the integration whose users you want to review.
5. In the upper-right corner of the integration's **User mappings** page, click **Display**.\


   ![](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/review-mapped-users.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=d0268c37ccece6f72904d5475dd48d36)
6. Toggle on or off the following:
   * **Active integrations only** (toggled on by default) - Show mappings only for integration configurations that are currently installed. Uninstalling a configuration doesn't delete the mappings you've saved for it; toggle this setting off to see them again.
   * **Hide mapped users** - Show only the users who don't have a mapping yet.
7. Click **Done**.

#### Mapping unmapped users

While viewing the user mappings for an integration, you can view Cortex's suggestions for user accounts. You can accept suggestions individually by clicking the checkmark next to a suggestion in a user’s row:

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/map-unmapped.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=38460d9cf4f2bfabf673e71415bb5065)

To accept multiple suggestions at once, click **Accept all suggestions** at the top of the list. This opens a dialog listing every account that has a suggested mapping, so you can review the suggestions and confirm them for many users at once.

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/mapping-bulk.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=b3390e497def3abe85aeb42871f35b91)

If Cortex doesn't have a suggestion, select a mapping for that user from the **Select mapping** drop-down.

### Mapping multiple identities to users

Cortex supports more than one identity per user, so if you run multiple instances of a Git provider or Jira, you can map an identity for each instance alias.

The following providers are supported:

* [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
* [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket)
* [GitHub](/ingesting-data-into-cortex/integrations/github)
* [GitLab](/ingesting-data-into-cortex/integrations/gitlab)
* [Jira](/ingesting-data-into-cortex/integrations/jira)

**To configure multiple mappings for a user**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. Scroll to the **Identity mappings section**.
4. Select the integration whose users you want to map.
5. Locate the user, then click the arrow next to their name to expand their mappings.
6. If an identity isn't mapped yet, the dropdown next to the instance alias suggests a user. Select the user, then click **Save**.
   * When a mapping isn't associated with an alias, the **Identity mappings** settings show a dropdown labeled **Unknown**. This can happen when an integration has multiple aliases configured. The next time Cortex syncs user identity information, it tries to match the mapping to an alias. The **Unknown** label doesn't affect how Cortex works.
   * Cortex lists only the aliases for integration configurations that are currently installed. If an alias you expect is missing from a user's mappings, the configuration it belongs to may have been removed or renamed. Uninstalling a configuration doesn't delete the mappings you've saved for it. To see them, click **Display** at the top of the list, then toggle off **Active integrations only**.

![](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/unmapped-users.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=bdff155a75e8cb82e010e23f755772c8)


# Onboarding management
Source: https://docs.cortex.io/configure/settings/managing-users/onboarding-mgmt



The Onboarding management tool allows you to stay informed about onboarding status for users in Cortex.

Users with the `View Onboarding management` permission can see the onboarding management tool. Users with the `Enable Onboarding management` permission can message users directly from this page to remind them to complete onboarding for logging in to your organization's Cortex instance.

## View onboarding management

To access onboarding management, navigate to **Tools > Onboarding**. Here you can view a list of teams and the number of team members who have onboarded. The tool also includes a progress bar so you can see the overall percentage of users who have been onboarded.

![onboarding 1](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/onboarding-mgmt.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=8f7c1525eb36ac5686b9bc487bb67d54)

### Onboarding statuses

Users will have one of four different statuses on this page:

* `Not connected`: Does not have their identity mapped from an external account.
* `Notified`: Has been sent a message for onboarding.
* `Connected`: Has identity mapped from an external account and can receive notifications about the onboarding process, but has not yet logged in to Cortex.
* `Onboarded`: Has completed onboarding.

#### Connecting a user with a "Not connected" status

If a user's onboarding status is `Not connected`, users with the `Configure identity mappings` permission can map the user's identity to an external account:

* Slack: Navigate to the [Slack Identity mappings page](https://app.getcortexapp.com/admin/settings/slack-mappings) in your Cortex settings.
* Microsoft Teams: Navigate to the [Microsoft Teams identity mappings page](https://app.getcortexapp.com/admin/settings/microsoftteams-mappings) in your Cortex settings.

From this identity mapping page, you can select a mapping from the dropdown menu for each user, as well as see and edit mapped users.

### Message users who have not onboarded

On this page, you can message team members who haven’t onboarded. The supported messaging methods are Slack and Microsoft Teams.

You must have the `Enable Onboarding management` permission to message users on this page.

1. On the onboarding management page, in the row displaying the user, click **Message user**:

   ![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/onboard-message.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=ba88aaed84b3d41c9aa4c30076ccad60)
2. Optionally include a custom message, and review the message preview on the right side of the modal.
3. Click **Send message**.

### Message teams who have not onboarded

If multiple members of the same team have not completed onboarding, you can message the team.

You must have the `Enable Onboarding management` permission to message users on this page.

1. In the row for the team, click **Message team**.
   * In the modal, expand "Message details" to view which users the message will be sent to.
2. Optionally include a custom message, and review the message preview on the right side of the modal.
3. Click **Send message**.


# Roles and permissions
Source: https://docs.cortex.io/configure/settings/managing-users/permissioning



Users and teams in Cortex can be assigned to a role which permits or limits the ability to perform specific actions within Cortex. These actions range from creating API keys and adding integrations to editing Scorecards and creating entities. Roles allow you to ensure that only authorized individuals can make high-level changes to your workspace. You can use the [default roles](/configure/settings/managing-users/permissioning#default-roles) or you can [create custom roles](/configure/settings/managing-users/permissioning#custom-roles).

If a user is assigned to more than one role, they will retain the permissions of the least restricted assigned role. For example, if a user is assigned a `Manager` role and they are a member of a team assigned the `Admin` role, then they will have admin permissions throughout Cortex. Using custom roles may introduce other permissions that supersede default roles.

If a user does not have permission to perform an action, the option will not appear for them.

## Roles in Cortex

### Default roles

When you first access your Cortex account, the following roles are available by default:

* **Admins:** Admins are the owners of the workspace. They have global access to everything within Cortex: settings, Scorecards, and entities.
* **Managers:** Managers have most of the same abilities as admins, but cannot modify permissions or other settings. Managers can create and edit Scorecards, entities, and teams.
* **Users:** Users cannot modify settings, nor can they edit or create Scorecards. Users can edit and create entities and teams.
* **Viewers:** Viewers cannot create or edit anything within the workspace. This is a read-only role.

The following table shows which permissions are associated with the default user roles in Cortex. Note that you can add each of these permissions to [custom roles](/configure/settings/managing-users/permissioning#custom-roles).

| Permission | Viewer | User | Manager | Admin |
| - | :-: | :-: | :-: | :-: |
| View CQL reports | ✓ | ✓ | ✓ | ✓ |
| View initiatives | ✓ | ✓ | ✓ | ✓ |
| View onboarding management | ✓ | ✓ | ✓ | ✓ |
| View Scorecards | ✓ | ✓ | ✓ | ✓ |
| View catalogs | ✓ | ✓ | ✓ | ✓ |
| Edit and create entities | | ✓ | ✓ | ✓ |
| Archive and delete entities | | ✓ | ✓ | ✓ |
| Edit and create entity types | | ✓ | ✓ | ✓ |
| Edit CQL reports | | ✓ | ✓ | ✓ |
| Edit initiatives | | ✓ | ✓ | ✓ |
| Configure Scaffolder templates | | ✓ | ✓ | ✓ |
| Run the Scaffolder | | ✓ | ✓ | ✓ |
| Run query builder | | ✓ | ✓ | ✓ |
| View GitOps logs | | ✓ | ✓ | ✓ |
| View Workflows | | ✓ | ✓ | ✓ |
| View Workflow runs | | ✓ | ✓ | ✓ |
| Execute Workflow runs | | ✓ | ✓ | ✓ |
| View Scorecard exemptions | | ✓ | ✓ | ✓ |
| View Eng Intelligence | | | ✓ | ✓ |
| Configure Eng Intelligence custom metrics | | | ✓ | ✓ |
| Configure Eng Intelligence | | | ✓ | ✓ |
| View Eng Intelligence user dimensions | | | ✓ | ✓ |
| Configure identity mappings | | | ✓ | ✓ |
| Edit and create Scorecards | | | ✓ | ✓ |
| Edit, create, and delete catalogs | | | ✓ | ✓ |
| Edit Eng Intelligence custom metric data | | | ✓ | ✓ |
| Edit OpEx comments | | | ✓ | ✓ |
| Edit Workflows | | | ✓ | ✓ |
| Run re-evaluation of Scorecards | | | ✓ | ✓ |
| View audit logs | | | | ✓ |
| View breaking API changes | | | | ✓ |
| View notification logs | | | | ✓ |
| View roles | | | | ✓ |
| Configure appearance | | | | ✓ |
| Configure catalog | | | | ✓ |
| Configure custom metrics | | | | ✓ |
| Configure discovery audit events | | | | ✓ |
| Configure entity verification periods | | | | ✓ |
| Configure integrations | | | | ✓ |
| Configure notifications | | | | ✓ |
| Configure plugin appearance | | | | ✓ |
| Configure Scorecard exemptions | | | | ✓ |
| Edit, create, and delete API keys | | | | ✓ |
| Edit custom metric data | | | | ✓ |
| Edit initiatives | | | | ✓ |
| Edit plugins | | | | ✓ |
| Edit plugin proxies | | | | ✓ |
| Edit, create, and delete secrets | | | | ✓ |
| Enable entity dependency discovery | | | | ✓ |
| Enable onboarding management | | | | ✓ |
| Execute notification logs | | | | ✓ |
| Configure IP allowlist | | | | ✓ |
| Configure OpenID Connector and SCIM | | | | ✓ |
| Configure roles | | | | ✓ |
| Configure settings | | | | ✓ |
| Run query builder with third-party integrations[^1] | | | | ✓ |

### Custom roles

Cortex gives you the ability to create custom roles with granular permissions so users have the access they need. Learn more in the [Custom Roles documentation](/configure/settings/managing-users/permissioning/custom-roles).

### Permissioning in Workflows

In addition to the granular permissions listed on this page that apply to [Workflows](/streamline/workflows), it is also possible to:

* Configure specific users, teams, or roles who are allowed to run a Workflow
* Require a user to be an Owner or Editor of an entity in order to run a workflow

These configurations are described in more detail in the [Workflow documentation](/streamline/workflows/configuring-workflow-settings) under "Step 2: Configure your Workflow settings."

## Viewing and assigning roles

### View roles

In [**Settings > Roles and permissions**](https://app.getcortexapp.com/admin/settings/permissions) in Cortex, users with the Admin role can view a list of all users in the workspace and their assigned roles. On this page, you can also assign roles and create custom roles.

![](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/user-management.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=8d0aed8549fc66e45254a12f31caa743)

### Filter the list

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/filter-users%20%281%29.jpg)

* To filter the list by role, click **Filter** in the upper right corner of the user list, then select and apply filters.
* To filter the list by user, click the magnifying glass icon in the upper right corner of the list, then type in a name.

### Assigning a role to a user

Users with the `Edit Roles` permission can change the roles assigned to a user. From the **Edit user roles** side panel, you can add roles, remove a single role, or remove all of a user's roles at once.

> [!NOTE]
>
> Every user must have at least one role assigned. If you remove all of a user's roles, add at least one role back before you save.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Security and access** section, then click **Permissions**.
4. From the **Users** tab, locate the user, then click the **pencil icon** next to their name.
5. In the side panel, do any of the following:
   * To add a role, select one or more roles from the dropdown.
   * To remove a single role, click **Remove** next to that role.
   * To remove every role at once, click **Remove all**.
6. Click **Save changes**.

Your changes apply as soon as you save. You don't need to reselect the roles you want to keep.

#### Assigning roles to multiple users

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Security and access** section, then click **Permissions**.
4. From the **Users** tab, select the checkboxes next to the users you want to assign a role to.
5. In the box that appears near the bottom of the list, click **Roles**, then select **Add roles**.
6. In the side panel, do one of the following:
   * To give every selected user an additional role, select **Add to existing roles**, then select the roles from the **Roles to be added** dropdown.
   * To overwrite the roles for every selected user, select **Replace existing roles**, then select their new roles from the dropdown.
7. Click **Add and save**.

> [!NOTE]
>
> Removing a single role isn't supported for bulk edits, because the same role may not apply to every selected user. To take one role away from several users, edit each user individually, or use **Replace existing roles** and select only the roles they should keep.

### Assigning a role to a team

Users with the `Edit Roles` permission can change the roles assigned to a team.
Team roles allow you to assign the team permissions to a set of users all at once. When you add a new member to a team, Cortex automatically assigns the team role to them.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Security and access** section, then click **Permissions**.
4. From the **Teams** tab, locate the team, then click the **pencil icon** next to its name.
5. In the side panel, do any of the following:
   * To add a role, select one or more roles from the dropdown.
   * To remove a single role, click **Remove** next to that role.
   * To remove every role at once, click **Remove all**.
6. Click **Save changes**.

Your changes apply as soon as you save. You don't need to reselect the roles you want to keep.

#### Assigning roles to multiple teams

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Security and access** section, then click **Permissions**.
4. From the **Teams** tab, select the checkboxes next to the teams you want to assign a role to.
5. In the box that appears near the bottom of the list, click **Roles**, then select **Add roles**.
6. In the side panel, do one of the following:
   * To give every selected team an additional role, select **Add to existing roles**, then select the roles from the **Team roles** dropdown.
   * To overwrite the roles for every selected team, select **Replace existing roles**, then select their new roles from the dropdown.
7. Click **Add and save**.

## Adding and removing Cortex users

### Review users

At the top of the [Roles and permissions settings page](https://app.getcortexapp.com/admin/settings/permissions), you can see the total number of seats, the number of users who have logged in to your instance, the number of users who have only received notifications but have not logged in, and the number of available seats remaining. You can also view this information in the [About page](https://app.getcortexapp.com/admin/settings/about) under Workspace settings.

### Set a default role for new users

To set a default role for all new users provisioned for your workspace:

1. At the top of the [Roles and permissions settings page](https://app.getcortexapp.com/admin/settings/permissions), click into the field under "Default roles."
2. Select the desired role.

### Add a user

To add a new user to the platform, first direct the user to attempt to log in to your organization's Cortex account. If the user has the appropriate email domain, they will be added automatically upon login.

If the user sees an "access denied" error, this indicates that the user is not authorized to access the app via your SSO tool.

#### **Add a secondary domain**

Cloud customers who need to add a secondary email domain should contact [help@cortex.io](mailto:help@cortex.io) for assistance. This restriction does not apply to self-hosted customers.

### Remove a user

To delete a user:

1. In the list of User permissions, locate the user you need to delete.
2. Click the trash icon for the user.

   ![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/delete-user%20%281%29.jpg)
3. In the confirmation modal, click **Delete**.

#### What is retained

When a user is deleted, all data created by the user — such as Scorecards, custom entities, Workflows, and other configuration — will remain in Cortex and continue to function normally. However, any personal access tokens created by the user will be permanently removed.

> [!WARNING]
>
> If any integrations or automation scripts depend on a deleted user's personal access token, they will stop working. Update those integrations to use a different token before deleting the user.

#### Ownership and team membership

Deleting a Cortex user only removes their ability to log in and their personal access tokens. It does **not** automatically remove their email from:

* **Entity ownership fields** — such as service owners or business owners defined in the Cortex UI or via `x-cortex-owners` in YAML
* **Team membership** — defined in the Cortex UI, YAML, or synced from external systems (e.g., GitHub, PagerDuty, Opsgenie)
* **Notification targets** — any notification rules, Workflow steps, or on-call references that use the user's email

Ownership and team membership are stored independently from user accounts. To fully remove a deleted user as an owner or team member, you must update those fields separately — either in the Cortex UI, in your YAML definitions, or in the external system that syncs that data.

#### Visibility of deleted users on teams

Depending on your workspace configuration, deleted users may or may not remain visible on Team pages after their account is removed. Team membership is stored separately from user accounts and can be controlled by workspace-level settings.

> [!NOTE]
>
> Contact [Cortex Support](mailto:help@cortex.io) if you need deleted users to remain visible on teams for ownership tracking purposes.

#### Reactivation

If a deleted user later regains access to your identity provider (for example, Okta or Google) and logs back into Cortex with the same email address, a **new** Cortex user account will be created. They will be assigned the workspace's default role. Any ownership or team membership that still references their email will continue to be associated with them automatically — no manual re-linking is required.

If an individual has left your organization entirely and is no longer a user in your identity provider, they will not be able to regain access to your organization's Cortex account.

[^1]: This permission is scoped to admins by default to avoid issues with rate limiting, but it can be added to a custom role.


# Custom roles
Source: https://docs.cortex.io/configure/settings/managing-users/permissioning/custom-roles



## Overview

In Cortex, there are [four default roles](/configure/settings/managing-users/permissioning#default-roles): Viewer, User, Manager, and Admin.

While each of these provides access to different Cortex features, you can also create custom roles to give users more granular permissions.

## Creating custom roles

### How to create a custom role

1. In Cortex, go to the [Roles and permissions settings page](https://app.getcortexapp.com/admin/settings/permissions).
   1. Click your avatar in the lower left corner, then click **Settings**.
   2. Under "Authentication and access," click **Roles and permissions**.
2. In the upper right corner, click **Create custom role**.

   ![The "Create custom role" button is on the right side](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/create-custom-role%20%281%29.jpg)
3. In the "Create custom role" modal, fill in the basic information:
   * **Role name**: Enter a name for the role.

   * **Identifier**: This field is automatically populated based on the role name. It is a unique identifier for the role, made of letters, digits, and hyphens.

   * **Description**: Optionally, add a description of the role to help others understand its purpose.

   * **Settings**: Expand each of the Permission sections to view and toggle on/off a permission setting for the role. All permissions are toggled off by default.

     ![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/create-custom-role%20%282%29.jpg)
4. Click **Create role**.

### Assign a custom role

You can assign a custom role to a team or user the same way you would assign a default role. See [Assigning a role to a user](/configure/settings/managing-users/permissioning#assigning-a-role-to-a-user) for instructions.

It is possible to assign multiple roles to an individual user or team. When multiple roles are assigned, the resulting permissions will be the maximum permissions associated with their assigned role(s). For example, if an individual is assigned two roles with distinct set of permissions, all of those permissions will be applied to that user.

### Set a custom role as default for new users

For information on creating or deleting users and setting a default role for new users, see [Adding and removing Cortex users](/configure/settings/managing-users/permissioning#adding-and-removing-cortex-users).

### Delete a custom role

To delete a custom role:

1. On the [Roles and permissions settings page](https://app.getcortexapp.com/admin/settings/permissions), click the **User role** tab.
2. Click the trash icon next to a role.

   ![](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/delete-custom-role.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=a175d59f9ae55a692a749f336d44b44b)
3. In the confirmation modal, click **Delete**.

Note that you cannot delete a custom role if it is associated with a [plugin](/streamline/plugins).

### Available permissions for custom roles

The table below describes the permission options you can add to a custom role.

| Category | Permission | Description |
| - | - | - |
| Catalogs | **Catalogs view** | View catalogs and entities |
| Catalogs | **Entity types edit** | Create, edit, and delete entity types |
| Catalogs | **Catalogs edit** | Create, edit, and delete catalogs |
| Catalogs | **Entities edit** | Create, edit, and delete entities |
| Catalogs | **Entities archive** | Archive entities |
| Catalogs | **Entities delete** | Delete entities |
| Catalogs | **Entity dependency discovery enable** | Sync dependencies directly when on the dependency graph feature |
| Catalogs | **Entity verification period configure** | Create and edit periods for verifying Cortex entities |
| Scorecards & Initiatives | **Scorecards view** | View scorecards |
| Scorecards & Initiatives | **Scorecards edit** | Create, edit, and delete scorecards |
| Scorecards & Initiatives | **Scorecards re-evaluation execute** | Manually trigger a scorecard's evaluation via the UI |
| Scorecards & Initiatives | **Scorecard exemptions view** | View scorecard exemptions |
| Scorecards & Initiatives | **Scorecard exemptions configure** | Approve or revoke scorecard exemptions |
| Scorecards & Initiatives | **Initiatives view** | View initiatives |
| Scorecards & Initiatives | **Initiatives edit** | Create, edit, and delete initiatives |
| Reporting | **Scorecard report view** | View scorecard reports |
| Reporting | **CQL report view** | Ability to view CQL reports |
| Reporting | **CQL report edit** | Create, edit, and delete CQL reports |
| Eng Intelligence | **Eng Intelligence view** | View Eng Intelligence metrics. Viewing data by individual users also requires **View Eng Intelligence User Dimensions** |
| Eng Intelligence | **Eng Intelligence configure** | Configure Eng Intelligence settings |
| Eng Intelligence | **View Eng Intelligence User Dimensions** | Filter, group, and export Eng Intelligence data by individual users, such as PR authors and reviewers, deployers, assignees, and entity owners |
| Eng Intelligence | **Custom Metrics configure** | Create, edit, and delete Eng Intelligence custom metrics |
| Eng Intelligence | **Custom Metric data edit** | Create, edit, and delete Eng Intelligence custom metrics data points via API |
| Workflows | **Workflows edit** | Create, edit, and delete workflows |
| Workflows | **Workflows view** | View workflows |
| Workflows | **Workflow runs view** | View workflow runs |
| Workflows | **Workflow runs execute** | Ability to run workflow |
| Plugins | **Plugins edit** | Create, edit, and delete plugins |
| Plugins | **Plugin proxies edit** | Create, edit, and delete plugin proxies |
| Plugins | **Plugin appearance configure** | Manage appearance of plugins |
| Tools | **Relationship graph enable** | View and engage with relationship graph |
| Tools | **Onboarding management view** | View onboarding management |
| Tools | **Onboarding management enable** | Trigger onboarding management notifications |
| Tools | **Discovery audit events configure** | Ignore or import entities found in the discovery audit tool |
| Tools | **Scaffolder templates configure** | Create, edit, and delete Scaffolder templates |
| Tools | **Scaffolder execute** | Run the Scaffolder |
| Tools | **Query builder (basic) enable** | Access to query builder tool that allows CQL queries to be created and run adhoc |
| Tools | **Query builder (with 3rd party integrations) enable** | Access to query builder tool that allows CQL queries to be created and run adhoc, including queries of 3rd party integration data |
| Notifications | **Workspace notification settings configure** | Enable or disable workspace notification settings |
| Notifications | **Notification logs view** | View notification logs |
| Notifications | **Notification logs execute** | Resend a notification |
| Settings | **Settings configure** | Edit workspace settings, identity mappings, and integration configurations |
| Settings | **Appearance settings configure** | Edit workspace appearance settings, including logo upload, plugin placement throughout the app, entity overview tabs and navigation order, and catalog sort order |
| Settings | **IP allowlist configure** | Configure restriction for Cortex app and public API access to specified IPs |
| Settings | **GitOps logs view** | View GitOps logs |
| Settings | **OpenID Connector & SCIM configure** | Manage OpenID application details and SCIM for Auth0, Azure, Google, and Okta |
| Settings | **Roles view** | View workspace role definitions and user role assignments |
| Settings | **Roles configure** | Manage workspace role definitions and user role assignments |
| Settings | **Breaking API changes view** | View breaking API changes |
| Settings | **Create API keys edit** | Create, edit, and delete Cortex API keys |
| Settings | **Identity mappings configure** | Review how team members defined in the team catalog are matched to external accounts (e.g. GitHub, Jira, PagerDuty, ClickUp, or Slack). |
| Settings | **Integrations configure** | Install, uninstall, and configure integrations |
| Access Management | **Create secrets edit** | Create, edit, and delete secret keys used in plugin proxies, secure access to 3rd party APIs, etc |
| Access Management | **Audit logs view** | View audit logs |

> [!NOTE]
>
> Custom roles that could already view Eng Intelligence were given **View Eng Intelligence User Dimensions** automatically, so existing users keep the access they had. To limit a role to team- and entity-level Eng Intelligence data, turn off **View Eng Intelligence User Dimensions** for that role.


# Configuring SCIM in Cortex
Source: https://docs.cortex.io/configure/settings/managing-users/scim/configuring-scim



Before you begin using SCIM to provision users, you must first turn on SCIM in your Cortex workspace. Follow the steps below to turn on SCIM.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Security and access** section, then select **SCIM**.
4. Toggle on the following settings:

   * **Enable automatic deprovisioning of users** - Cortex automatically deprovisions any user it detects has been removed from your provider instance.
   * **Enable automatic provisioning of users** - Cortex automatically provisions any user it detects has been added to your provider instance.

   > [!NOTE]
   >
   > Enabling automatic provisioning of users may impact seat counts.

Each toggle controls a distinct set of SCIM operations:

* **Enable automatic provisioning of users** gates user creation and reactivation. While it is off, your provider cannot create or reactivate users in Cortex.
* **Enable automatic deprovisioning of users** gates user deletion and deactivation. While it is off, your provider cannot delete or deactivate users in Cortex.

A user created or reactivated while automatic provisioning is on is always assigned your workspace's default role. For the API responses returned when a required toggle is off, see the [SCIM API reference](/api/rest/scim).

> [!NOTE]
>
> Track provisioned and deprovisioned users in the [Cortex audit logs](/configure/settings/audit-logs). Access the logs from the **Settings** menu. Scroll to the *Logging* section, then select **Audit logs**.

For an overview of the complete SCIM provisioning workflow, see [Okta SCIM Configuration](/configure/settings/managing-users/scim/okta-scim) or [Microsoft Entra ID SCIM Configuration](/configure/settings/managing-users/scim/entraid-scim).


# Configuring Microsoft Entra ID SCIM for Cortex
Source: https://docs.cortex.io/configure/settings/managing-users/scim/entraid-scim



This article explains how to configure Microsoft Entra ID SCIM to work with Cortex. If you're looking to turn on SSO in Cortex via Entra ID, refer to [this article](/configure/settings/managing-users/configuring-sso/entraid).

When Entra ID SCIM is configured, you can create, import, edit, and deactivate users.

> [!NOTE]
>
> Prior to configuring Entra ID SCIM, you must first turn on SCIM in Cortex. Refer to [Configuring SCIM in Cortex](/configure/settings/managing-users/scim/configuring-scim) for more information.

## Prerequisites

Create an API key in Cortex that has the **Admin** role or a custom role that contains the `Configure Open ID Connector & SCIM`, `Edit Roles`, and `Manage Identity Mappings` permissions. See [API Keys, Secrets, and Tokens](/configure/settings/api-keys#create-api-key) for more information.

> [!NOTE]
>
> Be sure to copy the API key and save it for later. Do not skip this step—you can only view the key once!

## Step 1: Adding an Entra ID non-gallery application for SCIM

You must be logged in to Entra ID as one of the following roles: Application Administrator, Cloud Application Administrator, or Global Administrator.

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com).
2. Navigate to **Entra ID > Enterprise apps**.
3. Click **+ New application**.
4. Click **+ Create your own application**.
5. Enter the application name, i.e. `Cortex SCIM`.
6. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
7. Click **Create**.

## Step 2: Configuring Entra ID automatic provisioning for SCIM

You must be logged in to Entra ID as one of the following roles: Application Administrator, Cloud Application Administrator, or Global Administrator.

### Setting up the connection between Cortex and Entra ID

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com).
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](/configure/settings/managing-users/scim/entraid-scim#step-1).
4. From the left menu, select **Provisioning**.
5. Click **Connect your application**.
6. Below **Admin Credentials**, complete the following fields:
   1. From the **Select authentication method** drop-down menu, select **Bearer authentication**.
   2. In the **Tenant URL** field, enter `https://api.getcortexapp.com/scim/v2`.
   3. In the **Secret token** field, enter your Cortex-generated API key.
7. Click **Test Connection**. A **Success** message appears.
8. Click **Create**.

### Configuring scope in Entra ID

Follow the steps below to set the user provisioning scope.

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com).
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](/configure/settings/managing-users/scim/entraid-scim#step-1).
4. From the left menu, select **Provisioning**.
5. Select the **Properties** tab.
6. Click the **pencil icon** next to Basics.
7. In the right panel, locate the **Scope** drop-down menu, then choose one of the following options:
   * **Sync only assigned users and groups** (recommended) - Only users explicitly assigned to the Cortex SCIM app will be provisioned in Cortex.
   * **Sync all users and groups** - All users in your directory will be provisioned in Cortex.

## Step 3: Enabling and verifying Entra ID SCIM provisioning

You must be logged in to Entra ID as one of the following roles: Application Administrator, Cloud Application Administrator, or Global Administrator.

When SCIM provisioning is turned on with Entra ID, the following happens:

* Entra ID begins the initial synchronization with Cortex. This process may take 15 to 20 minutes.
* Entra ID triggers ongoing incremental synchronizations with Cortex every 40 minutes.

> [!NOTE]
>
> You can monitor the synchronization status in Entra ID via the provisioning logs.

Users are created in Cortex based on the user assignments configured in Entra ID.

### Turning on provisioning in Entra ID

Follow the steps below to enable user provisioning in Entra ID.

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com).
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](/configure/settings/managing-users/scim/entraid-scim#step-1).
4. From the left menu, select **Provisioning**.
5. Click **Start Provisioning**.

### Verifying provisioning in Entra ID

Follow the steps below to confirm successful user provisioning in Entra ID.

1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com).
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](/configure/settings/managing-users/scim/entraid-scim#step-1).
4. From the left menu, select **Provisioning**.
5. From the left menu, select **Provisioning logs**.
6. Review the logs for any errors.
7. Verify that users display a **Success** status.

> [!NOTE]
>
> Entra ID synchronizes with Cortex every 40 minutes. If you are within the 40-minute window, there may not be any recent information in the logs.

### Verifying provisioning in Cortex

Follow the steps below to confirm successful user provisioning in Cortex.

1. Log in to Cortex.
2. From the main sidebar, click your avatar in the bottom-left corner.
3. Click **Settings**.
4. From the **Settings** menu, scroll to the **Security and access** section, then select **Permissions**.
5. Confirm that users are listed in the **Users** tab.

   > [!NOTE]
   >
   > You can change the default role assigned to new users who are provisioned from Entra ID. Select the *Default role* drop-down menu to change the default role.

### Deprovisioning users

When a user is [removed or deprovisioned in Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works#deprovisioning), the following happens in Cortex:

* The user's roles are removed
* The user's team memberships are removed
* The user's personal API keys are deleted
* All of the user's active sessions are immediately invalidated

> [!NOTE]
>
> Removing a Cortex seat does not delete the user's git identity mappings. If they're still active in your git provider (e.g. GitHub), their contribution data continues to be attributed correctly in Eng Intelligence.

Deprovisioned users can no longer access Cortex, even if they had an active browser session at the time of removal. No additional action is required to enforce access revocation—removal from your identity provider is sufficient.

**Verifying a user has been deprovisioned in Cortex**:

1. Log in to Cortex.
2. From the main sidebar, click your avatar in the bottom-left corner.
3. Click **Settings**.
4. From the **Settings** menu, scroll to the **Security and access** section, then select **Permissions**.
5. Select the **Users** tab, then verify that the user has been removed.


# Configuring Okta SCIM for Cortex
Source: https://docs.cortex.io/configure/settings/managing-users/scim/okta-scim



This article explains how to configure Okta SCIM to work with Cortex. If you're looking to turn on SSO in Cortex via Okta, refer to [this article](/configure/settings/managing-users/configuring-sso/okta).

When Okta SCIM is configured, you can create, import, edit, and deactivate users.

> [!NOTE]
>
> Prior to configuring Okta SCIM, you must first turn on SCIM in Cortex. Refer to [Configuring SCIM in Cortex](/configure/settings/managing-users/scim/configuring-scim) for more information.

## Limitations

Note the following limitations when using Okta SCIM:

* A user's email cannot be changed
* Only given and family names can be updated
* Users can only be reactivated via a `PUT` operation

## Prerequisites

1. Create an API key in Cortex that has the **Admin** role or a custom role that contains the `Configure Open ID Connector & SCIM`, `Edit Roles`, and `Manage Identity Mappings` permissions. See [API Keys, Secrets, and Tokens](/configure/settings/api-keys#create-api-key) for more information.

   > **Note:** Be sure to copy the API key and save it for later. Do not skip this step—you can only view the key once!
2. In Okta, navigate to **Applications > Sign on > Credential details** and set the **Application username format** to **Email**. SCIM requires this format.
3. If your organization requires you to allowlist domains, ensure that [Okta's IP addresses](https://support.okta.com/help/s/article/list-of-ip-addresses-that-should-be-allowlisted-for-inbound-traffic) can access your Cortex instance:
   1. In Cortex, click your avatar in the bottom-left corner, then click **Settings**.
   2. From the **Settings** menu, locate the **Security and access** section, then click **IP allowlist**. If there are no IP addresses listed here, access is allowed from any IP address.
   3. Click **Add IP addresses** in the upper-right corner.
   4. Enter an individual IP address or an IP range in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing), then click **Add addresses**.

## Step 1: Adding the Cortex OIN app

Add the Cortex OIN app for Okta from [Okta's Cortex integration docs](https://www.okta.com/integrations/cortex/). This is also available in your Okta instance under **Applications > App integration catalog**.

## Step 2: Configuring the API integration

1. In your Okta admin dashboard, navigate to **Applications** then click the Cortex app.
2. Click the **Provisioning** tab.
3. Under the **Settings** panel, click **Integration**. Do the following:
   * Select the **Enable API integration** checkbox.
   * **API token** - Enter your Cortex-generated API key.
4. Click **Test API Credentials** to verify that your configuration works.
5. Click **Save**.

## Step 3: Turning on provisioning in Okta

Provisioning settings can be turned on once the integration is configured.

1. Enable the following settings in Okta:
   * **Create users** - This creates a user in Cortex when the app is assigned to a user in Okta.
     * The default username used to create accounts is set to the **Okta username**.
   * **Update user attributes** - This setting allows Okta to update a user's attributes in Cortex when the app is assigned.
     * Cortex only supports updating the user's name (i.e. birth and family names).
   * **Deactivate users** - This deactivates or deletes a user's Cortex account when the app is unassigned to that user or when their Okta account is deactivated.
     * Accounts can be reactivated if the app is reassigned to the user in Okta.
     * By default, deprovisioned users will not remain visible in team membership. Contact [Cortex Support](mailto:help@cortex.io) to change this behavior.
     * When a deprovisioned user is reprovisioned and logs back in with the same email, any ownership or team membership that still references their email will continue to be associated with them.
2. Click **Save**.

## Syncing user data between Okta and Cortex

Follow the steps below to force a data sync between Okta and Cortex.

1. In your Okta admin dashboard, open the Cortex app then select the **Provisioning** tab.
2. Under the **Settings** panel, click **To App**.
3. Under **Cortex Attribute Mappings**, click **Force sync**.

## Verifying provisioning in Cortex

Follow the steps below to confirm successful user provisioning in Cortex.

1. Log in to Cortex.
2. From the main sidebar, click your avatar in the bottom-left corner.
3. Click **Settings**.
4. From the **Settings** menu, scroll to the **Security and access** section, then select **Permissions**.
5. Confirm that users are listed in the **Users** tab.

   > [!NOTE]
   >
   > You can change the default role assigned to new users who are provisioned from Okta. Select the *Default role* drop-down menu to change the default role.

## Deprovisioning users

When a user is [removed or deprovisioned in Okta](https://developer.okta.com/docs/concepts/scim/#delete-deprovision), the following happens in Cortex:

* The user's roles are removed
* The user's team memberships are removed
* The user's personal API keys are deleted
* All of the user's active sessions are immediately invalidated

> [!NOTE]
>
> Removing a Cortex seat does not delete the user's git identity mappings. If they're still active in your git provider (e.g. GitHub), their contribution data continues to be attributed correctly in Eng Intelligence.

Deprovisioned users can no longer access Cortex, even if they had an active browser session at the time of removal. No additional action is required to enforce access revocation—removal from your identity provider is sufficient.

**Verifying a user has been deprovisioned in Cortex**:

1. Log in to Cortex.
2. From the main sidebar, click your avatar in the bottom-left corner.
3. Click **Settings**.
4. From the **Settings** menu, scroll to the **Security and access** section, then select **Permissions**.
5. Select the **Users** tab, then verify that the user has been removed.

## Troubleshooting and FAQ

See frequently asked questions below.

> **Why might I see a 'Forbidden from remote server' error in Okta when testing authentication?**
>
> This can happen if you did not configure user provisioning in your SCIM settings in Cortex before testing the integration in Okta. Follow the [steps to configure SCIM](/configure/settings/managing-users/scim/configuring-scim), then try again.

> **Do I need the Okta integration set up on the Cortex side to use Okta SCIM?**
>
> You do not need to have the Okta integration configured on the Cortex side. However, you will still need to use the Cortex Okta Integration Network app within Okta using a valid Cortex API key.


# Provisioning Cortex users with SCIM
Source: https://docs.cortex.io/configure/settings/managing-users/scim/provisioning-users-with-scim



System for Cross-domain Identity Management (SCIM) is an open standard protocol that automates the exchange of user identity information between an identity provider (IdP)—such as Microsoft Entra ID or Okta—and a target application like Cortex. It defines a standard schema and REST API for creating, updating, and deprovisioning user accounts, eliminating the need for manual account management. IT administrators and DevOps teams commonly use SCIM to manage user lifecycles at scale across multiple applications from a single source of truth. By automating user provisioning and deprovisioning, SCIM reduces the risk of human error, ensures access is granted and revoked in a timely manner, and frees up administrators from repetitive manual tasks, making it especially valuable in organizations with large or frequently changing user bases.

> [!NOTE]
>
> Cortex supports SCIM provisioning from [Okta](/configure/settings/managing-users/scim/okta-scim) and [Microsoft Entra ID](/configure/settings/managing-users/scim/entraid-scim).


# Notifications
Source: https://docs.cortex.io/configure/settings/notifications



Notifications are built into Cortex to help users stay on top of changes within their environments and the platform. Admins can [configure notifications for the entire workspace](/configure/settings/notifications#setting-notifications-for-the-entire-workspace), while [users can configure their personal notification subscriptions](/configure/settings/notifications#adjusting-your-personal-notification-subscriptions).

See the full list of notification options below under [Notification subscription options in Cortex](/configure/settings/notifications#notification-options-in-cortex).

### Notification markdown limitations

It is possible to use markdown in some fields in Cortex. Some of these fields, such as the description field for a [data verification policy](/configure/settings/entity-settings/verification), appear in notifications. While Cortex will render markdown as expected in the UI, Slack and email notifications may have issues rendering some markdown.

Markdown limitations include, but are not limited to, the following:

* The first element in the description cannot start with `#`.
* Slack supports basic lists, but nested lists are not supported.
* Multi-line code blocks will lose formatting in Slack.
* Inline images with standard markdown (`![alt text](./images/url)`) will not be displayed in Slack.
* Strike-through syntax does not render in Slack.
* Line breaks may not render in Slack.
* Hyperlinks may not be clickable in emails.

To read about other Slack limitations, please see [Markdown Guide's documentation on using Markdown in Slack](https://www.markdownguide.org/tools/slack/).

## Setting notifications for the entire workspace

In the [Notifications settings](https://app.getcortexapp.com/admin/settings/notifications) page in Cortex, you can enable notifications and refine the types of notifications received by users and teams across the workspace.

To set notifications for the workspace, you must be an admin or have a role that includes the `Configure Workspace notification settings` permission.

### Configure allowed notification methods

You can choose whether to allow notifications via the following methods:

* **Email**
  * Note that if a user does not have a defined email address, they will not receive email notifications.
* **Slack**
  * You must have the [Slack integration](/ingesting-data-into-cortex/integrations/slack) configured in order to send notifications to entity Slack channels.
* **Microsoft Teams**
  * You must have the [Microsoft Teams ](/ingesting-data-into-cortex/integrations/microsoftteams)integration configured in order to send notifications to entity Teams channels.

### Configure what type of user can receive notifications

You can enable the following options across the workspace:

* **Enable notifications for non-Cortex users**: When you toggle this setting on, it will enable all notifications for people who are not yet Cortex users but are owners of entities in Cortex.
* **Enable notifications for external members**: When you toggle this setting on, it will enable notifications for any Cortex users who are members of an externally-sourced team, such as Workday or Okta.
* **Limit notifications through CQL**: Any entity that does not match the query will be excluded from all notifications. For entities that match the query, Cortex will continue sending out notifications to their entity owners.
  * After you enable this setting, a text box appears. Enter your query into the box, then click **Save query**.

![You can configure notification types in the Notification settings page.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/user-type-notifs.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=a59ace5cf9965c1ed81613307e7a4462)

### Enabling notifications for users, teams, and entities

You can enable or disable notifications in the Cortex UI or in an [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-with-yaml). Note that users also have the ability to unsubscribe from a notification in their [personal settings](/configure/settings/notifications#adjusting-your-personal-notification-subscriptions).

#### Understanding notification types

Before configuring notifications, it's important to understand the distinction between notifications being enabled for individual users, teams, or entities:

| Notification type | Sent to (options) | Example use cases |
| - | - | - |
| **Team based** These are about the entities owned by a team. |  • The Slack or MS Teams channel tied to a **team** in Cortex • Email addresses of team members |  • You enable the Team-based "On-call changes" notification and [team itself](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams) has a Slack channel linked; When on-call changes for an entity, the team members who own the entity receive a notification. |
| **Entity based** These are about the entity itself. |  • The Slack or MS Teams channel tied to an **entity** in Cortex If the entity's owner and the entity share the same Slack channel, Cortex will only notify the owner; a duplicate notification won't be sent. |  • You enable the Entity-based "On-call changes" notification; When on-call changes for an entity, a notification is sent to the Slack or MS Teams channel linked in the [entity's YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml). • You enable the Entity-based "Initiative Creation" notification; When an entity is included in a recently-created Initiative, a notification is sent to the Slack or MS Teams channel linked in the [entity's YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml). Note that the Initiative must be published, not in draft form. |
| **User based** These go to individual users. |  • Via DM to the user in Slack or MS Teams (DMs are from the Cortex app) • A user's email address |  • You enable the User-based "Onboarding tips" notification; When a new user is added to your workspace, they receive onboarding tip notifications • You enable the User-based "On-call changes" notification; When a user's on-call changes, they receive a notification. |

> [!NOTE]
>
> Note that [some notification types cannot be disabled](/configure/settings/notifications#notifications-that-cannot-be-disabled).

#### Configure notifications for users, teams, and entities

Expand the tabs below to learn how to configure notifications via the Cortex UI and in an entity's YAML.

> **Cortex UI**
>
> **Configure notifications in the UI**
>
> On the [notification settings page](https://app.getcortexapp.com/admin/settings/notifications), after configuring the [methods](/configure/settings/notifications#configure-allowed-notification-methods) and [which type of users](/configure/settings/notifications#configure-what-type-of-user-can-receive-notifications) can receive notifications, you can enable individual notifications under the tabs for User, Team-based, and Entity-based:
>
> 1. For each notification type in the list, enable the toggle to turn on notifications.
>
> * In each row, there are separate toggles for each allowed notification method.
>
>   ![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/notifications-ui.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=de4cf24aed40cefa861bbddaea6969d6)
>
> 2. The notification list defaults to user notifications. Click the **Team-based** and **Entity-based** tabs to review and enable additional notifications.
>
> * Review the [notification types table](/configure/settings/notifications#understanding-notification-types) above to understand where notifications are sent.
>
> Read more about each type of notification below under [Notification options in Cortex](/configure/settings/notifications#notification-options-in-cortex).

> **Cortex YAML**
>
> **Define notifications for team members in the entity descriptor**
>
> If you are configuring the members list for a [team entity](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams) via an entity descriptor, you can define the `notificationsEnabled` field as `true` or `false`. When `notificationsEnabled=true`, users/teams will receive all enabled [notification types](/configure/settings/notifications#notification-options-in-cortex) that apply to them.
>
> The example below demonstrates how to configure notifications for team members in the entity descriptor:
>
> ```yaml theme={null}
>   openapi: 3.0.1
>   info:
>     title: Eng Team
>     x-cortex-tag: eng-team
>     x-cortex-team:
>       groups:
>       - name: Engineering
>         provider: GITLAB
>         description: Our engineering team
>       members:
>       - name: Maya Chen
>         role: Engineering Manager
>         email: maya.chen@cortex-labs.com
>         notificationsEnabled: true
>       - name: Andy Li
>         role: Staff Software Engineer
>         email: andy.li@cortex-labs.com
>         notificationsEnabled: false
> ```
>
> You can also enable or disable notifications for a Slack or Microsoft Teams channel associated with an entity, as shown in the examples below.
>
> In a service entity:
>
> ```yaml theme={null}
> openapi: 3.0.1
> info:
>   title: Backend App
>   x-cortex-tag: backend-app
>   x-cortex-owners:
>   - type: SLACK
>     channel: engineering
>     notificationsEnabled: true
>   - name: eng-team
>     type: group
>     provider: CORTEX
>     notificationsEnabled: false
> ```
>
> In a team entity:
>
> ```yaml theme={null}
> ...
>   x-cortex-slack:
>     channels:
>     - name: team-insights
>       notificationsEnabled: true
>     - name: escalate-insights
>       notificationsEnabled: false
> ```

## Adjusting your personal notification subscriptions

Notification subscriptions allow users to further refine the notifications they receive. These settings will override workspace notifications, effectively allowing a user to "unsubscribe" from a given notification type.

For example, if a workspace admin has enabled **Entity evaluation** in workspace notifications, but a user has disabled **Entity evaluation** in Notification subscriptions, the user will not receive updates when Scorecard scores change for their entities.

To adjust which notifications you receive:

1. Navigate to the [My notifications page in Settings](https://app.getcortexapp.com/admin/settings/notification-subscriptions).

   ![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/my-notifications.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=35a8c48cc53353044f94721ca33baa77)
2. For each notification option, use the toggle switch to enable or disable notifications.

If an admin has disabled a notification type in [workspace notifications](/configure/settings/notifications#setting-notifications-for-the-entire-workspace), users will **not** be able to enable it. Disabled notification subscriptions will be grayed out. If you hover over the toggle switch, you will see a banner stating, "This notification has been disabled by your Admin."

If a notification type has been enabled, but the notification method (e.g., Slack, MS Teams, or email) is disabled, the same note will appear under the notification method toggle for each notification type.

## Notification options in Cortex

### Notifications that cannot be disabled

The following notification types cannot be disabled via workspace settings or in an individual user's notification settings:

* API token expiration
* [On-call assistant](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant)
* Broken OpenAPI spec
* Cortex contract or trial expiration
  * This notification goes to users with the `Configure settings` permission.

### Configurable notification options

The configurable notification options are listed below. As described earlier on this page, an admin (or a user with the `Configure Workspace notification settings` permission) can choose which of these options are [available across the workspace](/configure/settings/notifications#setting-notifications-for-the-entire-workspace).

If an entity channel and owner channel are the same, Cortex will not send duplicate notifications; in this case, Cortex will only send the owner a notification.

Note that notifications can be sent to private Slack channels, but the [Cortex Slack Bot](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#adding-the-ai-assistant-to-a-slack-channel) must be a member of the channel in order for the notification to be delivered to the channel.

> **Entity evaluation (users only)**
>
> Entity evaluation notifications go out to users when an entity they own is re-evaluated by a Scorecard due to changes in its `cortex.yaml` file. This alert will tell you whether the score for that entity has increased or decreased.
>
> **You will not receive a notification if the score is unchanged after Cortex processes the changes.**

> **Initiative creation (users, teams, and entities)**
>
> Draft Initiatives only trigger notifications for users with the `Edit Scorecards` permission. Notifications for draft Initiatives will not trigger for team notifications.
>
> * Initiative creation notifications alert **teams** *when at least one entity they own is included in a recently created Initiative*. These notifications include [action items](/improve/initiatives) associated with entities owned by that team.
> * Initiative creation notifications are sent to **users** *when entities they own are included in a recently created Initiative*. Initiative creation notifications will go to users when an entity is not owned by a team, and/or when the **Initiative creation - Teams** notification is disabled.
> * Initiative creation notifications are sent to **entity channels** *when the entity is included in a recently created Initiative*. Cortex checks for created Initiatives and sends relevant notifications every 10 minutes.

> **Initiative custom scheduled reminders (users and teams)**
>
> Draft Initiatives only trigger notifications for users with the `Edit Scorecards` permission. Notifications for draft Initiatives will not trigger for team notifications.
>
> Initiative custom scheduled reminders send progress notifications to users that are part of a given Initiative. The Initiative owner can determine the cadence of these reminders when creating or editing an Initiative.

> **Initiative reminders (users and teams)**
>
> Draft Initiatives only trigger notifications for users with the `Edit Scorecards` permission. Notifications for draft Initiatives will not trigger for team notifications.
>
> Initiative reminders alert users 7 days and 1 day before an Initiative's target date. The notification will include the amount of time that remains for an Initiative and a given user's uncompleted action items.

> **Integration configuration errors (users only)**
>
> Integration configuration error notifications notify users with `Configure settings` permissions when the configuration for an integration has been changed and is no longer valid.
>
> Cortex runs a nightly cron job that checks to ensure configurations are valid; when it detects a change that makes the configuration invalid, admins will receive a notification around 2 p.m. UTC alerting them to fix it.

> **Onboarding tips (users only)**
>
> Onboarding tip notifications send out important information about getting started with Cortex. This notification can be enabled or disabled for the workspace and your personal notification settings.

> **On-call changes (users, teams, and entities)**
>
> On-call change notifications are sent to users, teams, and/or entities when the appointed user on call changes. These notifications will go out about 1 hour before an on-call shift.

> **On-call reminder (users only)**
>
> On-call reminder notifications notify the user on call for a given entity 7 days and 1 day before an on-call shift. **Reminder notifications don’t have to go to a designated entity owner.**

> **OpEx mentions (users only)**
>
> OpEx mention notifications go out to users when someone @mentions them in a comment on an [OpEx Review report](/improve/opex-review/using-opex#commenting-on-a-report).

> **OpEx thread activity (users only)**
>
> OpEx thread activity notifications go out to users when someone replies to an OpEx Review comment thread they've commented on, or resolves a thread they started.

> **New scheduled rules created (users, teams, and entities)**
>
> New scheduled rules created notifications go to users, teams, and/or entities when a scheduled rule is added to a Scorecard evaluating an entity they own.
>
> Notifications for draft Scorecards will only trigger for users that have the `Edit Scorecards` permission. Notifications for draft Scorecards will not trigger for team notifications.

> **Rule exemption request (users only)**
>
> Rule exemption request notifications alert users with `Configure Scorecards` permissions when a rule exemption is requested for a given [Scorecard](/standardize/scorecards).
>
> Cortex checks for requested rule exemptions and sends relevant notifications every 10 minutes.

> **Scheduled rules reminder (users, teams, and entities)**
>
> Scheduled rules reminders are sent to users, teams, and/or entities 7 days and 1 day before a scheduled Scorecard rule impacting one of their owned entities goes into effect.
>
> Notifications for draft Scorecards will only trigger for users that have the `Edit Scorecards` permission. Notifications for draft Scorecards will not trigger for team notifications.

> **Score drop (teams and entities)**
>
> Score drop notifications go to teams and entities after an entity is evaluated by a Scorecard, if its score dropped.

> **Verification period started (users only)**
>
> Verification period started notifications go out to users when a verification period begins that impacts one of their entities.

> **Verification period reminder (users only)**
>
> Verification period reminders go out to users on Mondays with information about entities that require verification during ongoing verification periods.

> **Weekly report (users, teams, and entities)**
>
> Weekly report notifications go out to users, teams, and/or entities on Mondays with information about entities associated with that user. These notifications will let users know how their entities are performing against Scorecards and Initiatives. This will include scores that improved or dropped, pull requests that are open and waiting for your review, and Jira tickets assigned to you.
>
> The team-based weekly report notification also includes information about who is on call for entities owned by that team.

> **Workflow status (users only)**
>
> Workflow status updates go out to users if a workflow fails or if someone runs a workflow that requires approval.

## How notifications are triggered

Draft Scorecards and Initiatives only trigger notifications for users with the `Edit Scorecards` permission.

| Notification type | Cortex will notify you: |
| - | - |
| **Entity evaluation** | When Scorecard scores for a given entity are re-evaluated because of changes to that entity's `cortex.yaml` |
| **Initiative creation** | With information about recently created Initiatives you are a part of |
| **Initiative custom scheduled reminders** | Information about a given Initiative's progress at a cadence defined by the Initiative owner |
| **Initiative reminders** | Reminders a few days before a given Initiative expires with the remaining action items |
| **Integration configuration errors** | If any of your integration configurations are invalid and need to be updated |
| **Onboarding tips** | With a welcome message and important information, including a set of onboarding tips |
| **On-call changes** | When on-call changes for an entity you own |
| **On-call reminder** | With a reminder a few days before you're on call |
| **OpEx mentions** | When someone mentions you in a comment on an OpEx Review report |
| **OpEx thread activity** | When someone replies to an OpEx Review thread you've commented on, or resolves a thread you started |
| **Rule exemption request** | When a Scorecard rule exemption is requested |
| **Weekly report** | Details about how your entities are tracking against Scorecards and Initiatives (sent on Mondays) |
| **Workflow status** | When a workflow fails or someone runs a workflow that requires approval |

## Troubleshooting and FAQ

#### I didn't receive an expected notification. How can I troubleshoot this?

Ensure that the user has an email address defined. Check whether the user has disabled the notification in their [My notification settings](https://app.getcortexapp.com/admin/settings/notification-subscriptions) page. Please also ensure that the user type is allowed to receive notifications, as configured in your workspace [notification settings](/configure/settings/notifications#configure-what-type-of-user-can-receive-notifications).


# Notification logs
Source: https://docs.cortex.io/configure/settings/notifications/logs



Notification logs allow you to understand and monitor what [notifications](/configure/settings/notifications/logs) are being sent for your workspace, who they're sent to, and how users are engaging with them.

![See the notification list on the notification logs page](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/notification-logs-page.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=f08775cde2a9dd7d6265af69593e739c)

### Log retention

Notification logs are retained for 30 days, and the contents of the notifications are retained for 14 days.

## Accessing notification logs in Cortex

You can view notification logs in the Cortex UI or fetch them through the [Cortex API](/configure/settings/notifications/logs#access-notification-logs-via-api).

### Access notification logs via the Cortex UI

Users with the `View notification logs` permission can access notification logs in Cortex under [**Settings > Notification logs**](https://app.getcortexapp.com/admin/settings/notification-logs).

**Notification log summary**

The summary at the top of this page includes:

* A count of how many notifications are enabled
  * In the upper right corner of the Notification logs page, click **Workspace notifications** to visit the Notifications page where you can review the list of enabled notifications.
* The number of notifications delivered in the last 7 days
* The number of notifications that failed to deliver in the last 7 days

![The notification log summary is at the top of the page](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/notification-log-overview.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=1876465b9efbe90ac35f823a09137e88)

**Notification log list fields**

The list of notifications includes:

* Timestamp when the notification was sent
  * The timestamp is based on the client timezone from your browser. Hover over the timestamp to view the timezone being used.
* The name of the notification
  * An icon appears next to the notification name to indicate which medium was used to notify the user.
* The status
  * Statuses include:
    * `Completed`: The message was delivered successfully.
    * `Completed with errors`: Some recipients received the notification, but some did not. Click the notification to review details.
    * `Failed`: Notification failed to be delivered.
    * `Ignored`: The notification was ignored. This can occur for several reasons, including:
      * `Disabled workspace`: This status will appear if the notification medium has been disabled for the workspace, but there was an attempt to send a notification via that medium. For example, if an email notification is triggered, but email notifications are disabled for the workspace.
      * `Scorecard disabled`: Notifications are disabled for a scorecard.
    * `Created`: The notification has not yet been sent. If this occurs, try [resending the notification](/configure/settings/notifications/logs#resend-a-notification).
* How many times it was sent
* The object that triggered the notification (e.g., a Scorecard, entity, initiative, etc.)
* The ability to resend the notification.

### Filter the notification logs list

1. In the upper right corner of the list, click **Filter**.
2. Select and configure filters for any of the following:
   * Failed reason
   * Ignored reason
   * Notification source
   * Notification type
   * Status

     ![Click the Filter icon then apply filters](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/notification-log-filter.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=72e1b3506a5df6dfee2c78a50da286dc)
3. Click **Apply**.

You can also sort by date:

1. Click **Date** in the upper right corner.
2. Choose whether to sort ascending or descending.

### **View more information about a notification**

Click into a log to open a side panel showing the date a notification was sent, when it was last resent, who the recipients of the message were, and the contents of the notification:

![A side panel shows more details about the notification](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/notif-log-example.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=dd9b9b1c7fa5f02b39625152a9492503)

Notification logs are retained for 30 days, and the contents of the notifications are retained for 14 days.

## **Resend a notification**

Users with the `Execute notification logs` permission can resend a notification to all users, or to specific users.

To resend a notification:

1. Locate the notification in the list.
2. In the row for the notification, click the **Resend** icon on the right side. ![Click the Resend icon at the end of the row](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/resend-notifications.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=1542668949386b574caf17732d6cb431)
3. A confirmation modal will appear.
   1. If the previous notification did not successfully send to all recipients, you will have the option to only resend to recipients who didn't receive the notification.

      ![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/resend-modal.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=667e7ef6d621c24fe81cd39b9c20ea6b)
4. Click **Resend notification**.

## Access notification logs via API

Notification logs can also be accessed through the [public API endpoint](/api/rest/notification-logs).


# Scorecard settings
Source: https://docs.cortex.io/configure/settings/scorecard



In Settings, admins can adjust general settings for Scorecards and view a list of Scorecard rule exemptions.

## **Accessing Scorecard settings**

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Scorecards**.
4. For general preferences, select the **General** tab. To view exemptions, select the **Rule exemptions** tab.

## General tab

![Scorecards Settings](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-settings.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=f595602958667027543390d6c7f2d8b1)

From the **General** tab, admins can configure the following preferences.

In the **Preferences** section:

* **Show absolute scores in Scorecards** - Toggle this setting on to show scores as absolute scores rather than percentages. This toggle affects the setting for all users.
* **Aggregate child scores in Team Scorecards by default** - Toggle this setting on to default to showing aggregated child scores on Team Scorecards.
* **Aggregate child scores in Domain Scorecards by default** - Toggle this setting on to default to showing aggregated child scores by default on Domain Scorecards.

In the **Scorecard evaluation window** section:

* **Minimum evaluation window** - Enter the minimum number of hours between Scorecard evaluations. The default is 4 hours, which is also the shortest window you can set. Increase this value to evaluate a Scorecard less often.
* **Default evaluation window (in hours)** - By default, Scorecards are evaluated every 4 hours. You can set a longer evaluation window (in hours), but not a shorter one.

## Rule exemptions tab

From this tab, admins can view a list of all rule exemptions. They can accept, reject, and revoke exemptions from this page.

![Scorecards Exemptions Settings List](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-exemptions-settings-list.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=fde7db25e8bd92053eaa042eb02c5237)

Do any or all of the following:

* Click **Filter** to narrow the list by status, entity, group, rule, requester, or approver.
* Click **Timestamp (default)** to sort exemptions based on expiration, rule, Scorecard, status, and timestamp (new to old OR old to new).
* On an exemption card, click **Details** to see who requested the exemption and when, the reason they gave, who approved it and when, and its expiration date.

Learn more about managing exemptions in [Scorecard rule exemptions](/standardize/scorecards/rule-exemptions).


# Using search in Cortex
Source: https://docs.cortex.io/configure/settings/search



Cortex offers two ways to search across your data:

* The **catalog search bar** is found in the upper-right corner of a list, e.g. the catalog list.
* The **global search** is found at the top of the main sidebar and lets you run a quick search from anywhere in Cortex across names, descriptions, and tags.

## Using the catalog search bar

When you need to find a specific entity in Cortex, use the search bar at the top of any catalog. See the [available operators](/configure/settings/search#search-index-and-operators) below.

1. Navigate to a catalog.
2. In the upper-right corner, enter text into the search bar. Note that you can use plain text for a basic search, or use operators to refine your search.\


   ![The search bar, located in the upper-right corner of a catalog page.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/entity-search-bar%20%281%29.png)

### Search suggestions and recent searches

The search bar shows you which fields it can search against, so you don't have to remember the syntax. Click into the search bar to see the available fields:

* Title (entity title)
* Tag
* Group
* Owner
* Member
* Repository

Select a field to add it to your query. Cortex keeps the results open while you keep refining.

As you type, the search bar shows which field your query is matching on. By default, a query matches on the entity's name. To match on something else, select a field from the search bar or enter its operator directly. For the full list, see [Search index and operators](/configure/settings/search#search-index-and-operators).

If you've searched this catalog before, your recent searches appear as a section in the search bar. Select one to run it again. Recent searches drop out of the list as you type, once they no longer match what you've entered.

### **Query syntax**

The catalog search bar supports web search–style syntax:

| Syntax | Example | Behavior |
| - | - | - |
| Multiple terms | `payments api` | Implicit AND — returns results matching all terms |
| `or` keyword | `payments OR billing` | OR — returns results matching either term |
| Quoted phrase | `"payment service"` | Matches the exact phrase |
| Negation (`-`) | `payment -legacy` | Excludes results containing the term after `-` |
| `field:value` | `owner:maya.chen@acme.com` | Scoped to a specific field (see table below) |

You can combine these: `owner:maya.chen@acme.com tag:payments -deprecated`

### Search index and operators

Cortex supports field-based specifiers for searching. A `prefix:value` token is treated as a field filter only when the prefix is a recognized search field (such as `owner:`, `tag:`, or `repo:`). Colons and other special characters in unrecognized positions are treated as plain text, so queries like `https://example.com` won't break. To search for a multi-word value, wrap it in double quotes (e.g., `owner:"Maya Chen"`).

| Search field | Corresponding YAML field | Explanation | Examples (based on sample YAMLs below) |
| - | - | - | - |
| `title:` or `name:` | `title` | Searches for the entity's name as defined in the `title` field. | • payments api • payments • title:"payments api" • name:"payments api" |
| `tag:` | `x-cortex-tag` | Searches for a Cortex tag as defined in the `x-cortex-tag` field. If a tag has more than one term separated by a hyphen, you can search for the tag using hyphens or spaces. At least one of these (or a wildcard) must be used for results to be generated. | • payments-api • payments • tag:"payments-api" • tag:"payments" |
| `group:` | `x-cortex-groups` | Searches for entity group names. | • payments • backend • group:"payments" • group:"backend" |
| `owner:` | `x-cortex-owners` | Searches for the owner(s) of an entity. If the owner is a team, Cortex searches team names and team members' names and email addresses. If the owner is an individual, Cortex searches for the user email. | • payments engineering • maya.chen • owner:"payments" • owner:"maya" |
| `member:` | `x-cortex-team`, `members` | Searches for the name and email address for a team member. This query only returns Team entities. | • maya chen • maya.chen • member:"maya" • member:"chen" |
| `repo:` or `repository:` | `x-cortex-git`, `repository` | Searches for a Git repository name. | • acme/payments-api • payments-api • repo:"payments-api" • repo:"acme/payments-api" |
| `cid:` | (depends on integration) | Searches for an ID associated with an entity. This usually comes from a third-party integration. | • P1AB2CD • cid:"P1AB2CD" |
| `description:` | `description` | Searches for the supplied term(s) in an entity's description. | • payment processing • transaction management • description:"payment" - description:"transaction" |
| `slack:` | `x-cortex-slack` | Searches for a Slack channel name defined in the `x-cortex-slack` field. | • payments-alerts • payments-eng • slack:"payments-alerts" • slack:"payments" |
| `microsoft-team:` | `x-cortex-microsoft-teams` | Searches for a Microsoft Teams channel name defined in the `x-cortex-microsoft-teams` field. | • payments-alerts • Payments Engineering • microsoft-team:"payments-alerts" • microsoft-team:"payments" |
| `repo-basepath:` or `repository-basepath:` | `x-cortex-git`, `basepath` | Searches for a Git repo basepath name. | • services/payments • repo-basepath:"services/payments" |
| `link:` | `x-cortex-link` | Searches for link based on `name` and `URL` defined under `x-cortex-link`. | • runbooks.acme.com • payments api runbook • link:"runbook" • link:"runbooks.acme" |
| Custom data (`key`:`value`) | `x-cortex-custom-metadata` | Searches for custom data imported from APIs, third-party integrations, and/or defined in the `x-cortex-metadata` block. The key is case-sensitive. | • tier:1 • region:us-east-1 |
| `aws-account-id:` | Defined in AWS, not in an entity's YAML | Searches for the AWS account ID of an entity. | • aws-account-id:"012345678901" |
| `aws-account-name:` | Defined in AWS, not in an entity's YAML | Searches for entities with an AWS account name. | • aws-account-name:"example-aws-account" |
| `aws-region:` | Defined in AWS, not in an entity's YAML | Searches for entities in an AWS region. | • aws-region:"us-west-1" |
| `aws-type:` | Defined in AWS, not in an entity's YAML | Searches for entities of a given AWS entity type. | • aws-type:"lambda" |
| `aws-name:` | Defined in AWS, not in an entity's YAML | Searches for an AWS entity name. | • aws-name:"abc-lambda" |
| `aws-identifier:` | Defined in AWS, not in an entity's YAML | Searches for an AWS primary identifier. | • aws-identifier:"value" |
| `aws-secondary-identifier:` | Defined in AWS, not in an entity's YAML | Searches for an AWS secondary identifier. | • aws-secondary-identifier:"value" |
| `aws-arn:` | Defined in AWS, not in an entity's YAML | Searches for an Amazon Resource Name (ARN). This is not supported for Cloud Control types. | • aws-arn:"arn:aws:iam::123456789012:user/johndoe" |

#### Example YAML files

The YAML files below show what an entity might look like based on the examples in the table above:

**'Payments API' entity YAML**

```yaml theme={null}
info:
  title: Payments API
  description: Core service handling payment processing and transaction management.
  x-cortex-tag: payments-api
  x-cortex-type: service
  x-cortex-groups:
    - payments
    - backend
  x-cortex-git:
    github:
      repository: acme/payments-api
      basepath: services/payments
  x-cortex-link:
    - url: https://runbooks.acme.com/payments-api
      name: Payments API runbook
      type: RUNBOOK
  x-cortex-owners:
    - name: payments-engineering
      type: group
      provider: CORTEX
    - type: email
      email: maya.chen@acme.com
  x-cortex-oncall:
    pagerduty:
      id: P1AB2CD
      type: SERVICE
  x-cortex-slack:
    channels:
      - name: payments-alerts
        notificationsEnabled: true
      - name: payments-eng
        notificationsEnabled: true
  x-cortex-microsoft-teams:
    channels:
      - name: payments-alerts
        teamName: Payments Engineering
        description: Alerting channel for the Payments Engineering team.
        notificationsEnabled: true
  x-cortex-metadata:
    tier: "1"
    region: us-east-1
```

**'Payments engineering' team YAML**

```yaml theme={null}
info:
  title: Payments Engineering
  description: Team responsible for payment processing services and infrastructure.
  x-cortex-type: team
  x-cortex-tag: payments-engineering
  x-cortex-team:
    groups:
      - name: acme/payments-engineering
        provider: GITHUB
    members:
      - name: Maya Chen
        email: maya.chen@acme.com
        notificationsEnabled: true
```

### When a search returns no results

When a search returns nothing, Cortex explains why instead of showing an empty list. The empty state tells you what the query matched on and suggests other searches to try, along with the number of results each suggestion would return. Select a suggestion to run it.

A few other things to check when a search comes up empty:

* The term you're looking for might live in a field other than the name, such as the owner or the repository. Try one of the suggested searches, or enter the operator yourself, for example `owner:"Maya Chen"` or `repo:"payments-api"`.
* Multiple terms are combined with an implicit AND, so `payments api` only returns entities matching both. Use `OR` to broaden the search, as in `payments OR billing`.
* Check for a stray `-` in your query. Anything after a hyphen is excluded from the results.
* The entity might be archived. Click **Display**, then turn on the option to show archived entities.
* You might be on the **Mine** tab, which only covers entities you own or are a member of. Select the **All** tab to search across every entity.

## Using global search

You can search the Cortex platform from any page using the global search function. Global search pulls from names, descriptions, and tags.

> [!NOTE]
>
> In-app quick search (Cmd+K) includes entity type filter chips, letting you narrow results by type—service, domain, resource, and more—without leaving the keyboard-driven flow.

1. From the main sidebar, click **Search**. The **Search** window opens.\


   ![The global search option, located in the main sidebar.](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/global-search.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=cb81db584ff0a04127830ba015cc67ca)
2. Enter text into the search bar.

Cortex global search covers all items by default, with tabs available to filter results by entities, Initiatives, catalogs, plugins, Scorecards, Workflows, or CQL reports. Clicking any result navigates directly to that item.

The first 10 results are displayed in the modal. Click **See all** to view additional results.

![The highlighted 'See all' link, used to view all search results.](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/in-app-search.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=be5fa89553f40cbf511d34b4b67c82ff)

Optionally, in the bottom-right corner of the **Search** window, toggle on **Show archived** to include archived items in the search results. Cortex saves your selection and restores it the next time you open this window.

![The highlighted 'Show archived' toggle in the bottom-right corner of the Search window.](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/in-app-search2.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=4529f05e4764b6e3a68efa05ba402e82)

## Search AWS details

Additional keys are available for searching AWS details in Cortex. See [Searching AWS entities in Cortex](/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws#searching-aws-entities-in-cortex) for more information.


# Customizing your workspace
Source: https://docs.cortex.io/configure/settings/workspace-customization



Cortex is built around customization, and the plugin framework extends this to the appearance of your workspace.

## Customizing the look of Cortex

Users with the `Configure Appearance Settings` permission can adjust workspace appearance settings.

1. From the main sidebar, click your avatar in the bottom-left corner.

   ![The circle icon with your initials in the bottom-left corner.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/avatar.png?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=698acd8b31d3c09550401b8a05e474d4)
2. Click **Settings**.

   The *General* settings page is displayed.
3. Do any or all of the following:
   1. View your organization's billing information, including user login information.
   2. Upload your organization's logo. The recommended minimum file size to display the logo in the expanded navigation is `200px x 80px`, and `80px x 80px` for collapsed navigation.
   3. Edit your organization's workspace name.
   4. Edit your organization's workspace brand colors. Note that this be a hex code, e.g. #800080.
4. Click **Save changes**.

## Customizing the main sidebar

* Users with the `Configure Appearance Settings` permission can adjust workspace appearance settings.
* Users with the `Configure Plugin Appearance` permission can configure where plugins appear.

Follow the steps below to reorder the main sidebar, controlling which catalogs and plugins appear and in what order.

1. From the main sidebar, click your avatar in the bottom-left corner.

   ![The circle icon with your initials in the      bottom-left corner.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/avatar.png?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=698acd8b31d3c09550401b8a05e474d4)
2. Click **Settings**.
3. Select the **Main sidebar** tab.
4. From the **Catalogs** tab, do the following:
   1. Locate the catalog you want to reorder.
   2. Hover over the **grip icon** and drag it to the desired position.
5. From the **Plugins** tab, do the following:

   1. Locate the plugin you want to reorder.
   2. Hover over the **grip icon** and drag it to the desired position.
   3. To remove a plugin from the main sidebar, click the **trash icon** next to it.
   4. To add a plugin to the main sidebar, click the *Select plugins* drop-down menu and select the plugin you want to add.

   A maximum of 5 plugins can be displayed in the main sidebar. If 3 or more are selected, they are nested under **Plugins**. Note that only plugins with a global context appear in the main sidebar.
6. Click **Save changes**.

> [!NOTE]
>
> For more information on customizing where plugins appear in Cortex, see [Viewing plugins](/streamline/plugins#viewing-plugins).


# Cortex AI chat
Source: https://docs.cortex.io/cortex-ai-chat

Ask Cortex AI questions about your engineering data from anywhere in Cortex

RESEARCH PREVIEW

Cortex AI is Cortex's AI-powered chat assistant. It answers questions about your engineering data in plain language, using the same data that powers your Scorecards, dashboards, and reports.

Questions that would otherwise become a research task, like who owns this service, which teams are behind on a Scorecard, or how deployments are trending over the last quarter, get answered where you are, without assembling the data yourself. Every answer is grounded in your real Cortex data.

> [!WARNING]
>
> **Cortex AI is not limited to the entities you can see**
>
> * Anyone with the Enable AI Chat permission can ask about any metric or Scorecard score for any entity in your workspace, including ones hidden from them elsewhere in Cortex.
> * Your own conversations stay private.
>
> ​Treat the `Enable AI Chat` permission as access to your organization's engineering data as a whole, and grant it accordingly.

> [!NOTE]
>
> **Cortex AI chat is in Research Preview**
>
> * Responses can be slow, especially for questions spanning many teams or entities.
> * Not all Cortex data is reachable from chat yet, so it can't answer every question about your organization.
> * It can't take action on your behalf. It won't create or edit Scorecards, Initiatives, Dashboards, or Workflows, and it won't change the report's content or filters.
>
> ​We're actively working on improvements. Share feedback with your account team or through the in-product feedback controls.

# Accessing Cortex AI

​`Admins` and users with the `Enable AI Chat` permission can use Cortex AI. The same permission covers chat inside OpEx Review. It does not cover the [Slack AI assistant](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#using-the-ai-assistant) or the [Cortex MCP](/get-started/cortex-ai-assistant/mcp), which have their own access.

​There are two ways to access Cortex AI chat, and they share the same conversations:

## ​Ask Cortex AI

​**Ask Cortex AI** sits at the bottom of the main sidebar and opens chat in a panel beside whatever you're looking at, so you can ask a question without losing your place.

1. ​Click **Ask Cortex AI** in the main sidebar, or press **⌘J** (**Ctrl+J** on Windows and Linux).

   !['Ask Cortex AI', highlighted at the bottom of the main sidebar.](https://mintcdn.com/cortex-290c0c42/z5k1sDZlDmCOZ-iP/images/cortex-ai-sidebar.png?fit=max\&auto=format\&n=z5k1sDZlDmCOZ-iP\&q=85\&s=1f2f479a987c78a313a42e8a3a28f6be)
2. Enter your question, then press **Enter**.

​The side panel follows you as you navigate. On an entity or Scorecard page, Cortex AI grounds your next question in what you're looking at. This means you can ask "who owns this?" or "why is this failing?" without naming the thing. Move to a different page and the line updates, so you always know what your next question will be about.

​Press the shortcut again to close the panel. The conversation stays as you move around Cortex, so closing and reopening the panel picks up where you left off.

## Cortex AI

**Cortex AI** in the main sidebar opens a dedicated page built for longer sessions, with your conversation history beside the chat.

## What you can ask

Cortex AI is built for the questions that come up while you're working, rather than for a fixed set of reports. For example:

* ***Who owns payments-service, and when was it last deployed?***
* ***Which services are failing our production readiness Scorecard, and what's the most common failing rule?***
* ***How has deployment frequency changed for my teams over the last quarter?***
* ***Which Workflows have been failing this week?***
* ***What's the status of our Go 1.22 migration Initiative?***
* ***How do I set up a custom Scorecard rule?***

Cortex AI can reach:

* **Your catalog** - Entities, ownership, teams, and entity details
* **Scorecards** - Definitions, scores, and how entities are performing against them
* **Initiatives** - What's in flight and how it's progressing
* **Workflows** - Recent runs and which ones are failing
* **Eng Intelligence metrics** - Deployment frequency, cycle time, incident metrics, and custom metrics, broken down by team, entity, or time period
* **Cortex documentation** - How a Cortex feature works, answered from the public docs

To compare what Cortex AI can reach with the Slack AI assistant and the Cortex MCP, see [Data available in each channel](/get-started/cortex-ai-assistant#data-available-in-each-channel).

See the [Cortex AI prompt library](/get-started/cortex-ai-assistant/library) for a full list of prompt patterns organized by use case and role.

### Managing your conversations

On the Cortex AI page, your past conversations are listed beside the chat.

![The Cortex AI page with past chats highlighted.](https://mintcdn.com/cortex-290c0c42/z5k1sDZlDmCOZ-iP/images/cortex-ai-past-convos.png?fit=max\&auto=format\&n=z5k1sDZlDmCOZ-iP\&q=85\&s=7621c008160d42a3ae5882535aa18714)

To access the Cortex AI page, select **Cortex AI** from the main sidebar. From this page you can:

* Select a chat to pick it back up.
* While in a chat, click the **overflow menu icon** in the upper-right corner to rename or delete it.
* Click **New chat** to start a fresh conversation.

A conversation you started from an OpEx Review report includes a link back to the report it originated from.

### Who can see your chats

Your conversations are private to you. Nobody else in your organization can see them, including admins, and they aren't visible to anyone you send the URL to; a conversation link only opens for the person who created it.


# AI in Cortex
Source: https://docs.cortex.io/get-started/cortex-ai-assistant

All of the ways you can interact with Cortex

Cortex answers natural-language questions about your engineering data—services, ownership, Scorecards, Initiatives, incidents, deployments, and more—so you can get answers without digging through the UI yourself. However you ask, answers are grounded in your real Cortex data and respect each individual's permissions.

* **In Slack via the AI assistant** - Mention `@Cortex` in a channel or DM to ask questions in plain language. See [Using the AI Assistant](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#using-the-ai-assistant) for more information.
* **In your AI tools via MCP** - Connect the [Cortex MCP](/get-started/cortex-ai-assistant/mcp) to ask questions from the tools your team already uses.
* **In Cortex via Cortex AI** - [Cortex AI](/cortex-ai-chat) is Cortex's AI-powered chat assistant. It answers questions about your engineering data in plain language, using the same data that powers your Scorecards, dashboards, and reports.

> [!NOTE]
>
> Cortex AI is in Research Preview and available to a limited group of customers. To request access, reach out to your Customer Success Manager.

Here are a few prompt examples for you to get started with:

* ***What are the patterns of incidents on my team over the last 2 quarters? What areas do you recommend we invest in to improve the reliability of our services?***
* ***Give me a summary of everything I worked on and my key accomplishments over the last quarter.***
* ***Has there been an increase in PR sizes recently? Does that correlate with longer review times?***
* ***What is our deployment frequency for the last 30 days across the services I own? Are there any patterns that may be causing that to change compared to the last quarter?***

See the [Cortex AI prompt library](/get-started/cortex-ai-assistant/library) for a full list of prompt patterns organized by use case and role.

## Data available in each channel

Cortex AI chat, the Slack AI assistant, and the Cortex MCP don't all reach the same Cortex data yet. Use the table below to choose the right channel for your question. Each channel respects your permissions in Cortex.

| Data | Cortex AI chat | Slack AI assistant | Cortex MCP |
| - | - | - | - |
| Entities and ownership | Yes | Yes | Yes |
| Teams | Yes | Yes | Yes |
| Scorecards and scores | Yes | Yes | Yes |
| Initiatives | Yes | Yes | Yes |
| Workflows | Yes | Partial (status alerts) | Yes |
| Eng Intelligence metrics (DORA and custom metrics) | Yes | Yes | Yes |
| Pull requests, deployments, and CI | Yes | Partial | Yes |
| OpEx Review report content | Yes | No | No |
| Entity relationships | Partial | Yes | Yes |
| Dependencies | No | Yes | Yes |
| On-call | No | Yes | Yes |
| Custom data | No | Yes | Yes |
| Custom events | No | Yes | Yes |
| Documentation, log, and runbook links | No | Yes | Partial |
| Your entities ("Mine") | Partial | Yes | Yes |
| Cortex documentation | Yes | Yes | Yes |

For the full list of what each channel can query, see [What you can ask](/cortex-ai-chat#what-you-can-ask) for Cortex AI chat, [Available capabilities](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#available-capabilities) for the Slack AI assistant, and [Available MCP tools](/get-started/cortex-ai-assistant/mcp/using-cortex-mcp#available-mcp-tools) for the Cortex MCP.


# Cortex AI prompt library
Source: https://docs.cortex.io/get-started/cortex-ai-assistant/library

Prompts for the AI Assistant and MCP

This article contains prompts for interacting with Cortex, inspired by how high-performing engineering teams use Cortex every day. The prompt examples in this article represent effective patterns across different roles and workflows. Use them as a starting point for building your own prompt library tailored to your team and organization.

Remember:

* **Be specific** - Instead of ***Tell me about services.***, you could say, ***Show me all critical services failing the Production Readiness Scorecard***. This provides you with more actionable information.
* **Combine multiple questions when context helps** - Cortex handles complex prompts like ***Who owns orders-api, when was it last deployed, and are there any open incidents?*** You receive richer context in response to one question instead of piecing together three separate queries.
* **Reference your organization's specific constructs** - If you've defined custom Scorecards or Initiatives in Cortex, reference them by name. Cortex understands your organization's specific standards and can query against them directly.
* **Use follow-up questions to drill down** - Start broad, then go narrow. ***Show me services with failing Scorecards***, followed by ***What specific checks is checkout-service failing?*** moves you from landscape view to action items.
* **Build a library of your most-used prompts** - If you ask the same question every Monday morning, save it. Some teams maintain shared prompt libraries so everyone can benefit from patterns that work.

## Use-case based prompts

### Incident response

| Prompt | What it does |
| - | - |
| ***Who owns payments-api and who's currently on-call?*** | Gets you the right contact immediately so you can escalate or start investigating. |
| ***What changed in checkout-service in the last 24 hours?*** | Most incidents trace back to a recent change, so this is usually the fastest path to identifying the root cause. |
| ***Which services depend on user-auth? Who do I need to loop in?*** | Understanding the blast radius of an incident helps you get the right teams involved before downstream impact compounds. |
| ***What are the top P1 incident drivers on my team this quarter?*** | Surfaces patterns across incidents so you can address systemic causes rather than treating each one as isolated. |
| ***How is our mean time to resolution trending compared to last quarter?*** | Gives you a clear signal on whether your reliability investments are actually improving response time. |

### Service ownership

| Prompt | What it does |
| - | - |
| ***Which services have no defined owner?*** | Unowned services are the ones most likely to fall through the cracks during an incident, audit, or migration. |
| ***Show me all Tier 1 services with no team assigned.*** | Tier 1 services without ownership represent your highest-risk gap. |
| ***Which of our upstream dependencies have no on-call rotation configured?*** | A dependency without on-call coverage means there's no clear path to resolution if it goes down after working hours. |
| ***If the data-platform team goes on a code freeze, which of our services are affected?*** | Helps you proactively identify risk and communicate impact before a freeze causes surprises. |

### Production readiness

| Prompt | What it does |
| - | - |
| ***Which of my team's services are failing the Production Readiness scorecard?*** | Gives you a prioritized view of which services need attention before gaps become incidents. |
| ***Which services are Tier 1 but haven't passed Production Readiness?*** | Your most critical services should meet the highest bar; this tells you exactly where that's not the case. |
| ***What are the most common gaps across my team's services?*** | Identifying patterns in failures helps you address systemic issues rather than fixing services one by one. |
| ***Which services have no runbook, no on-call rotation, or no defined owner?*** | These three gaps together represent a service that no one can reliably respond to when something goes wrong. |

### Engineering health and trends

| Prompt | What it does |
| - | - |
| ***What are the incident patterns on my team over the last two quarters?*** | Reveals whether your reliability posture is improving over time or if the same failure modes keep recurring. |
| ***Has PR size increased recently? Does that correlate with longer review times?*** | Large PRs slow down review cycles and introduce more risk. This tells you whether the two are connected on your team. |
| ***Which teams have improved their deploy frequency the most this quarter?*** | Deployment frequency is a leading indicator of team velocity and confidence, so knowing who's improving helps you identify what's working. |
| ***What's the overall operational maturity trend for my org over the last 6 months?*** | A high-level view of whether your implementation investments are moving the needle across the organization. |
| ***Summarize the key engineering health metrics for my org — I need this for a leadership review.*** | Pulls together the data you'd otherwise spend hours assembling from dashboards, spreadsheets, and status updates. |

### New hire onboarding

| Prompt | What it does |
| - | - |
| ***What dependencies does my team's services have and who owns them?*** | The fastest way to understand your team's scope of responsibility without waiting for someone to walk you through it. |
| ***Which of our services have open action items or are failing their Scorecard?*** | Surfaces the most pressing work on your team so you can start contributing without needing a full handoff. |
| ***Give me a summary of what my team has shipped in the last 90 days.*** | Gets you up to speed on recent deployments so you can have informed conversations with your team from day one. |

### Migration tracking

| Prompt | What it does |
| - | - |
| ***Which services have been migrated to \[NEW PLATFORM] and which are still pending?*** | Gives you a real-time view of migration progress without chasing teams for status updates. |
| ***Which teams haven't completed the migration yet and what's blocking them?*** | Surfaces where the migration is stalling so you can direct support to the right places before deadlines slip. |
| ***Which migrated services are failing their scorecard since the cutover?*** | Catches regressions introduced by the migration before they turn into incidents or compliance gaps. |
| ***What's the migration completion rate across the org this quarter?*** | Tracks overall migration progress across the org so you know whether you're on pace to hit your target or need to intervene. |

## Role-based prompts

### Prompts for engineers

The best prompts for engineers eliminate context switching at the moments when focus matters most.

#### Understanding unfamiliar services

| Prompt | What it does |
| - | - |
| ***Tell me about the \[SERVICE NAME] service, including who owns it, what it does, and where the documentation lives.*** | Pulls everything from your Cortex catalog at once. You get ownership, a description of what the service does, links to documentation, and the team's communication channels. Instead of hunting across wikis, Slack, and GitHub, you have the context you need to start working. |
| ***Show me the dependencies for \[SERVICE NAME]. Which services does it depend on, and which services depend on it?*** | Understanding the dependency graph is critical when planning changes with potential downstream impact. This prompt reveals what might break and which teams need to be in the conversation before you make a move. |
| ***Which Scorecard is \[SERVICE NAME] failing, and what do I need to fix?*** | Transforms maintenance from reactive to proactive. Instead of waiting for your platform team to flag issues or discovering gaps during an incident, you see exactly which Scorecards are failing and what specific checks need attention. You can address production readiness, security, or documentation gaps on your own schedule, before they become blockers. |

#### During code review

| Prompt | What it does |
| - | - |
| ***Check the Scorecards for \[SERVICE NAME]. Does this service meet our production readiness standards?*** | Starting here when you're unfamiliar with a service changes the conversation. If the service is already failing key Scorecards, you'll know which questions to ask and where the risks actually are. |
| ***Show me recent incidents for \[SERVICE NAME].*** | Past incidents tell you where a service has been fragile. When you see that history before approving changes, you can evaluate whether the PR addresses root causes or introduces new failure modes. |

#### Tracking work

| Prompt | What it does |
| - | - |
| ***What Initiatives are assigned to the Engineering team, and what's the status of each?*** | Condenses your weekly status check into a single query. Run it at the start of your week or during standup and you get a complete picture of your Initiative commitments and their current state. Instead of navigating to the Cortex web UI or mentally tracking what you're responsible for, you see everything assigned to you without leaving your IDE or chat interface. |
| ***Show me the details for \[INITIATIVE NAME]. What still needs to be done?*** | When you're ready to make progress on a specific Initiative, this surfaces the remaining tasks and their current state. You know exactly what's left and where to focus. |

### Prompts for engineering leaders

The best prompts for engineering leaders are about trends, patterns, and the health of systems; these prompts surface the signals that inform strategic decisions.

#### Understanding team health

| Prompt | What it does |
| - | - |
| ***Show me MTTR trends over the last quarter. How has it changed?*** | Incident response either gets faster or it doesn't. If MTTR is climbing, something in your system has degraded. This prompt gives you the trend line and a clear signal to investigate process or tooling gaps. |
| ***Which teams have the most failing Scorecards right now?*** | Surfaces which teams are struggling with compliance or buried in technical debt. The answer reveals where support and resources should flow. Instead of waiting for teams to escalate problems or discovering issues through incident patterns, you have a clear view of which teams need help right now. That visibility lets you have proactive conversations about priorities, staffing, or process changes before compliance gaps become production incidents. |
| ***How has deployment frequency changed over the last six months for the Platform team?*** | Deployment frequency serves as a proxy for both velocity and confidence. When you track this metric over time, you get clear evidence of whether your investments in tooling and process improvements are actually working.If deployment frequency is climbing, teams are shipping faster and feel confident doing it. If it's flat or declining despite investments, you need to investigate whether new tools are adding friction, whether processes are getting in the way, or whether something else is slowing teams down. The trend line tells you whether to double down on your current approach or change course. |

#### Tracking AI adoption impact

| Prompt | What it does |
| - | - |
| ***How has AI adoption impacted MTTR and deployment frequency over the last quarter?*** | Connects AI spending directly to concrete business outcomes. When you run this query, you're comparing metrics before and after AI tool adoption. If MTTR dropped and deployment frequency increased after rolling out Copilot or similar tools, you have hard data to justify continued investment and potentially expand the rollout.If the metrics haven't moved despite adoption, you need to ask different questions: Are teams actually using the tools? Do they need more training? Are the tools solving the wrong problems? The comparison gives you evidence to either double down on your AI strategy or course-correct before spending more. |
| ***Which teams have adopted AI tools, and how does their velocity compare to teams that haven't?*** | Reveals whether AI adoption is actually delivering the productivity gains you expected. The comparison between adopters and non-adopters gives you a clear control group to measure impact. If teams using AI tools show meaningfully higher velocity, you have validation to expand the rollout and invest more.If there's no significant difference, or if adopters are actually slower, you need to understand why. Maybe teams need better training on how to use the tools effectively. Maybe the tools work better for certain types of work than others. Maybe adoption is superficial and teams aren't integrating the tools into their actual workflows. The data points you toward the right interventions. |

#### Spotting bottlenecks

| Prompt | What it does |
| - | - |
| ***Where are the biggest bottlenecks slowing down the Checkout team?*** | When a team's velocity drops unexpectedly, this surfaces the patterns that sprint metrics miss: services with high incident rates, missing documentation, or blocked Initiatives. You get data, not speculation. |
| ***Show me services with the highest incident rates in the last month.*** | High incident rates point to deeper reliability issues. This tells you where to invest in stability before those services become everyone's problem. |

### Prompts for platform teams

The best prompts for platform teams show you where adoption is working, where it's stalled, and which teams need support.

#### Tracking standards adoption

| Prompt | What it does |
| - | - |
| ***Show me how teams are performing on the Production Readiness Scorecard. Which services are failing?*** | Gives you a complete view of compliance across the organization without manually checking each team's services. You see which teams are struggling to meet standards and which services create the most risk. The answer tells you where to focus your enablement efforts and which conversations to prioritize. Instead of discovering compliance gaps reactively during incidents or audits, you have a real-time picture of organizational health. |
| ***Which services don't have runbooks, and who owns them?*** | Missing runbooks are incidents waiting to happen. When something breaks at 3 AM, responders need clear guidance to restore service quickly. This prompt shows you exactly which services lack that critical documentation and who's responsible for creating it.With this information, you can prioritize outreach based on service criticality. A critical payment service without a runbook demands immediate attention, while a lower-tier internal tool might wait. Instead of discovering documentation gaps during an active incident when every minute counts, you can systematically close them before they cost you hours of downtime. |
| ***Show me AI maturity Scorecard results across all teams. Where are the biggest gaps?*** | If you're driving AI adoption, this reveals which aspects of maturity need attention. The gaps tell you whether teams need training, tooling, process changes, or something else entirely. |

#### Managing Initiatives

| Prompt | What it does |
| - | - |
| ***Which services are blocking completion of the \[INITIATIVE NAME]?*** | When an initiative stalls, this identifies exactly which services or teams are holding things up. Now you know where to focus your attention and who needs support. |
| ***Show me progress on the Kubernetes Migration Initiative. Which teams are on track, and which are falling behind?*** | Surfaces real-time status across every team involved in the initiative without sending Slack messages or requesting manual updates. You get an immediate picture of which teams are making progress, which are stuck, and which haven't started. That visibility lets you direct support and resources to the teams that need it most, rather than treating every team the same or discovering delays only when deadlines slip. |
| ***Give me a plan to get the Checkout team back on track with production readiness.*** | Once you've identified a team falling behind, this generates a concrete action plan based on the specific gaps in their Scorecards and service metadata. You move straight to solutions. |

#### Gap analysis

| Prompt | What it does |
| - | - |
| ***Which critical services are missing SLOs?*** | SLOs are foundational to reliability. This scopes the gap and identifies which services should be prioritized based on business impact before an incident forces the conversation. |
| ***Show me services without proper monitoring. What's missing?*** | Monitoring gaps are blind spots waiting to bite you during incidents. This surfaces which services need instrumentation and what specific monitoring is absent, so you can build a targeted remediation plan. |

### Prompts for SREs

The best prompts for SRE teams focus on proactive incident prevention or responding quickly to a incident in progress.

#### During incidents

| Prompt | What it does |
| - | - |
| ***Who's on call for \[SERVICE NAME] right now, and when was it last deployed?*** | The first question in almost every incident. One prompt gets you the owner, the on-call contact, and recent deployment history. You can escalate or start investigating without hunting through five different systems. |
| ***Show me recent deploys and changes for \[SERVICE NAME].*** | Most incidents trace back to recent changes. This gives you a timeline pointing to likely culprits so you can focus your investigation on what actually changed. |
| ***Show me the incident readiness Scorecard for \[SERVICE NAME]. Are we prepared to respond?*** | Not all services are equally ready for incidents. This tells you whether runbooks exist, whether monitoring is in place, and whether escalation paths are documented. You know what tools you have before you need them. |

#### Proactive reliability work

| Prompt | What it does |
| - | - |
| ***Show me services with the highest MTTR in the last month.*** | High MTTR means certain services are consistently difficult to debug or restore. This tells you where reliability improvements will have the biggest impact on your time and your team's sanity. |
| ***Which critical services have had the most incidents recently?*** | Frequent incidents signal deeper problems that incident response won't fix. This helps you spot patterns and prioritize services that need architectural investigation, not just patches. |
| ***Show me services that are missing runbooks or escalation procedures.*** | When incidents happen, responders need clear guidance. This identifies documentation gaps that will slow response time before they cost you hours during an outage. |

### Prompts for security engineering teams

The best prompts for security engineers help them monitor, audit, and enforce security posture across services.

#### Compliance monitoring

| Prompt | What it does |
| - | - |
| ***Which services are failing our SOC-2 Scorecard?*** | Gives you a view of SOC-2 compliance across the organization without manually checking each team's services. The answer tells you where to focus your efforts and which conversations to prioritize. Instead of discovering compliance gaps reactively during incidents or audits, you have a real-time picture of organizational health. |

#### Proactive security health

| Prompt | What it does |
| - | - |
| ***Which services have no on-call rotation configured in PagerDuty?*** | When incidents happen, it's important to have on-call information readily available to ensure a fast response time. |
| ***What is the progress on my Security Initiative and what are some quick wins?*** | Surfaces real-time status for an Initiative without requesting manual updates from team members. You get an immediate picture of which entities are making progress and which are not. That visibility lets you direct support and resources to the teams that need it most. |
| ***List all services with open vulnerabilities labeled CRITICAL or HIGH.*** | Helps determine which services need attention. |

### Prompts for product managers

The best prompts for product managers focus on visibility, delivery health, and compliance to engineering standards that affect product velocity and quality.

#### Delivery and health metrics

| Prompt | What it does |
| - | - |
| ***Which services in the \[PRODUCT AREA] domain are failing their DORA metrics?*** | Gives quick insight into which services in that product area domain are failing DORA metrics. |

#### Initiatives and adoption tracking

| Prompt | What it does |
| - | - |
| ***Give me all currently active initiatives and ideas for how I can improve them.*** | Helps track progress on key initiatives and ensure teams are moving toward business goals. |
| ***Give me links to the docs and runbooks for \[REPOSITORY].*** | Helps find the documentation for a feature's related repository. |


# Cortex MCP
Source: https://docs.cortex.io/get-started/cortex-ai-assistant/mcp



The [Cortex MCP](https://github.com/cortexapps/cortex-mcp) is a Model Context Protocol server that brings your engineering data into the tools your team already works in, enabling natural language queries across your catalog, Scorecards, metrics, and Initiatives.

It provides:

* **Natural language querying** - Ask questions in plain English rather than constructing API calls directly
* **Contextual awareness** - Maintains awareness of your workspace's structure when answering questions, so responses are grounded in your org's actual data
* **AI-assisted insights** - Synthesizes Eng Intelligence metrics, Scorecard status, ownership, and initiative data into actionable recommendations
* **Cross-tool availability** - Surfaces inside the tools your team already uses, making it an in-workflow intelligence layer rather than a standalone API
* **Prompt-driven workflows** - Supports complex, multi-part queries that combine data from multiple Cortex systems in a single response
* **Taking action** - Create and update entities, Scorecards, Initiatives, Workflows, and more from your MCP client, then run Workflows and check the status of each run
* **Documentation querying** - The remote MCP implementation includes a `query_docs` tool that lets you ask questions against Cortex's own documentation and knowledge base in natural language

## Cortex MCP overview

More of a visual learner? Watch the Cortex MCP in action in this short video.

[YouTube video player](https://www.youtube.com/embed/Tjm6nwO4ByQ)


# Configuring the Cortex MCP
Source: https://docs.cortex.io/get-started/cortex-ai-assistant/mcp/configuring-cortex-mcp



You can host the MCP server locally, or you can use a remote implementation.

# Prerequisites

The following are required prior to configuring the Cortex MCP:

1. Ensure that you have a compatible MCP client installed, such as [Claude Desktop](https://claude.ai/download), [Jetbrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html), or [Visual Studio Code (VSCode)](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). Paid subscriptions to MCP clients generally give you a larger context window, but the free versions of these clients should suffice.
2. If hosting the MCP server locally, [Docker](https://www.docker.com/) must be installed and running.
3. Create a personal access token in Cortex. See [Creating personal access tokens](/configure/settings/api-keys/personal-tokens).

# Configuring the Cortex MCP

Follow the steps below to configure the Cortex MCP.

## Hosting the Cortex MCP server locally

Follow the steps below if the MCP server is hosted locally.

### Step 1: Installing the Cortex MCP

Open terminal and run the following command:

```bash theme={null}
docker pull ghcr.io/cortexapps/cortex-mcp:latest
```

### Step 2: Configuring your MCP client

> [!NOTE]
>
> Looking for IDE-specific setup? See the [README](https://github.com/cortexapps/cortex-mcp?tab=readme-ov-file#installation)

Update your MCP client's configuration file. Make sure to include your Cortex personal access token value for the `CORTEX_API_TOKEN` argument:

```json theme={null}
{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--pull",
        "always",
        "-i",
        "--env",
        "CORTEX_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN_HERE",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
  }
}
```

**Alternate option: Create and configure the file in terminal**

Alternatively, you could enter the following in terminal to create and configure the file:

```
export CORTEX_API_TOKEN=VALUE_OF_YOUR_PERSONAL_ACCESS_TOKEN
cat << EOF > ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--pull",
        "always",
        "--rm",
        "-i",
        "--env",
        "CORTEX_API_TOKEN=${CORTEX_ACCESS_TOKEN}",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
 }
}
EOF
```

### Step 3: Restarting your MCP client

After updating your configuration, restart your MCP client.

## Hosting the Cortex MCP server remotely

The remote Cortex MCP uses the public `cortex-mcp` package as a dependency, installed from GitHub. This configuration of the Cortex MCP enables:

* **Faster setup** - No need to install or maintain local binaries.
* **Updated context** - Cortex automatically keeps the service aligned with the latest MCP specification.
* **Secure access** - Tokens and access are managed in your Cortex workspace with security best practices.
* **Seamless integration** - It works out of the box with popular MCP clients like VSCode, Claude Code, and Cursor.
* **More tools** - The remote MCP implementation includes more tools, such as the `query_docs` tool that allows you to query Cortex's documentation and knowledge base in natural language. Ask questions like *How do I configure PagerDuty for my Cortex services?*, or *How can I use Cortex to drive AI maturity at my org?* It also includes the ability to add private tools and integrations on top of the public functionality.

### Choosing the remote MCP server URL for your region

Use the remote MCP server URL that matches the region your Cortex workspace is hosted in:

| Region | Remote MCP server URL |
| - | - |
| US | `https://mcp.cortex.io/mcp` |
| EU | `https://mcp.eu.cortex.io/mcp` |

### Allowlisting the remote MCP server

If your organization restricts network traffic, the IP addresses you need to allowlist depend on which direction the traffic flows:

* **To the MCP server** - Your network restricts which destinations users can reach, or you firewall inbound access to the MCP server. Allowlist the MCP server's IP address.
* **From the MCP server** - You need to permit calls the MCP server makes, such as to your Cortex workspace when it has an [IP allowlist](/configure/settings/ip-allowlist) enabled, or into your network to reach a self-hosted Jira instance, Prometheus, or a custom MCP server. Allowlist the IP addresses that Cortex sends outbound traffic from.

| Region | To the MCP server | From the MCP server |
| - | - | - |
| US | `34.111.236.6` | `34.94.6.235`, `34.94.42.38`, and `35.236.92.1` |
| EU | `136.110.164.69` | `34.140.212.3`, `34.78.206.73`, and `34.78.61.126` |

The MCP server IP addresses are reserved static addresses, so they don't change.

> [!WARNING]
>
> Don't use the MCP server's IP address to permit traffic coming from the MCP server. Outbound calls come from the IP addresses in the **From the MCP server** column, so allowlisting the MCP server's address instead causes those requests to fail with a `403` error.

### Step 1: Adding the remote MCP server to your MCP client

Follow the instructions below for Claude, VSCode, or Cursor. Make sure to replace `<CORTEX_TOKEN>` with the value of the personal access token you generated in Cortex.

The examples below use the US server URL. If your workspace is in the EU region, replace `https://mcp.cortex.io/mcp` with `https://mcp.eu.cortex.io/mcp`.

**Claude Code**

Run the following command to add the Cortex remote MCP server:

```
claude mcp add --transport http cortex-remote https://mcp.cortex.io/mcp --header "Authorization: Bearer <CORTEX_TOKEN>"
```

**VSCode**

Add the following configuration to your `.vscode/mcp.json` file:

```json theme={null}
{
  "servers": {
    "cortex": {
      "url": "https://mcp.cortex.io/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer <CORTEX_TOKEN>"
      }
    }
  }
}
```

For more information, see the [official VSCode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

**Cursor**

Add the following configuration to your Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "cortex": {
      "type": "http",
      "url": "https://mcp.cortex.io/mcp",
      "headers": {
        "Authorization": "Bearer <CORTEX_TOKEN>"
      }
    }
  }
}
```

### Step 2: Validating your remote MCP configuration

Validate that your remote Cortex MCP is working:

* **VSCode** - Open the Command Palette and search for "MCP: List servers." Confirm that `cortex` appears as a connected server.
* **Claude** - Run the command `claude mcp list` and verify that cortex-remote is in the list of servers.
* **Cursor** - Open **Settings > MCP Servers** and verify that `cortex` is listed and connected.

### Step 3: Restarting your MCP client

After updating your configuration, restart your MCP client.

#### Self-managed additional configuration

If you are a [self-managed Cortex customer](/self-managed), you must also set `CORTEX_API_BASE_URL=https://` alongside the `CORTEX_API_TOKEN` variable.

**Self-managed configuration example**

Set the `CORTEX_API_BASE_URL` to your backend host URL:

```json theme={null}
{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--pull",
        "always",
        "-i",
        "--env",
        "CORTEX_API_TOKEN=YOUR_ACCESS_TOKEN_HERE",
        "--env",
        "CORTEX_API_BASE_URL=https://api.cortex.company.com",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
  }
}
```

If you are running a self-hosted instance with CA-signed certificates, you may need to mount them to the container as seen in the example below:

```json theme={null}
{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--pull",
        "always",
        "-i",
        "-v",
        "/path/to/your//company_certs.ca:/etc/ssl/certs/company-ca.crt:ro",
        "--env",
        "REQUESTS_CA_BUNDLE=/etc/ssl/certs/company-ca.crt",
        "--env",
        "SSL_CERT_FILE=/etc/ssl/certs/company-ca.crt",
        "--env",
        "CURL_CA_BUNDLE=/etc/ssl/certs/company-ca.crt",
        "--env",
        "CORTEX_API_TOKEN=YOUR_ACCESS_TOKEN_HERE",
        "--env",
        "CORTEX_API_BASE_URL=https://api.cortex.company.com",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
  }
}
```


# Signing in to the remote Cortex MCP with OAuth
Source: https://docs.cortex.io/get-started/cortex-ai-assistant/mcp/mcp-oauth

Connect your MCP client to the remote Cortex MCP by logging in with your Cortex account instead of a personal access token

PUBLIC BETA

> [!NOTE]
>
> This feature is available for Cortex cloud.

The remote Cortex MCP supports OAuth, so you can connect your MCP client by logging in to Cortex in your browser. You don't need to create a personal access token or add it to your client's configuration. Your MCP client handles the sign-in flow and keeps your session authorized.

This page covers how to connect with OAuth. For an overview of what the Cortex MCP can do, see [Cortex MCP](/get-started/cortex-ai-assistant/mcp). To connect with a personal access token instead, see [Configuring the Cortex MCP](/get-started/cortex-ai-assistant/mcp/configuring-cortex-mcp).

## Prerequisites

Before you get started:

* Make sure you have an MCP client that supports remote MCP servers with OAuth, such as [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp).
* Have your Cortex tenant code ready. Your tenant code identifies your Cortex workspace and is part of the MCP server URL. See [Finding your tenant code](#finding-your-tenant-code) below.

### Finding your tenant code

Your tenant code is the workspace name you enter in the **Enter your workspace name** field when you sign in to Cortex, e.g. `cortex-labs`.

If you sign in from a bookmarked link, check the URL. Your tenant code is the value after `tenantCode=`. For example, in `https://app.getcortexapp.com/login?tenantCode=cortex-labs`, the tenant code is `cortex-labs`.

> [!NOTE]
>
> The **Workspace name** field under **Settings > General** is the display name shown next to your logo. **It isn't your tenant code**.

If you don't know your tenant code, contact your account team or Cortex support.

## Choosing your MCP server URL

The OAuth-enabled MCP server URL includes your tenant code. Use the URL for the region your Cortex workspace is hosted in, and replace `<TENANT_CODE>` with your tenant code:

| Region | MCP server URL |
| - | - |
| US | `https://mcp.cortex.io/t/<TENANT_CODE>/mcp` |
| EU | `https://mcp.eu.cortex.io/t/<TENANT_CODE>/mcp` |

> [!NOTE]
>
> These URLs are different from the token-based remote MCP URLs. Make sure to include `/t/<TENANT_CODE>` in the path, or the OAuth sign-in flow won't start.

## Connecting with Claude Code

**1. Add the Cortex MCP server**

Run the following command. If your workspace is in the EU region, use the EU URL instead.

```bash theme={null}
claude mcp add --transport http --scope user cortex https://mcp.cortex.io/t/<TENANT_CODE>/mcp
```

**2. Authenticate**

Open Claude Code and run `/mcp`. Select `cortex`, then select **Authenticate**.

**3. Log in to Cortex**

A browser window opens to the Cortex login page. Log in to your Cortex account to authorize the connection, then return to Claude Code.

To confirm the connection, run `/mcp` again and check that `cortex` shows as connected.

## Connecting with Glean

> [!NOTE]
>
> To add the Cortex MCP server in Glean, you need the Glean Admin or MCP Server Moderator role, and you must also be a Cortex user. Glean signs in to Cortex as you to discover the available tools. To make the tools available to other users after setup, you need the Glean Admin role.

**1. Add a new MCP server**

In Glean, start the **+ MCP** flow to add a remote MCP server, then open the **Configuration** tab.

**2. Name the server**

Enter an **MCP server name** and **Description**, for example `Cortex MCP`.

**3. Enter the server URL**

In **MCP server URL**, enter the MCP server URL for your region, including your tenant code. Leave **Use Glean proxy** cleared unless you have trouble connecting.

**4. Choose the transport and authentication**

Under **Transport type**, select **Streaming HTTP**. Under **Authentication method**, select **Dynamic client registration**. Glean fills in the **Client ID** automatically.

**5. Connect to Cortex**

Under **Connect to server**, sign in to Cortex when prompted. When the status shows **Connected**, click **Refresh tools** to load the Cortex MCP tools.

**6. Enable the tools**

Under **Enable tools**, click **Edit settings** and choose which teammates can use the Cortex tools. Then click **Save**.

After you enable the tools, each Glean user signs in to Cortex with their own account the first time they use a Cortex tool. Glean uses each user's own Cortex identity, not the admin's connection, so users can only see and do what their Cortex account allows.

For more information, see the Glean documentation on [connecting remote MCP servers to Glean](https://docs.glean.com/administration/tools/connect-remote-mcp-servers-to-glean).

## Connecting with other MCP clients

If your MCP client asks for connection details when you add a remote server, use the following settings:

* **Server URL** - The MCP server URL for your region, including your tenant code.
* **Transport type** - HTTP (streamable HTTP).
* **Authentication** - OAuth with Dynamic Client Registration (DCR). You don't need a client ID or client secret. Your MCP client registers itself with Cortex automatically.

After you add the server, start the sign-in flow from your client. A browser window opens where you log in to Cortex.

> [!NOTE]
>
> During Public Beta, OAuth sign-in works with a set of supported MCP clients. If you have trouble connecting your client, contact your account team.

## Staying signed in

After you sign in, your authentication lasts for multiple days. Your MCP client refreshes your access tokens automatically multiple times per day, so you don't need to do anything to keep your session active.

When your authentication expires, sign in to Cortex again from your MCP client. In Claude Code, run `/mcp`, select `cortex`, then select **Authenticate**.

## Share your feedback

Have feedback or run into issues? Reach out to your account team.


# Using the Cortex MCP
Source: https://docs.cortex.io/get-started/cortex-ai-assistant/mcp/using-cortex-mcp



This article explains how to use the Cortex MCP. For information on setting up the Cortex MCP, refer to [Configuring the Cortex MCP](/get-started/cortex-ai-assistant/mcp/configuring-cortex-mcp).

> [!TIP]
>
> **We'd love your feedback!**\\
>
> If you're using the Cortex MCP, we'd love to hear your direct feedback on the configuration process, the tools available, and how you've been using it. Your feedback helps us improve and expand Cortex's capabilities. If you're interested in helping guide Cortex's MCP direction, [take the survey](https://forms.gle/yNLgLBrHTjKRJ34y5).

## Starting a new chat

In your MCP client, ask a question about your Cortex workspace. The client uses the Cortex API to provide detailed answers based on your data.

**Examples**

* You might ask what's going on with a specific Scorecard. The MCP client responds with an overview, Scorecard structure information, a progress summary, and suggestions for next steps.

  ![Screenshot 1 of MCP example conversation](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/mcp-scorecard.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=eab43c778da380f351f27f268370c277)
* You could ask about an entity's custom data. The MCP client responds with that entity's custom data and information about when it was created.

  ![Screenshot 2 of MCP example conversation](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/mcp-custom-data.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=571b54d5cfec6272cbbcd97961e6cb85)
* You could ask about an entity's dependencies. The MCP client responds with a list of incoming and outgoing dependencies.

  ![Screenshot 3 of MCP example conversation](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/mcp-dependencies.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=7861e98735af0854bf3e5e8b75d770e1)

## Available MCP tools

The Cortex MCP can use the following [Cortex REST API](/api) endpoints. Some tools read data, and others create or update data in your workspace. The Cortex MCP can't delete data. It runs bulk operations only on ownership recommendations. See [Making changes with the Cortex MCP](#making-changes-with-the-cortex-mcp).

> **Catalog / Entities**
>
> * [searchCatalog](/api/rest/catalog-entities/search-entities) - Find entities by relevance; the primary way to search the catalog
> * [listAllEntities](/api/rest/catalog-entities/list-entities) - Enumerate entities by structured filters (groups, types, owners, repos)
> * [getEntityDetails](/api/rest/catalog-entities/retrieve-entity-details) - Full details for one entity: metadata, ownership, hierarchy, relationships
> * [getEntityDescriptor](/api/rest/catalog-entities/retrieve-entity-descriptor) - A single entity's descriptor (optionally YAML)
> * [listEntityDescriptors](/api/rest/catalog-entities/list-entity-descriptors) - List entity descriptors (optionally YAML)
> * [createOrUpdateEntity](/api/rest/catalog-entities/create-or-update-entity) - Create an entity, or replace the descriptor of an existing entity
> * [createOrPatchEntity](/api/rest/catalog-entities/create-or-patch-entity) - Create an entity, or update only the fields you include
> * [archiveEntity](/api/rest/catalog-entities/archive-an-entity) - Archive an entity
> * [unarchiveEntity](/api/rest/catalog-entities/unarchive-an-entity) - Restore an archived entity
> * [listGroupsForEntity](/api/rest/groups/retrieve-groups-for-entity) - Groups assigned to an entity
> * [addGroupsToEntity](/api/rest/groups/add-groups-to-entity) - Add groups to an entity
> * [listDefinitions](/api/rest/entity-types/list-entity-types) - All entity types (definitions)
> * [getDefinition](/api/rest/entity-types/retrieve-entity-type) - Schema and details for one entity type
> * [createDefinition](/api/rest/entity-types/create-entity-type) - Create an entity type
> * [updateDefinition](/api/rest/entity-types/update-entity-type) - Update an entity type
> * [listCatalogPages](/api/rest/catalogs/list-catalogs) - All catalogs in your workspace
> * [getCatalogPage](/api/rest/catalogs/get-catalog) - One catalog's configuration, by slug
> * [upsertCatalogPage](/api/rest/catalogs/create-or-replace-a-catalog) - Create a catalog, or replace an existing one
> * [getOpenApiDocForEntity](/api/rest/docs/retrieve-openapi-docs-for-entity) - OpenAPI documentation attached to an entity
> * [KubernetesGetK8sResourcesForEntity](/api/rest/kubernetes-api/get-kubernetes-resource-details-for-an-entity) - Kubernetes resources linked to an entity
> * [AWSGetAwsResources](/api/rest/aws-api/get-aws-resource-details-for-an-entity) - Cached Amazon Web Services (AWS) resource details for an entity
>
> **Additional tools**
>
> * `getMyWorkspace` - Enabled by default, this tool supports the "Mine" capabilities that are available in the Cortex UI. Ask questions like, "show me my Cortex entities" or "tell me how my entities are performing against the Production Readiness Scorecard."

> **Custom data and events**
>
> * [getCustomDataForEntity](/api/rest/custom-data/list-custom-data-for-entity) - All custom key-value data for an entity
> * [getCustomDataForEntityByKey](/api/rest/custom-data/retrieve-custom-data-for-entity-by-key) - One custom data value by key
> * [retrieveCustomDataForEntityAdvanced](/api/rest/custom-data-advanced/retrieve-custom-data-for-entity) - Custom data across entities
> * [addCustomDataForEntity](/api/rest/custom-data/add-custom-data-for-entity) - Add a custom data key-value pair to an entity
> * [addCustomDataForEntityAdvanced](/api/rest/custom-data-advanced/add-custom-data-for-entity-advanced) - Add custom data to an entity, identified in the request body
> * [listCustomEventsForEntity](/api/rest/custom-events/list-custom-events-for-entity) - Custom events for an entity (filter by type/time)
> * [getCustomEventForEntityByUuid](/api/rest/custom-events/retrieve-custom-event-by-uuid) - One custom event by UUID
> * [createCustomEventForEntity](/api/rest/custom-events/create-custom-event-for-entity) - Add a custom event to an entity
> * [replaceCustomEventForEntityByUuid](/api/rest/custom-events/update-custom-event-by-uuid) - Update a custom event by UUID

> **Dependencies and relationships**
>
> * [listDependenciesForEntity](/api/rest/dependencies/retrieve-all-dependencies-for-an-entity) - Incoming + outgoing dependencies (blast radius)
> * [getDependency](/api/rest/dependencies/retrieve-dependency-between-entities) - Details of one dependency between two entities
> * [createDependency](/api/rest/dependencies/create-dependency-from-entity) - Create a dependency between two entities
> * [updateDependency](/api/rest/dependencies/update-dependency-between-entities) - Update a dependency between two entities
> * [listRelationshipTypes](/api/rest/entity-relationship-types/list-relationship-types) - All relationship types
> * [getRelationshipTypeDetails](/api/rest/entity-relationship-types/get-a-relationship-type) - Config/rules for one relationship type
> * [createRelationshipType](/api/rest/entity-relationship-types/create-relationship-type) - Create a relationship type
> * [updateRelationshipType](/api/rest/entity-relationship-types/update-relationship-type) - Update a relationship type
> * [listEntityRelationships](/api/rest/entity-relationships/list-entity-relationships-for-a-relationship-type) - Full org graph for a relationship type
> * [listEntitySourcesForRelationshipType](/api/rest/entity-relationships/list-entity-sources-for-a-relationship-type) - Sources for a relationship type & entity
> * [listEntityDestinationsForRelationshipType](/api/rest/entity-relationships/list-entity-destinations-for-a-relationship-type) - Destinations for a relationship type & entity

> **Scorecards**
>
> * [listScorecards](/api/rest/scorecards/list-scorecards) - All scorecards (filter by group/entity/team)
> * [getScorecard](/api/rest/scorecards/retrieve-scorecard) - Full scorecard config, rules, levels, weights
> * [createOrUpdateScorecard](/api/rest/scorecards/create-or-update-scorecard) - Create a Scorecard from a YAML descriptor, or replace the Scorecard that has the same tag
> * [listScorecardScores](/api/rest/scorecards/retrieve-scorecard-scores) - Scores for all entities on a scorecard
> * [listScorecardScoresForEntity](/api/rest/catalog-entities/retrieve-entity-scorecard-scores) - An entity's scores across all Scorecards
> * [refreshScorecardScoreForEntity](/api/rest/scorecards/evaluate-entity-scorecard-score) - Re-evaluate an entity's score on a Scorecard
> * [getScorecardNextStepsForEntity](/api/rest/scorecards/retrieve-next-steps-for-entity-in-scorecard) - Steps to reach an entity's next maturity level
> * [listScorecardRuleExemptions](/api/rest/scorecards/list-scorecard-rule-exemptions) - Rule exemptions across Scorecards, with status, requester, approver, and expiry
> * [requestScorecardRuleExemption](/api/rest/scorecards/request-scorecard-rule-exemption) - Request a rule exemption for an entity
> * [approveScorecardRuleExemption](/api/rest/scorecards/approve-scorecard-rule-exemption) - Approve a pending rule exemption
> * [denyScorecardRuleExemption](/api/rest/scorecards/deny-scorecard-rule-exemption) - Deny a pending rule exemption
> * [revokeScorecardRuleExemption](/api/rest/scorecards/revoke-scorecard-rule-exemption) - Revoke an approved rule exemption

> **Initiatives**
>
> * [listInitiatives](/api/rest/initiatives/list-initiatives) - All initiatives (optional draft/expired)
> * [getInitiative](/api/rest/initiatives/get-initiative) - One initiative's goals, timeline, targets, progress
> * [createInitiative](/api/rest/initiatives/create-an-initiative) - Create an Initiative
> * [updateInitiative](/api/rest/initiatives/update-an-initiative) - Update an Initiative

> **Verifications**
>
> * [listVerifications](/api/rest/verifications/retrieve-verifications) - Entity verifications across your workspace
> * [listVerificationPeriods](/api/rest/verifications/retrieve-verification-periods) - All verification periods
> * [retrieveVerificationPeriod](/api/rest/verifications/retrieve-a-verification-period) - Details for one verification period
> * [createVerificationPeriod](/api/rest/verifications/create-a-verification-period) - Create a verification period
> * [updateVerificationPeriod](/api/rest/verifications/update-a-verification-period) - Update a verification period
> * [listVerificationsForEntity](/api/rest/catalog-entities/retrieve-entity-verifications) - Verification history for an entity
> * [verifyEntityForPeriod](/api/rest/catalog-entities/verify-an-entity-for-a-verification-period) - Verify one entity for a verification period

> **Metrics**
>
> * [getCustomMetricData](/api/rest/custom-metrics/retrieve-custom-metrics-data-points) - Custom metric time-series for an entity
> * [createCustomMetricData](/api/rest/custom-metrics/add-custom-metrics-data-point) - Add a single custom metric data point for an entity
> * [listCustomMetricDefinitions](/api/rest/custom-metrics/list-custom-metric-definitions) - Custom metric definitions in your workspace
> * [getCustomMetricDefinition](/api/rest/custom-metrics/retrieve-a-custom-metric-definition) - A single custom metric definition by key
> * [createCustomMetricDefinition](/api/rest/custom-metrics/create-a-custom-metric-definition) - Define a new API custom metric
> * [updateCustomMetricDefinition](/api/rest/custom-metrics/update-a-custom-metric-definition) - Replace the definition of an API custom metric
> * [queryTraceEvents](/api/rest/eng-intel-trace/query-raw-trace-events-from-engineering-data-sources) - Individual Eng Intelligence event records (filter, sort, paginate)
>
> **Additional tools**
>
> * `listMetricDefinitions` - This tool returns the Eng Intelligence metrics available in your workspace, along with the metadata needed to query them. Ask questions like, "which engineering metrics can I ask about?" or "what deployment data is available in Eng Intelligence?"
> * `queryPointInTimeMetrics` - This tool returns current values for one or more Eng Intelligence metrics, with optional comparisons against a previous period and grouping by team, entity, or user. Ask questions like, "what's our deployment frequency this quarter compared to last?" or "show me change failure rate by team for the last 30 days."

> **Teams and on-call**
>
> * [getTeamDetails](/api/rest/teams/retrieve-team-details) - Team members, Slack channels, metadata
> * [updateCortexTeamMembers](/api/rest/teams/\[cortex-managed-teams]-update-members-in-team) - Update the members of a Cortex-managed team
> * [archiveTeam](/api/rest/teams/archive-team) - Archive a team
> * [unarchiveTeam](/api/rest/teams/unarchive-team) - Restore an archived team
> * `listTeamMemberRoles` - All team member roles in your workspace
> * `createTeamMemberRole` - Create a team member role
> * [getTeamHierarchyRelationships](/api/rest/team-hierarchies/retrieve-team-relationships) - Parent and child relationships between teams
> * [getCurrentOncallForEntity](/api/rest/on-call/retrieve-current-on-call-for-entity) - Real-time on-call for an entity

> **Ownership recommendations**
>
> * [listOwnershipRecommendations](/api/rest/recommendations/list-ownership-recommendations) - Team ownership recommendations for entities, strongest first, filtered by entity, team, confidence, or status
> * [listOwnershipRecommendationEntities](/api/rest/recommendations/list-entities-with-ownership-recommendations) - Entities that have ownership recommendations, with the number of open recommendations for each
> * [acceptOwnershipRecommendation](/api/rest/recommendations/accept-an-ownership-recommendation) - Add the recommended team as an owner of the entity
> * [batchAcceptOwnershipRecommendations](/api/rest/recommendations/accept-many-ownership-recommendations) - Accept many recommendations in one request
> * [rejectOwnershipRecommendation](/api/rest/recommendations/reject-an-ownership-recommendation) - Hide a recommendation from the open list
> * [batchRejectOwnershipRecommendations](/api/rest/recommendations/reject-many-ownership-recommendations) - Reject many recommendations in one request
> * [restoreOwnershipRecommendation](/api/rest/recommendations/restore-an-ownership-recommendation) - Open a rejected recommendation again
> * [batchRestoreOwnershipRecommendations](/api/rest/recommendations/restore-many-ownership-recommendations) - Restore many recommendations in one request

> **Deploys**
>
> * [getDeploysForEntity](/api/rest/deploys/list-deployments-for-entity) - Deployment history for an entity
> * [searchDeploys](/api/rest/deploys/search-deployments-across-the-tenant) - Search deployments across all entities
> * [listDeployEnvironments](/api/rest/deploys/list-all-distinct-deploy-environments-for-this-tenant) - All deploy environments in your workspace
> * [addDeployForEntity](/api/rest/deploys/add-deployment-for-entity) - Add a deploy to an entity
> * [updateDeployByUuid](/api/rest/deploys/update-deployment-by-uuid) - Update a deploy by UUID

> **Workflows**
>
> * [listWorkflows](/api/rest/workflows/list-workflows) - All Workflows
> * [getWorkflow](/api/rest/workflows/retrieve-workflow) - One Workflow's configuration and actions
> * [validateWorkflowDescriptor](/api/rest/workflows/validates-yaml-descriptor) - Check a Workflow's YAML descriptor for errors before you save it
> * [createOrUpdateWorkflow](/api/rest/workflows/create-or-update-workflow) - Create a Workflow, or replace the Workflow that has the same tag. Requires the `Edit Workflows` permission.
> * [runWorkflow](/api/rest/workflows/run-a-workflow) - Start a run of a Workflow. Requires the `Execute Workflow Runs` permission.
> * [getWorkflowRun](/api/rest/workflows/get-workflow-run-details) - One Workflow run, including the outcome of each action
> * [listWorkflowRuns](/api/rest/workflows/list-workflow-runs) - Workflow runs from the last 30 days, with filters and pagination

> **Plugins**
>
> * [listAllPlugins](/api/rest/plugins/get-all-plugins) - All plugins in your workspace
> * [getPluginByTag](/api/rest/plugins/get-plugin-by-tag) - One plugin's configuration
> * [createPlugin](/api/rest/plugins/create-a-plugin) - Create a plugin
> * [updatePlugin](/api/rest/plugins/replace-a-plugin) - Replace a plugin's full configuration
> * `patchPlugin` - Update only the plugin fields you include

> **Scaffolder**
>
> * [listScaffolders](/api/rest/scaffolder/list-scaffolder-templates) - All Scaffolder templates
> * [getScaffolder](/api/rest/scaffolder/retrieve-scaffolder-template) - One Scaffolder template's configuration
> * [createOrUpdateScaffolder](/api/rest/scaffolder/create-or-update-scaffolder-template) - Create a Scaffolder template, or replace an existing one
> * [updateScaffolder](/api/rest/scaffolder/update-scaffolder-template) - Update a Scaffolder template

> **CQL queries**
>
> * [createQuery](/api/rest/queries/run-query) - Run a CQL query across your entities. This doesn't change any data.
> * [getQueryResults](/api/rest/queries/retrieve-query-results) - Results of a CQL query you ran

> **Packages**
>
> Upload a dependency manifest or lockfile to record an entity's packages:
>
> * [uploadJavaPackage](/api/rest/packages/\[java]-upload-single-java-package) - A single Java package
> * [uploadMavenPom](/api/rest/packages/\[java]-upload-maven-pomxml) - Maven `pom.xml`
> * [uploadNpmPackageJson](/api/rest/packages/\[js]-upload-npmyarnpnpm-packagejson) - npm, Yarn, or pnpm `package.json`
> * [uploadNpmPackageLockJson](/api/rest/packages/\[js]-upload-npm-package-lockjson) - npm `package-lock.json`
> * [uploadPnpmLock](/api/rest/packages/\[js]-upload-pnpm-lockyaml) - `pnpm-lock.yaml`
> * [uploadYarnLock](/api/rest/packages/\[js]-upload-yarnlock) - `yarn.lock`
> * [uploadPipfileLock](/api/rest/packages/\[python]-upload-pipfilelock) - `Pipfile.lock`
> * [uploadRequirementsTxt](/api/rest/packages/\[python]-upload-requirementstxt) - `requirements.txt`
> * [uploadGoSumPackage](/api/rest/packages/\[golang]-upload-gosum) - `go.sum`
> * [uploadNugetCsproj](/api/rest/packages/\[csharp]-upload-nuget-csproj) - NuGet `.csproj`
> * [uploadNugetPackagesLock](/api/rest/packages/\[csharp]-upload-nuget-packageslockjson) - NuGet `packages.lock.json`
> * `uploadNugetPackagesConfig` - NuGet `packages.config`

> **Docs and meta**
>
> * [listIntegrationStatuses](/api/rest/integration-status/list-installed-integrations-and-their-status) - Installed integrations and the result of each one's most recent connection check
> * `query_docs` - This tool queries the Cortex help center.
> * `get_more_tools` - This tool discovers additional specialized tools.

## Enabling and disabling provided tools

Before submitting questions or commands, you may want to limit the number of provided tools being used by the MCP provider. For example, you might want to use the MCP to ask about entities, but you don't want to allow questions about Scorecards.

If you want the Cortex MCP to stay read-only, turn off the tools that create, update, archive, upload, approve, or run something. Read tools generally start with `get`, `list`, `search`, `retrieve`, or `query`. `createQuery` runs a CQL query without changing data, so you can leave it on.

**Example**

In the settings of your MCP client, it's possible to limit which Cortex tools are being used. For example, in Claude desktop:

1. Navigate to **Settings > Connectors > Cortex > 3 dots icon > Tools and Settings**.
2. Below **Provided Tools**, toggle off the options you don't need.
3. Restart Claude.
4. Navigate to your Claude chat and enter commands.

## Eng Intelligence metrics in the Cortex MCP

[Eng Intelligence](/improve/eng-intelligence) metrics are also available to Cortex MCP. This brings metric data directly into the Cortex MCP, enabling richer AI-assisted insights, not only into engineering performance, but across your entire Cortex ecosystem. It allows you to be a more proactive leader and enables more data-driven planning sessions.

### Querying Eng Intelligence metrics in the Cortex MCP

Ensure you have the latest Cortex MCP version configured in your environment. Once enabled, the MCP automatically includes endpoints for Eng Intelligence metrics. You can then query Eng Intelligence metrics alongside ownership, Scorecard, and Initiative information. For example:

* ***Evaluate my DORA metric performance in Q3. Highlight where the team is performing well and bring areas of improvement to my attention.***
* ***Which services have concerning MTTR trends, and what scorecard gaps are contributing?***
* ***Recommend initiatives and scorecard changes I could consider to address my upward trend in incidents.***
* ***Review last quarter’s performance against our goals, identify the top three bottlenecks, and suggest changes to our scorecards to address them.***
* ***Is there a correlation between my PR size and how fast we ship?***

## Making changes with the Cortex MCP

In addition to answering questions, the Cortex MCP can create and update data in your workspace. For example, you can ask your client to create an Initiative, record a deploy for an entity, or request a Scorecard rule exemption. See [Available MCP tools](#available-mcp-tools) for the full list.

### Prerequisites

* The Cortex MCP acts as the user who owns your personal access token. It can only make changes that user has [permission](/configure/settings/managing-users/permissioning) to make in Cortex.
* Make sure you're using the latest version of the Cortex MCP. If you host it locally, pull the latest `ghcr.io/cortexapps/cortex-mcp:latest` image.

### Example prompts

* ***Create an Initiative that asks every service in the Payments group to reach Gold on the Production Readiness Scorecard by March 31, 2027.***
* ***Add a deploy to the `payments-api` entity for version 2.4.1 in the production environment.***
* ***Request an exemption from the "Has a runbook" rule on the Production Readiness Scorecard for `legacy-billing`. It's being retired this quarter.***
* ***Archive the `old-search` entity.***
* ***Add `tier: 1` as custom data on the `checkout` entity.***

### What the Cortex MCP can't do

* **Delete data.** To protect your data from accidental removal, no delete endpoints are available through the Cortex MCP. This includes deleting custom data, deploys, and custom events. Delete data in Cortex or with the [Cortex REST API](/api/rest/custom-data/delete-custom-data-for-entity) instead. See [Deleting custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data#deleting-custom-data) for more information.
* **Run bulk operations.** Endpoints that change many records at once aren't available, except the endpoints that accept, reject, or restore many ownership recommendations. This includes adding custom data, dependencies, or custom metric data points in bulk, verifying entities in bulk, uploading multiple Java packages at once, and replacing all team hierarchy relationships. Make these changes in Cortex or with the REST API.
* **Create teams, edit team details, or change relationships and OpenAPI docs.** The Cortex MCP can't create a team, update a team's details, add or update an entity's relationship sources and destinations, or update an entity's OpenAPI documentation. Make these changes in Cortex or with the REST API.
* **Manage workspace administration.** Integration configurations, API keys, users, and workspace settings aren't available through the Cortex MCP.

### Things to know

* Some tools create a new object or replace an existing one that has the same tag: `createOrUpdateEntity`, `createOrUpdateScorecard`, `createOrUpdateScaffolder`, `upsertCatalogPage`, and `updatePlugin`. If you aren't sure whether the tag is already in use, ask your client to look it up first.
* To change only some fields on an entity or plugin, ask your client to use `createOrPatchEntity` or `patchPlugin`, which leave everything else as is.
* Archiving is reversible. Use `unarchiveEntity` or `unarchiveTeam` to restore an archived entity or team.
* Many MCP clients ask you to approve each tool call. Check the details before you approve a change.

## Creating and running Workflows with the Cortex MCP

You can use the Cortex MCP to create, update, and run [Workflows](/streamline/workflows) without leaving your MCP client. For example, you can ask your client to build a Workflow from a description, start a run, and then check on the run until it finishes.

### Prerequisites

* To create or update a Workflow, the user who owns your personal access token needs the `Edit Workflows` [permission](/configure/settings/managing-users/permissioning).
* To run a Workflow, the user needs the `Execute Workflow Runs` permission. The Viewer role doesn't include this permission.
* The Workflow must be published (not a draft) and have **Runnable via API** turned on. See [Enabling API access](/streamline/workflows/publishing-a-workflow#enabling-api-access).

If a Workflow doesn't meet these requirements, the MCP client tells you what's blocking the run, so you can fix it in Cortex and try again.

### Example prompts

* ***Run the "Provision staging database" Workflow.***
* ***Run the "Rotate service credentials" Workflow for the `payments-api` entity, then tell me when it finishes.***
* ***Create a Workflow that posts a message to the #deploys Slack channel, and make it runnable via API.***
* ***Show me the runs of the "Onboard new service" Workflow from the last week. Did any of them fail?***

### Things to know

* `createOrUpdateWorkflow` replaces any existing Workflow that has the same tag. Ask your client to look up the Workflow first if you aren't sure the tag is unique.
* When you run a Workflow for a specific entity, include the entity in your prompt. A Workflow scoped to an entity can't run without one.
* By default, run results returned to the MCP leave out the run context (for example, secret names and the entity descriptor) to keep responses short. To get the context, ask your client to include it.
* `listWorkflowRuns` returns runs from the last 30 days.
* You can't delete Workflows through the Cortex MCP. Delete them in Cortex instead.

## Crafting effective MCP prompts

The Cortex MCP becomes more powerful when using it becomes second nature to your teams. That shift happens when you have developed prompts that fit your specific role, answer your recurring questions, and surface information in the exact moments you need it. Refer to the [Cortex MCP Prompt Library](/get-started/cortex-ai-assistant/library) for more information.

## Troubleshooting and FAQ

See frequently asked questions below.

> **When I ask a question in my MCP client, why do I see an error that says I hit the max length for this chat?**
>
> This can happen if you're on the free plan of your MCP client.

> **Can I make changes via the Cortex MCP?**
>
> Yes. The Cortex MCP can create and update many kinds of data, such as entities, Scorecards, Initiatives, and Workflows, if the user who owns your personal access token has the required permissions. It can't delete data or run bulk operations. See [Making changes with the Cortex MCP](#making-changes-with-the-cortex-mcp).

> **How do I resolve "unauthorized" errors in the MCP?**
>
> Ensure the value of your Cortex API token is valid in your configuration.

> **How do I resolve "file not found" errors in the MCP?**
>
> Ensure your OpenAPI spec path is correct when mounting.

> **How do I resolve connection issues with the MCP?**
>
> Verify your Cortex API endpoint is accessible.

> **How do I resolve a 403 forbidden error in the remote MCP?**
>
> Ensure that you set up the remote MCP with a [personal access token](/configure/settings/api-keys/personal-tokens) generated in Cortex. Remote MCP setup requires a personal access token, not an API key.

> **Why do I see an SSL certificate error while using the MCP?**
>
> This is most likely caused by an issue within your network. It's recommended to contact your organization's infrastructure or security team to troubleshoot.


# Cortex quick start guide
Source: https://docs.cortex.io/get-started/quickstart

This guide walks you through Cortex's core concepts and initial setup. By the end, you'll understand how Cortex works and how to start using it.

## **Welcome to Cortex!**

Cortex is an Engineering Operations Platform (EngOps) that brings your entire engineering ecosystem into a single, trusted source of truth. Instead of hunting through spreadsheets, wikis, and a dozen disconnected tools to answer basic questions like, "who owns this service?", "is it production-ready?", or "what depends on it?", your team gets the answers at a glance, always up to date.

Under the hood, Cortex continuously polls your existing tools and stitches that data into a unified model of your software. On top of that model, you can define standards, automate self-service actions, and give every engineer the context they need to ship reliable software faster.

## The building blocks

Before you begin, take a minute to get familiar with the core Cortex concepts. They're the foundation for everything in this guide and everything that comes after.

## Entities

An entity is anything in your engineering world that you want to track. Most commonly, that means services and the infrastructure they run on, but entities can also represent teams, domains, APIs, pipelines, ML models, or any other construct that matters to how you build software. Entities can own other entities, depend on each other, and roll up into higher-level groupings—which is what turns a flat list of components into a real map of your architecture.

## Catalogs

A catalog is a curated view of your entities, defined by entity type, i.e. service, domain, or team. It's searchable, filterable, and browsable, serving as the home base your developers return to every day to see what exists, who owns it, and how healthy it is. As you add entities and turn on integrations, your catalog fills in automatically, becoming the foundation for everything else Cortex offers: Scorecards, self-service actions, and AI-powered insights.

## Scorecards

A scorecard is how you define and enforce quality standards across your entities. You set the rules (what "good" looks like), organize them into levels (bronze, silver, gold, or whatever progression fits), and Cortex continuously evaluates each entity against them. The result is a clear, always-current score for things like production readiness, security posture, or operational maturity.

## Initiatives

An initiative is a focused, time-bound campaign for rolling out a specific improvement across your entities. You define the goal, e.g. *Migrate all services to Kubernetes by Q3*, scope it to the right entities, and set a deadline. Cortex tracks progress automatically, surfaces what's still outstanding, and keeps the right owners accountable.

## Relationships / Dependencies

Relationships capture how your entities connect to one another, turning a flat list of components into a real map of your architecture. Some relationships are implicit and created automatically, like the hierarchy between domains, teams, and services, or the dependencies between services. Others are generic relationships that you configure to reflect the connections that matter to your organization, whether that's "calls", "stores data in", "deployed by", or anything else.

## Entity descriptor (YAML)

Every entity in Cortex is backed by a YAML descriptor—a single file that captures its metadata, ownership, and context. Each `x-cortex-*` block defines a specific piece of information: owners, links to dashboards or runbooks, Slack channels, custom metadata, and more. You can edit descriptors directly in the Cortex UI, or manage them in your own repositories and sync them via GitOps—whichever fits your team's workflow.

## Integrations

Integrations are the connections between Cortex and the tools your team already uses—GitHub, PagerDuty, Datadog, Jira, your cloud provider, and so on. Each integration pulls live data into Cortex and attaches it to the right entity automatically. A service in the catalog isn’t just a name; it’s a rich, current view of its on-call rotation, deployment history, open incidents, documentation, and dependencies.

## Custom data

Custom data is how you extend Cortex with information specific to your organization. It includes user-defined metadata (any key-value context you want to track), audit trails that record how entities change over time, and operational health metrics like deploy frequency, lead time, and other indicators of how your software is actually performing. If the out-of-the-box integrations don't capture what your team needs, custom data fills the gap.


# Building on the foundation: Catalogs, Scorecards, Workflows, and Eng Intelligence
Source: https://docs.cortex.io/get-started/quickstart/building-on-the-foundation-catalogs-scorecards-workflows-and-eng-intelligence



With your foundation in place, it's time to put Cortex to work. This article covers the core features your team will use every day and how they turn your connected data into real visibility, accountability, and action.

## Working with the catalog

A [catalog](/ingesting-data-into-cortex/catalogs) is a defined selection of entities you use to track the components of your infrastructure—services, domains, cloud resources, and more. Entities are defined in YAML, but catalogs are created in the Cortex UI and act like filters that group related entities together. A single entity can belong to multiple catalogs.

Cortex includes four built-in catalogs: Services, Infrastructure (with AWS, Azure, and Google Cloud resources pulled in automatically), Domains (displayed hierarchically), and Teams (displayed hierarchically with a Scorecard leaderboard).

You can rename the defaults or create custom catalogs to match your organization's structure.

## Understanding Scorecards

[Scorecards](/standardize/scorecards) are how you establish and enforce standards across your entities—whether that's defining best practices, tracking migrations, promoting accountability, standardizing configuration, or setting maturity benchmarks. Each Scorecard evaluates entities against a set of rules, which can reference metadata within Cortex or pull data from third-party integrations. Levels and points add a layer of gamification, giving developers clear, incremental goals.

Scorecards are designed for ongoing standards, not time-bound pushes. When you need to hit a specific deadline, create an [Initiative](/improve/initiatives) to drive focused progress by a target date.

## Reports

Use reporting in Cortex to track how entities perform against Scorecards, analyze Scorecard trends over time, and surface the areas that need attention. Reports apply to published Scorecards in your workspace. See [Reports](/improve/reports) for more information.

Cortex offers several built-in reports out of the box: Executive, All Scorecards, Bird's Eye, Progress, and Report Card.

## Using Workflows

Engineering teams use [Workflows](/streamline/workflows) when they need to standardize and automate high-stakes operations like service creation, access provisioning, or incident response, especially when those processes involve multiple tools, people, or approval steps. They're also useful for onboarding, where repeatability and speed matter.

## Leveraging Eng Intelligence

[Eng Intelligence](/improve/eng-intelligence) gives engineering leaders a clear, data-driven view of how their organization builds and ships software. Surface bottlenecks in the pull request lifecycle, measure incident response, understand cross-team activity, and identify where to dig deeper.

Eng Intelligence in Cortex includes:

* Dashboards
  * [DORA Dashboard](/improve/eng-intelligence/dora-dashboard) - The speed, reliability, and efficiency of your development practices at a glance
  * [Velocity Dashboard](/improve/eng-intelligence/velocity-dashboard) - Team progress across the software development lifecycle
  * [AI impact for GitHub Copilot Dashboard](/improve/eng-intelligence/dashboards/ai-impact) - Copilot adoption and engagement across engineering
  * [Custom Dashboards](/improve/eng-intelligence/dashboards/custom) - Shared views tailored to the metrics your organization cares about most
* [Data Explorer](/improve/eng-intelligence/data-explorer) - Explore trends over time and drill into the underlying data, covering deploys, version control, project management (Jira), and incident management (PagerDuty)
* [Custom metrics](/improve/eng-intelligence/custom-metrics) - Define your own time series metrics to power Eng Intelligence analytics, drawing from your Cortex integrations or internal data sources


# Getting started: Logging in to Cortex and configuring your workspace
Source: https://docs.cortex.io/get-started/quickstart/getting-started-logging-in-to-cortex-and-configuring-your-workspace



This article walks through logging in to Cortex for the first time. It also includes additional information for admins on how to configure the Cortex workspace.

## Logging in to Cortex

> [!NOTE]
>
> On-prem users log in through their organization's unique URL, e.g.  `https://app.cortex.your-org-name.com`. Check with your Cortex admin if you don't know your URL.

Follow the steps below to log in to Cortex Cloud.

1. Go to the Cortex login page:
   1. US environment - [https://app.getcortexapp.com/login](https://app.getcortexapp.com/login)
   2. EU environment - [https://app.eu.cortex.io/login](https://app.eu.cortex.io/login)
2. Enter your workspace name, then click **Sign in**.

When you first log in to your Cortex workspace, you are prompted through the steps of configuring your account and connecting data. See the video below for a demonstration:

[YouTube video player](https://www.youtube.com/embed/yT6Ka0y_r80)

> [!NOTE]
>
> Once Cortex detects a user's workspace, it automatically redirects them to their SSO provider and preserves any deep links, so they land exactly where they intended without any extra steps.

### Session timeouts

Cortex sessions expire after **7 days of inactivity**. Inactivity is defined as not having made a request in the past 7 days. Active usage resets the timer, so users only need to re-authenticate after a continuous period without activity.

**How it works**

When a user authenticates, Cortex creates a session that remains active as long as the user continues to make requests. After 7 days without activity, the session expires and the user must re-authenticate.

This behavior is the same for both Cloud and On-Prem deployments. The only difference between the two is the authentication method:

* **Cloud** (US and EU) - Authentication goes through Auth0 + OIDC.
* **On-Prem** - Authentication uses OIDC directly.

**Logging out**

When a user logs out from the UI, Cortex clears the session and cookie, then redirects them to the login page.

> [!NOTE]
>
> The session timeout is a global configuration value and cannot currently be customized per tenant.

## For Cortex Admins

Users with the `Admin` role have full access to everything in Cortex, from customizing the organization's workspace and setting up SSO to managing users and configuring entities. This section covers the essentials for getting your workspace set up and ready for your team.

> [!NOTE]
>
> Access your Cortex workspace using the workspace ID provided to you by the Cortex team. If you are deploying Cortex on-premises, the Cortex team will provide you with access to an installer.

### Setting up SSO

Your initial login is configured to use Google for Single Sign-On (SSO).

If you do not use a Google domain email address, contact the Cortex team at [help@cortex.io](mailto:help@cortex.io) to discuss initial access and [configuring an alternate SSO provider](/configure/settings/managing-users/configuring-sso).

### Customizing the look of your workspace

A few quick tweaks to your workspace can help make it feel like part of your company's toolkit. Head to general settings to upload your logo, set a workspace name, and choose a brand color. See [Customizing your workspace](/configure/settings/workspace-customization) for more information.

### Adding users to your workspace

With your account set up, you're ready to bring your team into Cortex. You can invite users one at a time or in bulk, and assign each person a role that reflects the level of access they need. See [Roles and permissions](/configure/settings/managing-users/permissioning) for more information.

Before you start inviting the broader team, it's strongly recommended to configure at least two users with the `Admin` role. Having a second admin ensures redundancy of access: if one admin is out of office, changes roles, or leaves the organization, you'll always have someone who can manage Cortex.

### Additional resources

Go further with your initial setup! We recommend reviewing the following resources:

* [Onboarding management](/configure/settings/managing-users/onboarding-mgmt) - Stay informed about user onboarding statuses.
* [IP allowlist](/configure/settings/ip-allowlist) - Use the IP allowlist to restrict which networks can access your Cortex workspace.
* [Workspace settings](/configure/settings) - Further customize your Cortex workspace and view audit logs.


# Going further with Cortex
Source: https://docs.cortex.io/get-started/quickstart/going-further-with-cortex



With the foundation laid and the core features in place, you're ready to take Cortex further. This article covers the capabilities that help you tailor Cortex to your organization.

## Tracking ownership with teams

In Cortex, teams play two roles: they're entities that represent your organization, and they're the owners of entities in your catalogs. Ownership is central to how Cortex works as organizations rely on it to establish clear accountability for services, data, and everything else in the catalog. It also determines who receives notifications from Cortex, including on-call changes, Scorecard updates, and other alerts.

Like other [entities](/ingesting-data-into-cortex/entities-overview/entities), teams can be evaluated with [Scorecards](/standardize/scorecards), enriched by [integrations](/ingesting-data-into-cortex/integrations), and extended with [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data). They can be organized into hierarchies, and their activity can be tracked and analyzed in [Eng Intelligence](/improve/eng-intelligence). You can create teams manually in Cortex or pull them in automatically from your integrations.

## Building your own plugin

When Cortex doesn't have exactly what you need out of the box, [plugins](/streamline/plugins) let you build it yourself. Use them to support custom workflows, surface data from internal systems, or connect tools Cortex doesn't natively integrate with.

Each plugin is a single HTML file rendered inside an iframe within Cortex. Plugin proxies handle CORS restrictions and can add custom headers and secrets to outbound requests, making it easy to work with external APIs. Plugins also get contextual information about where they're running in the app, so they can adapt what they show.

## Managing external docs

Documentation is often one of the biggest pain points in a growing engineering org—scattered across wikis, Google Docs, repos, and shared drives, with no easy way to tell what's current or relevant. Cortex solves this by becoming the source of truth for your external docs. You can aggregate documentation onto the entities it relates to, so a service's runbook, architecture notes, and onboarding guide all live right next to its ownership and health information. See [Adding external documentation](/ingesting-data-into-cortex/entities-overview/entities/external-docs) for more information.

## Using GitOps with Cortex

Instead of managing everything through the Cortex UI, you can take a [GitOps approach](/configure/gitops).

GitOps is a practice that treats configuration the same way engineering teams already treat code: stored in a Git repository, reviewed through pull requests, and deployed automatically when changes are merged. Applied to Cortex, that means your entities, Scorecards, and Workflows are defined as descriptor files in a repo you own. When someone opens a PR to update a descriptor, your team reviews it like any other change; once it's merged, Cortex picks it up and syncs the update automatically.

This approach offers several advantages:

* **Version-controlled metadata** - Every change has history, context, and an author.
* **A single source of truth** - The repository where your code lives also holds the definitions of how that code is represented in Cortex.
* **Full ownership of your data** - Descriptors live in your repository, not locked inside the UI.
* **Clear auditability** - GitOps logs let you monitor and track every sync, making it easy to debug issues or review changes.

## Querying your Cortex data with AI

Cortex puts your engineering data within reach through natural-language questions, so you can pull answers from the tools you already work in instead of clicking through the UI. Ask about services, ownership, Scorecards, Initiatives, incidents, deployments, and more—all in plain language.

You can reach it two ways:

* Via the [AI Assistant in Slack](/get-started/cortex-ai-assistant) (mention `@Cortex` in any channel or DM)
* Through your own [AI tools via MCP](/get-started/cortex-ai-assistant/mcp)
  Either way, responses are based on your actual Cortex data and honor each person's individual permissions.


# Laying the foundation: Data modeling, integrations, and identity mapping
Source: https://docs.cortex.io/get-started/quickstart/laying-the-foundation-data-modeling-integrations-and-identity-mapping



Before you can get the most out of Cortex, a few foundational pieces need to be in place. This article walks through planning your data model, configuring your first integrations, and mapping user identities across tools—the groundwork that makes everything else in Cortex work smoothly.

## Data modeling

Your data model is the foundation of everything else in Cortex, so it's worth planning before you start importing entities. Think about which parts of your engineering ecosystem you want to represent, how they relate to one another, and how different teams will want to slice and view them.

* Identify the key entities you want to represent in your catalogs. See [Managing entities](/ingesting-data-into-cortex/entities-overview/entities) for a rundown of the default entity types.
* Create [custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types) if the defaults don't fit your use case.
* [Set up catalogs](/ingesting-data-into-cortex/catalogs) to organize the entities that make up your infrastructure.

## Integrating your tools with Cortex

As you integrate your tools with Cortex, it's also possible to streamline work during an incident, efficiently track issues, monitor your code for vulnerabilities, and more. See the [full list of available integrations](/ingesting-data-into-cortex/integrations).

Cortex meets your team where they already work, with integrations across version control, project management, on-call, communication, infrastructure, security, issue tracking, code quality, and beyond.

## Configuring identity mappings and reviewing mapped services

[Identity mappings](/configure/settings/managing-users/identity-mapping) connect accounts from your integrations to the right Cortex users by matching on name or email. This keeps integrations working correctly for each team member and ensures features like the Developer Homepage and Eng Intelligence show the right data for the right people.

Cortex handles most matches automatically, but when account details differ across tools, admins can review and map users manually under **Settings > Identity mappings**.

## Reviewing mapped services

Cortex recommends connections for your services. For example, if you connected PagerDuty, Slack, and Jira, then Cortex will recommend an entity's on-call service, Slack channel, and Jira project. You can change these details before confirmation.


# Cookbooks
Source: https://docs.cortex.io/guides

Proven, step-by-step guides for getting real work done in Cortex

Cookbooks help you go from "how do I do this?" to done. Each one is organized by product area and packed with recipes—short, step-by-step guides for the tasks teams tackle most in Cortex.

> **[Scorecards](/guides/product-areas/scorecards)**
>
> Recipes for building and managing Scorecards

> **[Workflows](/guides/product-areas/workflows)**
>
> Recipes for automating tasks with Workflows

> **[Eng Intelligence](/guides/product-areas/eng-intelligence)**
>
> Recipes for tracking and improving engineering performance with Eng Intelligence

> **[Data verification](/guides/product-areas/data-verification)**
>
> Recipes for keeping your catalog data accurate with data verification

> **[Plugins](/guides/product-areas/plugins)**
>
> Recipes for extending Cortex with custom plugins


# Establish consistent AI security controls
Source: https://docs.cortex.io/guides/ai-excellence/establish-consistent-ai-security-controls



Organizations often experience pain points around AI practices where AI models or pipelines live in isolated repositories, security and compliance requirements are inconsistently applied, and there's no unified way to measure quality across teams.

To improve consistency across your AI practices:

* You can [launch an AI Governance Scorecard](/guides/ai-excellence/establish-consistent-ai-security-controls#step-1-create-the-scorecard-and-configure-its-basic-settings). Cortex provides an AI Governance template in-app, which can be modified based on your organization's needs.
* You can [launch an Initiative](/guides/ai-excellence/establish-consistent-ai-security-controls#create-an-ai-governance-initiative) associated with the Scorecard, which gives your engineers a deadline for when to complete certain goals.
* [Use reports and Cortex MCP](/guides/ai-excellence/establish-consistent-ai-security-controls#measuring-success) to better understand progress and next steps.

## Create an AI Governance Scorecard

### Step 1: Create the Scorecard and configure its basic settings

1. On the [**Scorecards** page](https://app.getcortexapp.com/admin/scorecards) in your workspace, click **Create Scorecard**.
2. On the `AI Governance` template, click **Use**.
3. Configure basic settings, including the Scorecard's name, unique identifier, description, and more.
   * Learn about configuring the basic settings in the [Creating a Scorecard documentation](/standardize/scorecards/create).

### Step 2: Review and modify rules

Cortex's templated rules are based on common industry standards:

> **AI Governance: Bronze level rules**
>
> * Secrets scanning and management\\
>
>   `git.fileExists(".github/workflows/*") AND git.codeSearch(query = "secret", fileExtension = "yml").length > 0`
> * PR reviews required from two or more reviewers\\
>
>   `git.branchProtection().numReviewsRequired > 1`
> * AI security documentation and guidelines\\
>
>   `git.fileExists("AI-SECURITY.md") OR git.fileExists("docs/ai-security.md") OR git.fileExists("docs/AI_USAGE_POLICY.md") OR git.fileExists("RESPONSIBLE_AI.md")`
> * Dependency vulnerability scanning\\
>
>   `git.fileExists(".github/workflows/*") AND (git.codeSearch(query = "dependabot", fileExtension = "yml").length > 0 OR git.codeSearch(query = "safety", fileExtension = "yml").length > 0 OR git.codeSearch(query = "snyk", fileExtension = "yml").length > 0)`
> * PR reviews from CODEOWNERS\\
>
>   `git.branchProtection().codeOwnerReviewsRequired == "true"`
> * AI service configuration security\\
>
>   `git.fileExists("AI-SERVICE-CONFIGURATION-POLICY.md")`

> **AI Governance: Silver level rules**
>
> * Mitre ATLAS matrix\\
>
>   `custom("owners-reviewed-mitre-atlas-matrix") == "true"`
> * Monitoring and alerting for AI applications\\
>
>   `datadog.monitors().filter((monitor) => monitor.name.matches(".*ai.*|.*model.*|.*ml.*")).length > 0`
> * Automated security testing in CI/CD\\
>
>   `git.fileExists(".github/workflows/*") AND (git.codeSearch(query = "security", fileExtension = "yml").length > 0 OR git.codeSearch(query = "sast", fileExtension = "yml").length > 0 OR git.codeSearch(query = "container.*scan", fileExtension = "yml").length > 0)`
> * Data privacy and PII protection measures\\
>
>   `git.fileExists("PRIVACY.md") OR git.fileExists("DATA-HANDLING.md") OR git.fileExists("docs/privacy.md") OR git.codeSearch(query = "PII", fileExtension = "md").length > 0`
> * AI model access controls and authentication\\
>
>   `git.fileExists("AI-MODEL-ACCESS-CONTROLS.md")`
> * External AI vendor risk assessment\\
>
>   `git.fileExists("AI-VENDORS.md") OR git.fileExists("APPROVED-AI-SERVICES.md") OR git.fileExists("docs/ai-vendor-security.md")`

> **AI Governance: Gold level rules**
>
> * Incident response plan for AI security\\
>
>   `git.fileExists("AI-INCIDENT-RESPONSE.md") OR git.fileExists("docs/ai-incidents.md") OR git.codeSearch(query = "ai.*incident|model.*breach", fileExtension = "md").length > 0`
> * Standford NLP version\\
>
>   `packageVersion("stanfordnlp") >= semver("4.5.10")`
> * AI ethics and bias testing framework\\
>
>   `git.fileExists("ETHICS.md") OR git.fileExists("BIAS-TESTING.md")`
> * AI security training and awareness documentation\\
>
>   `git.fileExists("AI-TRAINING.md") OR git.fileExists("docs/ai-security-training.md") OR git.codeSearch(query = "training|awareness|security.*guideline", fileExtension = "md").length > 0`
> * No secret scanning vulnerabilities\\
>
>   `git.numOfVulnerabilities(source=["GITHUB_SECRET_SCANNING"]) == 0`
> * Adversarial attack detection and prevention\\
>
>   `git.fileExists("ADVERSARIAL-TESTING.md") OR git.codeSearch(query = "tests/*adverserial*").length > 0`
> * No critical vulnerabilities\\
>
>   `git.numOfVulnerabilities(severity=["CRITICAL"]) == 0`
> * AI compliance and regulatory documentation\\
>
>   `git.fileExists("AI-COMPLIANCE.md") OR git.fileExists("NIST-AI-RMF.md") OR git.fileExists("docs/ai-governance.md") OR git.codeSearch(query = "compliance|regulation|gdpr|nist", fileExtension = "md").length > 0`
> * Open NLP version\\
>
>   `packageVersion("opennlp") >= semver("2.5.5")`

You can reorder, delete, and edit rules, add more rules to a level, and assign more points to a rule to signify its importance. Behind each rule is a [Cortex Query Language (CQL) ](/standardize/cql)query; you can edit the existing CQL or write your own queries to further refine your rules.

## Create an AI Governance Initiative

Follow the steps below to create an Initiative:

> **Create an AI Governance Initiative**
>
> To motivate change by a certain deadline, you can create an Initiative:
>
> 1. While viewing your AI Governance Scorecard, click **Create Initiative** in the upper right.
> 2. Configure the Initiative fields, including a descriptive name so your team members understand the purpose of the Initiative. For example, `Complete Bronze level AI Governance rules by end of quarter`.
>    * Make sure to enable notifications so users are notified if an entity they own is failing the Initiative's goal.
> 3. Save the Initiative.
>
> After the Initiative is published, entity owners will be notified if their entity is not meeting the goal.
>
> Learn more about [creating Initiatives in the docs](/improve/initiatives).

## Measuring success

To understand progress of your Scorecard:

* Ask [Cortex MCP,](/get-started/cortex-ai-assistant/mcp) "How is my AI Governance Scorecard doing?" The MCP will respond with information on the entities that are failing rules and suggested next steps.
* Review reports: The [Bird's Eye report](/improve/reports/birds-eye) gives insight into how entities are performing against the Scorecard by visualizing the data as a heat map:\


  ![The AI Governance Scorecard in the Bird's Eye report shows mostly passing entities and only two that are failing a rule.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/ai-gov-birdseye.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=2eaf9d4719917956b61191b825e3baa0)

You can also review your Engineering Intelligence metrics for impact on key engineering metrics, such as:

* **MTTR**: With best practices in place, such as incident response plans and AI security runbooks linked, you should see faster incident response.
* **Incident frequency**: You may see less incidents overall with the implementation of rules such as requiring more than one PR review and proactively ensuring there are no critical vulnerabilities.


# Measure AI impact
Source: https://docs.cortex.io/guides/ai-excellence/measure-ai-impact



You can leverage the [Eng Intelligence](/improve/eng-intelligence) features in Cortex to measure the impact of AI.

### Copilot Dashboard

The [Copilot Dashboard](/improve/eng-intelligence/dashboards/ai-impact) provides insights into the adoption and impact of AI coding tools (starting with GitHub Copilot) across your engineering teams. It allows you to:

* **View AI adoption rates by team:** See how many developers are actively using Copilot and how adoption trends over time.
* **Correlate AI usage with engineering performance:** Compare key metrics (cycle time, deployment frequency, incident frequency, merged PRs, PR size, time to resolution, and work items completed) between teams or users who use AI tools and those who do not.
* **Track AI adoption over time:** Monitor how Copilot usage changes and how it affects delivery and reliability metrics.
* **Filter and analyze:** Use filters for time range, team, user, and more to drill into the data that matters most to you.

These insights help you identify whether AI tools are improving efficiency, accelerating delivery, or introducing new risks, and allow you to take targeted action based on real data.

### Data Explorer

[Data Explorer](/improve/eng-intelligence/data-explorer) includes AI-specific metrics such as:

* **AI adoption rate:** Percentage of licensed seats that are active users of AI coding tools.
* **Active AI users:** Number of users who used AI tools in a given period.

You can group any Eng Intelligence metric by the Cortex-generated "AI Usage" user label to compare performance between AI users and non-AI users.

## Drive continuous Improvement

You can use insights from the Copilot Dashboard and Data Explorer to understand what your teams are doing well and areas where they could improve. Use this data to inform your next steps and promote continuous improvement.

For example, if you notice a spike in incidents among AI users, you could [create an Initiative](/improve/initiatives) to improve test coverage or code review practices.


# Prepare for effective use of AI tools
Source: https://docs.cortex.io/guides/ai-excellence/prepare-for-effective-use-of-ai-tools



To prepare your services for effective usage of AI tools, you can use the AI Maturity Scorecard template. This Scorecard validates the presence of essential files, pre-commit, safeguards, and observability integrations, ensuring you can effectively leverage AI tools across the software lifecycle.

## Create a Scorecard for AI Maturity

### Step 1: Create the Scorecard and configure its basic settings

1. On the [**Scorecards** page](https://app.getcortexapp.com/admin/scorecards) in your workspace, click **Create Scorecard**.
2. On the `AI Maturity` template, click **Use**.
3. Configure basic settings, including the Scorecard's name, unique identifier, description, and more.
   * Learn about configuring the basic settings in the [Creating a Scorecard documentation](/standardize/scorecards/create).

### Step 2: Review and modify rules

Cortex's templated rules are based on common industry standards:

> **AI Maturity: Bronze level rules**
>
> * Git PR templates exist\\
>
>   `git.fileExists("pull_request_template.md") OR git.fileExists("docs/pull_request_template.md") OR git.fileExists(".github/PULL_REQUEST_TEMPLATE.md") OR git.fileExists(".github/pull_request_template.md") OR git.fileExists(".github/PULL_REQUEST_TEMPLATE/*.md") OR git.fileExists("PULL_REQUEST_TEMPLATE/*.md") OR git.fileExists("docs/PULL_REQUEST_TEMPLATE/*.md")`
> * Pre-commit settings file\\
>
>   `git.fileExists(".pre-commit-config.yaml")`
> * Repository contains README file\\
>
>   `git.fileExists("README.md")`

> **AI Maturity: Silver level rules**
>
> * Anthropic Claude instructions in repo\\
>
>   `git.fileExists("CLAUDE.md")`
> * Google Gemini instructions in repo\\
>
>   `git.fileExists("GEMINI.md")`
> * GitHub Copilot coding agent development environment\\
>
>   `git.fileExists(".github/workflows/copilot-setup-steps.yml")`
> * GitHub Copilot instructions in repo\\
>
>   `git.fileExists(".github/copilot-instructions.md")`
> * Amazon Q instructions in repo\\
>
>   `git.fileExists("AmazonQ.md")`

> **AI Maturity: Gold level rules**
>
> * Amazon Q rules in repo\\
>
>   `git.fileExists(".amazonq/rules/*.md")`
> * GitHub Copilot rules in repo\\
>
>   `git.fileExists(".github/instructions/*.instructions.md")`
> * Cursor rules in repo\\
>
>   `git.fileExists(".cursor/rules/*")`
> * AI-driven anomaly detection in observability stack\\
>
>   `datadog.monitors().filter((monitor) => monitor.name.matches(".ai.")).length > 0`

You can reorder, delete, and edit rules, add more rules to a level, and assign more points to a rule to signify its importance. Behind each rule is a [Cortex Query Language (CQL) ](/standardize/cql)query; you can edit the existing CQL or write your own queries to further refine your rules.


# Scaffold an ML model project
Source: https://docs.cortex.io/guides/ai-excellence/scaffold-ml-model



You can use a Workflow in Cortex to scaffold new Machine Learning (ML) projects with best practices built in from the start.

### Step 1: Create an entity type called ML Model

In Cortex, [create a custom entity type](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#creating-a-custom-entity-type) called ML Model (with a unique entity type identifier  `ml-model`).

### Step 2: Register the cookiecutter template in Cortex

Follow the [Cortex documentation on registering a Scaffolder template](/streamline/workflows/scaffolder),

> **Add the template**
>
> You must have the `Configure Scaffolder templates` permission to follow these steps.
>
> 1. In Cortex, navigate to **Workflows** from the main nav. In the upper right corner of the page, click **Register Scaffolder template**.
>
> ![In the upper right corner click 'Register Scaffolder template.'](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/register-scaffolder-template.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=281f96c56af7d87729dfabaf65013a71)
>
> 2. Configure the template details:
>    * **Provider**: Select which Git provider you are using.
>    * **Name**: Enter a name for the template, such as "MLOps cookiecutter"
>    * **Description**: Add a description, such as "A standardized, flexible project structure for MLOps"
>    * **Tags**: Optionally, add tags to describe the template. We recommend adding a tag such as "mlops".
> 3. Under "Configuration," fill in the fields:
>    * **Git provider configuration**: Enter the configuration, e.g., `default`
>      * By default, the option **Use this configuration for all git operations** is **enabled**. When enabled, Cortex uses the selected configuration for **all** Git operations (e.g., fetching the template details, populating the form options, and creating the new repo or Pull Request). The form options will be filtered to only those organizations or repositories that the selected configuration has access to.
>      * With this setting **disabled**, you can use a single Scaffolder template with multiple organizations/configurations. While the selected configuration must still have to access the template's repository, the remaining Git operations will be run dynamically based on the user's form selections. The Scaffolder form options will be populated using data from all configurations. Then, Cortex will automatically use a configuration with access to the selected organization (if scaffolding a new repository) or repository (if scaffolding a new PR) for all remaining Git operations.
>    * **Git URL**: Enter the git URL where your template lives.
>      * In this example we are using the [MLOps cookiecutter template in Cortex's Solutions repository](https://github.com/cortexapps/solutions/tree/master/workflows/scaffolders/cookiecutter-mlops): `https://github.com/cortexapps/solutions/tree/master/workflows/scaffolders/cookiecutter-mlops`
>    * **Configuration requirements**: Select `Neither`, as this Scaffolder will create entities for the `ml-model` type rather than creating entities of the `service` type.
>    * **Visibility**: When creating a new repository choose the default visibility of the repository. If you do not specify, the template defaults to setting a new repository as private.
>      * The available options depend on the Git provider. The `Public` setting only works if the org containing the repository allows it. The `Internal` setting only works for GitHub Enterprise accounts.
>      * When running a Workflow that contains a Scaffolder block, you can configure an override to change the repo visibility.
>    * **Create cortex.yaml in git when creating a new service**: Disable this setting, as the Workflow you run will include a block to add the new entity to your workspace.
>    * **Show README.md during Scaffolding**: When enabled, the project's README.md will be displayed when inputting the variables to use while rendering the template. If there is no README.md, nothing will be shown.
> 4. Click **Register Scaffolder template**.

### Step 3: Create a Workflow with a Scaffolder block

You can use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to add the example Workflow to your workspace. This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more:

> **Import the Workflow via CLI**
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: New ML Model
> tag: scaffolder-workflow-a1d4d2d3-624c-473f-a9f2-b933a44a92df
> description: "Workflow that leverages the [cookiecutter-mlops](https://github.com/Chim-SO/cookiecutter-mlops)\
>   \ template to create new logical, reasonably standardized, but flexible project\
>   \ structure for MLOps."
> isDraft: true
> filter:
>   type: GLOBAL
> runResponseTemplate: "Your repository is ready! \nPlease browse to {{actions.create-repo.outputs.response.gitURL}}\n\
>   The Model is also being tracked in Cortex. Please browse to https://app.getcortexapp.com/admin/index?tag={{actions.slugify-project-name.outputs.result}}"
> failedRunResponseTemplate: null
> restrictActionCompletionToRunnerUser: false
> actions:
> - name: Gathering Model Details...
>   slug: model-details
>   schema:
>     inputs:
>     - name: Project Name
>       description: null
>       key: project-name
>       required: false
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: Description
>       description: null
>       key: description
>       required: false
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: TEXTAREA_FIELD
>     - name: License
>       description: null
>       key: license
>       required: false
>       options:
>       - MIT
>       - BSD-3-Clause
>       - No license file
>       optionsLabels:
>       - MIT
>       - BSD-3-Clause
>       - No license file
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     - name: s3 Bucket
>       description: null
>       key: s3-bucket
>       required: false
>       defaultValue: null
>       placeholder: "[Optional] do not include 's3://'"
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: AWS Profile
>       description: null
>       key: aws-profile
>       required: false
>       defaultValue: default
>       placeholder: default
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: Python Interpreter
>       description: null
>       key: python-interpreter
>       required: false
>       options:
>       - Python
>       - Python3
>       optionsLabels:
>       - Python
>       - python3
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     inputOverrides: []
>     jsValidatorScript: ""
>     type: USER_INPUT
>   outgoingActions:
>   - slugify-project-name
>   isRootAction: true
> - name: Getting Ready to Scaffold New Repository...
>   slug: slugify-project-name
>   schema:
>     expression: .actions."model-details".outputs."project-name" | ascii_downcase |
>       gsub(" ";"-")|gsub("_";"-")
>     type: JQ
>   outgoingActions:
>   - create-repo
>   isRootAction: false
> - name: Creating Repository in GitHub...
>   slug: create-repo
>   schema:
>     scaffolderTemplateId: st38e74ce20dc23c29
>     createNewRepository: true
>     createService: false
>     inputOverrides:
>     - inputKey: project_name
>       outputVariable: actions.model-details.outputs.project-name
>       editable: false
>       type: VALUE
>     - inputKey: author_name
>       outputVariable: context.initiatedBy.email
>       editable: false
>       type: VALUE
>     - inputKey: description
>       outputVariable: actions.model-details.outputs.description
>       editable: false
>       type: VALUE
>     - inputKey: repo_name
>       outputVariable: actions.slugify-project-name.outputs.result
>       editable: false
>       type: VALUE
>     - inputKey: open_source_license
>       outputVariable: actions.model-details.outputs.license
>       editable: false
>       type: VALUE
>     - inputKey: s3_bucket
>       outputVariable: actions.model-details.outputs.s3-bucket
>       editable: false
>       type: VALUE
>     - inputKey: aws_profile
>       outputVariable: actions.model-details.outputs.aws-profile
>       editable: false
>       type: VALUE
>     - inputKey: python_interpreter
>       outputVariable: actions.model-details.outputs.python-interpreter
>       editable: false
>       type: VALUE
>     - inputKey: publisherOrg
>       outputVariable: variables.org
>       editable: false
>       type: VALUE
>     - inputKey: publisherRepoName
>       outputVariable: actions.slugify-project-name.outputs.result
>       editable: false
>       type: VALUE
>     - inputKey: publisherBranch
>       outputVariable: variables.branch-name
>       editable: false
>       type: VALUE
>     - inputKey: publisherCommitMessage
>       outputVariable: variables.commit-msg
>       editable: false
>       type: VALUE
>     - inputKey: publisherRepoVisibility
>       outputVariable: variables.visibility
>       editable: false
>       type: VALUE
>     type: SCAFFOLDER
>   outgoingActions:
>   - add-entity-to-catalog
>   isRootAction: false
> - name: Adding Entity to Catalog...
>   slug: add-entity-to-catalog
>   schema:
>     inputs:
>       body: "openapi: 3.0.1\ninfo:\n  title: {{actions.model-details.outputs.project-name}}\n\
>         \  x-cortex-tag: {{actions.slugify-project-name.outputs.result}}\n  x-cortex-type:\
>         \ ml-model\n  x-cortex-git:\n    github:\n      repository: {{variables.org}}/{{actions.slugify-project-name.outputs.result}}\n\
>         \  x-cortex-groups:\n  - ml-model      \n      "
>       dryRun: false
>       appendArrays: false
>       failIfEntityDoesNotExist: false
>     integrationAlias: null
>     actionIdentifier: cortex.createOrPatchEntity
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - notify-end-user
>   isRootAction: false
> - name: Notifying User...
>   slug: notify-end-user
>   schema:
>     channel: demos
>     message: "Your repository is ready! \nPlease browse to {{actions.create-repo.outputs.response.gitURL}}\n\
>       The Model is also being tracked in Cortex. Please browse to https://app.getcortexapp.com/admin/index?tag={{actions.slugify-project-name.outputs.result}}"
>     type: SLACK
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> variables:
> - slug: commit-msg
>   type: STRING
>   defaultValue: Initial Commit
> - slug: branch-name
>   type: STRING
>   defaultValue: main
> - slug: visibility
>   type: STRING
>   defaultValue: PUBLIC
> - slug: org
>   type: STRING
>   defaultValue: <your-org>
>
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file: `cortex workflows create -f <path-to-your-workflow.yaml>`

### Step 4: Run the Workflow

While viewing the Workflow in Cortex, click **Run**.

When you run the Workflow, the following events happen:

* The User Input block runs, collecting input from the user running the Workflow
* A new ML project is scaffolded in your Git repository, using the information collected from the initial User Input block
* A corresponding new entity (of the type `ml-model`) is created in your workspace
* A notification is sent to the Slack channel you configured in the Slack block of the Workflow


# Set benchmarks for AI readiness
Source: https://docs.cortex.io/guides/ai-excellence/set-benchmarks-for-ai-readiness



You can use Cortex's AI Readiness Scorecard template to start setting benchmarks and checking whether your services meet criteria for your goals. The AI Readiness template evaluates whether services have the foundational software engineering practices in place to safely and effectively adopt AI technologies.

## Create a Scorecard for AI Readiness

### Step 1: Create the Scorecard and configure its basic settings

1. On the [**Scorecards** page](https://app.getcortexapp.com/admin/scorecards) in your workspace, click **Create Scorecard**.
2. On the `AI Readiness` template, click **Use**.
3. Configure basic settings, including the Scorecard's name, unique identifier, description, and more.
   * Learn about configuring the basic settings in the [Creating a Scorecard documentation](/standardize/scorecards/create).

### Step 2: Review and modify rules

Cortex's templated rules are based on common industry standards:

> **AI Readiness: Bronze level rules**
>
> * Version control in use\\
>
>   `git != null`
> * Basic documentation exists\\
>
>   `git.fileExists("README.md") OR git.fileExists("docs/README.md") OR git.fileExists("API.md")`
> * Service ownership defined\\
>
>   `ownership.allOwners().length > 0`
> * Basic health monitoring\\
>
>   `datadog.monitors().length > 0`
> * Dependency management\\
>
>   `dependencies.in().length > 0 or dependencies.out().length > 0`

> **AI Readiness: Silver level rules**
>
> * Automated CI/CD pipeline\\
>
>   `git.fileExists(".github/workflows/*.yml") OR git.fileExists("Jenkinsfile") OR git.fileExists(".gitlab-ci.yml") OR git.fileExists("azure-pipelines.yml")`
> * Integration testing implemented
> * `git.codeSearch(query = "integration.*test|test.*integration", fileExtension = "*").length > 0 OR captures("integration-tests", custom("integration_tests_exist")) == "enabled"`
> * SLO defined\\
>
>   `slos().length > 0`
> * Test coverage minimum met\\
>
>   `captures("test-coverage", sonarqube.metric("coverage") >= 80)`
> * Secret management implemented\\
>
>   `git.fileExists(".github/workflows/*") AND git.codeSearch(query = "secret", fileExtension = "yml").length > 0`
> * Incident response runbook\\
>
>   `links("RUNBOOK").length > 0`
> * Deployment rollback capability\\
>
>   `captures("rollback", custom("rollback_capability")) == "enabled" OR git.codeSearch(query = "rollback|revert|previous.*version", fileExtension = "*").length > 0`

> **AI Readiness: Gold level rules**
>
> * Distributed tracing implemented\\
>
>   `captures("tracing", custom("distributed_tracing")) == "enabled" OR git.codeSearch(query = "jaeger|zipkin|opentelemetry|tracing", fileExtension = "*").length > 0`
> * Change approval process\\
>
>   `links("CHANGE_APPROVAL").length > 0`
> * Data classification documented\\
>
>   `git.fileExists("DATA-CLASSIFICATION.md") OR git.codeSearch(query = "data.*classif|pii|sensitive.*data|gdpr", fileExtension = "md").length > 0`
> * Comprehensive audit logging\\
>
>   `captures("audit-log", custom("audit_logging")) == "enabled" OR git.codeSearch(query = "audit.*log|compliance.*log|access.*log", fileExtension = "*").length > 0`
> * Feature flags for controlled rollouts\\
>
>   `launchDarkly != null`
> * Zero critical and high vulnerabilities\\
>
>   `captures("critical-vulns", custom("critical_vulnerabilities")) == 0 AND captures("high-vulns", custom("high_vulnerabilities")) == 0`
> * AI model security scanning\\
>
>   `captures("model-scan", custom("ai_model_scanning")) == "enabled" OR git.codeSearch(query = "model.*scan|adversarial.*test|bias.*detect", fileExtension = "*").length > 0`

You can reorder, delete, and edit rules, add more rules to a level, and assign more points to a rule to signify its importance. Behind each rule is a [Cortex Query Language (CQL) ](/standardize/cql)query; you can edit the existing CQL or write your own queries to further refine your rules.


# Verify services after AI-based auto-mapping
Source: https://docs.cortex.io/guides/ai-excellence/verify-auto-mappings



While importing your data, [Cortex automatically recommends team owners](/ingesting-data-into-cortex/entities-overview/entities/ownership/viewing-and-managing-ownership#finding-entities-without-owners) for entities that do not have an owner. A user with the `Edit entities` permission can accept these recommendations in bulk.

When making changes in bulk, it is best practice to ensure the data is verified soon after. [Data verifications](/configure/settings/entity-settings/verification) ensure that entity data in the catalog (e.g., ownership and metadata) stays accurate over time.

### Set up a data verification for your recently imported entities

If you have not reviewed each entity's recommended owner individually, you can set up a data verification to make sure owners review and verify the data within a specified timeframe. You must have the `Configure verification periods` permission to set up a verification.

1. In Cortex, navigate to the [Entity verification settings](https://app.getcortexapp.com/admin/settings/entities/verification) page. Click **+Add verification period**.
2. In the side panel, fill in the fields:
   * **Start date** and **End date**: Enter the start and end dates for the verification period.
     * The start date cannot be in the past. The end date must be at least one day after the start date.
     * Choose a timeframe that is reasonable based on the number of entities that each team will need to verify.
   * **Name**: Enter a descriptive name, e.g., `Verify auto-mapped entities`.
   * **Verification instructions**: Enter clear and concise instructions that will appear on the entity's details page, e.g., `These entity owners were mapped via AI-based recommendations. Please review and verify the entity's ownership and metadata.`
   * **Require reason for verification**: Check this box to require the user to include a reason if they confirm that the entity's data is invalid.
     * We recommend requiring a reason, as it will allow you to quickly understand what needs to be fixed on an entity.
   * **Team member roles responsible for verification**: Select which Cortex users will be responsible for verifying data.
     * If you select multiple roles, any of those users can verify data.
     * If you do not select a team member role, any user who owns the entity can verify data.
   * **Entities to verify**: Specify which entities the verification policy applies to.
     * You can select a specific entity type to include (for example, you could apply the verification to all entities of the type `service`) or if your entities have groups assigned, you can filter by specific groups.
     * Under **Advanced options**, you can use CQL to refine which entities you want to verify. For example, you might narrow your selection to entities created in the last two weeks:\

       `entity.created() < duration("P2W")`
3. Click **Create verification period**.

Within a few minutes of saving the verification period, it will be visible to admins in the list of verifications on the [Entity verification settings page](https://app.getcortexapp.com/admin/settings/entities/verification).

## Remediate entities with incorrect data

After setting up the verification period, you can [create a CQL report to view all entities that have been verified as incorrect](/configure/settings/entity-settings/viewing-and-verifying-data-verifications#viewing-verification-statuses) using a prebuilt CQL report template.

Cortex also offers a prebuilt [Scorecard template to flag entities that have not yet been verified](/configure/settings/entity-settings/viewing-and-verifying-data-verifications#flagging-unverified-entities-via-a-scorecard).


# Bulk accept entity data verifications
Source: https://docs.cortex.io/guides/compliance/bulk-accept-entity-data-verifications

Let owners accept verification for all of their entities in one run, instead of one entity at a time

This guide explains how to use a Workflow to let entity owners accept verification for many entities at once during a [verification period](/configure/settings/entity-settings/verification).

By default, owners verify entities one at a time from each entity's page. With this Workflow, an owner picks an open verification period, selects the entities they own, and marks all of them as verified correct in a single run.

> [!TIP]
>
> Link to this Workflow in your verification period's **Verification instructions**, for example: *"To bulk accept the entities you own, run the Bulk Entity Verification workflow: \[link]"*. Owners can then choose to verify one entity from its entity page, or open the Workflow to accept several at once.

## Create a Workflow to bulk accept entity verifications

### Prerequisites

Before getting started:

* You must have the `Edit Workflows` [permission](/configure/settings/managing-users/permissioning) to create the Workflow, and the `Execute Workflow runs` permission to run it.
* To verify entities, at least one verification period must be open. If none are open, the run ends with a "No open verification periods found" message and nothing is verified.
* The person running the Workflow must own the entities they verify, and hold any roles the verification period requires.

### Step 1: Create the Workflow

You can create a Workflow in the Cortex UI or via the Cortex CLI.

**Cortex CLI**

#### Add the Workflow via CLI

You can use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to add the example Workflow to your workspace. This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more:

> **Import the Workflow via CLI**
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null} theme={null}
> name: Bulk Entity Verification
> tag: bulk-entity-verification
> description: Select entities you own and mark them all as verified correct for an open verification period in one step.
> isDraft: true
> isRunnableViaApi: false
> restrictActionCompletionToRunnerUser: true
> iconTag: CheckCircle
> filter:
>   type: GLOBAL
> runRestrictionPolicies: []
> variables:
>   - slug: result-message
>     type: STRING
>     defaultValue: ""
>     description: Summary shown as the run response; set by whichever path the run takes.
> runResponseTemplate: "{{variables.result-message}}"
> failedRunResponseTemplate: Bulk verification failed. Check the failed step's output for details.
> actions:
>   - name: Fetch open verification periods
>     slug: fetch-periods
>     isRootAction: true
>     outgoingActions:
>       - format-periods
>     schema:
>       type: HTTP_REQUEST
>       httpMethod: GET
>       url: /api/v1/verification-periods?isActive=true&pageSize=250&page=0
>       integration: Cortex
>       headers:
>         Accept: application/json
>
>   - name: Format periods for dropdown
>     slug: format-periods
>     isRootAction: false
>     outgoingActions:
>       - check-periods
>     schema:
>       type: JQ
>       expression: >-
>         .actions["fetch-periods"].outputs.body
>         | (if type == "string" then fromjson else . end)
>         | (.periods // [])
>         | map("\(.name) (\(.cid))")
>
>   - name: Any open periods?
>     slug: check-periods
>     isRootAction: false
>     outgoingActions:
>       - select-entities
>       - no-periods-message
>     schema:
>       type: CONDITIONAL_BRANCH
>       branches:
>         - type: CONDITIONAL
>           slug: has-open-periods
>           name: Open periods found
>           expression: size(actions["format-periods"].outputs.result) > 0
>           outgoingAction: select-entities
>       fallbackBranch:
>         type: FALLBACK
>         slug: no-open-periods
>         name: No open periods
>         outgoingAction: no-periods-message
>
>   - name: Set 'no periods found' message
>     slug: no-periods-message
>     isRootAction: false
>     outgoingActions: []
>     schema:
>       type: SET_VARIABLES
>       variables:
>         - slug: result-message
>           source:
>             type: JAVASCRIPT
>             script: >-
>               return "No open verification periods found. Nothing was verified.
>               Ask an admin to open a verification period, then run this workflow again.";
>
>   - name: Select entities to verify
>     slug: select-entities
>     isRootAction: false
>     outgoingActions:
>       - build-payload
>     schema:
>       type: USER_INPUT
>       jsValidatorScript: ""
>       inputOverrides:
>         - type: OPTION
>           inputKey: period
>           outputVariable: actions.format-periods.outputs.result
>       inputs:
>         - type: SELECT_FIELD
>           key: period
>           name: Verification period
>           description: Open verification periods in this workspace.
>           required: true
>           allowAdditionalOptions: false
>           options: []
>         - type: CORTEX_ENTITY_FIELD
>           key: entities
>           name: Entities to verify
>           description: Choose the entities you own that you confirm are correct. Only entities you own are listed.
>           required: true
>           allowMultiple: true
>           limitEntitiesToRunnerUserScope: true
>           shouldDisplayOptionsAsHierarchy: false
>           entityFilter: {}
>         - type: TOGGLE_FIELD
>           key: confirm
>           name: I confirm these entities' details are correct
>           required: true
>           defaultValue: false
>
>   - name: Build verification payload
>     slug: build-payload
>     isRootAction: false
>     outgoingActions:
>       - bulk-verify
>     schema:
>       type: JQ
>       expression: |-
>         .actions["select-entities"].outputs as $in
>         | if ($in.confirm != true) then
>             error("Confirmation toggle was not turned on; nothing was verified.")
>           else
>             ($in.period | capture("\\((?<cid>vp[0-9a-zA-Z]+)\\)$").cid) as $period
>             | ($in.entities
>                 | if type == "array" then . else [.] end
>                 | map(if type == "object" then (.tag // .cid) else . end)) as $tags
>             | {
>                 count: ($tags | length),
>                 periodCid: $period,
>                 body: ({verifications: [$tags[] | {entity: ., periodCid: $period, status: "VERIFIED_CORRECT"}]} | tojson)
>               }
>           end
>
>   - name: Bulk verify
>     slug: bulk-verify
>     isRootAction: false
>     outgoingActions:
>       - result-summary
>     schema:
>       type: HTTP_REQUEST
>       httpMethod: PUT
>       url: /api/v1/verifications
>       integration: Cortex
>       headers:
>         Content-Type: application/json
>       payload: "{{{actions.build-payload.outputs.result.body}}}"
>
>   - name: Set result summary
>     slug: result-summary
>     isRootAction: false
>     outgoingActions: []
>     schema:
>       type: SET_VARIABLES
>       variables:
>         - slug: result-message
>           source:
>             type: JAVASCRIPT
>             script: |-
>               const raw = actions["bulk-verify"].outputs.body;
>               let body = raw || {};
>               if (typeof raw === "string") { try { body = JSON.parse(raw); } catch (e) { body = { raw: raw }; } }
>               const sent = actions["build-payload"].outputs.result.count;
>               const period = actions["select-entities"].outputs.period;
>               const errors = Array.isArray(body.errors) ? body.errors : [];
>               const noun = (n) => n === 1 ? "entity" : "entities";
>               if (errors.length === 0) {
>                 return `Verified ${sent} ${noun(sent)} as correct for ${period}.`;
>               }
>               const ok = Math.max(sent - errors.length, 0);
>               return `Submitted ${sent} ${noun(sent)} for ${period}: ${ok} verified, ${errors.length} failed.\n` + errors.map(e => "- " + (typeof e === "string" ? e : JSON.stringify(e))).join("\n");
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file: `cortex workflows create -f <path-to-your-workflow.yaml>`

**Cortex UI**

#### Step 1.1: Create the Workflow and configure basic settings

1. In Cortex, navigate to **Workflows**. In the upper right corner, click **+Create workflow**. Choose a blank Workflow.
2. Follow the documentation to [configure the basic settings for your Workflow](/streamline/workflows/create#creating-a-workflow).
   * In this example, we use the name `Bulk Entity Verification`.
   * Leave the scope set to **Global**, so the Workflow isn't tied to a single entity.
3. In the Workflow settings, add a variable:
   * **Slug**: `result-message`
   * **Type**: String
4. Set the **Run response template** to `{{variables.result-message}}`.

#### Step 1.2: Add blocks to the Workflow

Add the following blocks to your Workflow:

> **Fetch open verification periods**
>
> This block gets the verification periods that are open today.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **HTTP request**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Fetch open verification periods` and the slug `fetch-periods`.
> 3. Configure the block:
>    * **HTTP method**: GET
>    * **Integration**: Cortex
>    * **URL**: `/api/v1/verification-periods?isActive=true&pageSize=250&page=0`
>    * **Headers**: `Accept: application/json`
> 4. At the bottom of the side panel, click **Save**.

> **Format periods for dropdown**
>
> This block turns each open period into a dropdown option such as `Q4 ownership review (vp0a1b2c3d4e5f6789)`, so users see the period name and the Workflow keeps its ID.
>
> 1. Click **+** below the previous block. In the block library modal, choose **JQ**.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Format periods for dropdown` and the slug `format-periods`.
> 3. Enter the following JQ expression:
>
> ```jq theme={null} theme={null}
> .actions["fetch-periods"].outputs.body
> | (if type == "string" then fromjson else . end)
> | (.periods // [])
> | map("\(.name) (\(.cid))")
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **Any open periods?**
>
> This block stops the run with a clear message when no verification period is open.
>
> 1. Click **+** below the previous block. In the block library modal, choose **Branch**.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Any open periods?` and the slug `check-periods`.
> 3. Add a conditional branch:
>    * **Name**: Open periods found
>    * **Slug**: `has-open-periods`
>    * **Expression**: `size(actions["format-periods"].outputs.result) > 0`
> 4. Name the fallback branch `No open periods`, with the slug `no-open-periods`.
> 5. At the bottom of the side panel, click **Save**.

> **Set 'no periods found' message**
>
> On the **No open periods** branch, this block sets the message the user sees.
>
> 1. On the **No open periods** branch, click **+**. In the block library modal, choose **Set variables**.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Set 'no periods found' message` and the slug `no-periods-message`.
> 3. Set the `result-message` variable using JavaScript:
>
> ```javascript theme={null} theme={null}
> return "No open verification periods found. Nothing was verified. Ask an admin to open a verification period, then run this workflow again.";
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **Select entities to verify**
>
> On the **Open periods found** branch, this block collects the period, the entities, and a confirmation from the user.
>
> 1. On the **Open periods found** branch, click **+**. In the block library modal, choose **User input**.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Select entities to verify` and the slug `select-entities`.
> 3. Click **+Add user input**. Add the following:
>    * **Name**: Verification period
>    * **Key**: period
>    * **Type**: Select
>    * **Path to override value**: `actions.format-periods.outputs.result`
>    * Click **Add input**.
> 4. Click **+Add user input**. Add the following:
>    * **Name**: Entities to verify
>    * **Key**: entities
>    * **Type**: Select
>    * **Data source**: Cortex entity
>    * Enable **Allow multiple**, and limit the options to entities the runner owns.
>    * Click **Add input**.
> 5. Click **+Add user input**. Add the following:
>    * **Name**: I confirm these entities' details are correct
>    * **Key**: confirm
>    * **Type**: Toggle
>    * Click **Add input**.
> 6. At the bottom of the side panel, click **Save**.

> **Build verification payload**
>
> This block checks that the user turned on the confirmation toggle, reads the period ID from the selected option, and builds one request body for all of the selected entities.
>
> 1. Click **+** below the previous block. In the block library modal, choose **JQ**.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Build verification payload` and the slug `build-payload`.
> 3. Enter the following JQ expression:
>
> ```jq theme={null} theme={null}
> .actions["select-entities"].outputs as $in
> | if ($in.confirm != true) then
>     error("Confirmation toggle was not turned on; nothing was verified.")
>   else
>     ($in.period | capture("\\((?<cid>vp[0-9a-zA-Z]+)\\)$").cid) as $period
>     | ($in.entities
>         | if type == "array" then . else [.] end
>         | map(if type == "object" then (.tag // .cid) else . end)) as $tags
>     | {
>         count: ($tags | length),
>         periodCid: $period,
>         body: ({verifications: [$tags[] | {entity: ., periodCid: $period, status: "VERIFIED_CORRECT"}]} | tojson)
>       }
>   end
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **Bulk verify**
>
> This block sends every selected entity to the [bulk verification endpoint](/api/rest/verifications#put-api-v1-verifications) in a single request.
>
> 1. Click **+** below the previous block. In the block library modal, choose **HTTP request**.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Bulk verify` and the slug `bulk-verify`.
> 3. Configure the block:
>    * **HTTP method**: PUT
>    * **Integration**: Cortex
>    * **URL**: `/api/v1/verifications`
>    * **Headers**: `Content-Type: application/json`
>    * **Payload**: `{{{actions.build-payload.outputs.result.body}}}`
> 4. At the bottom of the side panel, click **Save**.

> **Set result summary**
>
> This block sets the message the user sees after the bulk request. It reports how many entities were verified and lists any that failed.
>
> 1. Click **+** below the previous block. In the block library modal, choose **Set variables**.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Set result summary` and the slug `result-summary`.
> 3. Set the `result-message` variable using JavaScript:
>
> ```javascript theme={null} theme={null}
> const raw = actions["bulk-verify"].outputs.body;
> let body = raw || {};
> if (typeof raw === "string") { try { body = JSON.parse(raw); } catch (e) { body = { raw: raw }; } }
> const sent = actions["build-payload"].outputs.result.count;
> const period = actions["select-entities"].outputs.period;
> const errors = Array.isArray(body.errors) ? body.errors : [];
> const noun = (n) => n === 1 ? "entity" : "entities";
> if (errors.length === 0) {
>   return `Verified ${sent} ${noun(sent)} as correct for ${period}.`;
> }
> const ok = Math.max(sent - errors.length, 0);
> return `Submitted ${sent} ${noun(sent)} for ${period}: ${ok} verified, ${errors.length} failed.\n` + errors.map(e => "- " + (typeof e === "string" ? e : JSON.stringify(e))).join("\n");
> ```
>
> 4. At the bottom of the side panel, click **Save**.

### Step 2: Run the Workflow

In the list of Workflows, locate the "Bulk Entity Verification" Workflow and click **Run**.

When you run the Workflow, the following events happen:

1. The Workflow retrieves the verification periods that are open today and formats them as dropdown options.
2. If no period is open, the run ends with the message "No open verification periods found." Nothing is verified.
3. If at least one period is open, the Workflow pauses to collect a response from the user during the User input block. The user selects a verification period, selects one or more entities they own, and turns on the confirmation toggle.
4. The JQ block checks the confirmation toggle. If it is off, the run fails and nothing is verified. Otherwise, it builds a single request that marks each selected entity as `VERIFIED_CORRECT` for the selected period.
5. The HTTP request block sends the request to the bulk verification endpoint.
6. The Workflow sets the run response to a summary of the result, such as "Verified 3 entities as correct for Q4 ownership review (vp0a1b2c3d4e5f6789)."

> [!NOTE]
>
> The bulk verification endpoint evaluates each entity separately. It can return `200 OK` even when some entities were not recorded, for example because the user doesn't own them. Those entities appear under `errors` in the response, and the Workflow lists them in the run summary.


# Data verifications for audit readiness
Source: https://docs.cortex.io/guides/compliance/data-verification



[Data verifications](/configure/settings/entity-settings/verification) ensure that entity data in the catalog (e.g., ownership and metadata) stays accurate over time.

As a best practice for audit readiness, we recommend scheduling periodic data verification to ensure your entities are up to date.

## Set up a data verification for audit readiness

You must have the `Configure verification periods` permission to set up a verification.

1. In Cortex, navigate to the [Entity verification settings](https://app.getcortexapp.com/admin/settings/entities/verification) page. Click **+Add verification period**.
2. In the side panel, fill in the fields:
   * **Start date** and **End date**: Enter the start and end dates for the verification period.
     * The start date cannot be in the past. The end date must be at least one day after the start date.
     * Choose a timeframe based on your audit's point in time. For example, if your SOC 2 period ends on March 31, you may want to ensure all verifications have timestamps within the last 90 days of that period.
   * **Name**: Enter a descriptive name, e.g., `Audit readiness`.
   * **Verification instructions**: Enter clear and concise instructions that will appear on the entity's details page, e.g., `These entities are subject to an upcoming audit. Please review to ensure we stay compliant.`
   * **Require reason for verification**: Check this box to require the user to include a reason if they confirm that the entity's data is invalid.
     * We recommend requiring a reason, as it will allow you to quickly understand what needs to be fixed on an entity.
   * **Team member roles responsible for verification**: Select which Cortex users will be responsible for verifying data.
     * If you select multiple roles, any team member with one of those roles can verify data.
     * If you do not select a team member role, any direct member of the entity's owning team can verify data.
     * Before you restrict verification to a role, confirm that your team members have that role assigned in Cortex. See [Who can verify an entity](/configure/settings/entity-settings/verification.md#who-can-verify-an-entity).
   * **Entities to verify**: Specify which entities the verification policy applies to.
     * You can select a specific entity type to include (for example, you could apply the verification to all entities of the type `service`) or if your entities have groups assigned, you can filter by specific groups.
     * Under **Advanced options**, you can use CQL to refine which entities you want to verify. For example, you might narrow your selection to entities created in the last two weeks:\

       `entity.created() < duration("P2W")`
3. Click **Create verification period**.

Within a few minutes of saving the verification period, it will be visible to admins in the list of verifications on the [Entity verification settings page](https://app.getcortexapp.com/admin/settings/entities/verification). Entity owners will receive notifications to verify their entities.

## Remediate entities with incorrect data

After setting up the verification period, you can [create a CQL report to view all entities that have been verified as incorrect](/configure/settings/entity-settings/verification#view-all-unverified-or-incorrect-entities) using a prebuilt CQL report template.

Cortex also offers a prebuilt [Scorecard template to flag entities that have not yet been verified](/configure/settings/entity-settings/verification#flag-unverified-entities-via-scorecard).


# Link SOC 2 documents to entity
Source: https://docs.cortex.io/guides/compliance/link-soc2-docs



This guide explains how to use a Workflow to streamline the process of linking SOC 2 documents to an entity.

## Create a Workflow to link SOC 2 documents to an entity

### Prerequisites

Before getting started:

* You must have the `Edit Workflows` [permission](/configure/settings/managing-users/permissioning) to create the Workflow, and the `Execute Workflow runs` permission to run it.

### Step 1: Create the Workflow

You can create a Workflow in the Cortex UI or via the Cortex CLI.

**Cortex CLI**

#### Add the Workflow via CLI

You can use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to add the example Workflow to your workspace. This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more:

> **Import the Workflow via CLI**
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: Link SOC2 Documents to Entity
> tag: link-soc2-documents-to-an-entity
> description: null
> isDraft: true
> filter:
>   entityFilter:
>     typeFilter:
>       types:
>       - service
>     entityGroupFilter: null
>   ownershipScope: ALL
>   type: ENTITY
> runResponseTemplate: null
> failedRunResponseTemplate: null
> restrictActionCompletionToRunnerUser: false
> actions:
> - name: User input
>   slug: user-input
>   schema:
>     inputs:
>     - name: Link Type
>       description: null
>       key: link-type
>       required: false
>       options:
>       - pen-test
>       - data-retention-policy
>       optionsLabels:
>       - Pen Test
>       - Data Retention Policy
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     - name: Link URL
>       description: null
>       key: link-url
>       required: false
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: INPUT_FIELD
>     inputOverrides: []
>     jsValidatorScript: ""
>     type: USER_INPUT
>   outgoingActions:
>   - retrieve-entity-descriptor
>   isRootAction: true
> - name: Retrieve entity descriptor
>   slug: retrieve-entity-descriptor
>   schema:
>     inputs:
>       entityId: "{{context.entity.tag}}"
>     integrationAlias: null
>     actionIdentifier: cortex.retrieveEntityDescriptor
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - javascript
>   isRootAction: false
> - name: JavaScript
>   slug: javascript
>   schema:
>     script: |+
>       const descriptor = actions['retrieve-entity-descriptor']?.outputs?.descriptor;
>       const linkType   = actions['user-input']?.outputs?.['link-type'];
>       const linkUrl    = actions['user-input']?.outputs?.['link-url'];
>
>       if (!descriptor || typeof descriptor !== 'string') {
>         throw new Error('Descriptor must be a YAML string.');
>       }
>       const rawType = String(linkType || '').trim();
>       const rawUrl  = String(linkUrl || '').trim();
>       if (!rawType || !rawUrl) {
>         throw new Error('Both link-type and link-url are required.');
>       }
>
>       // Normalize input for mapping
>       const normalize = s => s.toLowerCase().replace(/[_\s-]+/g, ' ').trim();
>       const normType = normalize(rawType);
>
>       let finalType, finalName;
>       if (normType === 'pen test' || normType === 'pentest') {
>         finalType = 'pen-test';
>         finalName = 'Pen Test';
>       } else if (normType === 'data retention policy') {
>         finalType = 'documentation';
>         finalName = rawType; // keep exactly what the user selected
>       } else {
>         finalType = rawType;
>         finalName = rawType;
>       }
>
>       // Parse YAML
>       let obj;
>       try {
>         if (typeof YAML.load === 'function') {
>           obj = YAML.load(descriptor) || {};
>         } else if (typeof YAML.parse === 'function') {
>           obj = YAML.parse(descriptor) || {};
>         } else {
>           throw new Error('YAML parser not available in this runtime.');
>         }
>       } catch (err) {
>         throw new Error('Failed to parse descriptor YAML: ' + err.message);
>       }
>
>       // Ensure x-cortex-link exists
>       if (!obj.info) obj.info = {};
>       const linkKey = 'x-cortex-link';
>       const existing = obj.info[linkKey];
>       obj.info[linkKey] = Array.isArray(existing) ? existing : (existing ? [existing] : []);
>
>       // Normalize existing links
>       const current = obj.info[linkKey]
>         .filter(Boolean)
>         .map(l => ({
>           url: l.url ? String(l.url).trim() : '',
>           name: l.name ? String(l.name).trim() : '',
>           type: l.type ? String(l.type).trim() : '',
>         }))
>         .filter(l => l.url && l.name && l.type);
>
>       // Add new link if not duplicate
>       const incoming = { url: rawUrl, name: finalName, type: finalType };
>       const sig = l => `${l.url}::${l.type}::${l.name}`;
>       const seen = new Set(current.map(sig));
>       if (!seen.has(sig(incoming))) current.push(incoming);
>
>       obj.info[linkKey] = current.map(l => ({ url: l.url, name: l.name, type: l.type }));
>
>       // Dump back to YAML
>       let updatedDescriptor;
>       try {
>         if (typeof YAML.dump === 'function') {
>           updatedDescriptor = YAML.dump(obj, { indent: 2, lineWidth: 120 });
>         } else if (typeof YAML.stringify === 'function') {
>           updatedDescriptor = YAML.stringify(obj, { indent: 2 });
>         } else {
>           throw new Error('YAML serializer not available.');
>         }
>       } catch (err) {
>         throw new Error('Failed to serialize descriptor YAML: ' + err.message);
>       }
>
>       // ✅ Return updatedDescriptor (not wrapped in {body=...})
>       return { updatedDescriptor };
>
>     type: JAVASCRIPT
>   outgoingActions:
>   - create-or-update-entity
>   isRootAction: false
> - name: Create or update entity
>   slug: create-or-update-entity
>   schema:
>     inputs:
>       body: "{{{actions.javascript.outputs.result.updatedDescriptor}}}"
>       dryRun: false
>     integrationAlias: null
>     actionIdentifier: cortex.createOrUpdateEntity
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: SecurityCamera
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file: `cortex workflows create -f <path-to-your-workflow.yaml>`

**Cortex UI**

#### Step 1.1: Create the Workflow and configure basic settings

1. In Cortex, navigate to **Workflows**. In the upper right corner, click **+Create workflow**. Choose a blank Workflow.
2. Follow the documentation to [configure the basic settings for your Workflow](/streamline/workflows/create#creating-a-workflow).

#### Step 1.2: Add blocks to the Workflow

Add the following blocks to your Workflow:

> **User input**
>
> Add a User Input block to collect the link type, link URL, and which entity to update.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **User input**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `User input` and the slug `user-input`.
> 3. Click **+Add user input**. Add the following:
>    * **Name**: Link type
>    * **Key**: link-type
>    * **Type**: Select
>    * **Data source**: Manual
>    * **Options**: Click **+Add option** to add options for `Pen Test` and `Data Retention Policy`.
>    * Click **Add input**.
> 4. Click **+Add user input**. Add the following:
>    * **Name**: Link URL
>    * **Key**: link-url
>    * **Type**: Text
>    * Click **Add input**.
> 5. At the bottom of the side panel, click **Save**.

> **Retrieve entity descriptor**
>
> This block retrieves the entity descriptor.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Cortex > Retrieve entity descriptor** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Retrieve entity descriptor` and the slug `retrieve-entity-descriptor`.
> 3. Configure the block:
>    * **Entity ID or tag**: `{{context.entity.tag}}`
> 4. At the bottom of the side panel, click **Save**.

> **JavaScript**
>
> This step retrieves the entity tag, validates required inputs, normalizes the data, and returns the updated link object in YAML format for use in the next Workflow block.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Cortex > Retrieve entity descriptor** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `JavaScript` and the slug `javascript`.
> 3. In the text editor under the **JavaScript** header, enter the following:
>
> ```javascript theme={null}
> const descriptor = actions['retrieve-entity-descriptor']?.outputs?.descriptor;
> const linkType   = actions['user-input']?.outputs?.['link-type'];
> const linkUrl    = actions['user-input']?.outputs?.['link-url'];
>
> if (!descriptor || typeof descriptor !== 'string') {
>   throw new Error('Descriptor must be a YAML string.');
> }
> const rawType = String(linkType || '').trim();
> const rawUrl  = String(linkUrl || '').trim();
> if (!rawType || !rawUrl) {
>   throw new Error('Both link-type and link-url are required.');
> }
>
> // Normalize input for mapping
> const normalize = s => s.toLowerCase().replace(/[_\s-]+/g, ' ').trim();
> const normType = normalize(rawType);
>
> let finalType, finalName;
> if (normType === 'pen test' || normType === 'pentest') {
>   finalType = 'pen-test';
>   finalName = 'Pen Test';
> } else if (normType === 'data retention policy') {
>   finalType = 'documentation';
>   finalName = rawType; // keep exactly what the user selected
> } else {
>   finalType = rawType;
>   finalName = rawType;
> }
>
> // Parse YAML
> let obj;
> try {
>   if (typeof YAML.load === 'function') {
>     obj = YAML.load(descriptor) || {};
>   } else if (typeof YAML.parse === 'function') {
>     obj = YAML.parse(descriptor) || {};
>   } else {
>     throw new Error('YAML parser not available in this runtime.');
>   }
> } catch (err) {
>   throw new Error('Failed to parse descriptor YAML: ' + err.message);
> }
>
> // Ensure x-cortex-link exists
> if (!obj.info) obj.info = {};
> const linkKey = 'x-cortex-link';
> const existing = obj.info[linkKey];
> obj.info[linkKey] = Array.isArray(existing) ? existing : (existing ? [existing] : []);
>
> // Normalize existing links
> const current = obj.info[linkKey]
>   .filter(Boolean)
>   .map(l => ({
>     url: l.url ? String(l.url).trim() : '',
>     name: l.name ? String(l.name).trim() : '',
>     type: l.type ? String(l.type).trim() : '',
>   }))
>   .filter(l => l.url && l.name && l.type);
>
> // Add new link if not duplicate
> const incoming = { url: rawUrl, name: finalName, type: finalType };
> const sig = l => `${l.url}::${l.type}::${l.name}`;
> const seen = new Set(current.map(sig));
> if (!seen.has(sig(incoming))) current.push(incoming);
>
> obj.info[linkKey] = current.map(l => ({ url: l.url, name: l.name, type: l.type }));
>
> // Dump back to YAML
> let updatedDescriptor;
> try {
>   if (typeof YAML.dump === 'function') {
>     updatedDescriptor = YAML.dump(obj, { indent: 2, lineWidth: 120 });
>   } else if (typeof YAML.stringify === 'function') {
>     updatedDescriptor = YAML.stringify(obj, { indent: 2 });
>   } else {
>     throw new Error('YAML serializer not available.');
>   }
> } catch (err) {
>   throw new Error('Failed to serialize descriptor YAML: ' + err.message);
> }
>
> // ✅ Return updatedDescriptor (not wrapped in {body=...})
> return { updatedDescriptor };
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **Create or update entity**
>
> This block takes the object returned in the previous block and uses it to update the entity.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Cortex > Create or update entity** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Create or update entity` and the slug `create-or-update-entity`.
> 3. Configure the block:
>    * **Descriptor**: `{{{actions.javascript.outputs.result.updatedDescriptor}}}`
> 4. At the bottom of the side panel, click **Save**.

When you are finished adding blocks, click **Save workflow** in the upper right corner of the page.

### Step 2: Run the Workflow

* In the [list of Workflows](https://app.getcortexapp.com/admin/workflows), locate the "Link SOC 2 Documents to Entity" Workflow and click **Run**.

When you run the Workflow, the following events happen:

1. The Workflow pauses to collect a response from the user during the User Input block. The user selects an entity, then enters a link type and link URL.
2. The next step runs, retrieving the entity descriptor.
3. The JavaScript block runs, which does the following:
   1. It retrieves the entity descriptor from the previous block, and it retrieves the link type and URL from the initial block. It validates that the required inputs exist.
   2. It normalizes the link type. It parses the descriptor string into a JavaScript object.
   3. It creates a new link object with url, name, and type, and it only adds the new link if it doesn't already exist.
   4. It converts the updated object back to YAML format, and returns `{ updatedDescriptor }` for use in subsequent Workflow blocks.
4. The "Create or update entity" block runs, updating the entity with the `updatedDescriptor` output of the previous block.


# Ensure SOC 2 compliance
Source: https://docs.cortex.io/guides/compliance/soc2



Cortex enables streamlined SOC 2 compliance by eliminating manual, spreadsheet-based tracking and connecting real time system data to control verification.

To improve consistency across your compliance tracking:

* You can [launch a SOC 2 Compliance Scorecard](/guides/compliance/soc2#create-a-soc-2-scorecard). Cortex provides a prebuilt SOC 2 compliance [Scorecard](/standardize/scorecards) template that you can use to track audit-related controls and standards.
* You can [launch an Initiative](/guides/compliance/soc2#create-a-soc-2-initiative) associated with the Scorecard, which gives your engineers a deadline for when to complete certain goals.
* [Use reports and Cortex MCP](/guides/compliance/soc2#measuring-success) to better understand progress and next steps.

## Create a SOC 2 Scorecard

### Prerequisites

Before using this Scorecard template:

* Ensure you have configured integrations for:
  * Version control: [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), or [GitLab](/ingesting-data-into-cortex/integrations/gitlab).
  * [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty)
  * [Snyk](/ingesting-data-into-cortex/integrations/snyk)
    * This Scorecard uses Snyk for its vulnerability scanning rules, but the rules can be modified to check vulnerability data from [Checkmarx](/ingesting-data-into-cortex/integrations/checkmarx), [Mend](/ingesting-data-into-cortex/integrations/mend), [Semgrep](/ingesting-data-into-cortex/integrations/semgrep), [Veracode](/ingesting-data-into-cortex/integrations/veracode), or [Wiz](/ingesting-data-into-cortex/integrations/wiz).
      * See [CQL Explorer](https://app.getcortexapp.com/admin/queries) in your Cortex workspace for example queries for these integrations.
* Ensure you have [created custom data fields](/ingesting-data-into-cortex/entities-overview/entities/custom-data) called `tls_enabled` and `last_risk_assessment_date`.

### Step 1: Create the Scorecard and configure its basic settings

You can create a Scorecard in the Cortex UI, or you can add it to your workspace via GitOps or the Cortex API.

**Cortex UI**

#### Create Scorecard in the Cortex UI

1. On the [**Scorecards** page](https://app.getcortexapp.com/admin/scorecards) in your workspace, click **Create Scorecard**.
2. On the `SOC-2 Compliance` template, click **Use**.
3. Configure basic settings, including the Scorecard's name, unique identifier, description, and more.
   * Learn about configuring the basic settings in the [Creating a Scorecard documentation](/standardize/scorecards/create).

**GitOps or API**

#### Create Scorecard via GitOps or API

When following a [GitOps approach](/configure/gitops), you can add a Scorecard YAML file to your `.cortex/scorecards` directory in your version control repository. Note that GitOps must be enabled for Scorecards in your [GitOps settings](/configure/settings/gitops-settings).

You could also use the [Cortex API,](/api/rest/scorecards) where you can submit a Scorecard definition in YAML.

> **SOC 2 Scorecard YAML**
>
> Use the YAML file below to add this Scorecard to your workspace via the API or via a GitOps flow.
>
> ```yaml theme={null}
> tag: soc-2
> name: SOC 2 Compliance
> description: |-
>   Ensure services meet SOC 2 requirements by tracking key security, operational, and maturity controls including ownership, TLS, vulnerability scans, and risk assessments.
>
>   (Created from Scorecard template)
> draft: false
> notifications:
>   enabled: false
>   scoreDropNotificationsEnabled: false
> exemptions:
>   enabled: true
>   autoApprove: false
>   userSpecificNotifications: false
> ladder:
>   name: Default Ladder
>   levels:
>   - name: Foundational Security
>     rank: 1
>     color: "#c38b5f"
>   - name: Operational Compliance
>     rank: 2
>     color: "#8c9298"
>   - name: Advanced SOC 2 Maturity
>     rank: 3
>     color: "#cda400"
> rules:
> - title: Pen test linked
>   expression: links("pen-test").length > 0
>   identifier: 1ac74f97-0e8a-3d5c-bde2-f71890c34f6d
>   weight: 1
>   level: Advanced SOC 2 Maturity
>   failureMessage: "Add a link of type pen-test by following the instructions in [our\
>     \ docs](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/external-docs#add-links-to-an-entity)."
> - title: On-call is set
>   expression: oncall != null
>   identifier: 2a2e6d7e-9ea1-3df6-a2a1-8db501126d53
>   weight: 1
>   level: Foundational Security
>   failureMessage: "Add an on-call rotation by following the instructions in our docs\
>     \ for the [on-call integration](https://docs.cortex.io/ingesting-data-into-cortex/integrations#on-call)\
>     \ your team uses."
> - title: Service has ownership
>   expression: ownership != null
>   identifier: 2d3e1a5a-2012-3b28-b561-dd31c73117aa
>   weight: 1
>   level: Foundational Security
>   failureMessage: "Add an owner by following the instructions in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership)."
> - title: Service included in Risk Assessment in last year
>   expression: custom("last_risk_assessment_date").fromNow() > duration("P1Y")
>   identifier: 66283efc-364e-3b29-9f00-9fb4bcc6e785
>   weight: 1
>   level: Advanced SOC 2 Maturity
> - title: TLS is enabled
>   expression: custom("tls_enabled") == true
>   identifier: 887c666a-09bd-3ab8-95e3-ff005e68563d
>   weight: 1
>   level: Foundational Security
> - title: Branch protection is set on default branch
>   expression: git.branchProtection("main") != null
>   identifier: 97cab18c-cd5b-3c66-baf3-4da2291cd022
>   weight: 1
>   level: Foundational Security
> - title: Data retention policy linked
>   expression: links("document").filter((link) => link.name.matches("data-retention*")).length
>     > 0
>   identifier: 9ebf4ee6-5af6-369b-8bb3-67365be7900f
>   weight: 1
>   level: Operational Compliance
>   failureMessage: "Add a link of type document with a name that starts with data-retention\
>     \ by following the instructions in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/external-docs#add-links-to-an-entity)."
> - title: PR approval is required to merge
>   expression: git.numOfRequiredApprovals() > 0
>   identifier: a148260a-81c3-3201-9692-de99fd08ed16
>   weight: 1
>   level: Foundational Security
> - title: Vuln scan passing (med & high)
>   expression: "snyk.numOfIssues(severity=[\"HIGH\", \"CRITICAL\", \"MEDIUM\"]) <=\
>     \ 0"
>   identifier: ce7d90a6-fa92-3bfb-9eaf-ab3bb3f1deb3
>   weight: 1
>   level: Operational Compliance
> - title: Unit testing in place
>   expression: |
>     git.workflowRuns().filter((run) => run.name.matchesIn("Unit Test")).length > 0
>   identifier: e5e9ecd2-683f-3b63-8da9-fdb807fbc736
>   weight: 1
>   level: Operational Compliance
> - title: "Vuln scan passing (low, med & high)"
>   expression: "snyk.numOfIssues(severity=[\"HIGH\", \"CRITICAL\", \"MEDIUM\", \"LOW\"\
>     ]) <= 0"
>   identifier: f7e0f628-cd94-3f08-aeb9-72b03565c5d7
>   weight: 1
>   level: Advanced SOC 2 Maturity
> filter:
>   kind: GENERIC
>   types:
>     include:
>     - service
> ```

### Step 2: Review and modify rules

Cortex's templated rules are based on common industry standards:

> **Level 1: Foundational Security**
>
> * On-call is set\\
>
>   `oncall != null`
> * Service has ownership\\
>
>   `ownership != null`
> * TLS is enabled\\
>
>   `custom("tls_enabled") == true`
> * Branch protection is set on default branch\\
>
>   `git.branchProtection("main") != null`
> * PR approval is required to merge\\
>
>   `git.numOfRequiredApprovals() > 0`

> **Level 2: Operational Compliance**
>
> * Data retention policy linked\\
>
>   `links("document").filter((link) => link.name.matches("data-retention*")).length > 0`
> * Vulnerability scan passing (medium & high)\\
>
>   `snyk.numOfIssues(severity=["HIGH", "CRITICAL", "MEDIUM"]) <= 0`
> * Unit testing in place\\
>
>   `git.workflowRuns().filter((run) => run.name.matchesIn("Unit Test")).length > 0`

> **Level 3: Advanced SOC 2 Maturity**
>
> * Pen test linked\\
>
>   `links("pen-test").length > 0`
> * Service included in Risk Assessment in last year\\
>
>   `custom("last_risk_assessment_date").fromNow() > duration("P1Y")`
> * Vulnerability scan passing (low, medium, & high)\\
>
>   `snyk.numOfIssues(severity=["HIGH", "CRITICAL", "MEDIUM", "LOW"]) <= 0`

You can reorder, delete, and edit rules, add more rules to a level, and assign more points to a rule to signify its importance. Behind each rule is a [Cortex Query Language (CQL) ](/standardize/cql)query; you can edit the existing CQL or write your own queries to further refine your rules.

## Create a SOC 2 Initiative

Follow the steps below to create an Initiative:

> **Create a SOC 2 Initiative**
>
> To motivate change by a certain deadline, you can create an Initiative:
>
> 1. While viewing your SOC 2 Compliance Scorecard, click **Create Initiative** in the upper right.
> 2. Configure the Initiative fields, including a descriptive name so your team members understand the purpose of the Initiative. For example, `Ensure data retention policy is linked for all services`.
>    * Make sure to enable notifications so users are notified if an entity they own is failing the Initiative's goal.
> 3. Save the Initiative.
>
> After the Initiative is published, entity owners will be notified if their entity is not meeting the goal.
>
> Learn more about [creating Initiatives in the docs](/improve/initiatives).

## Measuring success

To understand progress of your Scorecard:

* Ask [Cortex MCP,](/get-started/cortex-ai-assistant/mcp) "How is my SOC 2 Scorecard doing?" The MCP will respond with information on the entities that are failing rules and suggested next steps.
* Review reports: The [Bird's Eye report](/improve/reports/birds-eye) gives insight into how entities are performing against the Scorecard by visualizing the data as a heat map:\


  ![The bird's eye report shows Scorecard progress as a heatmap.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/soc2-birds-eye-1.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=78551fc1b6ce83a8e17151e294aab64a)

You can also review your Engineering Intelligence metrics for impact on key engineering metrics, such as:

* **MTTR**: With best practices in place, such as on-call rotation and ownership, you should see faster incident response.
* **Deployment frequency**: Improved governance reduces rework and manual gates. Once baselines are set, you may see deployment frequency increasing.


# Automate user access to Copilot
Source: https://docs.cortex.io/guides/dev-onboarding/automate-user-access-to-copilot



This Workflow automatically sets up developers with access to GitHub Copilot.

In this example, approval from a specific team is required. Depending on your organization's requirements, you may want to configure a [User input](/streamline/workflows/blocks#configuring-a-core-block) block instead, effectively allowing users to self-serve access to GitHub Copilot without needing approval from a specific team.

### Prerequisites

Before getting started:

* Before calling the GitHub API endpoint in the Async HTTP request block, your organization must already be on Copilot Business or Enterprise and have seat management policies configured.
* You must [create a secret in Cortex](/configure/settings/api-keys/secrets).
  * In this example, the secret in Cortex must be named `GITHUB_COPILOT_TOKEN`.

### Step 1: Start creating the Workflow

Follow the steps in the documentation to [create a Workflow](/streamline/workflows/create) and [configure its basic settings](/streamline/workflows/create#creating-a-workflow).

Note that Cortex has a pre-built template for this Workflow that contains the [Async HTTP request](/guides/dev-onboarding/automate-user-access-to-copilot#step-2-add-blocks-to-the-workflow) block. The example on this page includes an additional [Manual approval](/guides/dev-onboarding/automate-user-access-to-copilot#step-2-add-blocks-to-the-workflow) block that allows you to designate an approving team. Also in this example, the payload of the Async HTTP block includes `approver": "{{actions.manual-approval.outputs.actor}}`, which references the output of the Manual approval block. This reference is not included in the pre-built Workflow template.

### Step 2: Add blocks to the Workflow

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Workflow YAML instructions**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: Approve access to GitHub Copilot
> tag: copilot-access
> description: "Get approval from the Platform team, then provision a seat in Copilot\
>   \ for the user who initiates the Workflow run."
> isDraft: true
> filter:
>   type: GLOBAL
> runResponseTemplate: "Successfully provisioned GitHub Copilot for {{context.initiatedBy.email}}"
> failedRunResponseTemplate: "Failed to add a seat to GitHub Copilot for {{context.initiatedBy.email}}"
> restrictActionCompletionToRunnerUser: false
> actions:
> - name: Manual approval
>   slug: manual-approval
>   schema:
>     approvingTeamIds:
>     - en319eca313083ac36
>     approverDescription: null
>     type: MANUAL_APPROVAL
>   outgoingActions:
>   - asynchronous-http-request
>   isRootAction: true
> - name: Asynchronous HTTP request
>   slug: asynchronous-http-request
>   schema:
>     headers:
>       Authorization: "Bearer {{ context.secrets.GITHUB_COPILOT_TOKEN }}"
>     httpMethod: POST
>     payload: |-
>       {
>       "inputs": {"email": "{{context.initiatedBy.email}}", "approver": "{{actions.manual-approval.outputs.actor}}", "callback": "{{callbackUrl}}", "github_user": "{{context.initiatedBy.identityMappings.github}}"  },
>       "ref": "main"
>       }
>     url: https://api.github.com/orgs/cortexapps/copilot/billing/selected_users
>     timeoutInSeconds: null
>     type: HTTP_REQUEST_ASYNC
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

Expand the tiles below to learn about each block in this Workflow and how to configure them in the Cortex UI:

> **Manual approval**
>
> In this block, you select which team has to give approval for the user to access GitHub Copilot.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Manual approval**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Manual approval` and the slug `manual-approval`.
> 3. Under **Teams allowed to approve**, select the teams authorized to approve access to GitHub Copilot.
> 4. Save the block.

> **Async HTTP request**
>
> This block looks at the initiating user's [identity mapping](/configure/settings/managing-users/identity-mapping) in Cortex for GitHub, then calls the GitHub API to grant access to Copilot for that user.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Async HTTP request**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Grant access to Copilot` and the slug `copilot-access`.
> 3. Configure the block:
>    * **HTTP method**: `POST`
>    * **URL**: Enter a URL for the request.
>      * In this example, we call the GitHub endpoint that adds users to your org's Copilot subscription: `https://api.github.com/orgs/<your-org>/copilot/billing/selected_users`
>    * **Headers**: `Authorization: Bearer {{ context.secrets.GITHUB_COPILOT_TOKEN }}`
>      * The token you configure must have [permissions to manage Copilot seats](https://docs.github.com/en/rest/copilot/copilot-user-management).
>      * In this example, the secret in Cortex must be named `GITHUB_COPILOT_TOKEN`.
>    * **Payload**:
>
> ```json theme={null}
> {
> "inputs": {"email": "{{context.initiatedBy.email}}", "approver": "{{actions.manual-approval.outputs.actor}}", "callback": "{{callbackUrl}}", "github_user": "{{context.initiatedBy.identityMappings.github}}"  },
> "ref": "main"
> }
> ```
>
> 4. Save the block.

### Step 3: Run the Workflow

When you run the Workflow, the following events happen:

* The Workflow pauses to collect a response from a member of one of the teams specified during the Manual approval block.
* After a user gives their approval, the Async HTTP request block runs. It uses the initiator of the Workflow as the GitHub user, then makes a call to the GitHub API to provision access to Copilot for that user.


# Automate user access to GitHub, PagerDuty, and Jira
Source: https://docs.cortex.io/guides/dev-onboarding/automate-user-access-to-github-pagerduty-and-jira



This Workflow automatically sets up new developers with access to GitHub, PagerDuty, and Jira.

#### Step 1: Start creating the Workflow [#step-1-start-creating-the-workflow](#step-1-start-creating-the-workflow)

Follow the steps in the documentation to [create a Workflow](/streamline/workflows/create) and [configure its basic settings](/streamline/workflows/create#creating-a-workflow).

#### Step 2: Add blocks to the Workflow [#step-2-add-blocks-to-the-workflow](#step-2-add-blocks-to-the-workflow)

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Workflow YAML instructions**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: "Dev Onboarding: User Access"
> tag: dev-onboarding-user-access
> description: "Automatically sets up new developers with access to GitHub, PagerDuty,\
>   \ and Jira."
> isDraft: false
> filter:
>   type: GLOBAL
> runResponseTemplate: null
> failedRunResponseTemplate: null
> restrictActionCompletionToRunnerUser: false
> actions:
> - name: Get GH Username
>   slug: get-gh-username
>   schema:
>     inputs:
>     - name: GitHub Username
>       description: Enter your personal GitHub username.
>       key: github-username
>       required: false
>       defaultValue: null
>       placeholder: null
>       validationRegex: "^[^\\s]+$"
>       type: INPUT_FIELD
>     inputOverrides: []
>     type: USER_INPUT
>   outgoingActions:
>   - add-user-to-org
>   isRootAction: true
> - name: Add user to GH org
>   slug: add-user-to-org
>   schema:
>     inputs:
>       org: cortexapps
>       role: member
>       username: actions.get-gh-username.outputs.github-username
>     integrationAlias: cortex
>     actionIdentifier: github.addUserToOrg
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - add-user-to-pd
>   isRootAction: false
> - name: Add user to PagerDuty
>   slug: add-user-to-pd
>   schema:
>     headers:
>       Accept: application/vnd.pagerduty+json;version=2
>       Authorization: "Bearer {{context.secrets.pd_token}}"
>     httpMethod: POST
>     payload: |-
>       {
>         "user": {
>           "type": "user",
>           "name": "{{context.initiatedBy.name}}",
>           "email": "{{context.initiatedBy.email}}"
>         }
>       }
>     url: https://api.pagerduty.com/users
>     type: HTTP_REQUEST
>   outgoingActions:
>   - add-user-to-jira
>   isRootAction: false
> - name: Add user to Jira
>   slug: add-user-to-jira
>   schema:
>     headers: {}
>     httpMethod: POST
>     payload: |-
>       {
>         "emailAddress": "{{context.initiatedBy.email}}",
>         "displayName": "{{context.initiatedBy.name}}"
>       }`
>     url: https://cortex.atlassian.net/rest/api/3/user
>     type: HTTP_REQUEST
>   outgoingActions:
>   - send-message
>   isRootAction: false
> - name: Send message
>   slug: send-message
>   schema:
>     channel: social
>     message: "{{context.initiatedBy.name}} has been added to GitHub, PagerDuty, and\
>       \ Jira."
>     type: SLACK
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: AndroidLogo
> variables: []
>
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

Expand the tiles below to learn about each block in this Workflow and how to configure them in the Cortex UI:

> **User input**
>
> In this example, we add a User Input block to obtain the user's GitHub username.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **User input**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get GH Username` and the slug `get-gh-username`.
> 3. Click **+Add user input**. Add the following:
>    * **Name**: GitHub Username
>    * **Key**: github-username
>    * **Description**: Enter your personal GitHub username.
>    * **Type**: Text
>    * Click **Add input**.
> 4. At the bottom of the side panel, click **Save**.

> **Add user to GitHub org**
>
> This block adds a user to a GitHub organization.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **GitHub > Add user to org** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Add user to GH org` and the slug `add-user-to-org`.
> 3. Configure the block:
>    * **Alias**: Choose which GitHub configuration to use.
>    * **Organization**: Enter your GitHub organization name.
>    * **Username**: Enter the handle for the user's GitHub account.
>      * In our example, we use templating to take the output of the previous step and set it as the value for this field: `actions.get-gh-username.outputs.github-username`
>    * **Role**: Select the role of the user in the organization.
> 4. At the bottom of the side panel, click **Save**.

> **HTTP requests**
>
> There are two HTTP requests that perform the following actions: Adding the user to PagerDuty and adding the user to Jira.
>
> **Add the user to PagerDuty**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **HTTP request** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Add user to PagerDuty` and the slug `add-user-to-pd`.
> 3. Configure the block:
>    1. **HTTP method**: POST
>    2. **URL**: In our example, we set this to `https://api.pagerduty.com/users`.
>    3. **Headers**: Set the following headers:
>       * `Accept`: `application/vnd.pagerduty+json;version=2`
>       * `Authorization`: `Bearer {{ context.secrets.pd_token }}`
>    4. **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>   "user": {
>     "type": "user",
>     "name": "{{context.initiatedBy.name}}",
>     "email": "{{context.initiatedBy.email}}"
>   }
> }
> ```
>
> 4. Save the block.
>
> **Add the user to Jira**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **HTTP request** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Add user to Jira` and the slug `add-user-to-jira`.
> 3. Configure the block:
>    1. **HTTP method**: POST
>    2. **URL**: In our example, we set this to:\\
>
>       `https://cortex.atlassian.net/rest/api/3/user`
>    3. **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>   "emailAddress": "{{context.initiatedBy.email}}",
>   "displayName": "{{context.initiatedBy.name}}"
> }`
> ```
>
> 4. Save the block.

> **Slack message**
>
> In this step, we send a templated message via Slack informing the user that they have been added to GitHub, PageryDuty, and Jira.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Slack** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Send message` and the slug `send-message`.
> 3. Select a Slack channel name.
> 4. Enter text for the message that will be sent via Slack. In our example, we use the following:
>
> ```
> {{context.initiatedBy.name}} has been added to GitHub, PagerDuty, and Jira.
> ```
>
> 5. Save the block.

#### Step 3: Run the Workflow [#step-3-run-the-workflow](#step-3-run-the-workflow)

When you run the Workflow, the following events happen:

* The Workflow pauses to collect a response from the user during the User Input block.
* The "Add user to org" block runs. It uses the output of the previous block as the username, then automatically adds to that user to the specified GitHub org.
* The first HTTP request runs. Using the name and email address of the user who initiated the Workflow, it creates a user in PagerDuty.
* The second HTTP request runs. Using the name and email address of the user who initiated the Workflow, it creates a user in Jira.
* The Slack block runs, which sends a Slack message to the user to let them know that their GitHub, PagerDuty, and Jira accounts are ready.


# Automate new dev environment
Source: https://docs.cortex.io/guides/dev-onboarding/env-setup-workflow



This example automates the creation of a GitHub repository, infrastructure provisioning with Terraform, and generates a PR for setting up an RDS instance.

### Step 1: Register the Scaffolder templates

This Workflow uses two Scaffolder templates:

* [Hello Org Template](https://github.com/cortex-workshops/hello-org-template)
* [Terraform RDS Template](https://github.com/cortex-workshops/terraform-rds-template)

Follow the instructions to [register the Scaffolder templates in Cortex](/streamline/workflows/scaffolder).

### Step 2: Start creating the Workflow

Follow the steps in the documentation to [create a Workflow](/streamline/workflows/create) and [configure its basic settings](/streamline/workflows/create#creating-a-workflow).

### Step 3: Add blocks to the Workflow

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Workflow YAML instructions**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: "Dev Onboarding: Environment Setup"
> tag: dev-onboarding-env-setup
> description: "This workflow automates the creation of a GitHub repository, infrastructure\
>   \ provisioning with Terraform, and generates a PR for setting up an RDS instance."
> isDraft: false
> filter:
>   type: GLOBAL
> runResponseTemplate: null
> failedRunResponseTemplate: null
> restrictActionCompletionToRunnerUser: false
> actions:
> - name: Transform User Info
>   slug: transform-user-info
>   schema:
>     expression: .context.initiatedBy.name + "-repo"
>     type: JQ
>   outgoingActions:
>   - scaffold-hello-org
>   isRootAction: true
> - name: Scaffold Hello Org Repo
>   slug: scaffold-hello-org
>   schema:
>     scaffolderTemplateId: st363f187d3e1a826e
>     createNewRepository: true
>     createService: null
>     inputOverrides:
>     - inputKey: repo_name
>       outputVariable: actions.transform-user-info.outputs.result
>       editable: false
>       type: VALUE
>     type: SCAFFOLDER
>   outgoingActions:
>   - trigger-workflow
>   isRootAction: false
> - name: Terraform Infrastructure Provisioning
>   slug: trigger-workflow
>   schema:
>     inputs:
>       ref: main
>       repo: cortex-workshops/terraform
>       inputs: "{\"user\": \"{{context.initiatedBy.name}}\"}"
>       workflow_id: .github/workflows/main.yaml
>     integrationAlias: cortex
>     actionIdentifier: github.createWorkflowDispatchEvent
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - scaffold-rds-terraform
>   isRootAction: false
> - name: Open PR with RDS terraform
>   slug: scaffold-rds-terraform
>   schema:
>     scaffolderTemplateId: st363f198d56473124
>     createNewRepository: false
>     createService: null
>     inputOverrides:
>     - inputKey: publisherRepoFullName
>       outputVariable: actions.scaffold-hello-org.outputs.response.gitURL
>       editable: false
>       type: VALUE
>     type: SCAFFOLDER
>   outgoingActions:
>   - notify-developer
>   isRootAction: false
> - name: Notify Developer
>   slug: notify-developer
>   schema:
>     channel: all-es-testing
>     message: "Hi, {{context.initiatedBy.name}}! Your new test environment is ready\
>       \ to go!"
>     type: SLACK
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: Keyboard
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

Expand the tiles below to learn about each block in this Workflow and how to configure them in the Cortex UI:

> **Data transformation**
>
> Create a data transformation to take the Workflow initiator's name and append `-repo` to it:
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Transform user info` and the slug `transform-user-info`.
> 3. Add a jq expression to take the initiator's name and add `-repo` to it:
>
> ```jq theme={null}
> .context.initiatedBy.name + "-repo"
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **Scaffolder**
>
> This block creates a new repository in your connected Git integration, using templating to apply the output of the previous block to the Scaffolder configuration.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Scaffolder** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    1. In this example, we use the name `Scaffold Hello Org Repo` and the slug `scaffold-hello-org`.
> 3. Under **Scaffolder template**, select your template. In this example, we use `Hello Org Template`.
> 4. Select the option to **Create a new repo**.
> 5. Add override variables. The **Variable** dropdown pulls in all the variables that are able to be overridden in the Git provider and in the Scaffolder template. In this example, we apply the following override:
>    * **repo\_name**: `actions.transform-user-info.outputs.result`
>      * This overrides the Repo Name field with the output of the "Transform user info" block earlier in the Workflow.
> 6. At the bottom of the side panel, click **Save**.

> **Trigger GitHub workflow**
>
> This block triggers Terraform infrastructure in GitHub.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **GitHub > Trigger workflow** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Terraform Infrastructure Provisioning` and the slug `trigger-workflow`.
> 3. Configure the block:
>    * **Repository**: Enter your repository name.
>    * **Ref**: Enter the Git reference to trigger the workflow on, e.g. `main`.
>    * **Workflow ID or file name**: Enter the ID of the GitHub workflow or the file name of the workflow file.
>      * In our example, we added `main.yaml`. Note that this should be just the file name and not the path to the file.
>    * **Inputs**: Optionally enter key-value pairs to pass to the workflow.
>      * In our example, we added: `{"user": "{{context.initiatedBy.name}}"}`
> 4. At the bottom of the side panel, click **Save**.

> **Scaffolder**
>
> This block opens a Pull Request to set up an RDS instance, using templating to apply the output of the previous block to the Scaffolder configuration.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Scaffolder** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    1. In this example, we use the name `Open PR with RDS terraform` and the slug `scaffold-rds-terraform`.
> 3. Under **Scaffolder template**, select your template. In this example, we use `Terraform RDS Template`.
> 4. Select the option to **Open a pull request**.
> 5. Add override variables. The **Variable** dropdown pulls in all the variables that are able to be overridden in the Git provider and in the Scaffolder template. In this example, we apply the following override:
>    * **publisherRepoFullName**: `actions.scaffold-hello-org.outputs.response.gitURL`
>      * This overrides the Repo Name field with the output of the "Scaffold Hello Org Repo" block earlier in the Workflow.
> 6. At the bottom of the side panel, click **Save**.

> **Slack message**
>
> In this step, we send a templated message via Slack informing the user that their test environment is ready.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Slack** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Notify developer` and the slug `notify-developer`.
> 3. Select a Slack channel name.
> 4. Enter text for the message that will be sent via Slack. In our example, we use the following:
>
> ```
> Hi, {{context.initiatedBy.name}}! Your new test environment is ready to go!
> ```
>
> 5. Save the block.

### Step 4: Run the Workflow

When you run the Workflow, the following events happen:

* The Data transformation block runs, which produces a repository name for the user based on your specified naming convention.
* The Scaffolder runs, creating a new repository. The repo's name is based on the output of the previous block.
* The GitHub "Trigger a workflow" block runs, which provisions Terraform infrastructure.
* The second Scaffolder block runs, which opens a Pull Request to set up an RDS instance.
* The Slack block runs, which sends a Slack message to the user to let them know that their test environment is ready.


# Measure DORA progress
Source: https://docs.cortex.io/guides/dora/scorecard



In Cortex, use Scorecards to measure progress against DORA benchmarks at your organization, and use the Eng Intelligence [DORA Dashboard](/improve/eng-intelligence/dora-dashboard) to see your metrics improve in realtime.

## DORA Metrics Scorecard example

In this example, assume that you have launched a DORA Metrics Scorecard based on the out-of-the-box template provided in Cortex.

> **To launch this Scorecard**
>
> 1. Click **Scorecards** from the main nav in Cortex.
> 2. In the upper right corner, click **Create Scorecard**. In the `DORA Operational Readiness` template tile, click **Use**.
>
> ![Click Create Scorecard, then select DORA Metrics.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/click-dora.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=05fb3ff99beb26c75559ffcecea2aa7e)

### DORA performance levels

Cortex's DORA Scorecard template is based on the established DORA standards of performance.

### Scorecard rules

The Scorecard contains four levels: Minimum, Established, Accelerating, and Elite. Each level corresponds with increasingly higher performance against DORA standards.

![Each level in the DORA Scorecard contains rules that show success against DORA metric benchmarks.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/dora-scorecard-img.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=f6093fcdddfc56bfe978aed1a45ef6c1)

Expand the tile below to learn about how the rules in each level give you insight into your team's performance.

> **DORA Scorecard rules**
>
> The progress your team makes against these rules allows you to assess the agility, stability, and quality of your software delivery process.
>
> #### Minimum
>
> These rules help you establish a baseline of readiness to start measuring DORA metrics.
>
> * Logs are linked
> * Ownership is set
> * Version control (Git) is in place
> * Documentation is present
>
> #### Established
>
> These rules motivate your teams to achieve DORA's Medium-level benchmarks for key metrics.
>
> * MTTR is less than 12 hours
> * Deployment frequency is at least 2x/month
> * Lead time for changes less than 5 days
> * Change failure rate: \<30% of deployments are rollbacks
> * Basic monitoring in place
> * CI/CD pipeline configured
>
> #### Accelerating
>
> These rules motivate your teams to achieve DORA's High-level benchmarks for key metrics.
>
> * MTTR less than 4 hours
> * Deployment frequency is at least 6x/month
> * Lead time for changes less than 3 days
> * Change failure rate: \<20% of deployments are rollbacks
> * Metrics dashboard embedded
> * Pipeline success rate => 85%
>
> #### Elite
>
> These rules motivate your teams to achieve DORA's Elite-level benchmarks for key metrics.
>
> * MTTR less than 1 hour
> * Deployment frequency is 30+ per month
> * Lead time for changes is less than 1 day
> * Change failure rate: \<10% of deployments are rollbacks
> * SLOs are defined
> * Pipeline success rate => 95%

### Understanding Scorecard levels

Assume the following for an entity:

* It's passing 3/4 rules in the Minimum level
  * It has logs linked, ownership set, and a version control integration configured (passing)
  * It does not have documentation linked (failing)
* It's passing all rules in the Established level

In this case, the entity would have **No Level**.

* It is failing the rule "Documentation is present" in the Minimum level. Because of this, it has not fully achieved the Minimum level, the first one that an entity can pass.
* Once the entity has documentation linked, it will achieve all rules in the Minimum level. Because it is already passing all rules required for the Established level, this means it will automatically achieve the Established level.

> [!TIP]
>
> This kind of gamification motivates developers to not only progress through the levels, but to maintain the quality of their entities over time.

### Driving continuous improvement against DORA benchmarks

Measuring your performance against DORA standards does not start and stop with launching a Scorecard. We recommend taking the steps described below to understand your baseline, motivate change, and continuously improve:

**1. Measure baseline metrics**

Measure your metrics in the [DORA Dashboard](/improve/eng-intelligence/dora-dashboard).

**2. Investigate**

Drill down into underlying data in [Data Explorer](/improve/eng-intelligence/data-explorer).

**3. Take action**

Codify expectations by launching a [Scorecard](/standardize/scorecards), allowing you to continuously evaluate entities against standards using live data from integrated tools.

**4. Validate impact**

Review your [DORA Dashboard](/improve/eng-intelligence/dora-dashboard) to see improved metrics, validating the impact of the DORA Metrics Scorecard.


# Reduce MTTA
Source: https://docs.cortex.io/guides/incident-mgmt/reduce-mtta



Mean Time to Acknowledge (MTTA) measures how quickly teams acknowledge an incident after it is triggered.

Reducing MTTA depends on:

* Operational readiness: Ensuring the right people are reachable at all times.
* Response behavior: Tracking and improving how fast incidents are acknowledged once triggered.

A well-designed Scorecard shouldn't just track MTTA as a number; **it should validate the conditions that enable low MTTA**, such as on-call setup, contact methods, and escalation policy depth.

### Best practices

When creating a Scorecard aimed at reducing MTTA, follow these best practices:

* Group rules by functional area (e.g., Incident Response, Monitoring, Reliability) to simplify assessment.
* Keep evaluation windows aligned so that related signals trend together.
* Enable Cortex notifications for when overall Scorecard scores drop, prompting teams to review and act.

## Rules that focus on reducing MTTA

| Category | Purpose | Example CQL expression |
| - | - | - |
| On-call configuration | Ensure service has an active PagerDuty schedule | `oncall != null` |
| Contact reliability | Verify responders can be reached through multiple channels | `oncall.usersWithoutContactMethods(allowed=["EMAIL","PHONE","PUSH_NOTIFICATION","SMS"]) == 0` |
| Escalation depth | Require at least two escalation tiers | `oncall.numOfEscalations() >= 2` |
| Acknowledgment time | Track MTTA against defined thresholds | `jq(oncall.analysis(...), '.meanSecondsToFirstAck <= 300')` |
| Monitoring coverage | Ensure critical services have active alerting rules | `datadog.monitors().length > 0` |
| SLO tracking | Validate that a service has defined SLOs and error budgets | `slos().any((slo) => slo.name.matchesIn(".*Uptime.*"))` |
| Ownership coverage | Require that every service has a defined owning team | `ownership != null` |
| Communication channel is set | Require that every service has a defined communication channel | `slack != null and slack.numOfMembers() > 0` |
| Entity was verified in the last 90 days | Require entity information, including ownership, on-call, and Slack to be verified in the last 90 days | `verifications().lastVerifiedAt() != null and verifications().lastVerifiedAt().fromNow() > duration("P-90D")` |
| Entity does not have pending verifications | Ensure entity does not have any pending verifications | `verifications().verifications().any(verification => verification.status == "PENDING") == 0` |

## Examples from real Cortex users

The following anonymized examples come from real uses cases our customers are solving with Cortex.

### Event Readiness Scorecard

For companies that have a busy season (e.g., companies that are busier during Black Friday), they might create a [seasonal readiness Scorecard](/guides/production-readiness/seasonal-readiness-scorecard) in Cortex. The following strategy ties performance metrics directly to readiness controls:

* Track MTTA \< 120 seconds for P1 and P2 incidents
* Require two-tier escalation policies in PagerDuty:\

  `oncall.numOfEscalations() >= 2`
* Validate that on-call users have valid contact methods configured:\

  `oncall.usersWithoutContactMethods(...) == 0`
* Combine outcome metrics (MTTA) with configuration checks to ensure teams can meet targets consistently.

### On-call Configuration Scorecard

The following strategy ensures every service can be reached before an incident occurs, eliminating the common MTTA outliers caused by misconfigured alerts:

* Verify that on-call rotations exist\

  `oncall != null`
* Validate that on-call users have valid contact methods configured:\

  `oncall.usersWithoutContactMethods(...) == 0`
* Flag services without assigned responders

This CQL applies to all on-call integrations: [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie), [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty), [Splunk On-Call (formerly VictorOps)](/ingesting-data-into-cortex/integrations/splunk-oncall), and [xMatters](/ingesting-data-into-cortex/integrations/xmatters).

### Operational Maturity Scorecard

The previous examples applies to services and other entities. Some organizations prefer to track team-level operational maturity, including incident management as one area of assessment.

The following strategy aims for low MTTA as part of a broader operational maturity, not an isolated performance goal:

* Measure operational behaviors like post-incident reviews, ownership clarity, and alert hygiene.
* Focus on consistent response patterns rather than single-point metrics.


# Reduce MTTR
Source: https://docs.cortex.io/guides/incident-mgmt/reduce-mttr



Mean Time to Resolution (MTTR) measures how quickly systems are restored after an incident begins.

Reducing MTTR depends on:

* Operational readiness: Clear ownership, actionable runbooks, and reliable on-call escalations ensure the right people are reachable at all times.
* Repair effectiveness: Tracking and improving how fast incidents are resolved and ensuring Cortex Workflows are configured to rollback, restart, scale up pods, and other processes you use during incidents.
  * See an example Workflow: [Rollback a service during an incident](/guides/incident-mgmt/workflow-rollback)

A well-designed Scorecard shouldn't just track MTTR as a number; **it should validate the conditions that enable low MTTR**, such as up-to-date runbooks, ownership, and on-call coverage with escalation depth.

### Best practices

When creating a Scorecard aimed at reducing MTTR, follow these best practices:

* Group rules by functional area (e.g., Incident Response, Observability, Reliability) to make gaps obvious.
* Keep evaluation windows aligned so that related signals trend together.
* Enable Cortex notifications for when overall Scorecard scores drop, prompting teams to review and act.

## Rules that focus on reducing MTTR

| Category | Purpose | Example CQL expression |
| - | - | - |
| On-call configuration | Ensure service has an active PagerDuty schedule | `oncall != null` |
| Contact reliability | Verify responders can be reached through multiple channels | `actMethods(allowed=["EMAIL","PHONE","PUSH_NOTIFICATION","SMS"]) == 0` |
| Ownership coverage | Require that every service has a defined owning team | `ownership != null` |
| Monitoring coverage | Ensure critical services have active alerting rules | `datadog.monitors().length > 0` |
| SLO tracking | Ensure SLOs exist for latency | `slos().filter((slo) => slo.name.matchesIn("latency") and slo.sliValue >= 0.9999).length > 0` |
| Ownership coverage | Require that every service has a defined owning team | `ownership != null` |
| Alerting channel configured | Require that a Slack or Microsoft Teams channel is configured for each service | `slack != null` |
| Runbooks configured | Require that a runbook is linked so responders have clear steps to follow | `links("runbook").length > 0` |
| MTTR benchmarks | Target benchmarks for MTTR: In lower levels of a Scorecard, you might target \<90 minutes, and in higher levels you might target \<30 minutes | `oncall.analysis(lookback = duration("P30D")).meanSecondsToResolve < 1800` |
| CI/CD pipeline configured | Require a CI/CD pipeline to exist so deployments can be automated and repeatable. | `git.fileExists(".gitlab-ci.yml")` |
| Pipeline success rate | Ensure builds are passing successfully, showing stable automation and tests. You might target 85-95%. | `git.percentBuildSuccess() >= 0.95` |

### Launch an Incident Preparedness Scorecard

Cortex offers a pre-built Scorecard for Incident Preparedness. You can launch this Scorecard to improve your incident processes, enabling a reduced MTTR.

## Example: LetsGetChecked

Cortex customer LetsGetChecked used Cortex to automatically sync service and resource catalogs, enabling their team to quickly find accurate service information. They used Scorecards to drive operational excellence for onboarding, service maturity, and deployment frequency.

### Impact

They reduced MTTR by 67% and doubled their deployment frequency.

### Learn more

Learn more in the case study: [How LetsGetChecked doubled deployment frequency and slashed MTTR by 67% with Cortex](https://www.cortex.io/case-studies/letsgetchecked).

## Example: H\&R Block

H\&R block used Cortex to automate manual, repetitive tasks that were draining velocity and morale.

### Impact

They reduced MTTR from up to 24 hours to less than one hour.

### Learn more

Learn more in the Cortex blog: [How H\&R Block automated the toil out of its developer experience](https://www.cortex.io/post/how-hr-block-automated-the-toil-out-of-developer-experience).


# Create ServiceNow incident
Source: https://docs.cortex.io/guides/incident-mgmt/servicenow



After [integrating Cortex with ServiceNow](/ingesting-data-into-cortex/integrations/servicenow), you can create Workflows to trigger ServiceNow actions, create tickets, or update records.

This guide describes how to use a Workflow to create a ServiceNow incident.

## How to automate ServiceNow incident creation in Cortex

### Prerequisites

Before getting started:

* [Create the following secrets](/configure/settings/api-keys/secrets) in Cortex:
  * A ServiceNow access token named `servicenow_token`
  * A token for name of your ServiceNow domain named `servicenow_domain`
* You must have the `Edit Workflows` [permission](/configure/settings/managing-users/permissioning) to create the Workflow, and the `Execute Workflow runs` permission to run it.

### Step 1: Create the Workflow

You can create a Workflow in the Cortex UI or via the Cortex CLI.

**Cortex CLI**

#### Add the Workflow via CLI

You can use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to add the example Workflow to your workspace. This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more:

> **Import the Workflow via CLI**
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: Create ServiceNow Incident
> tag: create-servicenow-incident-2bed57cd-fcf4-40ed-a916-0857f9748ff0
> description: "This template allows you to create a ServiceNow incident from Cortex.\
>   \ \nThe following fields are included, but you can add more:\n* Short Description\n\
>   * Description\n* Severity\n\nThe workflow will use the email from the user running\
>   \ the workflow to set the `opened by` field. If the workflow is run from an entity's\
>   \ context and it has an `x-cortex-servicenow.service.id`, the incident is associated\
>   \ to the CI in ServiceNow. This assumes that the service was imported from the `cmdb_ci_service`\
>   \ table in ServiceNow.\n\nThis workflow requires that you set up the following secrets\
>   \ in the [Secrets settings page](/admin/settings/secrets):\n* ServiceNow access\
>   \ token: (servicenow_token)\n* Name of ServiceNow domain: (servicenow_domain)\n\n\
>   Failure to do so will result in errors when running the workflow."
> isDraft: true
> filter:
>   entityFilter:
>     typeFilter:
>       types:
>       - service
>     entityGroupFilter: null
>   ownershipScope: ALL
>   type: ENTITY
> runResponseTemplate: null
> failedRunResponseTemplate: null
> restrictActionCompletionToRunnerUser: false
> actions:
> - name: Incident details
>   slug: incident-details
>   schema:
>     inputs:
>     - name: Short description
>       description: null
>       key: short-description
>       required: true
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: Description
>       description: null
>       key: description
>       required: true
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: TEXTAREA_FIELD
>     - name: Severity
>       description: null
>       key: severity
>       required: true
>       options:
>       - "1"
>       - "2"
>       - "3"
>       - "4"
>       - "5"
>       optionsLabels: null
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     - name: Urgency
>       description: null
>       key: urgency
>       required: false
>       options:
>       - 1 - High
>       - 2 - Medium
>       - 3 - Low
>       optionsLabels: null
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     - name: Impact
>       description: null
>       key: impact
>       required: false
>       options:
>       - 1 - High
>       - 2 - Medium
>       - 3 - Low
>       optionsLabels: null
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     inputOverrides: []
>     jsValidatorScript: null
>     type: USER_INPUT
>   outgoingActions:
>   - get-user-sys-id
>   isRootAction: true
> - name: Get User Sys_ID
>   slug: get-user-sys-id
>   schema:
>     headers:
>       Authorization: "Basic {{ context.secrets.servicenow_token }}"
>     httpMethod: GET
>     payload: null
>     url: "https://{{context.secrets.servicenow_domain}}.service-now.com/api/now/table/sys_user?sysparm_query=email%3D{{context.initiatedBy.email}}&sysparm_limit=10"
>     type: HTTP_REQUEST
>   outgoingActions:
>   - extract-user-sys-id
>   isRootAction: false
> - name: Extract User Sys ID
>   slug: extract-user-sys-id
>   schema:
>     expression: ".actions.\"get-user-sys-id\".outputs.body.result[0].sys_id"
>     type: JQ
>   outgoingActions:
>   - get-sysid-of-service
>   isRootAction: false
> - name: Get SysID of Service
>   slug: get-sysid-of-service
>   schema:
>     expression: .context.entity.descriptor
>     type: JQ
>   outgoingActions:
>   - extract-service-sys-id
>   isRootAction: false
> - name: Extract Service Sys ID
>   slug: extract-service-sys-id
>   schema:
>     expression: ".actions.\"get-sysid-of-service\".outputs.result.info.\"x-cortex-servicenow\"\
>       .services[0].id"
>     type: JQ
>   outgoingActions:
>   - create-incident
>   isRootAction: false
> - name: Create Incident
>   slug: create-incident
>   schema:
>     headers:
>       Content-Type: application/json;charset=UTF-8
>       Authorization: "Basic {{ context.secrets.servicenow_token }}"
>     httpMethod: POST
>     payload: "{\"short_description\":\"{{actions.incident-details.outputs.short-description}}\"\
>       ,\"description\":\"{{actions.incident-details.outputs.description}}\",\"opened_by\"\
>       :\"{{actions.extract-user-sys-id.outputs.result}}\",\"severity\":\"{{actions.incident-details.outputs.severity}}\"\
>       ,\"business_service\":\"{{actions.extract-service-sys-id.outputs.result}}\"\
>       , \"urgency\":\"{{actions.incident-details.outputs.urgency}}\", \"impact\":\"\
>       {{actions.incident-details.outputs.impact}}\"}"
>     url: "https://{{context.secrets.servicenow_domain}}.service-now.com/api/now/table/incident"
>     type: HTTP_REQUEST
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file: `cortex workflows create -f <path-to-your-workflow.yaml>`

**Cortex UI**

#### Select the template and save

1. In Cortex, navigate to **Workflows**. In the upper right corner, click **+Create workflow**.
2. Locate the template for "Create ServiceNow Incident." Click **+Use**.
3. Edit the Workflow as needed.
   * The User Input block is configured to ask the user for short description, description, severity, urgency, and impact. All fields except for "impact" are set to be required. You can adjust this per field.
4. In the upper right corner of the page, click **Save workflow**.

### Step 2: Run the Workflow

* In the [list of Workflows](https://app.getcortexapp.com/admin/workflows), locate the "Create ServiceNow incident" Workflow and click **Run**.

When you run the Workflow, the following events happen:

1. The Workflow pauses to collect a response from the user during the User Input block. The user enters a short description, description, severity, urgency, and impact.
2. The HTTP Request block runs, which obtains the ServiceNow Sys\_ID of the user who initiated the Workflow in Cortex.
3. The Data transformation blocks run, transforming the data to get the Sys\_ID of the service and its entity descriptor from Cortex.
4. In the final HTTP Request block, it sends a payload to the ServiceNow API including the information entered by the user during the first step, and the data that was pulled from the SysID and entity descriptor. An incident is opened in ServiceNow.

## Install Cortex's ServiceNow Incidents plugin

To further highlight visibility of ServiceNow incidents in Cortex, you can also [install the ServiceNow Incidents plugin](/streamline/plugins/marketplace#installing-a-plugin-from-the-cortex-plugin-marketplace).

After installing, you can view incidents within a ServiceNow tab directly on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details):

![ServiceNow incidents are displayed under a tab on an entity details page.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/servicenow-plugin.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=f1096ffb79b780153aa30fb5b500d4ff)


# Rollback a service during an incident
Source: https://docs.cortex.io/guides/incident-mgmt/workflow-rollback



You can use a Cortex Workflow to roll back services, allowing quick remediation in the event of incidents.

## How to rollback a service with a Cortex Workflow

### Step 1: Start creating the Workflow

Follow the steps in the documentation to create a Workflow and configure its basic settings.

This Workflow is scoped to the "service" entity type.

### Step 2: Add blocks to the Workflow

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Workflow YAML instructions**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: Rollback Service
> tag: workflow-0e405a5d-6a1c-41a6-84a8-d3287941c000
> description: null
> isDraft: true
> filter:
>   entityFilter:
>     typeFilter:
>       types:
>       - service
>     entityGroupFilter: null
>   ownershipScope: ALL
>   type: ENTITY
> runResponseTemplate: null
> failedRunResponseTemplate: null
> restrictActionCompletionToRunnerUser: false
> actions:
> - name: Get incident info
>   slug: get-incident-info
>   schema:
>     inputs:
>     - name: Incident Name
>       description: null
>       key: incident-name
>       required: false
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: Incident Severity
>       description: null
>       key: incident-severity
>       required: false
>       options:
>       - SEV0
>       - SEV1
>       - SEV2
>       optionsLabels: null
>       defaultValue: null
>       placeholder: ""
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     - name: Create Incident Slack Channel?
>       description: null
>       key: create-incident-slack-channel
>       required: true
>       defaultValue: false
>       type: TOGGLE_FIELD
>     inputOverrides: []
>     type: USER_INPUT
>   outgoingActions:
>   - list-deployments-for-entity
>   isRootAction: true
> - name: List deployments for entity
>   slug: list-deployments-for-entity
>   schema:
>     inputs:
>       page: 0
>       entityId: "{{context.entity.tag}}"
>       pageSize: 2
>     integrationAlias: null
>     actionIdentifier: cortex.getDeploysForEntity
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - javascript
>   isRootAction: false
> - name: Format deployments
>   slug: javascript
>   schema:
>     script: "// Assume \"deployments\" is the JSON from the previous step\nconst deployments\
>       \ = actions['list-deployments-for-entity'].outputs.response.deployments\n\n\
>       // Create a flat array of strings formatted for a dropdown\nconst shasFormatted\
>       \ = deployments.map(dep => \n  `${dep.title} (${dep.sha.slice(0,7)}) - ${dep.timestamp}`\n\
>       );\n\n// Also return the raw SHAs if needed for later steps\nconst shas = deployments.map(dep\
>       \ => dep.sha);\n\nreturn {\n  totalDeployments: deployments.length,\n  deployments:\
>       \ deployments,       // full objects if you need them\n  shas: shas,       \
>       \              // raw SHA values\n  shasFormatted: shasFormatted    // flat\
>       \ string array for dropdowns\n};"
>     type: JAVASCRIPT
>   outgoingActions:
>   - user-input
>   isRootAction: false
> - name: User input
>   slug: user-input
>   schema:
>     inputs:
>     - name: Commit ID to rollback to
>       description: null
>       key: commit-id-to-rollback-to
>       required: false
>       options: []
>       optionsLabels: null
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     inputOverrides:
>     - inputKey: commit-id-to-rollback-to
>       outputVariable: actions.javascript.outputs.result.shasFormatted
>       type: OPTION
>     type: USER_INPUT
>   outgoingActions:
>   - extract-sha
>   isRootAction: false
> - name: Extract SHA
>   slug: extract-sha
>   schema:
>     script: |-
>       // The selected option from the User Input block
>       const selectedOption = actions['user-input'].outputs['commit-id-to-rollback-to']
>
>       // Extract the text between parentheses
>       const match = selectedOption.match(/\((.*?)\)/);
>       const sha = match ? match[1] : null;
>
>       return {
>         selectedOption: selectedOption, // full string
>         sha: sha                        // extracted commit SHA
>       };
>     type: JAVASCRIPT
>   outgoingActions:
>   - trigger-workflow
>   isRootAction: false
> - name: Trigger workflow
>   slug: trigger-workflow
>   schema:
>     inputs:
>       ref: main
>       repo: cortex-workshops/deployment
>       inputs: |-
>         {
>         "service": "{{context.entity.tag}}",
>         "rollback_to": "{{actions.extract-sha.outputs.result.sha}}"
>         }
>       workflow_id: rollback.yaml
>     integrationAlias: cortex
>     actionIdentifier: github.createWorkflowDispatchEvent
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - branch
>   isRootAction: false
> - name: Branch
>   slug: branch
>   schema:
>     branches:
>     - name: Create incident Slack channel
>       slug: create-incident-slack-channel-path
>       outgoingAction: create-incident-slack-channel
>       expression: "actions[\"get-incident-info\"].outputs[\"create-incident-slack-channel\"\
>         ] == true"
>       type: CONDITIONAL
>     - name: Do not create Slack channel
>       slug: do-not-create-slack-channel
>       outgoingAction: send-fyi-message
>       expression: "actions[\"get-incident-info\"].outputs[\"create-incident-slack-channel\"\
>         ] == false"
>       type: CONDITIONAL
>     fallbackBranch: null
>     joiningAction: null
>     type: CONDITIONAL_BRANCH
>   outgoingActions:
>   - create-incident-slack-channel
>   - send-fyi-message
>   isRootAction: false
> - name: Create Incident Slack Channel
>   slug: create-incident-slack-channel
>   schema:
>     headers:
>       Content-Type: application/json
>       Authorization: "Bearer {{context.secrets.apiKey}}"
>     httpMethod: POST
>     payload: |-
>       {
>         "name": "incident-{{actions.get-incident-info.outputs.incident-name}}"
>       }
>     url: https://slack.com/api/conversations.create
>     type: HTTP_REQUEST
>   outgoingActions:
>   - send-slack-message
>   isRootAction: false
> - name: Send FYI message
>   slug: send-fyi-message
>   schema:
>     channel: public-channel
>     message: "Service {{context.entity.tag}} with incident does not have a separate Slack channel."
>     type: SLACK
>   outgoingActions: []
>   isRootAction: false
> - name: Send Slack Message
>   slug: send-slack-message
>   schema:
>     headers:
>       Content-Type: application/json
>       Authorization: "Bearer {{context.secrets.apiKey}}"
>     httpMethod: POST
>     payload: |-
>       {
>         "channel": "incident-{{actions.get-incident-info.outputs.incident-name}}",
>         "text": "Rollbacked service {{context.entity.tag}} to commit ID {{actions.extract-sha.outputs.result.sha}}."
>       }
>     url: https://slack.com/api/chat.postMessage
>     type: HTTP_REQUEST
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

Expand the tiles below to learn about each block in this Workflow and how to configure them in the Cortex UI:

> **User input**
>
> In this example, we add a User Input block to obtain information about an incident.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **User input**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get Incident info` and the slug `get-incident-info`.
> 3. Click **+Add user input**. Add the following:
>    * **Name**: Incident Name
>    * **Key**: incident-name
>    * **Type**: Text
>    * Click **Add input**.
> 4. Click **+Add user input**. Add the following:
>    * **Name**: Incident Severity
>    * **Key**: incident-severity
>    * **Type**: Select
>    * **Options**: Click **+Add option** to add options for the severity labels. In our example, we use `SEV0`, `SEV1`, and `SEV2`.
>    * Click **Add input**.
> 5. Click **+Add user input**. Add the following:
>    * **Name**: Create incident Slack channel?
>    * **Key**: create-incident-slack-channel
>    * **Type**: Toggle
>    * **Default value**: False
>    * Click **Add input**.
> 6. At the bottom of the side panel, click **Save**.

> **List deployments for entity**
>
> This block lists the deployments for an entity.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Cortex > List deployments for entity** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `List deployments for entity` and the slug `list-deployments-for-entity`.
> 3. Configure the block:
>    * **Page size**: In our example, we configured `2`.
> 4. At the bottom of the side panel, click **Save**.

> **JavaScript**
>
> This block uses JavaScript to format the deployments.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **JavaScript** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Format Deployments` and the slug `javascript`.
> 3. In the **JavaScript** text editor box, enter an expression. Our example uses the following:
>
> ```javascript theme={null}
> /*#CORTEX_IGNORE*/import {_, YAML, hcl, context, actions, variables, fetch} from './utils.js'; async () => {
> // Assume "deployments" is the JSON from the previous step
> const deployments = actions['list-deployments-for-entity'].outputs.response.deployments
>
> // Create a flat array of strings formatted for a dropdown
> const shasFormatted = deployments.map(dep => 
>   `${dep.title} (${dep.sha.slice(0,7)}) - ${dep.timestamp}`
> );
>
> // Also return the raw SHAs if needed for later steps
> const shas = deployments.map(dep => dep.sha);
>
> return {
>   totalDeployments: deployments.length,
>   deployments: deployments,       // full objects if you need them
>   shas: shas,                     // raw SHA values
>   shasFormatted: shasFormatted    // flat string array for dropdowns
> };
> /*#CORTEX_IGNORE*/}
> ```
>
> 4. Save the block.

> **User input**
>
> This block asks the user for the commit ID to roll back to, pulling the commit IDs from the previous step.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **User input** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `User input` and the slug `user-input`.
> 3. Click +Add user input. Add the following:
>    * **Name**: Commit ID to rollback to
>    * **Key**: commit-id-to-rollback-to
>    * **Type**: Select
>    * **Data source**: Manual
>    * Click **Add input**.
>    * **Path to override value**: Enter `actions.javascript.outputs.result.shasFormatted`.
> 4. Save the block.

> **JavaScript**
>
> This block uses JavaScript to extract the SHA that was selected in the previous step.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **JavaScript** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Extract SHA` and the slug `extract-sha`.
> 3. In the **JavaScript** text editor box, enter an expression. Our example uses the following:
>
> ```javascript theme={null}
> /*#CORTEX_IGNORE*/import {_, YAML, hcl, context, actions, variables, fetch} from './utils.js'; async () => {
> // The selected option from the User Input block
> const selectedOption = actions['user-input'].outputs['commit-id-to-rollback-to']
>
> // Extract the text between parentheses
> const match = selectedOption.match(/\((.*?)\)/);
> const sha = match ? match[1] : null;
>
> return {
>   selectedOption: selectedOption, // full string
>   sha: sha                        // extracted commit SHA
> };
> /*#CORTEX_IGNORE*/}
> ```
>
> 4. Save the block.

> **Trigger GitHub workflow**
>
> This block triggers a GitHub workflow to roll back the deployment.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **GitHub > Trigger workflow** block.
> 2. In the side panel, enter a name and unique slug for the block. In this example, we use the name `Trigger workflow` and the slug `trigger-workflow`.
> 3. Configure the block:
>    * **Repository**: Enter your repository name.
>    * **Ref**: Enter the Git reference to trigger the workflow on, e.g. `main`.
>    * **Workflow ID or file name**: Enter the ID of the GitHub workflow or the file name of the workflow file.
>      * In our example, we added `rollback.yaml`.
>    * **Inputs**: Optionally enter key-value pairs to pass to the workflow.
>      * In our example, we added:
>
>        ```json theme={null}
>        {
>          "service": "{{context.entity.tag}}",
>          "rollback_to": "{{actions.extract-sha.outputs.result.sha}}"
>        }
>        ```
> 4. At the bottom of the side panel, click **Save**.
>
> This block's `response` output includes `workflow_run_id`, `run_url`, and `html_url` for the triggered GitHub Actions run. You can reference these in later blocks, for example to poll the run's status or include a link to the run in a Slack message.

> **Branch**
>
> During the first User input step, the user can choose whether or not to create a Slack channel for the incident. Their choice determines which path will be followed during the Branch block.
>
> If they chose to create an incident Slack channel:
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Branch**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Branch` and the slug `branch`.
> 3. Click +Add path. Configure the conditional path:
>    * **Name**: Create incident Slack channel
>    * **Slug**: create-incident-slack-channel-path
>    * **Path expression**: `actions["get-incident-info"].outputs["create-incident-slack-channel"] == true`
>    * Save the path.
> 4. Click **+Add path**. Configure the conditional path:
>    * **Name**: Do not create Slack channel
>    * **Slug**: do-not-create-slack-channel
>    * **Path expression**: `actions["get-incident-info"].outputs["create-incident-slack-channel"] == false`
>    * Save the path.
> 5. Save the block.
>
> #### Add blocks to the "Create incident Slack channel" path
>
> **HTTP requests**
>
> 1. Click **+** under the new path. In the block library modal, choose **HTTP request**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Create incident Slack channel` and the slug `create-incident-slack-channel`.
> 3. Configure the block:
>    * **HTTP method**: POST
>    * **URL**: `https://slack.com/api/conversations.create`
>    * **Headers**:
>      * `Content-Type: application/json`
>      * `Authorization: Bearer {{context.secrets.apiKey}}`
>    * **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>   "name": "incident-{{actions.get-incident-info.outputs.incident-name}}"
> }
> ```
>
> 4. Save the block.
> 5. Click **+** under the path. In the block library modal, choose **HTTP request**.
> 6. In the block configuration side panel, enter a name and unique slug for this block. In this example, we use the name `Send Slack message` and the slug `send-slack-message`.
> 7. Configure the block:
>    1. **HTTP method**: POST
>    2. **URL**: `https://slack.com/api/conversations.create`
>    3. **Headers**:
>       * `Content-Type: application/json`
>       * `Authorization: Bearer {{context.secrets.apiKey}}`
>    4. **Payload**: In our example, we enter the following:
>
> ```
> {
>   "channel": "incident-{{actions.get-incident-info.outputs.incident-name}}",
>   "text": "Rollbacked service {{context.entity.tag}} to commit ID {{actions.extract-sha.outputs.result.sha}}."
> }
> ```
>
> 8. Save the block.
>
> **Add block to the "Do not create Slack channel" path**
>
> 1. Click **+** under the new path. In the block library modal, choose **Slack > Send message**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Send FYI message` and the slug `send-fyi-message`.
> 3. Configure the block:
>    * **Slack channel name**: Select the channel where you want to send a message informing the team that you did not create a separate Slack channel for the incident.
>    * **Message text**: In our example, we set this to:\\
>
>      `Service {{context.entity.tag}} with incident does not have a separate Slack channel.`
> 4. Save the block.

### Step 3: Run the Workflow

* At the top of the page, click **Run Workflow**.

When you run the Workflow, the following events happen:

1. The Workflow pauses to collect a response from the user during the User Input block. The user enters a name and severity for the incident, and chooses whether to create a Slack channel
   * Some incidents require additional team work and collaboration, while others can be easily mitigated and may not require a dedicated channel.
2. The "List deployments for entity" block runs, fetching a list of deployments associated with the entity.
3. The JavaScript block runs, which formats the deployment data.
4. The next User Input block runs, which uses the formatted data from the previous block to provide a commit ID to rollback to.
5. The second JavaScript block runs, which extracts the SHA from the output of the previous block.
6. The GitHub workflow is triggered to roll back the affected service.
7. The Branch block runs:
   * If the user selected to create a Slack channel: An HTTP request runs to create an incident Slack channel, and an HTTP block runs to send a Slack message into the channel including the incident name, the service being rolled back, and the commit ID.
   * If the user selected to not create a Slack channel: The "Do not create Slack channel" path runs. A Slack block runs, which sends a Slack message to an existing team channel to let them know a separate incident channel was not created.


# Accelerate migration to K8s
Source: https://docs.cortex.io/guides/migrations-and-modernization/accelerate-migration-to-k8s



Organizations migrate to Kubernetes because it solves critical scalability, reliability, security, and developer-velocity challenges that modern teams face. At its core, Kubernetes provides a standardized, automated, self-healing platform for running applications.

Accelerating a Kubernetes migration is often a strategic engineering decision made to meet certain business requirements, such as lowering infrastructure costs or improving MTTR, in a shorter timeframe.

To accelerate a migration to Kubernetes:

* [Launch a Kubernetes Deployment Baseline Scorecard](/guides/migrations-and-modernization/accelerate-migration-to-k8s#create-a-kubernetes-scorecard). Cortex provides a prebuilt Kubernetes [Scorecard](/standardize/scorecards) template that you can use to track migration-related controls and standards.
* [Launch an Initiative](/guides/migrations-and-modernization/accelerate-migration-to-k8s#create-a-k8s-acceleration-initiative) associated with the Scorecard, which gives your engineers a deadline for when to complete certain goals.
* [Use reports and Cortex MCP](/guides/migrations-and-modernization/accelerate-migration-to-k8s#measuring-success) to better understand progress and next steps.

> [!TIP]
>
> Cortex customer LetsGetCheck cut their Kubernetes migration timeline from 24 months down to 16 months by targeting goals with Initiatives. [Read the full case study here](https://www.cortex.io/case-studies/letsgetchecked).

## Create a Kubernetes Scorecard

### Prerequisites

Before using this Scorecard template:

* Ensure you have configured integrations for:
  * Version control: [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), or [GitLab](/ingesting-data-into-cortex/integrations/gitlab).
  * [Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes)

### Step 1: Create the Scorecard and configure its basic settings

You can create a Scorecard in the Cortex UI, or you can add it to your workspace via GitOps or the Cortex API.

**Cortex UI**

#### Create Scorecard in the Cortex UI

1. On the [**Scorecards** page](https://app.getcortexapp.com/admin/scorecards) in your workspace, click **Create Scorecard**.
2. On the `Kubernetes Deployment Baseline` template, click **Use**.
3. Configure basic settings, including the Scorecard's name, unique identifier, description, and more.
   * Learn about configuring the basic settings in the [Creating a Scorecard documentation](/standardize/scorecards/create).

**GitOps or API**

#### Create Scorecard via GitOps or API

When following a [GitOps approach](/configure/gitops), you can add a Scorecard YAML file to your `.cortex/scorecards` directory in your version control repository. Note that GitOps must be enabled for Scorecards in your [GitOps settings](/configure/settings/gitops-settings).

You could also use the [Cortex API,](/api/rest/scorecards) where you can submit a Scorecard definition in YAML.

> **Kubernetes Scorecard YAML**
>
> Use the YAML file below to add this Scorecard to your workspace via the API or via a GitOps flow.
>
> ```yaml theme={null}
> tag: kubernetes-deployment-baseline
> name: Kubernetes Deployment Baseline
> description: |-
>   This Scorecard enforces a minimum set of standards for services running on Kubernetes. It validates resource requests/limits, probes, container image hygiene, and Git branch protection so that workloads are reliable, predictable, and safe to operate in production.
> draft: true
> notifications:
>   enabled: true
>   scoreDropNotificationsEnabled: false
> exemptions:
>   enabled: true
>   autoApprove: false
>   userSpecificNotifications: false
> ladder:
>   name: Default Ladder
>   levels:
>   - name: Foundational container hygiene
>     rank: 1
>     description: The service is at least containerized in a basic way.
>     color: "#c38b5f"
>   - name: Runtime ready
>     rank: 2
>     description: This container behaves predictably when scheduled on Kubernetes.
>     color: "#8c9298"
>   - name: Kubernetes production ready
>     rank: 3
>     description: This service is safe to run in production from a governance and reliability
>       perspective.
>     color: "#cda400"
> rules:
> - title: Memory limit is set
>   description: "Prevents a single pod from consuming all node memory. To ensure all\
>     \ containers have memory limits set, this rule compares the total number of containers\
>     \ with the number of containers that have memory limits."
>   expression: |-
>     jq(k8s.spec(), "[.[].template.spec.containers[]] | length") ==
>     jq(k8s.spec(), "[.[].template.spec.containers[] | select(.resources.limits.memory != null)] | length")
>   identifier: 17376f1a-bfbe-361b-86d7-eac192f729d9
>   weight: 1
>   level: Runtime ready
> - title: Git branch protection
>   description: Prevent direct pushes and unsafe merges to the main branch; enforce
>     reviews and status checks.
>   expression: git.branchProtection() != null
>   identifier: 21c30af3-6dd6-3bce-bbe5-56e43549015f
>   weight: 1
>   level: Kubernetes production ready
>   failureMessage: Configure Git branch protection.
> - title: CPU request is set
>   description: "This rule checks if CPU resource requests are defined for all containers\
>     \ in your Kubernetes deployments, which is important for: \n- Kubernetes scheduler\
>     \ to properly place pods on nodes\n- CPU throttling behavior (requests affect\
>     \ CPU shares)\n- Cluster capacity planning\n- QoS classification (along with limits\
>     \ and memory requests)\n\nTo ensure all containers have CPU resource requests,\
>     \ this rule compares the total number of containers with the number of containers\
>     \ that have CPU resource requests."
>   expression: |-
>     jq(k8s.spec(), "[.[].template.spec.containers[]] | length") ==
>     jq(k8s.spec(), "[.[].template.spec.containers[] | select(.resources.requests.cpu != null)] | length")
>   identifier: 22d76d97-33a5-358a-8694-cf35909acc71
>   weight: 1
>   level: Runtime ready
> - title: Memory request is set
>   description: "Prevents a single pod from consuming all node memory. To ensure all\
>     \ containers have memory limits set, this rule compares the total number of containers\
>     \ with the number of containers that have memory limits."
>   expression: "jq(k8s.spec(), \"[.[].template.spec.containers[]] | length\") == \n\
>     jq(k8s.spec(), \"[.[].template.spec.containers[] | select(.resources.requests.memory\
>     \ != null)] | length\")"
>   identifier: 46f4d17e-ceab-37dd-9a64-ddac9ee4aa73
>   weight: 1
>   level: Runtime ready
> - title: Runs in cluster
>   description: This indicates operational use of Kubernetes.
>   expression: k8s != null
>   identifier: 6cfcc6f2-53ea-3da8-afaf-8659177d1896
>   weight: 1
>   level: Foundational container hygiene
> - title: No "latest" tag for base image
>   description: |-
>     This is a best practice rule that ensures all base images have explicit version tags instead of using `:latest`, which:
>     - Prevents unpredictable builds when `:latest` changes
>     - Ensures build reproducibility
>     - Makes it clear what version is being used
>   expression: "git.fileContents(\"Dockerfile\").matchesIn(\"^FROM[ \\t]+(?!.*:latest\\\
>     b).*$\")"
>   identifier: 873c36b3-5a18-3a09-9c58-bff967ffd6bd
>   weight: 1
>   level: Kubernetes production ready
> - title: Liveness probe is set
>   description: |-
>     This ensures your services have liveness probes configured, which are critical for:
>
>     - Detecting when a container is stuck or deadlocked
>     - Automatically restarting unhealthy containers
>     - Improving service reliability and reducing MTTR
>     - Preventing containers that are "running" but not actually functioning
>
>     To ensure all containers have liveness probes, this rule compares the total number of containers with the number of containers that have liveness probes.
>   expression: |-
>     jq(k8s.spec(), "[.[].template.spec.containers[]] | length") ==
>     jq(k8s.spec(), "[.[].template.spec.containers[] | select(.livenessProbe != null)] | length")
>   identifier: b1f477fc-2ec5-39b0-9d48-b9a2922d7623
>   weight: 1
>   level: Runtime ready
> - title: Readiness probe is set
>   description: |-
>     Ensures the service defines a Kubernetes readiness probe so that traffic is only routed to containers that are fully initialized and able to serve requests. A readiness probe prevents the service mesh or load balancer from sending user traffic to a pod that is still starting up, misconfigured, or temporarily degraded. This improves request success rates, reduces startup-induced errors, and helps maintain overall service reliability.
>
>     To ensure all containers have readiness probes, this rule compares the total number of containers with the number of containers that have readiness probes.
>   expression: "jq(k8s.spec(), \"[.[].template.spec.containers[]] | length\") == jq(k8s.spec(),\
>     \ \"[.[].template.spec.containers[] | select(.readinessProbe != null)] | length\"\
>     )"
>   identifier: b4bed489-db7d-3566-826a-c78f6da22190
>   weight: 1
>   level: Runtime ready
>   failureMessage: "This service does not have a Kubernetes readiness probe configured.\
>     \ Without a readiness probe, the load balancer may send traffic to pods before\
>     \ they are ready, leading to failed requests and degraded reliability. Add a readiness\
>     \ probe to ensure only healthy, ready pods receive traffic."
> - title: Dockerignore file exists
>   description: Keep images lean and builds fast by excluding unnecessary files.
>   expression: git.fileExists(".dockerignore")
>   identifier: deb30726-2692-3a2d-8858-a828d33fea17
>   weight: 1
>   level: Foundational container hygiene
> - title: Dockerfile exists
>   description: Verify the service is containerized using a maintained Dockerfile.
>     This enables consistency across different environments.
>   expression: git.fileExists("Dockerfile")
>   identifier: df928975-90e7-35ab-a05c-67ca7cb034a2
>   weight: 1
>   level: Foundational container hygiene
> filter:
>   kind: GENERIC
>   types:
>     include:
>     - service
> ```

### Step 2: Review and modify rules

Cortex's templated rules are based on common industry standards. See the template in-app for more context on each rule:

> **Level 1: Foundational container hygiene**
>
> * Runs in cluster\\
>
>   `k8s != null`
> * Dockerignore file exists\\
>
>   `git.fileExists(".dockerignore")`
> * Dockerfile exists\\
>
>   `git.fileExists("Dockerfile")`

> **Level 2: Runtime ready**
>
> * Memory request is set\\
>
>   `jq(k8s.spec(), "[.[].template.spec.containers[]] | length") == jq(k8s.spec(), "[.[].template.spec.containers[] | select(.resources.requests.memory != null)] | length")`
> * Memory limit is set\\
>
>   `jq(k8s.spec(), "[.[].template.spec.containers[]] | length") == jq(k8s.spec(), "[.[].template.spec.containers[] | select(.resources.limits.memory != null)] | length")`
> * Liveness probe is set\\
>
>   `jq(k8s.spec(), "[.[].template.spec.containers[]] | length") == jq(k8s.spec(), "[.[].template.spec.containers[] | select(.livenessProbe != null)] | length")`
> * Readiness probe is set\\
>
>   `jq(k8s.spec(), "[.[].template.spec.containers[]] | length") == jq(k8s.spec(), "[.[].template.spec.containers[] | select(.readinessProbe != null)] | length")`
> * CPU request is set\\
>
>   `jq(k8s.spec(), "[.[].template.spec.containers[]] | length") == jq(k8s.spec(), "[.[].template.spec.containers[] | select(.resources.requests.cpu != null)] | length")`

> **Level 3: Kubernetes production ready**
>
> * Git branch protection\\
>
>   `git.branchProtection() != null`
> * No "latest" tag for base image\\
>
>   `git.fileContents("Dockerfile").matchesIn("^FROM[ \t]+(?!.*:latest\b).$")`

You can reorder, delete, and edit rules, add more rules to a level, and assign more points to a rule to signify its importance. Behind each rule is a [Cortex Query Language (CQL) ](/standardize/cql)query; you can edit the existing CQL or write your own queries to further refine your rules.

## Create a K8s acceleration Initiative

If you notice the team isn't making progress as quickly as expected, or you need to complete certain rules within a specific timeframe, you can create an Initiative to motivate completion.

Follow the steps below to create an Initiative:

> **Create a Kubernetes Initiative**
>
> 1. While viewing your Kubernetes Deployment Baseline Scorecard, click **Create Initiative** in the upper right.
> 2. Configure the Initiative fields, including a descriptive name so your team members understand the purpose of the Initiative. For example, `Accelerate K8s migration`.
>    * Make sure to enable notifications so users are notified if an entity they own is failing the Initiative's goal.
>    * For the goal, you might want to ask your team to complete a certain level, or specific rules. Examples: `Complete all "Runtime ready" level rules by the end of the quarter` or `Make sure a Dockerfile exists for every service by end of month`.
> 3. Save the Initiative.
>
> After the Initiative is published, entity owners will be notified if their entity is not meeting the goal. They will see action items listed on their [engineering homepage](/streamline/homepage) and they will automatically receive a weekly progress update from the Initiative.
>
> Learn more about [creating Initiatives in the docs](/improve/initiatives).

## Measuring success

To understand progress of your Scorecard:

* Ask [Cortex MCP,](/get-started/cortex-ai-assistant/mcp) "How is my Kubernetes Deployment Baseline Scorecard doing?" The MCP will respond with information on the entities that are failing rules and suggested next steps.
* Review reports: The [Bird's Eye report](/improve/reports/birds-eye) gives insight into how entities are performing against the Scorecard by visualizing the data as a heat map:\


  ![The bird's eye report shows Scorecard progress as a heat map.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/kubernetes-birds-eye.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=e8de31484db809953274df430021a857)

You can also review your Engineering Intelligence metrics for impact on key engineering metrics, such as:

* **MTTR**: Kubernetes best practices, such as liveness probes in place, can result in faster diagnosis and auto-recovery. You may see MTTR decrease.
* **Change failure rate**: With resource limits reducing pod crashes and no "latest" image tag resulting in deterministic builds, you may see more successful deploys on first attempt, thus decreasing change failure rate.


# Manage an Upcoming EOL for AWS
Source: https://docs.cortex.io/guides/migrations-and-modernization/manage-an-upcoming-eol-for-aws



AWS maintains End of Life calendars for RDS, Lambda and Elasticache. Risks of not upgrading and running an unsupported version include forced upgrades, frozen configurations (no changes possible), and ineligibility for technical support and security patches.

You can use a Cortex Scorecard to define and track the progress of your entities migrating to newer versions of RDS, Lambda, and Elasticache. When implemented, the Scorecard in this guide helps you identify services that have or have not yet upgraded.

You can create Scorecards via [API, GitOps](/guides/migrations-and-modernization/manage-an-upcoming-eol-for-aws#create-aws-eol-scorecard-via-api-or-gitops), or the [Cortex UI](/guides/migrations-and-modernization/manage-an-upcoming-eol-for-aws#create-aws-eol-scorecard-in-the-cortex-ui).

## Create AWS EOL Scorecard via API or GitOps

When following a GitOps approach, you can add a Scorecard YAML file to your `.cortex/scorecards` directory in your version control repository. Note that GitOps must be enabled for Scorecards in your GitOps settings.

You could also use the Cortex API, where you can submit a Scorecard definition in YAML.

> **AWS EOL Scorecard YAML**
>
> Use the YAML file below to add this Scorecard to your workspace via the API or via a GitOps flow.
>
> ```yaml theme={null}
> description: >-
>
>   AWS maintains End of Life calendars for RDS, Lambda and Elasticache.
>
>
>   Risk of not upgrading and running an unsupported version includes forced upgrade, frozen configuration ( no changes possible) . ineligibility for technical support and security patches.
> name: "! EOL Upcoming - AWS"
> rules:
>   - description: null
>     expression:
>  (jq(aws.details(), ".resources[0].engine") == "aurora-postgresql" AND jq(aws.details(), ".resources[0].engineVersion | startswith(\"13.\")") == true)
> OR
> (jq(aws.details(), ".resources[0].engine") == "aurora-mysql" AND jq(aws.details(), ".resources[0].engineVersion | startswith(\"8.\")") == true)
>     failureMessage: null
>     filter:
>       category: RESOURCE
>       query: entity_descriptor.info.`x-cortex-type` = "rds"
>     level: null
>     title: PostgreSQL EOL Version Upgrade Completed
>     weight: 10
>   - description: null
>     expression: (jq(aws.details(), ".resources[0].metadata.engine") == "redis" AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[0] | tonumber") >= 7)
> OR
> (jq(aws.details(), ".resources[0].metadata.engine") == "memcached" AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[0] | tonumber") >= 1 AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[1] | tonumber") >= 6)
>     failureMessage: null
>     filter:
>       category: RESOURCE
>       query: entity_descriptor.info.`x-cortex-type` = "elasticache"
>     level: null
>     title: Elasticache EOL Version Upgrade Completed
>     weight: 10
> tag: aws-end-of-life-migration
> filter:
>   category: RESOURCE
>   query: entity_descriptor.info.`x-cortex-type` = "rds" OR
>     entity_descriptor.info.`x-cortex-type` = "lambda" OR
>     entity_descriptor.info.`x-cortex-type` = "elasticache"
> ```

## Create AWS EOL Scorecard in the Cortex UI

### Step 1: Create the Scorecard and configure its basic details

1. In Cortex, navigate to **Scorecards** and click **+Create Scorecard**. Start with a blank Scorecard.
2. Configure the basic details.
   * Include a name that helps your users understand the purpose of the Scorecard (e.g., `Upcoming EOL for AWS`) and a description.
3. Under "Apply to specific entities," narrow the scope of your Scorecard by choosing `RDS`, `Lamba`, and `AWS Elasticache for Redis` entity types.\


   ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/migration-scorecard-entity-types.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=37d99758a1523e3f47f68889413d6f95)

### Step 2: Add levels and rules

1. Under **Define evaluation rules**, add two levels:
   * EOL Upgrade Required
   * No Pending EOL Upgrade
2. In the "No Pending EOL Upgrade" level, add a rule called `PostgreSQL EOL Version Upgrade Completed`. Include a CQL expression that verifies the entities are not on EOL versions. The following rule passes when Aurora PostgreSQL is 13.x or when Aurora MySQL is 8.x:

```
(jq(aws.details(), ".resources[0].engine") == "aurora-postgresql" AND jq(aws.details(), ".resources[0].engineVersion | startswith(\"13.\")") == true)
OR
(jq(aws.details(), ".resources[0].engine") == "aurora-mysql" AND jq(aws.details(), ".resources[0].engineVersion | startswith(\"8.\")") == true)
```

3. Add another rule called `Elasticache EOL Version Upgrade Completed`. Include a CQL expression that verifies the entities are not on EOL versions. The following rule passes when Redis is 7.x or newer, Memcached is 1.6 or newer, or if no Elasticache exists for the entity:

```
(jq(aws.details(), ".resources[0].metadata.engine") == "redis" AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[0] | tonumber") >= 7)
OR
(jq(aws.details(), ".resources[0].metadata.engine") == "memcached" AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[0] | tonumber") >= 1 AND jq(aws.details(), ".resources[0].metadata.engineVersion | split(\".\")[1] | tonumber") >= 6)
```

4. At the bottom of the page, click **Save Scorecard**.


# Validate data after migration
Source: https://docs.cortex.io/guides/migrations-and-modernization/validate-data



[Data verifications](/configure/settings/entity-settings/verification) ensure that entity data in the catalog (e.g., ownership and metadata) stays accurate over time.

As a best practice after migrating data (for example, migrating services from spreadsheets into Cortex), we recommend scheduling a data verification to ensure your entities are up to date.

## Set up a data verification after a migration

You must have the `Configure verification periods` permission to set up a verification.

1. In Cortex, navigate to the [Entity verification settings](https://app.getcortexapp.com/admin/settings/entities/verification) page. Click **+Add verification period**.
2. In the side panel, fill in the fields:
   * **Start date** and **End date**: Enter the start and end dates for the verification period.
     * The start date cannot be in the past. The end date must be at least one day after the start date.
     * Choose a timeframe that is reasonable based on the number of entities that each team will need to verify.
   * **Name**: Enter a descriptive name, e.g., `Validate data after migration`.
   * **Verification instructions**: Enter clear and concise instructions that will appear on the entity's details page, e.g., `These entities were recently imported from spreadsheets. Please review and verify whether they're accurate.`
   * **Require reason for verification**: Check this box to require the user to include a reason if they confirm that the entity's data is invalid.
     * We recommend requiring a reason, as it will allow you to quickly understand what needs to be fixed on an entity.
   * **Team member roles responsible for verification**: Select which Cortex users will be responsible for verifying data.
     * If you select multiple roles, any of those users can verify data.
     * If you do not select a team member role, any user who owns the entity can verify data.
   * **Entities to verify**: Specify which entities the verification policy applies to.
     * You can select a specific entity type to include (for example, you could apply the verification to all entities of the type `service`) or if your entities have groups assigned, you can filter by specific groups.
     * Under **Advanced options**, you can use CQL to refine which entities you want to verify. For example, you might narrow your selection to entities created in the last two weeks:\

       `entity.created() < duration("P2W")`
3. Click **Create verification period**.

Within a few minutes of saving the verification period, it will be visible to admins in the list of verifications on the [Entity verification settings page](https://app.getcortexapp.com/admin/settings/entities/verification). Entity owners will receive notifications to verify their entities.

## Remediate entities with incorrect data

After setting up the verification period, you can [create a CQL report to view all entities that have been verified as incorrect](/configure/settings/entity-settings/verification#view-all-unverified-or-incorrect-entities) using a prebuilt CQL report template.

Cortex also offers a prebuilt [Scorecard template to flag entities that have not yet been verified](/configure/settings/entity-settings/verification#flag-unverified-entities-via-scorecard).


# Automate a sync in ArgoCD
Source: https://docs.cortex.io/guides/operational-readiness/argocd-workflow



After integrating Cortex with [ArgoCD](/ingesting-data-into-cortex/integrations/argocd), you can use [Workflows](/streamline/workflows) to streamline and automate daily tasks. Rather than manually performing a sync through the ArgoCD UI, you can automate syncs by leveraging the ArgoCD API in a Workflow.

This guide walks through a Workflow that will sync the ArgoCD application to the same cluster that ArgoCD is running, but to a different namespace, and will allow the user to choose options for the sync.

## How to automate an ArgoCD sync with a Workflow in Cortex

### Prerequisites

Before getting started:

* Create an [API token in ArgoCD](https://argo-cd.readthedocs.io/en/stable/).
  * In ArgoCD, navigate to your account settings then click **Tokens > Generate New**. Copy the token and store it in a secure location, as you will need it in the next steps.\


    ![argocd actions 1](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/argocd-actions-1.jpeg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=90662d71050588b23eb9d58865d6341d)
* Create a secret in Cortex.
  * Give the secret the name `argocd`.
  * For the secret value, enter the value of your ArgoCD API token.

### Step 1: Create a Workflow

1. In the main nav of Cortex, click **Workflows**.
2. Follow the steps of the [Workflows documentation](/streamline/workflows/create) to start creating a Workflow from scratch and configure its settings.
   * Give the Workflow a descriptive name such as "Create and sync application."
   * In the **Response template** field you can pass a blank response body or use [Mustache templating](https://mustache.github.io/) to create messages depending on what the user enters in each field.

     * For example, you may want to configure a response to confirm whether a sync was successful when the workflow is run. You could add the following to check the `sync.status` field. This example assumes you add an HTTP request action with the slug `http-request` in your Workflow:

     ```
     {{#actions.http-request.outputs.body.status.sync.status}}
     Successfully synced application!
     {{/actions.http-request.outputs.body.status.sync.status}}
     {{^actions.http-request.outputs.body.status.sync.status}}
     Unable to sync application. Are you sure this application exists in ArgoCD?
     {{/actions.http-request.outputs.body.status.sync.status}}
     ```

### Step 2: Add blocks to the Workflow

In your Workflow, you will add an HTTP request block to call the ArgoCD sync via the [ArgoCD API](https://argoproj.github.io/argo-events/sensors/triggers/http-trigger/), and a user input block where you define inputs that map to the JSON body of the block. The inputs should be the same sync options shown under **Sync** in your ArgoCD instance. The instructions below map `REVISION`, `DRY RUN`, and `PRUNE` as the sync options.

See the [Workflows documentation](/streamline/workflows/blocks) for more information on configuring blocks.

1. In the Workflow, click **+** to add a block. Select **User input**. Configure the block:
   * **Block name**: Enter a name for the block (e.g., `User input`).
   * **Slug**: The slug field is automatically populated based on the block name.
   * Under "User input fields," click **Add input**. Configure the input:
     * **Type**: Select `Text`.
     * **Name**: Enter `Revision`.
     * **Placeholder**: Enter `HEAD`.
     * At the bottom of the modal, click **Add input field**.
   * Under "User input fields," click **Add input**. Configure another input:
     * **Type**: Select `Toggle`.
     * **Name**: Enter `Dry run`.
     * At the bottom of the modal, click **Add input field**.
   * Under "User input fields," click **Add input**. Configure another input:
     * **Type**: Select `Toggle`.
     * **Name**: Enter `Prune`.
     * At the bottom of the modal, click **Add input field**.
2. Click **Save**.
3. In the Workflow, click **+** to add another block. Select **HTTP request**. Configure the block:
   * **Block name**: Enter a name for the block (e.g., `HTTP request`).
   * **Slug**: The slug field is automatically populated based on the block name.
   * **HTTP method**: Select `POST`.
   * **URL**: Enter the target URL.
   * **Headers**: Enter the following key/value pairs:
     * **Header Key**: `Authorization`, **Header Value**: `Bearer {{{context.secrets.argocd}}}`
       * If you used a different name for your secret, replace `argocd` with your secret's name.
   * **Payload**: Enter the payload referencing the output of the "User input" block. The payload that you supply can be templated and can reference an entity that the Workflow is being run with.

     * In this example, you could enter:

     ```json theme={null}
     {
       "prune": {{context.actions.user-input.outputs.prune}},
       "dryRun": {{context.actions.user-input.outputs.dry-run}},
       "revision": "{{context.actions.user-input.outputs.revision}}"
     }
     ```
4. Click **Save**.
5. Click **Save Workflow**.


# Run a Humanitec pipeline
Source: https://docs.cortex.io/guides/operational-readiness/humanitec-pipeline



[Humanitec](https://humanitec.com/) offers products to build on top of your Internal Developer Portal (IDP) for containerized workloads.

You can use a Workflow in Cortex to call the Humanitec API and run a Humanitec pipeline. For instructions, see [Integrations > Humanitec](/ingesting-data-into-cortex/integrations/humanitec).


# Call internal service endpoints in a Workflow
Source: https://docs.cortex.io/guides/operational-readiness/internal-endpoints



Your organization may have services that are not publicly accessible but contain information that would be useful to manage in Cortex. You can use an [HTTP action in a Workflow](/streamline/workflows/create) and [Cortex's Axon Relay](/ingesting-data-into-cortex/integrations/axon-relay) to call internal services without exposing the service or authentication outside of your firewall.

### How to call internal service endpoints in a Workflow [#how-to-call-internal-service-endpoints-in-a-workflow](#how-to-call-internal-service-endpoints-in-a-workflow)

#### Prerequisites [#prerequisites](#prerequisites)

Before getting started, you should have already [set up the Cortex Axon agent](/ingesting-data-into-cortex/integrations/axon-relay) and [set your Cortex API token in the .env file](/ingesting-data-into-cortex/integrations/axon-relay#step-1-2-create-a-env-file-and-a-docker-compose-yml-file).

**Considerations**

* This guide describes using a Docker compose file, but note that Axon Relay can be run in Kuberenetes or other container systems.
* As an example throughout this guide, assume a service in the network has the following endpoint:

`GET http://cities.internal.my-company.com/api/cities/s => ["Seattle", "Sydney", "Shanghai" ...]`

#### Step 1: Create request forwarding configuration [#step-1-create-request-forwarding-configuration](#step-1-create-request-forwarding-configuration)

* Create a file that defines how requests are routed.
  * The example below permits any requests, but note that the `method` and `path` can be narrowed to allow access to specific endpoints:

```
{
   "private": [
     {
       "method": "any", 
       "path": "/*",   
       "origin": "http://cities.internal.my-company.com"
     }
   ]
}

```

#### Step 2: Configure Axon Docker container [#step-2-configure-axon-docker-container](#step-2-configure-axon-docker-container)

1. Create an accept file (in this example, `docker-compose.yml`) that defines how the container will route traffic and which routes are allowed.
   * For production employments, two replicas should be specified. The example below can be used to test the system.

```
services:
 relay-cities:
   image: ghcr.io/cortexapps/cortex-axon-agent:latest
   environment:
     HOSTNAME: relay-cities-${HOSTNAME:-local}
     CORTEX_API_TOKEN: $CORTEX_API_TOKEN
   volumes:
     - "./accept.cities.json:/app/accept.json"
   command: [
     "relay",
     "-a", "axon-relay-cities", # this can be any unique value
     "-f", "/app/accept.json",
   ]
```

2. Start the container, which will register it with Cortex: Run the command `docker compose up`.

#### Step 3: Create the Workflow in Cortex [#step-3-create-the-workflow-in-cortex](#step-3-create-the-workflow-in-cortex)

1. Follow the [steps to start creating a Workflow](/streamline/workflows/create#creating-a-workflow) and [configure its basic details](/streamline/workflows/create#creating-a-workflow).
2. Add an HTTP request block to your Workflow. Configure the block:
   * **Block name**: Enter a human readable name.
   * **Slug**: Enter a unique identifier for the block.
   * **HTTP method**: GET
   * **URL**: Enter a URL in the following format: `http://[your-configuration-alias]@relay-proxy.cortex.io[/desired/url/path]`
     * For the example from this guide, it would be `http://axon-relay-cities@relay-proxy.cortex.io/api/cities/s`
   * **Headers**: For more information on headers, see the [HTTP request block documentation](/streamline/workflows/create).
3. After saving your changes, run the Workflow.
   * Click **Run** at the top of the Workflow.
   * Learn more about Workflow runs in [Running a Workflow](/streamline/workflows/run).

After running the Workflow, check its **Outputs** for the "Call cities endpoint" data:

![The 'call cities endpoint' data appears in the Output of the Workflow.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/cities-endpoint.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=efea92adc630a9eb7d95ddb98241049d)


# Loop in a JavaScript block and return specified output
Source: https://docs.cortex.io/guides/operational-readiness/javascript-looping



The [JavaScript block](/streamline/workflows/blocks#configuring-a-core-block) in a Cortex Workflow allows you to write custom scripts directly in your Workflow logic, giving you the flexibility to streamline tasks that would otherwise require additional tooling or manual intervention. Common use cases include:

* Transforming data: Use JavaScript to convert API responses or output from another block into something easier to use downstream.
* Filtering or searching inside data: Narrow down results from a previous block, like selecting high-priority items or matching a tag.
* Math and aggregation: Run calculations across arrays or values, including handling time-based logic.
* Defaults and fallbacks: Avoid runtime errors by checking if values exist before using them elsewhere in the Workflow.

## Configure a JavaScript block to return user names and company names

The example below demonstrates how to fetch and work with example user data from a public API. In this example, you call an external API, parse and loop through the results, then return useful output into the [Workflow's evolving state](/streamline/workflows/blocks/states).

It performs the following actions:

1. Sends a GET request to `jsonplaceholder.typicode.com/users`
2. Sets a typical `Content-Type` header
3. Uses `await` to pause execution until the response is received
4. Turns the data into an array of objects and creates a flat array of strings
5. Once the response is received, it parses the JSON body and extracts just the user names and their company names

The final output includes the HTTP status code and a simplified list of users. This output becomes part of the `actions` object. Both the `responseStatus` and the parsed `users` array are now available as action context, which can be [referenced in subsequent steps of the Workflow](/guides/operational-readiness/javascript-looping#referencing-the-output-later-in-the-workflow).

#### Alternate option: Upload the example Workflow YAML

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Create the Workflow via Cortex CLI**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the JavaScript Workflow example YAML file below:
>
> ```yaml theme={null}
> name: JS Block Example Workflow
> tag: workflow-tag
> description: This is an example demonstrating how to use looping in a JavaScript block.
> isDraft: true
> filter:
>   type: GLOBAL
> runResponseTemplate: null
> failedRunResponseTemplate: null
> actions:
> - name: JavaScript
>   slug: javascript
>   schema:
>     script: "// Example base URL \nconst baseUrl = `https://jsonplaceholder.typicode.com/users`;\
>       \  // Public API that returns fake user data\n\nconst myHeaders = {\n    \"\
>       Content-Type\": \"application/json\"  // Typical header for JSON APIs \n};\n\
>       \n// Send the HTTP request and wait for the response to come back\nconst response\
>       \ = await fetch(baseUrl, {\n    headers: myHeaders  // Makes a GET request with\
>       \ the specified headers\n});\n// Pauses the function until the fetch call finishes\
>       \ (asynchronously)\n\n// Parse the response body as JSON and wait for it to\
>       \ complete\nconst responseBody = await response.json();  \n\n// Create a simplified\
>       \ array of objects with name and company\nconst simplifiedUsers = responseBody.map(user\
>       \ => ({\n    name: user.name,                 // Pulls out the user's full name\n\
>       \    company: user.company.name       // Pulls out the name of the user's company\n\
>       }));\n\n// Create a flat array of strings like \"Leanne Graham (Romaguera-Crona)\"\
>       \n// This is required for use in dropdowns or multiselect inputs\nconst usersFormatted\
>       \ = simplifiedUsers.map(user => `${user.name} (${user.company})`);\n\nreturn\
>       \ {\n    responseStatus: response.status,  // Returns the HTTP status code (e.g.,\
>       \ 200 for success)\n    users: simplifiedUsers,           // Cleaned-up list\
>       \ of name + company pairs (objects)\n    usersFormatted: usersFormatted    //\
>       \ Flat string array — works in User Input blocks\n};\n"
>     type: JAVASCRIPT
>   outgoingActions:
>   - user-input
>   isRootAction: true
> - name: User input
>   slug: user-input
>   schema:
>     inputs:
>     - name: Choose name
>       description: In this step, select a name from the dropdown
>       key: choose-name
>       required: false
>       options: []
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     inputOverrides:
>     - inputKey: choose-name
>       outputVariable: actions.javascript.outputs.result.usersFormatted
>       type: OPTION
>     type: USER_INPUT
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

### Add a JavaScript block to the Workflow

1. Follow the instructions to [create a Workflow](/streamline/workflows/create) and [configure its settings](/streamline/workflows/create#creating-a-workflow).
2. Add a JavaScript block to your Workflow.
   * In the block configuration side panel, add a block name and a unique slug.
3. Under the **Javascript** header, in the text editor, enter your JavaScript expression.\


   ![The JavaScript text editor appears under the Block name and Slug fields.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/js-block-editor.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=80bad4432cc4feeceeb368c1f2cbeae5)

   In this example, we use the following:

```javascript theme={null}
// Example base URL 
const baseUrl = `https://jsonplaceholder.typicode.com/users`;  // Public API that returns fake user data

const myHeaders = {
    "Content-Type": "application/json"  // Typical header for JSON APIs 
};

// Send the HTTP request and wait for the response to come back
const response = await fetch(baseUrl, {
    headers: myHeaders  // Makes a GET request with the specified headers
});
// Pauses the function until the fetch call finishes (asynchronously)

// Parse the response body as JSON and wait for it to complete
const responseBody = await response.json();  

// Create a simplified array of objects with name and company
const simplifiedUsers = responseBody.map(user => ({
    name: user.name,                 // Pulls out the user's full name
    company: user.company.name       // Pulls out the name of the user's company
}));

// Create a flat array of strings like "Leanne Graham (Romaguera-Crona)"
// This is required for use in dropdowns or multiselect inputs
const usersFormatted = simplifiedUsers.map(user => `${user.name} (${user.company})`);

return {
    responseStatus: response.status,  // Returns the HTTP status code (e.g., 200 for success)
    users: simplifiedUsers,           // Cleaned-up list of name + company pairs (objects)
    usersFormatted: usersFormatted    // Flat string array — works in User Input blocks
};
```

4. Click **Save** at the bottom of the block configuration side panel.

### Run the Workflow

* After you have finished creating your Workflow, click **Run** in the upper right corner while viewing the Workflow.\


After the run completes, go to the **Outputs** tab of the run to view the `users` and `responseStatus` values returned by the JavaScript block:

![The run output includes the user names and companies.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/workflow-js-output.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=a96b27dff841279e32cf1bec23ca6483)

## Referencing the output later in the Workflow

It is possible to reference the outputs of the JavaScript block later in the Workflow, using the following:

* `actions.<your-block-slug>.outputs.result.usersFormatted`
* `actions.<your-block-slug>.outputs.result.responseStatus`

### Example: Add a User input block after the JavaScript block

You might later want to include a **User input** block where the person running the Workflow can select a name from the JavaScript block's output:

1. In your Workflow, add a **User input** block.
2. In the block configuration side panel, include a name and a unique slug for the block, then click **Add user input**.
3. Configure the input:
   * Enter a name and key for the input.
     * In this example, the name is "Choose name."
   * Select a type. This example uses the `Select` type.
   * In the **Path to override value** field, include a reference to the list of `users` that came from the output of the JavaScript block (which uses the slug `javascript`):\

     `actions.javascript.outputs.result.usersFormatted`
4. Click **Save** at the bottom of the block configuration side panel.
5. Run the Workflow.
6. After the JavaScript block runs, you will be prompted to select a name. After selecting, click **Submit**.\


   ![During a user input step, select an option from the dropdown.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/provide-user-input-block.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=9ff6f8dae493f90e3ac0a13cb8b2b035)

After you run the Workflow and select a choice, you will see the choice in the **Outputs** tab at the bottom of the page:

![The object you chose during the User Input step will appear in the Outputs tab of the workflow run.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/user-input-outputs-block.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=3ebd47b6948c4e4544343e7d20f6a615)

#### Next steps

After a user makes a select from your User input block, you can use the collected input in many different ways in the next steps of your Workflow. For example:

* **Branch the Workflow based on the user's selection**: You could add a [Branch block](/streamline/workflows/blocks#configuring-a-core-block). This can use a conditional expression (in CEL syntax) that references the user's selection to determine the path the Workflow should take next.
  * For example, you might set a path expression like `actions["user-input"].outputs.selection == "Leanne Graham (Romaguera-Crona)"` to run a specific set of steps if the user chose the name `Leanne Graham (Romaguera-Crona)` from the dropdown during the User input step.
* **Trigger integration blocks**: The user's selection could be used to [drive actions in third-party integrations](/streamline/workflows/blocks#configuring-an-integration-block) such as creating a Pull Request in GitHub, sending a notification to Slack or Microsoft Teams, and more. Cortex offers a [block library](/streamline/workflows/blocks#configuring-a-workflow-block-basic) with over 200 actions to choose from.


# Trigger internal Jenkins jobs
Source: https://docs.cortex.io/guides/operational-readiness/jenkins-axon



You can use [Cortex Workflows](/streamline/workflows) and [Axon Relay](/ingesting-data-into-cortex/integrations/axon-relay) to trigger Jenkins jobs running inside your private network without exposing your CI/CD tools to the public internet. This guide walks you through setting up a Docker-based Jenkins instance, configuring Axon Relay to communicate with it securely, and building a Workflow that listens for the job result via callback URL.

### Prerequisites

Before getting started:

* Create a [Cortex API token](/configure/settings/api-keys).
* You should have the following tools installed locally:
  * [Docker](https://docs.docker.com/get-docker/)
  * [Docker Compose](https://docs.docker.com/compose/install/)
* You should have [Jenkins](https://hub.docker.com/r/jenkins/jenkins) configured (used via Docker container in this guide).

### **Considerations**

* This guide describes using a Docker compose file, but note that Axon Relay can be run in Kubernetes or other container systems.

### Step 1: Configure Jenkins

1. Start a basic Jenkins instance in Docker:

```bash theme={null}
docker run -p 9090:8080 -p 50000:50000 jenkins/jenkins:lts
```

2. Once Jenkins starts, follow the UI to unlock and configure it. [Create a new job](https://www.jenkins.io/doc/book/pipeline/getting-started/#through-the-classic-ui), and use the following example simple pipeline:

> [!NOTE]
>
> This script includes a `Hello World` stage for lightweight setup and testing. Replace it with your own build, test, or deployment logic.

```
pipeline {
    agent any
    
    parameters {
        string(
            name: 'callbackURL',
            defaultValue: '',
            description: 'The callback URL to POST to'
        )
    }
    
    stages {
        stage('Hello World') {
            steps {
                echo 'Hello World'
            }
        }
        
    }
    
    post {
        always {
            script {
                if (params.callbackURL?.trim()) {
                    def status = currentBuild.currentResult ?: 'SUCCESS'
                    def message = ""
                    def statusCode = ""
                    
                    if (status == 'SUCCESS') {
                        message = "Pipeline completed successfully"
                        statusCode = "success"
                    } else {
                        message = "Pipeline failed during execution"
                        statusCode = "failure"
                    }
                    
                    withCredentials([string(credentialsId: 'cortex_api_token', variable: 'API_TOKEN')]) {
                        sh """
                            curl -X POST "${params.callbackURL}"\
                                 -H "Content-Type: application/json" \
                                 -H "Authorization: Bearer \${API_TOKEN}" \
                                 -d '{
                                     "status": "update",
                                     "message": "${message}",
                                     "response": {
                                     "build_number": "${env.BUILD_NUMBER}",
                                     "job_name": "${env.JOB_NAME}",
                                     "timestamp": "'"\$(date -Iseconds)"'"}
                                 }' \
                                 --fail \
                                 --show-error
                                 
                            curl -X POST "${params.callbackURL}"\
                                 -H "Content-Type: application/json" \
                                 -H "Authorization: Bearer \${API_TOKEN}" \
                                 -d '{
                                     "status": "${statusCode}",
                                     "message": "${message}"
                                 }' \
                                 --fail \
                                 --show-error
                        """
                    }
                    echo "Sent ${statusCode} notification to ${params.callbackURL}"
                } else {
                    echo "No callback URL provided, skipping POST request"
                }
            }
        }
        
        failure {
            echo "Pipeline failed!"
        }
        success {
            echo "Pipeline completed successfully!"
        }
    }
}
```

### Step 2: Set up and run Axon Relay

To call a Jenkins instance behind a firewall, you’ll need to run the [Cortex Axon Relay](/ingesting-data-into-cortex/integrations/axon-relay) locally or within your infrastructure.

#### **Step 2.1: Create the `.env` file**

In your project directory, create a file called `.env`. It should include:

```env theme={null}
CORTEX_API_TOKEN=<your_cortex_api_token>
JENKINS_URL=<https://your.jenkins.url>
JENKINS_TOKEN=<admin:your_jenkins_api_token>
```

Make sure these environment variables match the configuration of your Jenkins instance.

> [!NOTE]
>
> If Jenkins and Axon are running on the same machine, Axon Relay may have issues reaching Jenkins using `http://localhost` or `127.0.0.1`, since those addresses refer to the container’s internal network.
>
> A  workaround is to use a tunneling service like [ngrok](https://ngrok.com/) to expose Jenkins with a public HTTPS URL. If you do so, use the generated public HTTPS URL as the value for `JENKINS_URL`.

#### **Step 2.2: Create `accept.json`**

In your project directory, create a file called `accept.json`, which controls what endpoints the Relay is allowed to forward requests to:

```
{
  "private": [
    {
      "method": "any",
      "path": "/*",
      "origin": "${JENKINS_URL}",
      "auth": {
        "scheme": "basic",
        "value": "${JENKINS_TOKEN}"
      }
    }
  ]
}
```

#### **Step 2.3: Create `docker-compose.yml`**

The `docker-compose.yml` file defines how to run the Cortex Axon agent (Relay) using Docker Compose. This file tells Docker how to configure and launch the Relay service so it can securely connect to your internal Jenkins instance and communicate with Cortex.

In your project directory, create the following file:

```yaml theme={null}
services:
  jenkins-relay:
    image: ghcr.io/cortexapps/cortex-axon-agent:latest
    env_file: .env
    volumes:
      - "./accept.json:/app/accept.json:rw"
    command: [
      "relay",
      "-a", "jenkins-relay",  # This must match the alias used in the Workflow block
      "-f", "/app/accept.json"
    ]
```

#### **Step 2.4: Run Axon Relay**

From your terminal, run:

```bash theme={null}
docker compose up
```

Axon Relay will start and register with Cortex using your API token.

### Step 3: Create the Workflow in Cortex

1. Follow the steps to [start creating a Workflow](/streamline/workflows/create) and [configure its basic details](/streamline/workflows/create#creating-a-workflow).
2. Add an [**Async HTTP request**](/streamline/workflows/blocks#configuring-a-core-block) block to your Workflow. Configure the block:
   * **Block name**: Enter a descriptive name, e.g., `Trigger Jenkins job`.
   * **Slug**: Enter a unique identifier for the block.
   * **HTTP method**: `POST`
   * **URL**: Enter the relay URL for your Jenkins job, in the following format:\

     `https://<relay-alias>.relays.cortex.io/job/<jenkins-job-name>/buildWithParameters?callbackURL={{callbackUrl}}`
     * Replace `<relay-alias>` with the alias you assigned to the Relay in your `docker-compose.yml` file (e.g., `jenkins-relay`).
     * Replace `<jenkins-job-name>` with the name of the job you want to trigger in Jenkins.
     * `{{callbackUrl}}` is a dynamic value provided by Cortex and required for async blocks.
3. Save the block.
4. In the upper right corner of the page, click **Save Workflow**.

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/zight-2025-08-14-at-5-00-11-pm.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=3f5f0faee181abb7774d78dc6504c369)

### Step 4: Run the Workflow

* Click **Run** on your Workflow.

> [!TIP]
>
> Learn more about Workflow runs in [Running a Workflow](/streamline/workflows/run).

When you run the Workflow, the following actions happen:

1. Cortex will POST to Jenkins via Axon.
2. Jenkins starts the job and makes two POSTs back to Cortex:
   * One `update` while in progress.
   * One `success` or `failure` when done.
3. The Workflow resumes and displays output in the **Async HTTP** block results:
   * Metadata about the initial outbound request to Jenkins (e.g., status, headers)
   * A callback with the job name, build number, and timestamp
   * A final result with success or failure

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/zight-2025-08-14-at-9-07-47-pm.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=e9ee77464c05bf9dd630a46199d2d5c5)


# Kick off a Jenkins pipeline
Source: https://docs.cortex.io/guides/operational-readiness/jenkins-workflow



After integrating Cortex with [Jenkins](/ingesting-data-into-cortex/integrations/jenkins), you can use a Cortex [Workflow](/streamline/workflows) to kick off your pipeline directly through Cortex, rather than switching to Jenkins to launch a build.

For full instructions on creating and configuring Workflows, see the [Workflows documentation](/streamline/workflows).

## How to kick off a Jenkins pipeline in a Workflow

### Prerequisites

Before getting started:

* [Configure your Jenkins instance in Cortex](/ingesting-data-into-cortex/integrations/jenkins#step-3-configure-jenkins-in-cortex-to-enable-jenkins-workflow-blocks).

### Step 1: Create a workflow

1. In the main nav of Cortex, click **Workflows**.
2. Follow the steps of the [Workflows documentation](/streamline/workflows) to start creating a Workflow from scratch and configure its settings.
   * Give the Workflow a descriptive name such as "Kick off Jenkins pipeline."

### Step 2: Add blocks to the workflow

You can add a block to run a build with parameters, or you can add a block to run a build without parameters. See the Jenkins documentation for [more information on submitting parameterized jobs](https://wiki.jenkins.io/display/JENKINS/Parameterized+Build).

1. Click **+** to view the block library.
2. Click **Jenkins**.
   * To choose a a build without parameters, select **Run a build**.
   * To choose a build with parameters, select **Run a build with parameters**.
3. Click **Insert** at the bottom of the library.\


   ![Select the Jenkins 'Run a build' block.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/jenkins-block.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=9e7ddf446a95be5fec94770b64bbf2d2)
4. In the side panel, configure the block.
   * **Block name**: Enter a name for the block (e.g., `Run a build in Jenkins`).
   * **Slug**: Enter a unique slug for the block.
   * **Alias**: Select the alias of your Jenkins instance.
   * **Job name**: Enter the name of the Jenkins job to run.
   * **Parameters**: For a build with parameters, you also need to configure valid JSON for the run job parameters.
5. At the bottom of the side panel, click **Save**.


# Tracking cloud costs
Source: https://docs.cortex.io/guides/operational-readiness/tracking-cloud-costs



Bring cloud spend into Cortex so infrastructure cost lives alongside the rest of your engineering health data (deployment frequency, reliability, scorecard compliance) instead of sitting in a separate FinOps tool that engineers never open.

This guide walks through surfacing actuals, budgets, and forecasts at the team level, displaying them on entity pages, and wiring cost into your scorecards. By the end, your engineering managers will be able to answer, ***How much is my team spending, and are we on track against budget?***, without leaving Cortex.

![A custom 'Cloud cost' dashboard in Cortex.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/screenshot-2026-06-10-at-2-25-38-pm.png?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=89a16f8ef10db02fcec2930287968c4c)

## Prerequisites

1. The `Configure Eng Intelligence custom metrics` permission to create and publish metric definitions.
2. An [API key](/configure/settings/api-keys#creating-an-api-key-in-cortex) with the same permission if you plan to push data programmatically (most cloud cost setups do).
3. Cost data you can export on a schedule from your cost management platform (AWS Cost Explorer, Azure Cost Management, Databricks, New Relic, etc.), or a CQL-computable source already in Cortex.

### **Custom metrics or custom data?**

Use [custom metrics](/guides/operational-readiness/tracking-cloud-costs#step-2-creating-custom-metrics) for anything that changes over time, e.g. monthly spend, budget targets, and forecasts. Cost dollars are a time series, so they belong in custom metrics. See [Custom metrics](/improve/eng-intelligence/custom-metrics) to learn more.

Use [custom data](/guides/operational-readiness/tracking-cloud-costs#step-5-tagging-entities-for-cost-attribution-custom-data) for slowly-changing tags like a cost-center or cost-attribution override. Refer to [Custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data) for more information.

## Step 1: Modeling your cost metrics

Cloud cost is most actionable at the team level where a budget owner can actually do something about it. Attach your metrics to team-type entities rather than individual services, at least to start.

A complete picture has three dimensions. A typical setup uses one metric per provider, per dimension:

**Actuals** *(what was spent)*:

* Total cloud cost
* AWS cost
* Azure cost
* Databricks cost
* New Relic cost
* AWS Marketplace cost

**Budgets** *(planned spend targets)*:

* Budgeted AWS
* Budgeted Databricks
* Budgeted New Relic

**Forecasts** *(projected spend for the period)*:

* Forecast AWS
* Forecast Databricks
* Forecast New Relic

You don't need every provider in every dimension. It's common for actuals to flow for more teams than budgets and forecasts, since budget planning is usually formalized for a smaller subset. Start with actuals everywhere, then layer in budgets and forecasts where the planning data exists.

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/image.png?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=2fef34324cb42479d9682f9b1976d37b)

## Step 2: Creating custom metrics

Add custom metrics in Cortex via [CQL](/improve/eng-intelligence/custom-metrics#creating-a-custom-metric-via-cql) or [API](/improve/eng-intelligence/custom-metrics#creating-a-custom-metric-via-api). Refer to the table below for field definitions.

| Field | Definition |
| - | - |
| **Ingestion method** | Choose API for cost data exported from an external platform (the common case), or CQL if the underlying numbers already exist in Cortex.  If you choose CQL, Cortex evaluates the expression every 12 hours and the result must resolve to a number, or it fails validation. |
| **Name** | The name of the custom metric. This is how it appears in Eng Intelligence, e.g. `AWS Cost`. |
| **Key** | A unique identifier of letters, digits, and hyphens, e.g. `aws-cost`. **Tip**: Keep a consistent prefix scheme like `cost-actual-aws`, `cost-budget-aws`, `cost-forecast-aws` so the three dimensions group cleanly later. |
| **Trend color indicator** | Determine if an upward or downward trend is positive. |
| **Draft** | Toggle off once you've validated the data, to make it visible to everyone with Eng Intelligence access. |

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/image-1.png?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=8b12f6eee60d6ee4cc3d053595f282a7)

## Step 3: Pushing your cost data

For externally-sourced cost data, post to each metric via the API on a regular cadence (a daily or monthly job, depending on how often your platform closes the books).

* Add points to a single entity, or bulk-add multiple points using `createBulkCustomMetricData` to load many teams at once.
* You can backfill up to two years, so load historical spend on first setup to get trends immediately rather than waiting months for them to accumulate.
* All API requests need an `Authorization: Bearer <token>` header.

A few operational notes:

* Cortex lags custom metric results until the end of the previous day, so today's posted data won't render until tomorrow.
* Bulk metric creation via the API is rate-limited. If you're loading dozens of teams, batch your requests and handle `429` responses with a retry-after delay rather than hammering the endpoint.
* Custom metric data is retained for 24 months.

## Step 4: Surfacing cost on team pages with a plugin

Eng Intelligence and [Data Explorer](/improve/eng-intelligence/data-explorer) show your cost metrics out of the box, but a dedicated custom plugin gives budget owners a purpose-built view on their team page.

Build a plugin that displays:

* Cloud cost trends across providers
* Budget vs. actuals comparison
* A unified spend view across AWS, Azure, Databricks, and New Relic

Scope the plugin to team-type entities only, so it appears where cost is actionable and stays off individual service pages where it would just be noise. The plugin reads your metric data through the Cortex API, so it stays in sync with whatever cadence you're posting on.

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/image-2.png?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=66c3bf11368df282bf3e3453cd8f302c)

## Step 5: Tagging entities for cost attribution (custom data)

If you need to attribute or override how individual services and resources roll up to a cost center, use a custom data field rather than a metric (this is the slowly-changing-metadata case). A field like operational-cost-override applied across your catalog lets your cost platform (or your own CQL) map services back to the right team or product.

This is what makes accurate chargeback and showback possible: the metrics tell you how much, the custom data tells you whose.

## Step 6: Putting cost to work in Scorecards and reports

Once cost is flowing, it stops being a dashboard and starts being a control:

* **Scorecard rules** - Flag teams whose actual spend exceeds forecast by more than a threshold, or whose spend has grown month-over-month beyond a set percentage. Cost becomes a standard you can drive, not just a number you observe. See [Scorecard rule filters](/standardize/scorecards/scorecard-filters)
* **CQL reports** - Build a tabular, cross-team cost comparison so leadership can rank spend without manually aggregating from a finance export. See [Using CQL reports](/standardize/cql/cql-reports)
* **Service-level cost** - Once team-level patterns are solid, extend attribution down to individual services using your cost-attribution custom data, so you can answer, ***Which service is driving this team's bill?***

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/image-3.png?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=5335f346ce7e000b148104584a2080dd)

## What you end up with

Cost data living where engineering decisions are made—closing the loop between the teams writing the code and the teams accountable for the bill—scoped to the level where someone can act on it, and tied into the same scorecards and reports that govern everything else in your catalog.


# Visualizing custom data in a plugin
Source: https://docs.cortex.io/guides/operational-readiness/visualizing-custom-data-in-a-plugin



Plugins let you build lightweight UI extensions that surface metadata directly in the Cortex UI. Cortex already renders custom data automatically in the **Custom data & metrics tab** on every [entity page](/ingesting-data-into-cortex/entities-overview/entities/details). However, many teams want to go further, like adding richer visualizations, grouping related fields, embedding links, or turning custom data into more opinionated dashboards.

This guide shows how to build a plugin page that reads custom data and renders it using your own UI.

### Overview

Cortex supports attaching structured metadata to any catalog entity using [**Custom Data**](/ingesting-data-into-cortex/entities-overview/entities/custom-data). This metadata automatically appears in the **Custom Data** tab of the entity page.

If your team wants to:

* organize fields into custom sections
* add tables, charts, or diagrams
* highlight important metadata
* provide context-specific controls
* match a specific visualization or compliance requirement

a plugin can fetch the same custom data and render a tailored UI that sits alongside the built-in Cortex experience.

### Step 1: Add custom data to an entity

To add custom data to an entity, you can use the [Custom Data API](/api/rest/custom-data/add-custom-data-for-entity). To illustrate how this works, we’ll use the following fictional metadata object:

```json theme={null}
{
  "service_owner": "Payments Team",
  "languages": "Node.js, TypeScript",
  "dependencies": "Redis, Kafka, BillingAPI",
  "service_tier": "Tier 2",
  "last_reviewed": "2025-11-01",
  "links": "[https://docs.example.com/runbook, https://example.com/architecture]"
}
```

This object is stored under the custom data key `sample-metadata`.

```
sample-metadata
```

### Step 2: Register the plugin

Once you have custom data to visualize, [register your plugin](https://app.getcortexapp.com/admin/plugins/new) in Cortex. Follow the [Creating Plugins documentation](/streamline/plugins/creating-plugins), making sure to choose `Specific entity types` as the context. This ensures your visualization displays when viewing an entity that contains the custom data.

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/zight-2025-11-20-at-2-45-56-pm-1.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=07bec996df2acfa1e1e9f558c1665914)

### Step 3: Download the Plugin Template

After registering the plugin, Cortex provides a downloadable plugin starter template, including:

* React setup
* Plugin Context provider
* Styling tokens (`--cortex-plugin-*`)
* Local development instructions
* A preconfigured route structure

Download the template from the [Register plugin page](https://app.getcortexapp.com/admin/plugins/new) in Cortex. This template is where you’ll build your visualization.

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/zight-2025-11-20-at-2-47-16-pm.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=0580b0722bc88b7e51d9851431810925)

### Step 4: Build the Custom Data Visualization

Inside the downloaded template:

1. Add a new component
2. Use the Plugin Context to read the current entity tag
3. Fetch custom data using `CortexApi.proxyFetch()`
4. Render a styled table or any UI you choose

Below is a complete example component (`SampleMetadataView.tsx`) that renders the fictional `sample-metadata` object.

#### Example Component

```tsx theme={null}
import React, { useEffect, useState } from "react";
import { CardTitle } from "@cortexapps/react-plugin-ui";
import { CortexApi } from "@cortexapps/plugin-core";

import { Heading, Section, Subsection } from "./UtilityComponents";
import { usePluginContextProvider } from "./PluginContextProvider";

type SampleMetadata = {
  service_owner?: string;
  languages?: string;
  dependencies?: string;
  service_tier?: string;
  last_reviewed?: string;
  links?: string;
};

const SampleMetadataView: React.FC = () => {
  const context = usePluginContextProvider();

  const [data, setData] = useState<SampleMetadata | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const fetchMetadata = async () => {
      try {
        const tag = encodeURIComponent(context.entity.tag);

        const response = await CortexApi.proxyFetch(
          `https://api.getcortexapp.com/api/v1/catalog/custom-data?tag=${tag}&key=sample-metadata`
        );

        if (!response.ok) throw new Error(`HTTP ${response.status}`);

        const json = await response.json();
        const entry = Array.isArray(json) ? json[0] : json;

        setData(entry?.value || null);
      } catch (e: any) {
        setError("Unable to load sample metadata");
      } finally {
        setLoading(false);
      }
    };

    if (context?.entity?.tag) fetchMetadata();
  }, [context]);

  const renderRow = (label: string, value: React.ReactNode) => (
    <tr key={label}>
      <th
        style={{
          textAlign: "left",
          padding: "8px 12px",
          fontWeight: 500,
          width: "35%",
          backgroundColor: "var(--cortex-plugin-input)",
          borderBottom: "1px solid var(--cortex-plugin-border)"
        }}
      >
        {label}
      </th>
      <td
        style={{
          padding: "8px 12px",
          borderBottom: "1px solid var(--cortex-plugin-border)",
          color: "var(--cortex-plugin-primary)"
        }}
      >
        {value || "Not set"}
      </td>
    </tr>
  );

  return (
    <Section>
      <Heading>
        <CardTitle>Sample Metadata</CardTitle>
      </Heading>
      <Subsection>
        {loading && <div>Loading…</div>}
        {error && <div>{error}</div>}
        {!loading && !error && data && (
          <div
            style={{
              borderRadius: 8,
              border: "1px solid var(--cortex-plugin-border)",
              backgroundColor: "var(--cortex-plugin-background)",
              overflowX: "auto"
            }}
          >
            <table style={{ width: "100%", borderCollapse: "collapse" }}>
              <tbody>
                {renderRow("Service Owner", data.service_owner)}
                {renderRow("Languages", data.languages)}
                {renderRow("Dependencies", data.dependencies)}
                {renderRow("Service Tier", data.service_tier)}
                {renderRow("Last Reviewed", data.last_reviewed)}
                {renderRow("Links", data.links)}
              </tbody>
            </table>
          </div>
        )}
      </Subsection>
    </Section>
  );
};

export default SampleMetadataView;
```

#### Add the component to `App.tsx`

Inside the downloaded template, open `App.tsx`.

In a single-view plugin like this, the recommended pattern is to render your visualization directly from `App.tsx`. Here’s what the minimal setup looks like:

#### `src/App.tsx`

```tsx theme={null}
import React from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import PluginProvider from "./RoutingPluginProvider";
import ErrorBoundary from "./ErrorBoundary";

import SampleMetadataView from "./components/SampleMetadataView";

import "../baseStyles.css";

const App: React.FC = () => {
  const queryClient = new QueryClient();

  return (
    <ErrorBoundary>
      <QueryClientProvider client={queryClient}>
        <PluginProvider enableRouting initialEntries={["/"]}>
          <SampleMetadataView />
        </PluginProvider>
      </QueryClientProvider>
    </ErrorBoundary>
  );
};

export default App;
```

### Step 5: Upload and Preview the Plugin in Cortex

Once your plugin is ready:

1. Run `npm run build` (or equivalent)
2. [Upload](/streamline/plugins/creating-plugins#step-4-uploading-and-previewing-the-plugin) the generated `UI.html` bundle in the Cortex UI
3. Open an entity of a supported type
4. Select your plugin in the left sidebar
5. Verify your custom visualization displays correctly

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/zight-2025-11-20-at-3-03-34-pm.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=8ff067c05e46fc716b4921f3ad295cf9)

This gives you a full end-to-end workflow for developing, testing, and launching plugin-based custom data visualizations.


# Data verification
Source: https://docs.cortex.io/guides/product-areas/data-verification



Use [data verification](/configure/settings/entity-settings/verification) to keep your catalog accurate over time. When you start a verification period, Cortex prompts entity owners to confirm details like ownership and metadata, so you can catch stale or incorrect data before it causes problems.

These recipes show when to run a verification, like after a large import, a migration, or ahead of an audit.

### [Verify services after AI-based auto-mapping](/guides/ai-excellence/verify-auto-mappings)

Confirm ownership is accurate after accepting recommended owners in bulk

AI excellence

### [Validate data after migration](/guides/migrations-and-modernization/validate-data)

Make sure entity data is up to date after moving it into Cortex

Migrations

### [Data verifications for audit readiness](/guides/compliance/data-verification)

Schedule regular verifications so your catalog is ready for every audit

Compliance


# Eng Intelligence
Source: https://docs.cortex.io/guides/product-areas/eng-intelligence



Use [Eng Intelligence](/improve/eng-intelligence) to turn the data your teams already produce into a clear picture of how software gets built and delivered. Instead of pulling reports from several tools, you can track DORA metrics, PR cycle times, and incident response in one place, and spot what's worth fixing.

These recipes show how to use Eng Intelligence dashboards and metrics to answer specific questions about your engineering organization.

### [Measure AI impact](/guides/ai-excellence/measure-ai-impact)

Use Eng Intelligence to see how AI tools change the way your teams ship

AI excellence

### [Improve bottlenecks in your SDLC](/guides/production-readiness/improve-bottlenecks)

Use Eng Intelligence to see how AI tools change the way your teams ship

Production readiness

### [Tracking cloud costs](/guides/operational-readiness/tracking-cloud-costs)

Use Eng Intelligence to see how AI tools change the way your teams ship

Operational readiness


# Plugins
Source: https://docs.cortex.io/guides/product-areas/plugins



Use [plugins](/streamline/plugins) to shape Cortex around the way your organization works. With plugins, you can bring in data from internal systems, connect tools Cortex doesn't support out of the box, and build your own views right where your teams already look.

These recipes show how to build plugins that put the information your teams need in front of them.

### [Visualizing custom data in a Plugin](/guides/operational-readiness/visualizing-custom-data-in-a-plugin)

Build a plugin page that displays custom data with your own UI

Operational readiness


# Scorecards
Source: https://docs.cortex.io/guides/product-areas/scorecards



Use [Scorecards](/standardize/scorecards) to turn your engineering standards into rules that Cortex checks automatically. Instead of keeping best practices in wiki pages and checklists, you can see which entities meet the bar, which don't, and what to fix.

These recipes cover common ways to use Scorecards, like preparing your services for AI tools, reducing incident response times, tracking migrations, and enforcing security and compliance standards.

### [Establish consistent AI security controls](/guides/ai-excellence/establish-consistent-ai-security-controls)

Apply the same security and compliance standards to every AI model and pipeline

AI excellence

### [Set benchmarks for AI readiness](/guides/ai-excellence/set-benchmarks-for-ai-readiness)

Check whether your services have the engineering foundations to adopt AI safely

AI excellence

### [Prepare for effective use of AI tools](/guides/ai-excellence/prepare-for-effective-use-of-ai-tools)

Make sure your repos have the files, safeguards, and integrations AI tools need

AI excellence

### [Seasonal readiness Scorecard](/guides/production-readiness/seasonal-readiness-scorecard)

Get your services ready before your busiest time of year

Production readiness

### [Reduce MTTA](/guides/incident-mgmt/reduce-mtta)

Make sure the right people are reachable and acknowledge incidents quickly

Incident management

### [Reduce MTTR](/guides/incident-mgmt/reduce-mttr)

Restore service faster with clear ownership, runbooks, and escalations

Incident management

### [Manage an upcoming EOL for AWS](/guides/migrations-and-modernization/manage-an-upcoming-eol-for-aws)

Track which services still need to upgrade RDS, Lambda, and ElastiCache versions

Migrations

### [Accelerate migration to K8s](/guides/migrations-and-modernization/accelerate-migration-to-k8s)

Track your services' progress moving to Kubernetes and keep the migration on schedule

Migrations

### [Ensure SOC 2 compliance](/guides/compliance/soc2)

Replace spreadsheet tracking by connecting live system data to SOC 2 controls

Compliance

### [Measure DORA progress](/guides/dora/scorecard)

Measure your teams against DORA benchmarks and watch the metrics improve

DORA metrics

### [Enforce security standards](/guides/security/scorecard)

Evaluate every service against your security standards before gaps turn into incidents

Security

### [Surface vulnerabilities in failed Scorecard rules](/guides/security/vulnerabilities-rules)

Show vulnerability details in rule failure messages so engineers know what to fix

Security

### [Surface code coverage in failed Scorecard rules](/guides/security/code-coverage-rules)

Show SonarQube code coverage in rule failure messages so engineers know what to fix

Security


# Workflows
Source: https://docs.cortex.io/guides/product-areas/workflows



Use [Workflows](/streamline/workflows) to turn everyday engineering tasks into a few clicks. Instead of switching between tools or waiting on a ticket, you can run the whole process from Cortex.

These recipes cover common ways to use Workflows, like giving developers access to the tools they need, creating new services with best practices built in, kicking off pipelines, and responding to incidents.

### [Scaffold an ML model project](/guides/ai-excellence/scaffold-ml-model)

Start every new machine learning project with best practices built in

AI excellence

### [Manage Terraform infrastructure](/guides/production-readiness/terraform)

Provision, maintain, and destroy cloud resources from a Workflow

Production readiness

### [Standardize new service creation](/guides/production-readiness/standardize-new-service-creation)

Create the repo, entity, and Jira ticket for a new service in one run

Production readiness

### [Rollback a service during an incident](/guides/incident-mgmt/workflow-rollback)

Roll back a service quickly when an incident hits

Incident management

### [Create ServiceNow incident](/guides/incident-mgmt/servicenow)

Open a ServiceNow incident directly from a Workflow

Incident management

### [Automate new dev environment](/guides/dev-onboarding/env-setup-workflow)

Create a repo, provision infrastructure with Terraform, and open a PR for an RDS instance

Developer onboarding

### [Automate user access to GitHub, PagerDuty, and Jira](/guides/dev-onboarding/automate-user-access-to-github-pagerduty-and-jira)

Give new developers access to the tools they need on day one

Developer onboarding

### [Automate access to Copilot](/guides/dev-onboarding/automate-user-access-to-copilot)

Grant GitHub Copilot access with an approval step or self-service

Developer onboarding

### [Kick off a Jenkins pipeline](/guides/operational-readiness/jenkins-workflow)

Launch a Jenkins build from Cortex without switching tools

Operational readiness

### [Call internal service endpoints](/guides/operational-readiness/internal-endpoints)

Reach services behind your firewall with Axon Relay, without exposing them

Operational readiness

### [Run a Humanitec pipeline](/guides/operational-readiness/humanitec-pipeline)

Call the Humanitec API to run a pipeline from a Workflow

Operational readiness

### [Trigger internal Jenkins jobs](/guides/operational-readiness/jenkins-axon)

Run Jenkins jobs in your private network without exposing your CI/CD tools

Operational readiness

### [Automate sync in ArgoCD](/guides/operational-readiness/argocd-workflow)

Sync ArgoCD applications from a Workflow instead of the ArgoCD UI

Operational readiness

### [Loop in a JavaScript block and return specified output](/guides/operational-readiness/javascript-looping)

Transform data with custom scripts instead of extra tooling

Operational readiness

### [Link SOC2 documents to an entity](/guides/compliance/link-soc2-docs)

Attach SOC 2 documents to entities without the manual busywork

Compliance

### [Bulk accept entity data verifications](/guides/compliance/bulk-accept-entity-data-verifications)

Let owners accept verification for all of their entities in one run

Compliance


# Improve bottlenecks in your software development lifecycle
Source: https://docs.cortex.io/guides/production-readiness/improve-bottlenecks



You can use Cortex MCP to quickly identify bottlenecks that are slowing your teams down, and use these insights to take action and track progress with Custom Dashboards.

### Step 1: Use Cortex MCP to identify bottlenecks

First, you can use [Cortex MCP](/get-started/cortex-ai-assistant/mcp) to quickly identify bottlenecks in your version control metrics across the organization.

Use a prompt such as *What are the bottlenecks in my version control metrics org-wide?.* The MCP will respond with an analysis of version control bottlenecks. Review the bottlenecks to understand what areas you should focus on.

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/mcp-bottlenecks.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=6037f5cfa288eb1b7083938f211b4df2)

In our example, the MCP flags the following:

* Review pickup is the primary bottleneck.
* Cycle time being lower than any single stage of review latency signals heavy overlap and/or outlier effects. Improvement should focus on accelerating reviewer response.
* Some teams have much longer wait times for first review.
* Another metric to watch is open PR count per team or repo.

#### Follow the MCP's recommended next steps

The MCP will also generate a list of suggestions to take action on the identified bottlenecks.

In our example, the MCP made the following recommendations:

* Set and enforce review SLAs on time to first review.
* Use Cortex [Data Explorer](/improve/eng-intelligence/data-explorer) to drill further by repository and reviewer to pinpoint which repos feed the extreme outliers.
* Close abandoned PRs.

### Step 2: Create a Custom Dashboard to track progress

In Cortex, create a [Custom Dashboard](/improve/eng-intelligence/dashboards/custom) to visualize the bottleneck. Add modules to the dashboard based on what was flagged by Cortex MCP.

> **Create modules for the metrics**
>
> In our example, the metrics flagged were Time to first review and Cycle time.
>
> 1. Navigate to **Eng Intelligence > Metrics Explorer**.
> 2. Click **+New module**, then click the default metric on the page (Cycle time). A modal will open where you can select a new metric.\\
>
>    ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/new-module.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=76aaa0b15ab6e8533dd365f27f27e284)
> 3. In the Version control metric category, select "Time to first review." Choose which operation to apply to the chart (average, max, median, min, P95, or sum) then click **View metric**.\\
>
>    ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/time-to-first-review.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=da15b06b42daffc01041b29610a28eb0)
> 4. The visualization will appear on the page. In the upper right corner, click **Save as**. Give the module a descriptive name, then click **Save module**.
>
> Repeat these steps for each metric you want to track.

> **Create a Custom Dashboard**
>
> 1. Navigate to **Eng Intelligence > Dashboards**. In the upper right corner, click **Create Dashboard**.
> 2. Enter a descriptive name for the dashboard, then at the bottom of the sidebar, click **Save**.
>    1. In our example, since we identified review time as the bottleneck, we name the dashboard "Review time bottleneck."
> 3. You will be prompted to select a module to add to your dashboard. Select a module, then at the bottom, click **Close**.\\
>
>    ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/select-modules.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=531d022ee052c222346f2ab9a1c43962)
> 4. The page will reload with your module visualization. To add another module, click the **+** icon at the bottom or side of the page. Select a module from the list again, then click **Close**.
>
> The custom dashboard - "Review time bottleneck" - now contains the two metrics flagged by Cortex MCP, allowing for an easy side-by-side comparison:
>
> ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/bottleneck-custom.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=2d30c99c6477981a712388a7ca988592)


# Seasonal readiness Scorecard
Source: https://docs.cortex.io/guides/production-readiness/seasonal-readiness-scorecard



For organizations that have a busy season, they can implement a seasonal readiness Scorecard to proactively ensure operational efficiency and consistency.

You can use our [example rules](/guides/production-readiness/seasonal-readiness-scorecard#example-rules) as a starting point, and you can learn more below about [how customer H\&R Block reduced bugs by 50% year-over-year by implementing a seasonal readiness Scorecard](/guides/production-readiness/seasonal-readiness-scorecard#example-h\&r-block’s-season-readiness-scorecard).

### Example rules

The focus areas of this type of Scorecard may be be specific to your organization's needs, but as general guidance, we would recommend creating a Scorecard that contains rules in these key focus areas:

> **Operational readiness**
>
> Example rules:
>
> * Entity has an owner\\
>
>   `ownership != null`
> * Runbook is linked\\
>
>   `links("runbook").length > 0`
> * Logs are linked\\
>
>   `links("logs").length > 0`

> **Reliability**
>
> Example rules:
>
> * SLO coverage\\
>
>   `slos().length > 0`
>
>   * Before configuring this rule, set up an integration that supports querying SLOs: [Datadog](/ingesting-data-into-cortex/integrations/datadog), [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace), [Google](/ingesting-data-into-cortex/integrations/google), [Lightstep](/ingesting-data-into-cortex/integrations/lightstep), [New Relic](/ingesting-data-into-cortex/integrations/newrelic), [Prometheus](/ingesting-data-into-cortex/integrations/prometheus), [Splunk Observability Cloud (SignalFx)](/ingesting-data-into-cortex/integrations/splunk-observability), or [Sumo Logic](/ingesting-data-into-cortex/integrations/sumologic).
> * Test coverage minimum met\\
>
>   `captures("test-coverage", sonarqube.metric("coverage") >= 80)`
>
>   * Before configuring this rule, set up an integration with [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube). The [Codecov](/ingesting-data-into-cortex/integrations/codecov) integration also supports querying code coverage. You can [surface these code coverage metrics in failure messages](/guides/security/code-coverage-rules) for failed Scorecard rules.
> * Zero critical and high vulnerabilities in Mend\\
>
>   `mend.vulnerabilities(risk = ["Critical", "High"]).length == 0`
>
>   * Before configuring this rule, set up an integration with [Mend](/ingesting-data-into-cortex/integrations/mend). Other integrations that support querying on vulnerabilities include [Apiiro](/ingesting-data-into-cortex/integrations/apiiro), [Checkmarx](/ingesting-data-into-cortex/integrations/checkmarx), [GitHub](/ingesting-data-into-cortex/integrations/github), [Mend](/ingesting-data-into-cortex/integrations/mend), [Semgrep](/ingesting-data-into-cortex/integrations/semgrep), and [Snyk](/ingesting-data-into-cortex/integrations/snyk).
> * On-call rotation has at least one escalation\\
>
>   `oncall.numOfEscalations() > 1`
>
>   * Before configuring this rule, set up an integration that supports querying on-call: [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie), [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty), [Splunk On-Call (VictorOps)](/ingesting-data-into-cortex/integrations/splunk-oncall), or [xMatters](/ingesting-data-into-cortex/integrations/xmatters).
> * Datadog monitor is set\\
>
>   `datadog.monitors().length > 0`
>
>   * Before configuring this rule, set up an integration with [Datadog](/ingesting-data-into-cortex/integrations/datadog).

> **Security**
>
> Example rules:
>
> * At least one required approval to merge\\
>
>   `git.numOfRequiredApprovals() > 0`\\
>
>   * Before configuring this rule, set up a version control integration: [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), or [GitLab](/ingesting-data-into-cortex/integrations/gitlab).
> * Code updated in the last week\\
>
>   `git.lastCommit().freshness < duration("P7D")`
>
>   * Before configuring this rule, set up a version control integration.
> * 0 critical Snyk issues\\
>
>   `snyk.issues(severity=["CRITICAL"], fixability=["FIXABLE"]) <= 0`
>
>   * Before configuring this rule, set up an integration with Snyk. Other integrations that support querying on vulnerabilities include [Apiiro](/ingesting-data-into-cortex/integrations/apiiro), [Checkmarx](/ingesting-data-into-cortex/integrations/checkmarx), [GitHub](/ingesting-data-into-cortex/integrations/github), [Mend](/ingesting-data-into-cortex/integrations/mend), [Semgrep](/ingesting-data-into-cortex/integrations/semgrep), and [Snyk](/ingesting-data-into-cortex/integrations/snyk).

### Get started with an example Scorecard

You can use the example rules above as a starting point for your Scorecard.

In this example Scorecard, the levels are organized by focus area. Scorecard levels are progressive, with the last level including the highest priority rules. Based on your organization's needs, you may want to reorder rules, add or remove rules, or rename the levels.

You can [create this Scorecard in the UI](/guides/production-readiness/seasonal-readiness-scorecard#create-example-scorecard-via-the-ui), or you can [upload the YAML file via API or GitOps](/guides/production-readiness/seasonal-readiness-scorecard#create-example-scorecard-via-gitops-or-api).

**UI**

### Create example Scorecard via the UI

#### Step 1: Create the Scorecard and configure its basic details

1. In Cortex, navigate to **Scorecards** and click **+Create Scorecard**. Start with a blank Scorecard.
2. Configure the basic details.
   * Include a name that helps your users understand the purpose of the Scorecard (e.g., `Season readiness`) and a description.
   * Learn more about configuring basic fields for Scorecards in [Create a Scorecard](/standardize/scorecards/create).

### Step 2: Add levels and rules

1. Under **Define evaluation rules**, add levels. In our example, we added levels based on focus area:
   * Operational readiness
   * Reliability
   * Security
2. Under a level, click **+Add rule** to add a rule.
   * For each level, add the [example rules](/guides/production-readiness/seasonal-readiness-scorecard#example-rules) listed earlier in these instructions.
3. At the bottom of the page, click **Save Scorecard**.

**API or GitOps**

#### Create example Scorecard via GitOps or API

When following a [GitOps approach](/configure/gitops), you can add a Scorecard YAML file to your `.cortex/scorecards` directory in your version control repository. Note that GitOps must be enabled for Scorecards in your [GitOps settings](/configure/settings/gitops-settings).

You could also use the [Cortex API,](/api/rest/scorecards) where you can submit a Scorecard definition in YAML.

> **Seasonal readiness Scorecard YAML**
>
> Use the YAML file below to add this Scorecard to your workspace via the API or via a GitOps flow.
>
> ```yaml theme={null}
> tag: seasonal-readiness
> name: Seasonal Readiness
> description: Ensuring services are ready before the busy season
> draft: false
> notifications:
>   enabled: true
>   scoreDropNotificationsEnabled: false
> exemptions:
>   enabled: true
>   autoApprove: false
>   userSpecificNotifications: false
> ladder:
>   name: Default Ladder
>   levels:
>   - name: Operational readiness
>     rank: 1
>     description: Minimum seasonal readiness
>     color: "#EBA27E"
>   - name: Reliability
>     rank: 2
>     description: Top level readiness rules
>     color: "#B3B3B3"
>   - name: Security
>     rank: 3
>     color: "#33393F"
> rules:
> - title: On-call rotation has at least one escalation
>   expression: oncall.numOfEscalations() > 1
>   weight: 1
>   level: Reliability
> - title: Logs are linked
>   expression: links("logs").length > 0
>   weight: 1
>   level: Operational readiness
> - title: Entity has owner
>   description: "For accountability, ensure entities have clear ownership"
>   expression: ownership != null
>   weight: 1
>   level: Operational readiness
> - title: Test coverage minimum met
>   expression: "captures(\"test-coverage\", sonarqube.metric(\"coverage\") >= 80)"
>   weight: 1
>   level: Reliability
> - title: SLO coverage
>   expression: slos().length > 0
>   weight: 1
>   level: Reliability
> - title: Datadog monitoring is set
>   expression: datadog.monitors().length > 0
>   weight: 1
>   level: Reliability
> - title: At least one required approval to merge
>   expression: git.numOfRequiredApprovals() > 0
>   weight: 1
>   level: Security
> - title: Runbook is linked
>   expression: links("runbook").length > 0
>   weight: 1
>   level: Operational readiness
> - title: Low number of Snyk issues
>   expression: snyk.issues().length < 5
>   weight: 1
>   level: Security
> - title: Zero critical and high vulnerabilities
>   expression: "captures(\"critical-vulns\", custom(\"critical_vulnerabilities\"))\
>     \ == 0 AND captures(\"high-vulns\", custom(\"high_vulnerabilities\")) == 0"
>   weight: 1
>   level: Reliability
> - title: Code updated in the last week
>   expression: git.lastCommit().freshness < duration("P7D")
>   weight: 1
>   level: Security
> filter:
>   kind: GENERIC
>   types:
>     include:
>     - service
> ```

## Example: H\&R Block's Season Readiness Scorecard

As described in their IDPCON talk, H\&R Block implemented a Season Readiness Scorecard ahead of tax season to drive operational consistency. Their Scorecard helped them automatically measure their organization's top priority areas: Security, resiliency, code coverage, and software development lifecycle best practices.

They included rules to verify on-call coverage, escalation depth, monitoring setup, SLOs, and package versions.

### Outcome

They reduced incidents and bugs by 50% year over year, while automating readiness tracking previously handled manually by six program managers.

#### Their next steps

To continue proactively meeting organizational benchmarks, they also created [Scaffolder templates](/streamline/workflows/scaffolder) with built-in compliance and coding standards. This allowed them to ensure that all new projects were scaffolded with the best practices baked in.

### See the IDPCON session

H\&R Block's Manager of Technology spoke at IDPCON to explain how their organization leveled up developer experience with automation in Cortex:

[YouTube video player](https://www.youtube.com/embed/_wLdQ5Fxb_g)


# Standardize new service creation
Source: https://docs.cortex.io/guides/production-readiness/standardize-new-service-creation



Developers often need to spin up new services for use cases like feature development and architecture processes. Doing this manually can be error-prone and inconsistent across teams. To achieve engineering excellence, it is critical to modernize and standardize this practice; you can use a Cortex Workflow to ensure every new service has best practices built in from the start.

The Workflow in this example streamlines service creation by guiding you through a form to input service information then automatically handling the rest: creating a new repository based on your input, creating an entity in Cortex that includes custom data and a linked repository, and automatically opening a Jira ticket to ensure visibility and tracking.

> [!TIP]
>
> Cortex customer Archer saves 24 hours per new service created by using Workflows to automate service creation with best practices built in. [Learn more below](/guides/production-readiness/standardize-new-service-creation#example-archer’s-deployment-workflow).

## Create a Workflow to standardize new service creation

### Prerequisites

Before getting started:

* Create a [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) with the `write:issue:jira` permission.
* Your Cortex role must have the [permissions](/configure/settings/managing-users/permissioning) `Edit Workflows`, `Execute Workflow runs`, `Configure Scaffolder templates`, and `Execute Scaffolder`.
* You should have already configured your version control provider integration with `write` access.
* Make sure you have already [registered your Scaffolder template](/streamline/workflows/scaffolder).
  * In this example, we use the [cookiecutter-spring-boot repository](https://github.com/cortex-workshops/cookiecutter-spring-boot).

### Step 1: Configure the Workflow basic settings

Follow the steps in the documentation to [create a Workflow](/streamline/workflows/create) and configure its basic settings.

### Step 2: Add blocks to the Workflow

Add the following blocks to the Workflow:

> **User input**
>
> This block contains the three fields that a user is prompted to fill out when the Workflow is run.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **User input** block.
> 2. In the side panel, enter a name and unique slug for the block.
> 3. Click **+Add user input**. Configure the input:
>    1. **Name**: Enter `Service Name`.
>    2. **Key**: Enter `service-name`.
>    3. **Description**: Optionally enter a description for this input.
>    4. **Required**: Toggle this setting on if you want to require your users to enter input for this field.
>    5. **Type**: Select `Text`.
>    6. Click **Add input**.
> 4. Click **+Add user input** again. Configure the input:
>    1. **Name**: Enter `Service Tag`.
>    2. **Key**: Enter `service-tag`.
>    3. **Description**: Optionally enter a description for this input. In our example, we add a description to ensure that users understand what a Cortex tag is in Cortex:\\
>
>       `The Cortex tag is a unique identifier that's used throughout Cortex. Do not use spaces. Example: my-service`
>    4. **Required**: Toggle this setting on if you want to require your users to enter input for this field.
>       * If you are asking for a unique tag, we recommend setting this field as required.
>    5. **Type**: Select `Text`.
>    6. Click **Add input**.
> 5. Click **+Add user input** again. Configure the input:
>    1. **Name**: Enter `Incident Process Documented`.
>    2. **Key**: Enter `incident-process-documented`.
>    3. **Description**: Optionally enter a description for this input. In our example, we add a description to ensure that users understand what this step is asking for:\\
>
>       `Has the incident process been submitted to your team lead?`
>    4. **Required**: Toggle this setting on if you want to require your users to enter input for this field.
>    5. **Type**: Select `Toggle`.
>    6. **Default value**: In our example, we set this to `False` to ensure users don't accidentally send a false positive.
>    7. Click **Add input**.
> 6. Click **Save** at the bottom of the side panel.
>
> ![The User input step contains three input fields.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/user-input-scaffolder-example.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=8735452114d0189beef5157aa862dece)

> **Scaffolder**
>
> This block creates a new repository in your connected Git integration, using templating to apply the outputs of the User Input step as the project name, app name, and repository name.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Scaffolder** block.
> 2. In the side panel, enter a name and unique slug for the block.
> 3. Under **Scaffolder template**, select your template. In this example, we use the `Spring Boot Template`.
> 4. Select the option to **Create a new repo**.
> 5. Add override variables. The **Variable** dropdown pulls in all the variables that are able to be overridden in the Git provider and in the Scaffolder template. In this example, we apply the following overrides:
>    * **project\_name**: `actions.user-input.outputs.service-name`
>      * This overrides it with the output of the "Service name" field from the User Input block earlier in the Workflow.
>    * **creator**: `context.initiatedBy.email`
>      * This overrides it with the email address of the person who initiated the Workflow.
>    * **app\_name**: `actions.user-input.outputs.service-name`
>      * Like the project\_name override, this one also overrides it with the output of the "Service Name" field from the User Input block.
>    * **publisherRepoName**: `actions.user-input.outputs.service-tag`
>      * This overrides it with the output of the "Service Tag" field from the User Input block earlier in the Workflow. This ensures that the repo name matches the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag).
> 6. Click **Save** at the bottom of the side panel.

> **Cortex custom data**
>
> Earlier in the Workflow, the User Input step prompts a user to enter a service name, tag, and to use a toggle to indicate whether the incident process was documented.
>
> The **Add custom data for entity** block determines where the user's response (the custom data) is recorded. Running this step results in the output of the `Incident Process Documented` toggle being added to an entity.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Add custom data for entity** block.
> 2. In the side panel, enter a name and unique slug for the block.
> 3. Configure the custom data details:
>    1. **Entity tag or ID**, use templating to reference the service tag provided by the user during the User Input step: `{{actions.user-input.outputs.service-tag}}`
>    2. **Key**: `incident-process-documented`
>    3. **Value**: `"{{actions.user-input.outputs.incident-process-documented}}"`
> 4. Click **Save** at the bottom of the side panel.

> **HTTP request**
>
> ### Step 4: Add an HTTP request block
>
> This step creates a Jira ticket for tracking and security review.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Add custom data for entity** block.
> 2. In the side panel, enter a name and unique slug for the block.
> 3. Configure the HTTP request:
>    1. **HTTP method**: Select `POST`.
>    2. **URL**: Enter your Jira API URL.
>    3. **Headers**: Include an authorization header and set the value to your Jira token.
>    4. **Payload**: In the payload, you can choose the project in Jira where you want the ticket created, and you can include other information such as the title of the Jira ticket (the `summary`) and the description of the ticket (the `content:text`). See [Jira's API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post) for more information on formatting the payload. In this example, we include the following payload:
>
> ```json theme={null}
> {
>   "fields": {
>     "project": {
>       "key": "SEC"
>     },
>     "summary": "Entity ready for security review.",
>     "description": {
>       "type": "doc",
>       "version": 1,
>       "content": [
>         {
>           "type": "paragraph",
>           "content": [
>             {
>               "type": "text",
>               "text": "New service ready for review."
>             }
>           ]
>         }
>       ]
>     },
>     "issuetype": {
>       "name": "Task"
>     }
>   }
> }
> ```
>
> 4. Click **Save** at the bottom of the side panel.

When you are finished adding blocks, click **Save Workflow** at the top of the page.

### Run the Workflow

* In the list of Workflows, locate your new service creation Workflow and click **Run**.
  * You will be redirected to a page showing the Workflow's steps.

The following chain of events occur during the run:

> **Workflow run steps**
>
> 1. The **User Input** block runs, which pauses the Workflow until the Workflow initiator enters a response.
>    1. In this example, we enter `Docs test` as the **Service Name**, `docs-test` as a **Service Tag**, and toggle on the option for **Incident Process Documented**. \\
>
>       ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/user-input-example.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=a83c51d001883929c81edbd86c74416c)
> 2. The **Scaffolder** block runs, which prompts you to configure and run the Spring Boot Template that was selected while [configuring the Scaffolder step](/guides/production-readiness/standardize-new-service-creation#step-2-add-blocks-to-the-workflow).
>    1. Because of the overrides that were configured in the Scaffolder step, the Project Name, App Name, Creator, and Repository fields are pre-filled. The overridden fields cannot be edited unless you select the option to make override fields editable while configuring the Scaffolder block.
>    2. During this step, you must also select the organization to create the repository in, include the branch name and a commit message, and choose the visibility of your repo. When you are finished, click **Submit**. A repository will be created in the organization you selected:\\
>
>       ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/repo-created.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=37bc4317d780413f98d48026663a546b)
> 3. The **Add custom data** block runs. The newly-created entity for the repository now contains the `incident-process-documented` key and value. You can see this in the **Output** tab of the block during the Workflow run, and in the [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details) **Custom data & metrics** sidebar link:\\
>
>    ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/custom-data-scaffolder.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=e7780fe304f202ed74c5d483f1f15357)
> 4. The **HTTP request** block runs. A ticket is created in Jira requesting a review from the security team. The title and description were set automatically based on the payload provided while [configuring the HTTP request step](/guides/production-readiness/standardize-new-service-creation#step-4-add-an-http-request-block):
>
>    ![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/scaffolder-jira-step.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=2157b4cf7a452ed75a2c4c0eb03310b4)

## Example: Archer's deployment Workflow

Cortex customer Archer implemented a Workflow combining scaffolding, infrastructure, deployment configuration, and cloud resources into a single process. All new services follow a consistent, repeatable workflow that includes best practices and requirements by default.

### Outcome

* Their teams go from concept to deployed service on a Kubernetes cluster in under 3 hours.
* They save 24 hours per new service creation.
* They saved an estimated \$72,000 across 30+ Workflow runs in 3 months.

### See the case study

Learn more about Archer's process in the case study: [Archer accelerates engineering efficiency with Workflows](https://www.cortex.io/case-studies/archer).


# Manage Terraform infrastructure
Source: https://docs.cortex.io/guides/production-readiness/terraform



You can use Workflows in Cortex to manage different aspects of Terraform infrastructure, including provisioning cloud resources, maintaining the resources, and destroying the resource to remove it from your Cortex workspace.

Handling these processes via a Workflow allows you to:

* **Automate infrastructure provisioning**: Use a Workflow to trigger the creation of cloud resources (such as AWS EC2 instances) by updating Terraform variables and executing runs
* **Enable self-service infrastructure requests**: Using a Workflow to streamline Terraform processes, organizations can enable self-service provisioning for developers.
* **Standardize environment bootstrapping:** Using the Scaffolder, teams can bootstrap new projects or environments with pre-defined Terraform templates, ensuring consistency and compliance with organizational standards.

See end-to-end Workflow examples in the following pages:

* [Provision EC2 instance with Terraform](/guides/production-readiness/terraform/provision)
* [Update EC2 instance](/guides/production-readiness/terraform/update)
* [Terraform destroy](/guides/production-readiness/terraform/destroy)


# Terraform destroy
Source: https://docs.cortex.io/guides/production-readiness/terraform/destroy



Using a Workflow, you can streamline the process of dismantling infrastructure that was previously provisioned and managed by a Terraform configuration. This Workflow will also remove the resource entity from your Cortex workspace.

## How to use a Workflow in Cortex to destroy a resource with Terraform

### Prerequisite

Before getting started, you should have already followed the guide to [Provision an EC2 instance with Terraform](/guides/production-readiness/terraform/provision).

#### Considerations

* This Workflow makes HTTP calls to [Terraform Cloud](https://www.hashicorp.com/en/products/terraform), but it is possible to call other Terraform orchestrators, such as [Spacelift](https://www.spacelift.io/).
* The Terraform orchestrator you use must have an API call to perform the destroy.

### Step 1: Start creating the Workflow

Follow the steps in the documentation to [create a Workflow](/streamline/workflows/create) and [configure its basic settings](/streamline/workflows/create#creating-a-workflow).

In the Workflow's basic settings, set its scope to apply to the entity type `AWS::EC2::Instance` and the group `terraform`. The prerequisite Workflow [Provision an EC2 instance with Terraform](/guides/production-readiness/terraform/provision) automatically adds the group to the entities it creates.

### Step 2: Add blocks to the Workflow

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Workflow YAML instructions**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: "[Terraform Cloud] Destroy"
> tag: workflow-terraform-destroy
> description: null
> isDraft: true
> filter:
>   entityFilter:
>     typeFilter:
>       types:
>       - AWS::EC2::Instance
>     entityGroupFilter:
>       entityGroups:
>       - terraform
>       excludedEntityGroups: []
>   ownershipScope: ALL
>   type: ENTITY
> runResponseTemplate: null
> failedRunResponseTemplate: null
> actions:
> - name: Are You Sure
>   slug: are-you-sure
>   schema:
>     inputs:
>     - name: Are You Sure? This will also delete it from the Catalog
>       description: null
>       key: are-you-sure
>       required: true
>       defaultValue: false
>       type: TOGGLE_FIELD
>     inputOverrides: []
>     type: USER_INPUT
>   outgoingActions:
>   - branch
>   isRootAction: true
> - name: Branch
>   slug: branch
>   schema:
>     branches:
>     - name: "yes"
>       slug: "yes"
>       outgoingAction: get-descriptor
>       expression: "actions[\"are-you-sure\"].outputs[\"are-you-sure\"] == true"
>       type: CONDITIONAL
>     fallbackBranch: null
>     joiningAction: null
>     type: CONDITIONAL_BRANCH
>   outgoingActions:
>   - get-descriptor
>   isRootAction: false
> - name: Get Descriptor
>   slug: get-descriptor
>   schema:
>     expression: .context.entity.descriptor
>     type: JQ
>   outgoingActions:
>   - get-workspace-id
>   isRootAction: false
> - name: Get Workspace ID
>   slug: get-workspace-id
>   schema:
>     expression: .actions."get-descriptor".outputs.result.info."x-cortex-metadata".terraform."workspace-id"
>     type: JQ
>   outgoingActions:
>   - terraform-destroy
>   isRootAction: false
> - name: Terraform Destroy
>   slug: terraform-destroy
>   schema:
>     headers:
>       Content-Type: application/vnd.api+json
>       Authorization: "Bearer {{context.secrets.tf_token}}"
>     httpMethod: POST
>     payload: |-
>       {
>            "data": {
>                       "attributes": {
>                                      "is-destroy": true,
>                                      "message": "Triggered Destroy",
>                                      "variables": []
>                           },
>                        "type":"runs",
>                        "relationships": {
>                                 "workspace": {
>                                                     "data": {
>                                                            "type": "workspaces",
>                                                            "id": "{{actions.get-workspace-id.outputs.result}}"
>                                                       }
>                                   }
>                        }
>                 }
>       }
>     url: https://app.terraform.io/api/v2/runs
>     type: HTTP_REQUEST
>   outgoingActions:
>   - delete-entity
>   isRootAction: false
> - name: Delete entity
>   slug: delete-entity
>   schema:
>     inputs:
>       entityId: "{{context.entity.tag}}"
>     integrationAlias: null
>     actionIdentifier: cortex.deleteEntity
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

Expand the tiles below to learn about each block in this Workflow and how to configure them in the Cortex UI:

> **User input**
>
> This block prompts the user to confirm that they want to destroy the resource.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **User input**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Are you sure` and the slug `are-you-sure`.
> 3. Click **+Add user input**. Add the following:
>    * **Name**: Are you sure? This will also delete it from the catalog
>    * **Key**: are-you-sure
>    * **Type**: Toggle
>    * **Default value**: This is set to `False` to prevent accidental deletion.
>    * Click **Add input**.
> 4. Save the block.

> **Branch**
>
> During the previous User input step, if the user selects "Yes" when prompted, the Workflow will branch into a set of blocks to destroy the resource. If the user does not select yes, then the Workflow will not continue.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Branch**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Branch` and the slug `branch`.
> 3. Configure the conditional path:
>    * **Name**: Yes
>    * **Slug**: yes
>    * **Path expression**: `actions["are-you-sure"].outputs["are-you-sure"] == true`
>
> #### Add blocks to the branched path
>
> The blocks in the path will get the entity descriptor and workspace ID, send an HTTP request to Terraform to destroy the resource, and delete the entity in your Cortex workspace.
>
> **Data transformations**
>
> 1. Click **+** under the new path. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Get descriptor` and the slug `get-descriptor`.
> 3. Enter a jq expression:
>
> ```jq theme={null}
> .context.entity.descriptor
> ```
>
> 4. Save the block.
> 5. Click **+** under the path. In the block library modal, choose **Data transformation**.
> 6. In the block configuration side panel, enter a name and unique slug for this block. In this example, we use the name `Get workspace ID` and the slug `get-workspace-id`.
> 7. Enter a jq expression:
>
>    ```jq theme={null}
>    .actions."get-descriptor".outputs.result.info."x-cortex-metadata".terraform."workspace-id"
>    ```
> 8. Save the block.
>
> **HTTP request**
>
> 1. Click **+** under the new path. In the block library modal, choose **HTTP request**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Terraform destroy` and the slug `terraform-destroy`.
> 3. Configure the block:
>    * **HTTP method**: POST
>    * **URL**: In our example, we set this to:\\
>
>      `https://app.terraform.io/api/v2/runs`
>    * **Headers**: Set the following headers:
>      * `Content-Type`: `application/vnd.api+json`
>      * `Authorization`: `Bearer {{ context.secrets.tf_token }}`
>    * **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>      "data": {
>                 "attributes": {
>                                "is-destroy": true,
>                                "message": "Triggered Destroy",
>                                "variables": []
>                     },
>                  "type":"runs",
>                  "relationships": {
>                           "workspace": {
>                                               "data": {
>                                                      "type": "workspaces",
>                                                      "id": "{{actions.get-workspace-id.outputs.result}}"
>                                                 }
>                             }
>                  }
>           }
> }
> ```
>
> 4. Save the block.
>
> **Delete entity**
>
> 1. Click **+** under the new path. In the block library modal, choose **Cortex > Delete entity**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Delete entity` and the slug `delete-entity`.
> 3. Under **Entity ID or tag**, enter `{{context.entity.tag}}`.

### Step 3: Run the Workflow

When you run the Workflow, the following events happen:

* The User input step prompts the user to confirm that they want to delete a resource.
* If the user confirms during the first block, then the branch block runs.
* The Workflow obtains the entity descriptor, then uses that information to obtain the related workspace ID.
* The HTTP request triggers a destroy in Terraform.
* The "Delete entity" step uses the entity descriptor obtained in the previous steps to determine which entity to delete.


# Provision EC2 instance with Terraform
Source: https://docs.cortex.io/guides/production-readiness/terraform/provision



This Workflow allows you to gather information about the resources, scaffold a new repository, create a new Terraform workspace, create an entity in your Cortex workspace, then send a message to Slack to confirm that the EC2 instance has been created.

## How to use a Cortex Workflow to provision an EC2 instance with Terraform

### Considerations

* This Workflow makes HTTP calls to [Terraform Cloud](https://www.hashicorp.com/en/products/terraform), but it is possible to call other Terraform orchestrators, such as [Spacelift](https://www.spacelift.io/).
* This Workflow demonstrates how to create a PR, but if you are using PR automation such as [Atlantis](https://www.runatlantis.io/), then you do not need to include the Async HTTP call to Plan and Apply.

### Step 1: Register the Scaffolder template in Cortex

Follow the instructions to [register the Scaffolder template in Cortex](/streamline/workflows/scaffolder). Use the following template:

> **Cookiecutter template**
>
> Save the JSON template below to register in Cortex:
>
> ```json theme={null}
> {
>     "project_name" :"new-vm",
>     "resource_name": "my-ec2-instance",
>     "region": [ "us-east-1","us-east-2", "us-west-1","us-west-2"],
>     "instance_type": [ "t2.micro", "t2.medium","t2.large"],
>     "version": "0.2"
> }
> ```

### Step 2: Start creating the Workflow

Follow the steps in the documentation to [create a Workflow](/streamline/workflows/create) and [configure its basic settings](/streamline/workflows/create#creating-a-workflow).

### Step 3: Add blocks to the Workflow

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Workflow YAML instructions**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: "[Terraform Cloud] - New EC2 Instance"
> tag: terraform-cloud-new-workspace
> description: null
> isDraft: false
> filter:
>   type: GLOBAL
> runResponseTemplate: |+
>   Your EC2 instance has been provisioned!
>
>   please use [this](https://{{ actions.get-region.outputs.result }}.console.aws.amazon.com/ec2/home?region={{ actions.get-region.outputs.result }}#InstanceDetails:instanceId={{actions.get-ec2-id.outputs.result }}) url
>
>   This has also been [added to Cortex](https://app.getcortexapp.com/admin/index?tag={{actions.slugify-resource-name.outputs.result}})  where you can perform Updates on this VM from the Workflows menu!
>
> failedRunResponseTemplate: null
> actions:
> - name: Resource Details
>   slug: resource-details
>   schema:
>     inputs:
>     - name: Resource Name
>       description: null
>       key: resource-name
>       required: true
>       defaultValue: null
>       placeholder: my-ec2-instance
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: Resource Size
>       description: null
>       key: resource-size
>       required: false
>       options:
>       - t2.micro
>       - t2.medium
>       - t2.large
>       defaultValue: t2.micro
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     - name: Resource Region
>       description: null
>       key: resource-region
>       required: false
>       options:
>       - us-east-1
>       - us-east-2
>       - us-west-1
>       - us-west-2
>       defaultValue: us-west-2
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     inputOverrides: []
>     type: USER_INPUT
>   outgoingActions:
>   - slugify-resource-name
>   isRootAction: true
> - name: Slugify Resource Name
>   slug: slugify-resource-name
>   schema:
>     expression: .actions."resource-details".outputs."resource-name" | ascii_downcase
>       | gsub(" ";"-")
>     type: JQ
>   outgoingActions:
>   - getting-github-details
>   isRootAction: false
> - name: Getting GitHub Details
>   slug: getting-github-details
>   schema:
>     expression: |-
>       {
>       "pr_name" : "PR for " + .actions."slugify-resource-name".outputs.result ,
>       "branch_name" : "branch-for-" + .actions."slugify-resource-name".outputs.result ,
>       "repo_name" : "cremerica/sample-iac-repo",
>       "path" : "modules/ec2s",
>       "commit_msg": "Commit automated by Cortex"
>       }
>     type: JQ
>   outgoingActions:
>   - scaffold-git-repo
>   isRootAction: false
> - name: Scaffold Git Repo
>   slug: scaffold-git-repo
>   schema:
>     scaffolderTemplateId: st2babdd4cc74929f2
>     createNewRepository: false
>     createService: false
>     inputOverrides:
>     - inputKey: resource_name
>       outputVariable: actions.slugify-resource-name.outputs.result
>       editable: false
>       type: VALUE
>     - inputKey: region
>       outputVariable: actions.resource-details.outputs.resource-region
>       editable: false
>       type: VALUE
>     - inputKey: instance_type
>       outputVariable: actions.resource-details.outputs.resource-size
>       editable: false
>       type: VALUE
>     - inputKey: publisherRepoName
>       outputVariable: actions.slugify-resource-name.outputs.result
>       editable: false
>       type: VALUE
>     - inputKey: publisherPullRequestTitle
>       outputVariable: actions.getting-github-details.outputs.result.pr_name
>       editable: false
>       type: VALUE
>     - inputKey: publisherBranch
>       outputVariable: actions.getting-github-details.outputs.result.branch_name
>       editable: false
>       type: VALUE
>     - inputKey: publisherRepoFullName
>       outputVariable: actions.getting-github-details.outputs.result.repo_name
>       editable: false
>       type: VALUE
>     - inputKey: publisherCommitMessage
>       outputVariable: actions.getting-github-details.outputs.result.commit_msg
>       editable: false
>       type: VALUE
>     - inputKey: project_name
>       outputVariable: actions.slugify-resource-name.outputs.result
>       editable: false
>       type: VALUE
>     - inputKey: publisherPullRequestBody
>       outputVariable: actions.getting-github-details.outputs.result.pr_name
>       editable: false
>       type: VALUE
>     type: SCAFFOLDER
>   outgoingActions:
>   - merge-a-branch
>   isRootAction: false
> - name: Merge a branch
>   slug: merge-a-branch
>   schema:
>     inputs:
>       repo: cremerica/sample-iac-repo
>       base_branch: main
>       head_branch: "{{actions.getting-github-details.outputs.result.branch_name}}"
>       commit_message: "y"
>     integrationAlias: cortex
>     actionIdentifier: github.mergeBranch
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - create-workspace
>   isRootAction: false
> - name: Create Workspace
>   slug: create-workspace
>   schema:
>     headers:
>       Content-Type: application/vnd.api+json
>       Authorization: "Bearer {{ context.secrets.tf_token }}"
>     httpMethod: POST
>     payload: "{\n   \"data\":{\n      \"type\":\"workspaces\",\n      \"attributes\"\
>       :{\n         \"auto-apply\": true,\n         \"environment\":\"default\",\n\
>       \         \"name\":\"{{actions.slugify-resource-name.outputs.result}}\",\n \
>       \        \"terraform-version\":\"1.8.5\",\n         \"working-directory\": \"\
>       modules/ec2s/{{actions.slugify-resource-name.outputs.result}}\",\n         \"\
>       resource-count\":0,\n         \"vcs-repo\":{\n            \"branch\":\"\",\n\
>       \            \"identifier\":\"cremerica/sample-iac-repo\",\n            \"display-identifier\"\
>       :\"cremerica/sample-iac-repo\",\n            \"github-app-installation-id\"\
>       :\"ghain-d3rQou9dNGew4LVx\",\n            \"repository-http-url\":\"https://github.com/cremerica/sample-iac-repo.git}\"\
>       ,\n            \"service-provider\":\"github_app\"\n         },\n         \"\
>       vcs-repo-identifier\":\"cremerica/sample-iac-repo\",\n         \"project\":{\n\
>       \            \"data\":{\n               \"id\":\"prj-nyRLtYxKHcWLggNU\",\n \
>       \              \"type\":\"projects\"\n            }\n         }\n      }\n \
>       \  } \n}"
>     url: "https://app.terraform.io/api/v2/organizations/{{context.secrets.tf_organization}}/workspaces/"
>     type: HTTP_REQUEST
>   outgoingActions:
>   - add-aws-access-key-environment-variable
>   isRootAction: false
> - name: Add AWS Access Key Environment Variable
>   slug: add-aws-access-key-environment-variable
>   schema:
>     headers:
>       Content-Type: application/vnd.api+json
>       Authorization: "Bearer {{ context.secrets.tf_token }}"
>     httpMethod: POST
>     payload: |-
>       {
>         "data": {
>           "type":"vars",
>           "attributes": {
>             "key":"AWS_ACCESS_KEY_ID",
>             "value":"{{context.secrets.aws_access_key_id}}",
>             "description":"some description",
>             "category":"terraform",
>             "hcl":false,
>             "sensitive":true
>           }
>         }
>       }
>     url: "https://app.terraform.io/api/v2/workspaces/{{ actions.create-workspace.outputs.body.data.id\
>       \ }}/vars"
>     type: HTTP_REQUEST
>   outgoingActions:
>   - add-aws-secret-key-environment-variable
>   isRootAction: false
> - name: Add AWS Secret Key Environment Variable
>   slug: add-aws-secret-key-environment-variable
>   schema:
>     headers:
>       Content-Type: application/vnd.api+json
>       Authorization: "Bearer {{ context.secrets.tf_token }}"
>     httpMethod: POST
>     payload: |-
>       {
>         "data": {
>           "type":"vars",
>           "attributes": {
>             "key":"AWS_SECRET_ACCESS_KEY",
>             "value":"{{context.secrets.aws_secret_access_key}}",
>             "description":"some description",
>             "category":"terraform",
>             "hcl":false,
>             "sensitive":true
>           }
>         }
>       }
>     url: "https://app.terraform.io/api/v2/workspaces/{{ actions.create-workspace.outputs.body.data.id\
>       \ }}/vars"
>     type: HTTP_REQUEST
>   outgoingActions:
>   - plan-and-apply
>   isRootAction: false
> - name: Plan and Apply
>   slug: plan-and-apply
>   schema:
>     headers:
>       Content-Type: application/vnd.api+json
>       Authorization: "Bearer {{context.secrets.tf_token}}"
>     httpMethod: POST
>     payload: |-
>       {
>            "data": {
>                       "attributes": {
>                                      "variables": [
>                                      { "key" : "cortex_callback", "value": "\"{{callbackUrl}}\"" },
>                                      { "key" : "cortex_token", "value": "\"{{context.secrets.workflows}}\"" }
>                                      ]
>                           },
>                        "type":"runs",
>                        "relationships": {
>                                 "workspace": {
>                                                     "data": {
>                                                            "type": "workspaces",
>                                                            "id": "{{actions.create-workspace.outputs.body.data.id }}"
>                                                       }
>                                   }
>                        }
>                 }
>       }
>     url: https://app.terraform.io/api/v2/runs
>     timeoutInSeconds: 300
>     type: HTTP_REQUEST_ASYNC
>   outgoingActions:
>   - parse-arn
>   isRootAction: false
> - name: Parse arn
>   slug: parse-arn
>   schema:
>     expression: .actions."plan-and-apply".outputs.result.output.data | split(":")
>     type: JQ
>   outgoingActions:
>   - get-ec2-id
>   isRootAction: false
> - name: Get EC2 ID
>   slug: get-ec2-id
>   schema:
>     expression: ".actions.\"parse-arn\".outputs.result[5] | split(\"/\")[1]"
>     type: JQ
>   outgoingActions:
>   - get-region
>   isRootAction: false
> - name: Get Region
>   slug: get-region
>   schema:
>     expression: ".actions.\"parse-arn\".outputs.result[3]"
>     type: JQ
>   outgoingActions:
>   - get-aws-account
>   isRootAction: false
> - name: Get AWS Account
>   slug: get-aws-account
>   schema:
>     expression: ".actions.\"parse-arn\".outputs.result[4]"
>     type: JQ
>   outgoingActions:
>   - add-entity-to-catalog
>   isRootAction: false
> - name: Add Entity to Catalog
>   slug: add-entity-to-catalog
>   schema:
>     inputs:
>       body: "openapi: 3.0.1\ninfo:\n  title: {{actions.resource-details.outputs.resource-name}}\n\
>         \  x-cortex-tag: {{actions.slugify-resource-name.outputs.result}}\n  x-cortex-type:\
>         \ AWS::EC2::Instance\n  x-cortex-infra:\n    aws:\n      cloudControl:\n \
>         \     - type: AWS::EC2::Instance\n        region: {{actions.get-region.outputs.result}}\n\
>         \        accountId: \"{{actions.get-aws-account.outputs.result }}\"\n    \
>         \    identifier: {{actions.get-ec2-id.outputs.result}}\n  x-cortex-metadata:\n\
>         \    terraform:\n      workspace-id: {{actions.create-workspace.outputs.body.data.id}}\n\
>         \  x-cortex-git:\n    github:\n      repository: {{actions.getting-github-details.outputs.result.repo_name}}\n\
>         \      basepath: modules/ec2s/{{actions.slugify-resource-name.outputs.result}}\n\
>         \  x-cortex-groups:\n  - terraform      \n      "
>       dryRun: false
>       appendArrays: false
>       failIfEntityDoesNotExist: false
>     integrationAlias: null
>     actionIdentifier: cortex.createOrPatchEntity
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - send-message
>   isRootAction: false
> - name: Send message
>   slug: send-message
>   schema:
>     channel: demos
>     message: |-
>       @{{context.initiatedBy.email}} - Your EC2 instance has been povisioned!
>
>       please use [this](https://{{ actions.get-region.outputs.result }}.console.aws.amazon.com/ec2/home?region={{ actions.get-region.outputs.result }}#InstanceDetails:instanceId={{actions.get-ec2-id.outputs.result }}) url
>
>       This has also been [added to Cortex](https://app.getcortexapp.com/admin/index?tag={{actions.slugify-resource-name.outputs.result}})  where you can perform Updates on this VM from the Workflows menu!
>     type: SLACK
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

Expand the tiles below to learn about each block in this Workflow and how to configure them in the Cortex UI:

> **User input**
>
> In this example, we add a User Input block to gather resource details from the user. For the resource size and region, the user can select from the options configured here.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **User input**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Resource details` and the slug `resource-details`.
> 3. Click **+Add user input**. Add the following:
>    * **Name**: Resource Name
>    * **Key**: resource-name
>    * **Type**: Text
>    * **Placeholder**: my-ec2-instance
>    * Click **Add input**.
> 4. Click **+Add user input**. Add the following:
>    * **Name**: Resource Size
>    * **Key**: resource-size
>    * **Type**: Select
>    * **Data source**: Manual
>    * **Placeholder**: In this example, the resource size options are t2.micro, t2.medium, and t2.large.
>    * Click **Add input**.
> 5. Click **+Add user input**. Add the following:
>    * **Name**: Resource Region
>    * **Key**: resource-region
>    * **Type**: Select
>    * **Data source**: Manual
>    * **Placeholder**: In this example, the region options are us-east-1, us-east-2, us-west-1, and us-west-2.
>    * Click **Add input**.
> 6. At the bottom of the side panel, click **Save**.

> **Data transformations**
>
> In this Workflow, we use two Data transformation blocks to reshape the data before scaffolding:
>
> Create a data transformation to lowercase the resource name:
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Slugify Resource Name` and the slug `slugify-resource-name`.
> 3. Add a jq expression to take the output of the previous action, then downcase its characters:
>
> ```jq theme={null}
> .actions."resource-details".outputs."resource-name" | ascii_downcase | gsub(" ";"-")
> ```
>
> 4. At the bottom of the side panel, click **Save**.
>
> Create a second data transformation to get GitHub details:
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    * In this example, we use the name `Getting GitHub details` and the slug `getting-github-details`.
> 3. Add a jq expression to take the output of the previous action, and use that to create a PR name and branch name:
>
> ```jq theme={null}
> {
> "pr_name" : "PR for " + .actions."slugify-resource-name".outputs.result ,
> "branch_name" : "branch-for-" + .actions."slugify-resource-name".outputs.result ,
> "repo_name" : "example/sample-iac-repo",
> "path" : "modules/ec2s",
> "commit_msg": "Commit automated by Cortex"
> }
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **Scaffolder**
>
> This block creates a new repository in your connected Git integration, using templating to apply the outputs of previous blocks to the Scaffolder configuration.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Scaffolder** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    1. In this example, we use the name `Scaffold Git Repo` and the slug `scaffold-git-repo`.
> 3. Under **Scaffolder template**, select your template. In this example, we use the `New EC2 Instance` template.
> 4. Select the option to **Create a new repo**.
> 5. Add override variables. The **Variable** dropdown pulls in all the variables that are able to be overridden in the Git provider and in the Scaffolder template. In this example, we apply the following overrides:
>    * **resource\_name**: `actions.slugify-resource-name.outputs.result`
>      * This overrides it with the output of the "Slugify resource name" block earlier in the Workflow.
>    * **region**: `actions.resource-details.outputs.resource-region`
>      * This overrides it with the output of the resource region chosen during the "Resource details" block earlier in the Workflow.
>    * **instance\_type**: `actions.resource-details.outputs.resource-size`
>      * This overrides it with the output of the resource size chosen during the "Resource details" block earlier in the Workflow.
>    * **publisherRepoName**: `actions.slugify-resource-name.outputs.result`
>      * This overrides it with the output of the "Slugify resource name" earlier in the Workflow.
>    * **publisherPullRequestTitle**: `actions.getting-github-details.outputs.result.pr_name`
>      * This overrides it with the pr\_name output from the "Getting GitHub details" block earlier in the Workflow.
>    * **publisherBranch**: `actions.getting-github-details.outputs.result.branch_name`
>      * This overrides it with the branch\_name output from the "Getting GitHub details" block earlier in the Workflow.
>    * **publisherRepoFullName**: `actions.getting-github-details.outputs.result.repo_name`
>      * This overrides it with the repo\_name output from the "Getting GitHub details" block earlier in the Workflow.
>    * **publisherCommitMessage**: `actions.getting-github-details.outputs.result.commit_msg`
>      * This overrides it with the commit\_msg output from the "Getting GitHub details" block earlier in the Workflow.
>    * **project\_name**: `actions.slugify-resource-name.outputs.result`
>      * This overrides it with the output from the "Slugify resource name" block earlier in the Workflow.
>    * **publisherPullRequestBody**: `actions.getting-github-details.outputs.result.pr_name`
>      * This overrides it with the pr\_name output from the "Getting GitHub details" block earlier in the Workflow.
> 6. At the bottom of the side panel, click **Save**.

> **GitHub merge branch**
>
> This block sets the head branch name and merges it.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **GitHub > Merge a branch** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Merge a branch` and the slug `merge-a-branch`.
> 3. Configure the block:
>    * **Repository**: Enter your repository name
>    * **Base branch**: Enter the name of the branch into which changes will be merged, e.g. `main`.
>    * **Head branch**: Enter the name of the head branch containing the changes to merge.
>      * In our example, we use the following template to pull the "branch name" output from the earlier Data transformation step whose slug is `getting-github-details`:\\
>
>        `{{actions.getting-github-details.outputs.result.branch_name}}`
>    * **Commit message**: Optionally enter a commit message.
> 4. At the bottom of the side panel, click **Save**.

> **HTTP requests**
>
> There are three HTTP requests that perform the following actions: Create a workspace in Terraform, add the AWS access key environment variable, and add the AWS secret key environment variable.
>
> **Create a workspace in Terraform**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **HTTP request** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example, we use the name `Create workspace` and the slug `create-workspace`.
> 3. Configure the block:
>    1. **HTTP method**: POST
>    2. **URL**: In our example, we set this to:\\
>
>       `https://app.terraform.io/api/v2/organizations/{{context.secrets.tf_organization}}/workspaces/`
>    3. **Headers**: Set the following headers:
>       * `Content-Type`: `application/vnd.api+json`
>       * `Authorization`: `Bearer {{ context.secrets.tf_token }}`
>    4. **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>    "data":{
>       "type":"workspaces",
>       "attributes":{
>          "auto-apply": true,
>          "environment":"default",
>          "name":"{{actions.slugify-resource-name.outputs.result}}",
>          "terraform-version":"1.8.5",
>          "working-directory": "modules/ec2s/{{actions.slugify-resource-name.outputs.result}}",
>          "resource-count":0,
>          "vcs-repo":{
>             "branch":"",
>             "identifier":"cremerica/sample-iac-repo",
>             "display-identifier":"cremerica/sample-iac-repo",
>             "github-app-installation-id":"ghain-d3rQou9dNGew4LVx",
>             "repository-http-url":"https://github.com/cremerica/sample-iac-repo.git}",
>             "service-provider":"github_app"
>          },
>          "vcs-repo-identifier":"cremerica/sample-iac-repo",
>          "project":{
>             "data":{
>                "id":"prj-nyRLtYxKHcWLggNU",
>                "type":"projects"
>             }
>          }
>       }
>    } 
> }
> ```
>
> 4. Save the block.
>
> **Add the AWS access key environment variable**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **HTTP request** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Add AWS Access Key environment variable` and the slug `add-aws-access-key-environment-variable`.
> 3. Configure the block:
>    1. **HTTP method**: POST
>    2. **URL**: In our example, we set this to:\\
>
>       `https://app.terraform.io/api/v2/workspaces/{{ actions.create-workspace.outputs.body.data.id }}/vars`
>    3. **Headers**: Set the following headers:
>       * `Content-Type`: `application/vnd.api+json`
>       * `Authorization`: `Bearer {{ context.secrets.tf_token }}`
>    4. **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>   "data": {
>     "type":"vars",
>     "attributes": {
>       "key":"AWS_ACCESS_KEY_ID",
>       "value":"{{context.secrets.aws_access_key_id}}",
>       "description":"some description",
>       "category":"terraform",
>       "hcl":false,
>       "sensitive":true
>     }
>   }
> }
> ```
>
> 4. Save the block.
>
> **Add the AWS secret key environment variable**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **HTTP request** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Add AWS Secret Key environment variable` and the slug `add-aws-secret-key-environment-variable`.
> 3. Configure the block:
>    1. **HTTP method**: POST
>    2. **URL**: In our example, we set this to:\\
>
>       `https://app.terraform.io/api/v2/workspaces/{{ actions.create-workspace.outputs.body.data.id }}/vars`
>    3. **Headers**: Set the following headers:
>       * `Content-Type`: `application/vnd.api+json`
>       * `Authorization`: `Bearer {{ context.secrets.tf_token }}`
>    4. **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>   "data": {
>     "type":"vars",
>     "attributes": {
>       "key":"AWS_SECRET_ACCESS_KEY",
>       "value":"{{context.secrets.aws_secret_access_key}}",
>       "description":"some description",
>       "category":"terraform",
>       "hcl":false,
>       "sensitive":true
>     }
>   }
> }
> ```
>
> 4. Save the block.

> **Async HTTP request**
>
> Note: If you are using PR automation such as [Atlantis](https://www.runatlantis.io/), then you do not need to include this HTTP call to Plan and Apply.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Async HTTP request** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Plan and Apply` and the slug `plan-and-apply`.
> 3. Configure the block:
>    1. **HTTP method**: POST
>    2. **URL**: In our example, we set this to:\\
>
>       `https://app.terraform.io/api/v2/runs`
>    3. **Headers**: Set the following headers:
>       * `Content-Type`: `application/vnd.api+json`
>       * `Authorization`: `Bearer {{ context.secrets.tf_token }}`
>    4. **Timeout**: 5 minutes
>    5. **Payload**: In our example, we enter the following:
>
> ```json theme={null}
> {
>      "data": {
>                 "attributes": {
>                                "variables": [
>                                { "key" : "cortex_callback", "value": "\"{{callbackUrl}}\"" },
>                                { "key" : "cortex_token", "value": "\"{{context.secrets.workflows}}\"" }
>                                ]
>                     },
>                  "type":"runs",
>                  "relationships": {
>                           "workspace": {
>                                               "data": {
>                                                      "type": "workspaces",
>                                                      "id": "{{actions.create-workspace.outputs.body.data.id }}"
>                                                 }
>                             }
>                  }
>           }
> }
> ```
>
> 4. Save the block.

> **Data transformations**
>
> This four data transformations take output from previous blocks then parse the ARN, get the EC2 ID, get the AWS region, and get the AWS account.
>
> **Parse the ARN**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Data transformation** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Parse arn` and the slug `parse-arn`.
> 3. Enter a jq expression:
>
> ```jq theme={null}
> .actions."plan-and-apply".outputs.result.output.data | split(":")
> ```
>
> 4. Save the block.
>
> **Get EC2 ID**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Data transformation** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Get EC2 ID` and the slug `get-ec2-id`.
> 3. Enter a jq expression:
>
> ```jq theme={null}
> .actions."parse-arn".outputs.result[5] | split("/")[1]
> ```
>
> 4. Save the block.
>
> **Get region**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Data transformation** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Get region` and the slug `get-region`.
> 3. Enter a jq expression:
>
> ```jq theme={null}
> .actions."parse-arn".outputs.result[3]
> ```
>
> 4. Save the block.
>
> **Get AWS account**
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Data transformation** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Get AWS account` and the slug `get-aws-account`.
> 3. Enter a jq expression:
>
> ```jq theme={null}
> .actions."parse-arn".outputs.result[4]
> ```
>
> 4. Save the block.

> **Create or patch entity**
>
> In this step, we use the output of previous blocks to create a new entity in Cortex.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Create or patch entity** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Add entity to catalog` and the slug `add-entity-to-catalog`.
> 3. Under descriptor, enter the following:
>
> ```yaml theme={null}
> openapi: 3.0.1
> info:
>   title: {{actions.resource-details.outputs.resource-name}}
>   x-cortex-tag: {{actions.slugify-resource-name.outputs.result}}
>   x-cortex-type: AWS::EC2::Instance
>   x-cortex-infra:
>     aws:
>       cloudControl:
>       - type: AWS::EC2::Instance
>         region: {{actions.get-region.outputs.result}}
>         accountId: "{{actions.get-aws-account.outputs.result }}"
>         identifier: {{actions.get-ec2-id.outputs.result}}
>   x-cortex-metadata:
>     terraform:
>       workspace-id: {{actions.create-workspace.outputs.body.data.id}}
>   x-cortex-git:
>     github:
>       repository: {{actions.getting-github-details.outputs.result.repo_name}}
>       basepath: modules/ec2s/{{actions.slugify-resource-name.outputs.result}}
>   x-cortex-groups:
>   - terraform     
> ```

> **Send Slack message**
>
> In this step, we use the output of previous steps to send a templated message via Slack informing the user that their EC2 instance has been created..
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Slack** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    * In this example we use the name `Send message` and the slug `send-message`.
> 3. Select a Slack channel name.
> 4. Enter text for the message that will be sent via Slack. In our example, we use the following:
>
> ```
> @{{context.initiatedBy.email}} - Your EC2 instance has been provisioned!
>
> please use [this](https://{{ actions.get-region.outputs.result }}.console.aws.amazon.com/ec2/home?region={{ actions.get-region.outputs.result }}#InstanceDetails:instanceId={{actions.get-ec2-id.outputs.result }}) url
>
> This has also been [added to Cortex](https://app.getcortexapp.com/admin/index?tag={{actions.slugify-resource-name.outputs.result}})  where you can perform Updates on this VM from the Workflows menu!
> ```
>
> 5. Save the block.

### Step 4: Run the Workflow

When you run the Workflow, the following events happen:

* The Workflow pauses to collect responses from the user during the User Input step.
* The Data transformation steps reshape the responses, then that reformatted data is used to create a repository during the Scaffolder step.
* A new Terraform workspace is created, and the AWS access key and secret key variables are included. The async HTTP request block triggers the planning and applying process in Terraform.
* The data is transformed, and the reformatted data is used to create an entity in Cortex.
* A message is sent in Slack to confirm that the EC2 instance has been provisioned. It includes a link to the EC2 instance and a link to the newly-created entity in Cortex:

  ![A Slack message confirms the EC2 instance is created.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/terraform-slack-example.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=d07b2cc3c38e0d632ae1bc59afb5a448)
* The entity in Cortex is connected to the repository and to the Terraform workspace.


# Update EC2 instance
Source: https://docs.cortex.io/guides/production-readiness/terraform/update



This Workflow allows you to streamline modifications to an existing EC2 instance.

## How to use a Workflow in Cortex to update an EC2 instance with Terraform

### Prerequisite

Before getting started, you should have already followed the guide to [Provision an EC2 instance with Terraform](/guides/production-readiness/terraform/provision).

### Step 1: Start creating the Workflow

Follow the steps in the documentation to [create a Workflow](/streamline/workflows/create) and [configure its basic settings](/streamline/workflows/create#creating-a-workflow).

In the Workflow's basic settings, set its scope to apply to the entity type `AWS::EC2::Instance` and the group `terraform`. The prerequisite Workflow [Provision an EC2 instance with Terraform](/guides/production-readiness/terraform/provision) automatically adds the group to the entities it creates.

### Step 2: Add blocks to the Workflow

The instructions on this page describe how to create this Workflow in the Cortex UI, but it is also possible to copy the Workflow YAML and add it to your workspace via the [Cortex CLI](https://pypi.org/project/cortexapps-cli/). This allows you to quickly set up the example configuration then iterate on it for your own use case. Expand the tile below to learn more.

> **Workflow YAML instructions**
>
> To upload the Workflow example YAML into your workspace:
>
> 1. Save the Workflow example YAML file below:
>
> ```yaml theme={null}
> name: "[Terraform Cloud] - Update EC2 instance"
> tag: update-ec2-instance
> description: null
> isDraft: true
> filter:
>   entityFilter:
>     typeFilter:
>       types:
>       - AWS::EC2::Instance
>     entityGroupFilter: null
>   ownershipScope: ALL
>   type: ENTITY
> runResponseTemplate: null
> failedRunResponseTemplate: null
> actions:
> - name: Get Descriptor
>   slug: get-descriptor
>   schema:
>     expression: .context.entity.descriptor
>     type: JQ
>   outgoingActions:
>   - get-terraform-file
>   isRootAction: true
> - name: Getting Terraform File
>   slug: get-terraform-file
>   schema:
>     inputs:
>       ref: main
>       path: "{{actions.get-descriptor.outputs.result.info.x-cortex-git.github.basepath}}/main.tf"
>       repo: "{{actions.get-descriptor.outputs.result.info.x-cortex-git.github.repository}}"
>     integrationAlias: cortex
>     actionIdentifier: github.getFile
>     type: ADVANCED_HTTP_REQUEST
>   outgoingActions:
>   - decoding-file-content
>   isRootAction: false
> - name: Decoding File Content
>   slug: decoding-file-content
>   schema:
>     expression: .actions."get-terraform-file".outputs.response.content | gsub("\n";"")
>       | @base64d
>     type: JQ
>   outgoingActions:
>   - getting-current-properties
>   isRootAction: false
> - name: Getting Current Properties
>   slug: getting-current-properties
>   schema:
>     script: |
>       var fileContent = actions['decoding-file-content'].outputs.result
>
>       var fileObject = hcl.parseToObject(fileContent)
>
>       return fileObject
>     type: JAVASCRIPT
>   outgoingActions:
>   - get-current-region
>   isRootAction: false
> - name: Get Current Region
>   slug: get-current-region
>   schema:
>     expression: ".actions.\"getting-current-properties\".outputs.result[0].provider.aws[0].region"
>     type: JQ
>   outgoingActions:
>   - get-current-instance-type
>   isRootAction: false
> - name: Get Current Instance Type
>   slug: get-current-instance-type
>   schema:
>     expression: ".actions.\"getting-current-properties\".outputs.result[0].resource.aws_instance.ubuntu[0].instance_type"
>     type: JQ
>   outgoingActions:
>   - get-current-instance-name
>   isRootAction: false
> - name: Get Current Instance Name
>   slug: get-current-instance-name
>   schema:
>     expression: ".actions.\"getting-current-properties\".outputs.result[0].resource.aws_instance.ubuntu[0].tags.Name"
>     type: JQ
>   outgoingActions:
>   - setting-github-fields
>   isRootAction: false
> - name: Setting GitHub Fields
>   slug: setting-github-fields
>   schema:
>     expression: |-
>       {
>       "pr_name" : "PR for " + .actions."get-current-instance-name".outputs.result ,
>       "branch_name" : "branch-for-" + .actions."get-current-instance-name".outputs.result ,
>       "repo_name" : "cremerica/sample-iac-repo",
>       "commit_msg": "Commit automated by Cortex"
>       }
>     type: JQ
>   outgoingActions:
>   - user-input
>   isRootAction: false
> - name: User input
>   slug: user-input
>   schema:
>     inputs:
>     - name: Current Instance Type
>       description: null
>       key: current-instance-type
>       required: false
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: Instance-Type
>       description: null
>       key: instance-type
>       required: false
>       options:
>       - t2.micro
>       - t2.medium
>       - t2.large
>       defaultValue: null
>       placeholder: ""
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     - name: Current Region
>       description: null
>       key: current-region
>       required: false
>       defaultValue: null
>       placeholder: null
>       validationRegex: null
>       type: INPUT_FIELD
>     - name: New Region
>       description: null
>       key: new-region
>       required: false
>       options:
>       - us-west-2
>       - us-west-1
>       - us-east-1
>       - us-east-2
>       defaultValue: null
>       placeholder: null
>       allowAdditionalOptions: false
>       type: SELECT_FIELD
>     inputOverrides:
>     - inputKey: current-instance-type
>       outputVariable: actions.get-current-instance-type.outputs.result
>       editable: false
>       type: VALUE
>     - inputKey: current-region
>       outputVariable: actions.get-current-region.outputs.result
>       editable: false
>       type: VALUE
>     type: USER_INPUT
>   outgoingActions:
>   - get-new-instance-type
>   isRootAction: false
> - name: Get New instance Type
>   slug: get-new-instance-type
>   schema:
>     expression: if .actions."user-input".outputs."instance-type" == null then .actions."user-input".outputs."current-instance-type"
>       else .actions."user-input".outputs."instance-type" end
>     type: JQ
>   outgoingActions:
>   - get-new-region
>   isRootAction: false
> - name: Get New Region
>   slug: get-new-region
>   schema:
>     expression: if .actions."user-input".outputs."new-region" == null then .actions."get-current-region".outputs.result
>       else  .actions."user-input".outputs."new-region" end
>     type: JQ
>   outgoingActions:
>   - scaffolder
>   isRootAction: false
> - name: 'Modify '
>   slug: scaffolder
>   schema:
>     scaffolderTemplateId: st2babdd4cc74929f2
>     createNewRepository: false
>     createService: false
>     inputOverrides:
>     - inputKey: instance_type
>       outputVariable: actions.get-new-instance-type.outputs.result
>       editable: true
>       type: VALUE
>     - inputKey: resource_name
>       outputVariable: actions.get-current-instance-name.outputs.result
>       editable: true
>       type: VALUE
>     - inputKey: project_name
>       outputVariable: actions.get-current-instance-name.outputs.result
>       editable: true
>       type: VALUE
>     - inputKey: publisherRepoFullName
>       outputVariable: actions.setting-github-fields.outputs.result.repo_name
>       editable: false
>       type: VALUE
>     - inputKey: publisherBranch
>       outputVariable: actions.setting-github-fields.outputs.result.branch_name
>       editable: true
>       type: VALUE
>     - inputKey: publisherPullRequestTitle
>       outputVariable: actions.setting-github-fields.outputs.result.pr_name
>       editable: false
>       type: VALUE
>     - inputKey: publisherPullRequestBody
>       outputVariable: actions.setting-github-fields.outputs.result.pr_name
>       editable: true
>       type: VALUE
>     - inputKey: publisherCommitMessage
>       outputVariable: actions.setting-github-fields.outputs.result.commit_msg
>       editable: false
>       type: VALUE
>     - inputKey: region
>       outputVariable: actions.get-new-region.outputs.result
>       editable: true
>       type: VALUE
>     type: SCAFFOLDER
>   outgoingActions: []
>   isRootAction: false
> runRestrictionPolicies: []
> iconTag: null
> variables: []
> ```
>
> 2. Use the [Cortex CLI](https://pypi.org/project/cortexapps-cli/) to run this command, using the path to your Workflow YAML file:\\
>
>    `cortex workflows create -f <path-to-your-workflow.yaml>`

Expand the tiles below to learn about each block in this Workflow and how to configure them in the Cortex UI:

> **Data transformation**
>
> Get the entity descriptor with a data transformation block.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get Descriptor` and the slug `get-descriptor`.
> 3. Add a jq expression to get the entity descriptor:
>
> ```jq theme={null}
> .context.entity.descriptor
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **GitHub get file**
>
> This block gets the Terraform file you want to update.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **GitHub > Get file**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Getting Terraform file` and the slug `get-terraform-file`.
> 3. For the Required parameters, configure the following:
>    * Repository: `{{actions.get-descriptor.outputs.result.info.x-cortex-git.github.repository}}`
>    * Path: `{{actions.get-descriptor.outputs.result.info.x-cortex-git.github.basepath}}/main.tf`
>    * Ref: `main`
> 4. Save the block.

> **Data transformation**
>
> Take the output from the previous block and decode its file contents.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Decoding file content` and the slug `decoding-file-content`.
> 3. Add a jq expression:
>
> ```jq theme={null}
> .actions."get-terraform-file".outputs.response.content | gsub("\n";"") | @base64d
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **JavaScript**
>
> Run a script to get the current properties from the file you got in previous steps of the Workflow.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **GitHub > Get file**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Getting current properties` and the slug `getting-current-properties`.
> 3. Add a JavaScript expression:
>
> ```javascript theme={null}
> /*#CORTEX_IGNORE*/import {_, YAML, hcl, context, actions, variables, fetch} from './utils.js'; async () => {
> var fileContent = actions['decoding-file-content'].outputs.result
>
> var fileObject = hcl.parseToObject(fileContent)
>
> return fileObject
>
> /*#CORTEX_IGNORE*/}
> ```
>
> 4. Save the block.

> **Data transformations**
>
> Add four Data transformation blocks to reformat the output from previous blocks:
>
> **Get current region**
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get current region` and the slug `get-current-region`.
> 3. Add a jq expression:
>
> ```jq theme={null}
> .actions."getting-current-properties".outputs.result[0].provider.aws[0].region
> ```
>
> 4. At the bottom of the side panel, click **Save**.
>
> **Get current instance type**
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get current instance type` and the slug `get-current-instance-type`.
> 3. Add a jq expression:
>
> ```jq theme={null}
> .actions."getting-current-properties".outputs.result[0].resource.aws_instance.ubuntu[0].instance_type
> ```
>
> 4. At the bottom of the side panel, click **Save**.
>
> **Get current instance name**
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get current instance name` and the slug `get-current-instance-name`.
> 3. Add a jq expression:
>
> ```jq theme={null}
> .actions."getting-current-properties".outputs.result[0].resource.aws_instance.ubuntu[0].tags.Name
> ```
>
> 4. At the bottom of the side panel, click **Save**.
>
> **Set GitHub fields**
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Setting GitHub fields` and the slug `setting-github-fields`.
> 3. Add a jq expression:
>
> ```jq theme={null}
> {
> "pr_name" : "PR for " + .actions."get-current-instance-name".outputs.result ,
> "branch_name" : "branch-for-" + .actions."get-current-instance-name".outputs.result ,
> "repo_name" : "cremerica/sample-iac-repo",
> "commit_msg": "Commit automated by Cortex"
> }
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **User input**
>
> In this example, we add a User Input block to gather resource details from the output of previous blocks and prompt the user to select the instance type and new region.
>
> 1. Click **+** in the center of the page. In the block library modal, choose **User input**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `User input` and the slug `user-input`.
> 3. Click **+Add user input**. Add the following:
>    * **Name**: Current instance type
>    * **Key**: current-instance-type
>    * **Type**: Text
>    * **Path to override value**: `actions.get-current-instance-type.outputs.result`
>    * Click **Add input**.
> 4. Click **+Add user input**. Add the following:
>    * **Name**: Instance type
>    * **Key**: instance-type
>    * **Type**: Select
>    * **Data source**: Manual
>    * **Placeholder**: In this example, the resource size options are t2.micro, t2.medium, and t2.large.
>    * Click **Add input**.
> 5. Click **+Add user input**. Add the following:
>    * **Name**: Current region
>    * **Key**: get-current-region
>    * **Type**: Text
>    * **Path to override value**: `actions.get-current-region.outputs.result`
>    * Click **Add input**.
> 6. Click **+Add user input**. Add the following:
>    * **Name**: New region
>    * **Key**: new-region
>    * **Type**: Select
>    * **Placeholder**: In this example, the options are us-west-2, us-west-1, us-east-1, and us-east-2.
>    * Click **Add input**.
> 7. Save the block.

> **Data transformations**
>
> Use two data transformations to format the new instance type and region that were entered during the previous step:
>
> **Get new instance type**
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get new instance type` and the slug `get-new-instance-type`.
> 3. Add a jq expression:
>
> ```jq theme={null}
> if .actions."user-input".outputs."instance-type" == null then .actions."user-input".outputs."current-instance-type" else .actions."user-input".outputs."instance-type" end
> ```
>
> 4. At the bottom of the side panel, click **Save**.
>
> **Get new region**
>
> 1. Click **+** in the center of the page. In the block library modal, choose **Data transformation**.
> 2. In the block configuration side panel, enter a name and unique slug for this block.
>    1. In this example, we use the name `Get new region` and the slug `get-new-region`.
> 3. Add a jq expression:
>
> ```jq theme={null}
> if .actions."user-input".outputs."new-region" == null then .actions."get-current-region".outputs.result else  .actions."user-input".outputs."new-region" end
> ```
>
> 4. At the bottom of the side panel, click **Save**.

> **Scaffolder**
>
> Run a Scaffolder to make modifications. In this block, you will configure override variables to pre-fill parts of the Scaffolder template based on the output of previous steps.
>
> 1. Click **+** in the center of the page. In the block library modal, select the **Scaffolder** block.
> 2. In the side panel, enter a name and unique slug for the block.
>    1. In this example, we use the name `Modify` and the slug `scaffolder`.
> 3. Under **Scaffolder template**, select your template. In this example, we use the `New EC2 Instance` template.
> 4. Select the option to **Open a pull request**.
> 5. Add override variables. The **Variable** dropdown pulls in all the variables that are able to be overridden in the Git provider and in the Scaffolder template. In this example, we apply the following overrides:
>    * **instance\_type**: `actions.get-new-instance-type.outputs.result`
>      * This overrides it with the output of the "Get new instance type" block earlier in the Workflow.
>    * **resource\_name**: `actions.get-current-instance-name.outputs.result`
>      * This overrides it with the output of the "Get current instance name" block earlier in the Workflow.
>    * **project\_name**: `actions.get-current-instance-name.outputs.result`
>      * This overrides it with the output of the "Get current instance name" block earlier in the Workflow.
>    * **publisherRepoFullName**: `actions.setting-github-fields.outputs.result.repo_name`
>      * This overrides it with the output of the "Setting GitHub fields" block earlier in the Workflow.
>    * **publisherBranch**: `actions.setting-github-fields.outputs.result.branch_name`
>      * This overrides it with the branch\_name output of the "Setting GitHub fields" block earlier in the Workflow.
>    * **publisherPullRequestTitle**: `actions.setting-github-fields.outputs.result.pr_name`
>      * This overrides it with the pr\_name output of the "Setting GitHub fields" block earlier in the Workflow.
>    * **publisherPullRequestBody**: `actions.setting-github-fields.outputs.result.pr_name`
>      * This overrides it with the pr\_name output of the "Setting GitHub fields" block earlier in the Workflow.
>    * **publisherCommitMessage**: `actions.setting-github-fields.outputs.result.commit_msg`
>      * This overrides it with the commit\_msg output of the "Setting GitHub fields" block earlier in the Workflow.
>    * **region**: `actions.get-new-region.outputs.result`
>      * This overrides it with the output of the resource region chosen during the "Get new region" block earlier in the Workflow.
> 6. Set a timeout of 5 minutes.
> 7. At the bottom of the side panel, click **Save**.

### Step 3: Run the Workflow

When you run the Workflow, the following events happen:

* The Workflow obtains the entity descriptor and gets the Terraform file.
* The Data transformation steps decode the file contents, reshape the data, then use that reformatted data to set fields in GitHub.
* The User input step collects the current instance type, new instance type, and current region.
* The data is transformed, and the reformatted data is used to apply modifications to the EC2 instance.


# Surface code coverage metrics from SonarQube in failed Scorecard rules
Source: https://docs.cortex.io/guides/security/code-coverage-rules



[CQL captures](/standardize/cql#captures) allow you to extract specific values from entity data when a rule fails, making it easier for engineers to understand what went wrong. A typical use of captures is to show key quality metrics, such as code coverage, or detailed data like vulnerabilities in Scorecard rule failure messages. This helps engineers quickly understand why a rule is failing for an entity.

## Capturing code coverage from SonarQube

You can use captures to surface quality metrics such as code coverage from third-party integrations like SonarQube.

1. Decide what data to show in the failure message. In this example, we want to display the code coverage metric reported by SonarQube.
2. While [configuring a Scorecard](/standardize/scorecards/create#step-1-configure-the-basic-scorecard-fields), add a rule using a CQL capture. Use a CQL expression to capture the code coverage metric and apply a threshold:\

   `captures("code-cov", sonarqube.metric("coverage")) > 50`
3. Customize the rule’s **Failure message** field to include the captured value. This message will appear when the rule fails (i.e., when coverage is 50% or lower):

```
This entity's code coverage metric from Sonarqube is:
{{context.evaluation.captures.code-cov}}%
```

4. After evaluation, view the Scorecard details. Navigate to the entity that failed the rule. Expand the failure message to view the captured code coverage value.

![](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/zight-2025-05-23-at-2-34-09-pm.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=cb263e83d57be56ce094c524b2d10790)


# Enforce security standards
Source: https://docs.cortex.io/guides/security/scorecard



Launching a Security Scorecard in Cortex allows you to automatically evaluate all services against defined security standards, such as. ownership, code coverage, and vulnerability scans. This ensures gaps are identified proactively rather than being discovered during incidents or audits.

To enforce security standards and promote continuous improvement:

* You can launch a Security Scorecard. Cortex provides a prebuilt Security [Scorecard](/standardize/scorecards) template that you can use to track security-related standards.
* You can [launch an Initiative](/guides/security/scorecard#create-a-security-initiative) associated with the Scorecard, which gives your engineers a deadline for when to complete certain goals.
* [Use reports and Cortex MCP](/guides/security/scorecard#measuring-success) to better understand progress and next steps.

## Create a Security Scorecard

### Prerequisites

Before using this Scorecard template:

* Ensure you have configured integrations for:
  * Version control: [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), or [GitLab](/ingesting-data-into-cortex/integrations/gitlab).
  * [Snyk](/ingesting-data-into-cortex/integrations/snyk)
    * This Scorecard uses Snyk for its vulnerability rules, but the rules can be modified to check vulnerability data from [Checkmarx](/ingesting-data-into-cortex/integrations/checkmarx), [Mend](/ingesting-data-into-cortex/integrations/mend), [Semgrep](/ingesting-data-into-cortex/integrations/semgrep), [Veracode](/ingesting-data-into-cortex/integrations/veracode), or [Wiz](/ingesting-data-into-cortex/integrations/wiz).
      * See [CQL Explorer](https://app.getcortexapp.com/admin/queries) in your Cortex workspace for example queries for these integrations.
  * [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube)
    * This Scorecard uses SonarQube for its code coverage rule, but the rule can be modified to check code coverage data from [Codecov](/ingesting-data-into-cortex/integrations/codecov).

### Step 1: Create the Scorecard and configure its basic settings

**Cortex UI**

#### Create the Scorecard in the Cortex UI

1. On the [**Scorecards** page](https://app.getcortexapp.com/admin/scorecards) in your workspace, click **Create Scorecard**.
2. On the `Security Scorecard` template, click **Use**.
3. Configure basic settings, including the Scorecard's name, unique identifier, description, and more.
   * Learn about configuring the basic settings in the [Creating a Scorecard documentation](/standardize/scorecards/create).

**GitOps or API**

When following a [GitOps approach](/configure/gitops), you can add a Scorecard YAML file to your `.cortex/scorecards` directory in your version control repository. Note that GitOps must be enabled for Scorecards in your GitOps settings.

You could also use the [Cortex API](/api/rest/scorecards), where you can submit a Scorecard definition in YAML.

Use the YAML file below to add this Scorecard to your workspace via the API or via a GitOps flow.

> **Security Scorecard YAML**
>
> ```yaml theme={null}
> tag: security-scorecard
> name: Security Scorecard
> description: |-
>   Enforce security standards across your organization, including code freshness, static analysis, and vulnerability scans.
>
>   (Created from Scorecard template)
> draft: false
> notifications:
>   enabled: true
>   scoreDropNotificationsEnabled: false
> exemptions:
>   enabled: true
>   autoApprove: false
>   userSpecificNotifications: false
> ladder:
>   name: Default Ladder
>   levels:
>   - name: Bronze
>     rank: 1
>     color: "#c38b5f"
>   - name: Silver
>     rank: 2
>     color: "#8c9298"
>   - name: Gold
>     rank: 3
>     color: "#cda400"
> rules:
> - title: SonarQube analysis uploaded within the last 7 days
>   expression: sonarqube.freshness() < duration("P7D")
>   identifier: 0abbfeac-eda7-3a60-a8a3-eaf4d8fb99f5
>   weight: 1
>   level: Silver
>   failureMessage: "Make sure SonarQube is properly set up by following the instruction\
>     \ in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/sonarqube)."
> - title: Default branch is protected
>   expression: git.branchProtection() != null
>   identifier: 21c30af3-6dd6-3bce-bbe5-56e43549015f
>   weight: 1
>   level: Silver
>   failureMessage: "This rule is only supported for GitLab and GitHub. If you don't\
>     \ have a repository specified, you can add one by following the instructions in\
>     \ our docs for [GitHub](https://docs.cortex.io/ingesting-data-into-cortex/integrations/github)\
>     \ or [GitLab](https://docs.cortex.io/ingesting-data-into-cortex/integrations/gitlab),\
>     \ depending on the tool that your team uses."
> - title: Has owners
>   expression: ownership.allOwners().length > 0
>   identifier: 92ab2234-ffb1-371b-9488-8ebe3485e503
>   weight: 1
>   level: Bronze
>   failureMessage: "Add an owner by following the instructions in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership)."
> - title: At least one required approval to merge
>   expression: git.numOfRequiredApprovals() > 0
>   identifier: a148260a-81c3-3201-9692-de99fd08ed16
>   weight: 1
>   level: Silver
>   failureMessage: "This rule is only supported for GitLab and GitHub. If you don't\
>     \ have a repository specified, you can add one by following the instructions in\
>     \ our docs for [GitHub](https://docs.cortex.io/ingesting-data-into-cortex/integrations/github)\
>     \ or [GitLab](https://docs.cortex.io/ingesting-data-into-cortex/integrations/gitlab),\
>     \ depending on the tool that your team uses."
> - title: Has a low number of Snyk issues
>   expression: snyk.issues().length < 5
>   identifier: afb081c6-b875-32af-a5fb-6be8073cd6b4
>   weight: 1
>   level: Gold
>   failureMessage: "Make sure Snyk is properly set up by following the instructions\
>     \ in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/snyk)."
> - title: Less than 5 SonarQube vulnerabilities
>   expression: sonarqube.metric("vulnerabilities") < 5
>   identifier: b4e82b64-65b6-3d91-af4f-2fca115e17ad
>   weight: 1
>   level: Gold
>   failureMessage: "Make sure SonarQube is properly set up by following the instruction\
>     \ in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/sonarqube)."
> - title: Code coverage is above 80%
>   expression: sonarqube.metric("coverage") > 80
>   identifier: c286f089-c344-3467-a2e2-cec9ab53871f
>   weight: 1
>   level: Silver
>   failureMessage: "Make sure SonarQube is properly set up by following the instruction\
>     \ in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/sonarqube)."
> - title: Less than 5 SonarQube security hotspots
>   expression: sonarqube.metric("security_hotspots") < 5
>   identifier: d93bbdb9-5a4b-387f-9722-a6bd2f42d2a9
>   weight: 1
>   level: Gold
>   failureMessage: "Make sure SonarQube is properly set up by following the instruction\
>     \ in [our docs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/sonarqube)."
> - title: Code last updated in the last week
>   expression: git.lastCommit().freshness < duration("P7D")
>   identifier: e76714ba-1a0e-31f9-ba34-930146da413f
>   weight: 1
>   level: Bronze
>   failureMessage: "You can add a git repository by following the instructions in our\
>     \ docs for [version control integrations](https://docs.cortex.io/ingesting-data-into-cortex/integrations#version-control),\
>     \ depending on the tool that your team uses."
> - title: Has Snyk project
>   expression: snyk != null
>   identifier: eef8b87a-6326-3418-bab7-2608059aafd4
>   weight: 2
>   level: Bronze
>   failureMessage: "You can add a Snyk project by following the instructions in [our\
>     \ docs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/snyk)."
> filter:
>   kind: GENERIC
>   types:
>     include:
>     - service
> ```

### Step 2: Review and modify rules

Cortex's templated rules are based on common industry standards:

> **Security: Bronze level rules**
>
> * Has owners\\
>
>   `ownership.allOwners().length > 0`
> * Code updated in the last week\\
>
>   `git.lastCommit().freshness < duration("P7D")`
> * Has Snyk project\\
>
>   `snyk != null`

> **Security: Silver level rules**
>
> * SonarQube analysis uploaded within last 7 days\\
>
>   `sonarqube.freshness() < duration("P7D")`
> * Default branch is protected\\
>
>   `git.branchProtection() != null`
> * At least one required approval to merge\\
>
>   `git.numOfRequiredApprovals() > 0`
> * Code coverage is above 80%\\
>
>   `sonarqube.metric("coverage") > 80`

> **Security: Gold level rules**
>
> * Low number of Snyk issues\\
>
>   `snyk.issues().length < 5`
> * Less than 5 SonarQube vulnerabilities\\
>
>   `sonarqube.metric("vulnerabilities") < 5`
> * Less than 5 SonarQube security hotspots\\
>
>   `sonarqube.metric("security_hotspots") < 5`

You can reorder, delete, and edit rules, add more rules to a level, and assign more points to a rule to signify its importance. Behind each rule is a [Cortex Query Language (CQL) ](/standardize/cql)query; you can edit the existing CQL or write your own queries to further refine your rules.

## Create a Security Initiative

Follow the steps below to create an Initiative:

> **Create a Security Initiative**
>
> To motivate change by a certain deadline, you can create an Initiative:
>
> 1. While viewing your Security Scorecard, click **Create Initiative** in the upper right.
> 2. Configure the Initiative fields, including a descriptive name so your team members understand the purpose of the Initiative. For example, `Ensure default branch is protected by end of quarter`.
>    * Make sure to enable notifications so users are notified if an entity they own is failing the Initiative's goal.
> 3. Save the Initiative.
>
> After the Initiative is published, entity owners will be notified if their entity is not meeting the goal.
>
> Learn more about [creating Initiatives in the docs](/improve/initiatives).

## Measuring success

To understand progress of your Scorecard:

* Ask [Cortex MCP,](/get-started/cortex-ai-assistant/mcp) "How is my Security Scorecard doing?" The MCP will respond with information on the entities that are failing rules and suggested next steps.
* Review reports: The [Bird's Eye report](/improve/reports/birds-eye) gives insight into how entities are performing against the Scorecard by visualizing the data as a heat map:\


  ![The Birds eye report shows scorecard progress as a heatmap.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/guides/images/security-birds-eye.jpg?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=a251a4e6cd14502a18f5768261564a39)

You can also review your Engineering Intelligence metrics for impact on key engineering metrics, such as:

* **Deployment frequency**: With best practices in place, such as requiring branch protection, you may see a reduction in rework and less failed builds.
* **Incident frequency**: You may see less incidents overall with the implementation of rules such as requiring 80% code coverage and proactively ensuring a low number of vulnerabilities.


# Surface vulnerability data in failed Scorecard rules
Source: https://docs.cortex.io/guides/security/vulnerabilities-rules



[CQL captures](/standardize/cql#captures) allow you to extract specific values from entity data when a rule fails, making it easier for engineers to understand what went wrong. A typical use of captures is to show key quality metrics, such as code coverage, or detailed data like vulnerabilities in Scorecard rule failure messages. This helps engineers quickly understand why a rule is failing for an entity.

### Surface security vulnerability information from custom data [#example-2-surface-security-vulnerability-information-from-custom-data](#example-2-surface-security-vulnerability-information-from-custom-data)

You can [configure custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data) to track any information you want to surface, or you can choose to track information pulled in from third-party integrations.

1. Determine what vulnerability data to display.

   * In this case, custom data is configured to include details like alert name, score, severity, and detection date.

   Example custom data under key `security-data`:

```
"alerts": [
      {
        "vulnName": "CV-2844",
        "alertName": "CVA-2844",
        "vulnScore": 5.2,
        "alertStatus": "ACTIVE",
        "productName": "AssetManager",
        "vulnSeverity": "MEDIUM",
        "alertDetected": "2025-05-08T10:49:07Z"
      }
    ]
```

2. ​[While configuring](/standardize/scorecards/create#step-1-configure-the-basic-scorecard-fields) a Scorecard, add a rule that uses captures to pull in the data you want to make more visible: `captures("security", custom('security-data')).get("alerts").length == 0`
3. In the rule's **Failure message** field, configure captures to pull in the relevant information. The following example captures vulnerability information from the custom security data into a table:

```
# Your entity is failing because of an unresolved vulnerability

## Table of data

| Product Name | Alert Name | Score | Severity | Date Detected |
| :---: | :---: | :---: | :---: | :---: |
{{#context.evaluation.captures.security.alerts}}
| {{productName}} | {{alertName}} | {{vulnScore}} | {{vulnSeverity}} | {{alertDetected}} |
{{/context.evaluation.captures.security.alerts}}
```

4. After evaluation, inspect the failing rule in the Scorecard. Click into the affected entity and expand the rule to see the vulnerability details in a structured format.


# Custom metrics
Source: https://docs.cortex.io/improve/eng-intelligence/custom-metrics



Engineering teams generate data everywhere—incidents resolved, coverage trends, deployment cadence, SLO drift—but most of it lives outside the tools that drive decisions. Custom metrics let you bring that data into Cortex, so the same analytics infrastructure you use for built-in engineering data can work with the metrics that matter most to your organization.

Whether you're pulling from an internal system, a tool Cortex doesn't natively integrate with, or computing derived values from existing integration data, custom metrics give you a consistent way to track, visualize, and act on that data. They surface in Data Explorer, on entity pages, and in Scorecards.

After defining a custom metric, data can be provided via the following methods:

* **API** - Post custom metric data to Cortex via [the API](/api/rest/custom-metrics).
* **CQL** - Compute data based on a CQL query that is evaluated by Cortex every 12 hours.

## Use cases

Custom metrics are useful any time you have engineering data that lives outside Cortex's built-in integrations, or when you want to derive new meaning from data that's already there. Examples include:

* **Incident data from ServiceNow or other ITSM tools.** Track open incident counts, MTTR, or severity trends per service. Example CQL: `custom("servicenow-incidents").length`
* **Custom-computed SLO metrics.** If your SLO calculations live in an internal system or don't map cleanly to a native integration, push the computed values directly via API so they're visible alongside the rest of your engineering health data.
* **Metrics from homegrown tooling.** Internal platforms, custom CI pipelines, or proprietary monitoring tools can all post metric data to Cortex via API, making them first-class citizens in Eng Intelligence.
* **Derived metrics from existing integrations.** Combine or reframe data from tools Cortex already connects to, e.g. code coverage from Codecov (`codecov.codeCoverage()`) or quality metrics from SonarQube (`sonarqube.metric("coverage")`).

> [!NOTE]
>
> When adding static or slowly changing metadata to entities, consider adding custom data instead of custom metrics. [Learn the differences](/ingesting-data-into-cortex/entities-overview/entities/custom-data#custom-data-vs.-custom-metrics)

## Creating a custom metric and adding data

### Prerequisites

Users with the following permissions can configure custom metrics:

* `Configure Eng Intelligence Custom Metrics` - Allows for creation, editing, and deletion a custom metric definition. Editable fields include name, filter, and CQL expression. This permission also includes the ability to publish the custom metric.
* `Manage Eng Intelligence Custom Metric data` - Only required to manage custom metrics via the API. Grants access to the public API for adding and deleting data points on an API custom metric.

### Creating a custom metric via CQL

Follow the steps below to create a custom metric using CQL.

> [!NOTE]
>
> Cortex evaluates CQL expressions every 12 hours to check for new metric data.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then expand **Eng Intelligence**.
4. Click **Custom metrics**.\


   ![Custom metrics option in the Settings sidebar.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-metrics-tab.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=4a541f03d24344ae24c6d8fd78a5a73d)
5. In the upper-right corner, click **Add metric**.
6. In the **Custom metrics** side panel, select the **CQL** radio button.
7. Under **Name**, enter a name for the custom metric, e.g. `pager-volume-7d` (required).
8. Optionally, change the key. The key auto-populates based on the custom metric name and is made up of letters, digits, and hyphens.
9. Under **Description**, enter a description of the custom metric.
10. From the **Category** drop-down menu, assign the custom metric a category. This controls where the metric can be found for selection in Data Explorer.
11. Under **Trend color indicator**, set an indicator to match whether higher is better or worse. This controls the color-coding of trends in Data Explorer.
12. Under CQL query, click **Add CQL query**. In the side panel, add a CQL expression to evaluate every 12 hours. The result of the expression must be a number, otherwise validation fails. Click **Save query**. See [Cortex Query Language (CQL)](/standardize/cql) for more information.
13. From the **Entity types** drop-down menu, choose whether to include or exclude specific entity types.
14. Toggle off **Draft** when you’re ready to publish. By default, the custom metric is in draft state and only visible to users with the permission to configure custom metrics. Toggle this setting off to immediately enable the metric within All Metrics and Data Explorer.
15. Click **Add metric**.

> [!NOTE]
>
> The data retention period for custom metric data is 24 months.

> [!NOTE]
>
> Results are not displayed until the end of the previous day.

### Creating a custom metric via API

Follow the steps below to create a custom metric using the API.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then expand **Eng Intelligence**.
4. Click **Custom metrics**.\


   ![Custom metrics option in the Settings sidebar.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-metrics-tab.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=4a541f03d24344ae24c6d8fd78a5a73d)
5. In the upper-right corner, click **Add metric**.
6. In the **Custom metrics** side panel, select the **API** radio button.
7. Under **Name**, enter a name for the custom metric, e.g. `pager-volume-7d` (required).
8. Optionally, change the key. The key auto-populates based on the custom metric name and is made up of letters, digits, and hyphens.
9. Under **Description**, enter a description of the custom metric.
10. From the **Category** drop-down menu, assign the custom metric a category. This controls where the metric can be found for selection in Data Explorer.
11. Under **Trend color indicator**, set an indicator to match whether higher is better or worse. This controls the color-coding of trends in Data Explorer.
12. Toggle off **Draft** when you’re ready to publish. By default, the custom metric is in draft state and only visible to users with the permission to configure custom metrics. Toggle this setting off to immediately enable the metric within All Metrics and Data Explorer.
13. Click **Add metric**.

You can also define an API custom metric without the UI. Use [Create a custom metric definition](/api/rest/custom-metrics/create-a-custom-metric-definition) in the Cortex API. The API can also list, update, and delete API custom metric definitions, so you can copy definitions between workspaces or manage them as code. CQL custom metrics are read-only through the API.

After defining the metric, you can post data to it via the [Cortex API](/api/rest/custom-metrics). Data points default to the current date and time, but results won't appear until the end of the previous day.

For information on adding metric data in bulk via the API, refer to [the documentation](/api/rest/custom-metrics). Note that bulk creation of metric data via the API is subject to rate limits and cardinality limits.

> [!NOTE]
>
> The API supports backfilling custom metric data up to two (2) years.

## Editing a custom metric

When editing a custom metric, note that the `key` and `type` cannot be changed. To update either, archive the existing metric and recreate it with a new key. All other fields can be edited at any time.

Note that editing a CQL custom metric definition makes its historical values inaccessible.

**To edit a custom metric**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then expand **Eng Intelligence**.
4. Click **Custom metrics**.\


   ![Custom metrics option in the Settings sidebar.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-metrics-tab.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=4a541f03d24344ae24c6d8fd78a5a73d)
5. Locate the metric you want to edit, then click the **pencil icon** next to it.\


   ![The pencil icon next to a custom metric.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-metrics-pencil-icon.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=6f1522970386585da18ec35df4cfca7c)
6. Make any necessary changes, then click **Save metric**.

## Viewing custom metric data

Custom metric data is available in the following areas of Cortex:

* Data Explorer
* Entity details page
* All Metrics (Legacy View)

#### Viewing custom metric data in Data Explorer

From the main sidebar, expand **Eng Intelligence**, then select **Data Explorer**. Custom metrics appear in a list alongside other Eng Intelligence metrics.

#### Viewing custom metric data on an entity's details page

From an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details), click **Custom metrics** in the sidebar to view that entity's metrics.

![Custom metrics option in the entity details sidebar.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-metric-entity-details.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=47e95d40c85dc975fb9908d957d43af4)

#### Viewing custom metric data in All Metrics (Legacy View)

From the main sidebar, expand **Eng Intelligence**, then select **All Metrics**. Custom metrics appear in a list alongside other Eng Intelligence metrics.

![Custom metrics displayed via the All Metrics tab.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-metrics-all-metrics.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=dbfba2b1f1793659be5f84b3af3ad558)

> [!NOTE]
>
> [Customize your view](/improve/eng-intelligence/eng-intelligence#all-metrics-settings) by reordering or hiding the columns.

## Querying custom metric data with CQL

Once a custom metric has data, you can query that data in CQL to build Scorecard rules and reports. The `customMetrics()` function takes the metric's key and a lookback window:

`customMetrics(key="error-rate", lookback=duration("P30D"))`

### Aggregating custom metric data

`customMetrics()` returns a list of data points, not a list of numbers. Each data point is a record with two fields:

* `value` - The numeric value recorded for the data point.
* `timestamp` - The date the data point was recorded.

Aggregation functions like `average()` and `sum()` only work on a list of numbers or a list of durations, so you can't apply them to the result of `customMetrics()` directly. Use `map()` to pull the field you want into its own list first, then aggregate:

```
customMetrics(key="error-rate", lookback=duration("P30D")).map((m) => m.value).average()
```

Without `map()`, the query returns the error "Could not apply average to non-numeric and non-duration element":

```
customMetrics(key="error-rate", lookback=duration("P30D")).average()
```

> [!WARNING]
>
> If a metric has no data points in the lookback window, `average()` returns the error "Cannot take average of empty list." Choose a lookback window long enough to always include at least one data point.


# Dashboards
Source: https://docs.cortex.io/improve/eng-intelligence/dashboards



Eng Intelligence dashboards give engineering leaders and teams real-time visibility into the metrics that matter most—delivery performance, team velocity, incident trends, and AI tool adoption. Each dashboard pulls directly from your Cortex catalog, so the data is always grounded in your actual services and teams. And because dashboards are natively integrated with Scorecards and Initiatives, you can move from spotting a problem to driving action without leaving Cortex.

Whether you're a leader looking for an org-wide view or a team lead investigating a slowdown in your release process, dashboards give you the right level of detail to understand what's happening and why.

See the documentation linked below to learn more about each dashboard:

* [DORA Dashboard](/improve/eng-intelligence/dora-dashboard) - Visualize the four key DORA metrics (cycle time, deployment frequency, change failure rate, and MTTR) to understand how fast, reliable, and efficient your engineering organization is over time.
* [Velocity Dashboard](/improve/eng-intelligence/velocity-dashboard) - Monitor version control metrics such as PR cycle time, PR size, and PR success rate to identify bottlenecks in your development process and track improvement over time.
* [AI impact for GitHub Copilot](/improve/eng-intelligence/dashboards/ai-impact) - Track Copilot adoption and engagement across your engineering teams. See how adoption rates correlate with delivery and reliability metrics at the team level, compare performance between Copilot users and non-users over the last seven (7) days, and monitor org-wide adoption trends over time.
* [Custom Dashboards](/improve/eng-intelligence/dashboards/custom) - Build tailored views by combining any combination of Eng Intelligence metrics into a single, shareable dashboard that's useful for team-specific reviews, executive reporting, or tracking progress on a specific initiative.


# AI impact dashboard for GitHub Copilot
Source: https://docs.cortex.io/improve/eng-intelligence/dashboards/ai-impact



PUBLIC BETA

> [!NOTE]
>
> The AI Impact Dashboard for Copilot is available to all cloud customers as a Public Beta feature. You can provide us [feedback here](https://forms.gle/wW86fGy8Cq2weVte7).

The AI Impact Dashboard provides insight into Copilot adoption and engagement across your engineering teams, including visualizations for:

* Impact by team AI adoption rate
  * Correlate team adoption rate to delivery and reliability metrics. Adoption rates are provided daily by comparing active users against Copilot seats.
* Impact of Copilot users vs. non-Copilot users
  * Compare delivery and reliability side-by-side between users who leveraged AI tools within the last 7 days, and those who did not. Understand whether recent AI usage affects engineering performance.
* AI adoption trends
  * View the overall trends for AI adoption across your organization.

Use these insights to identify issues and [drive continuous improvement](/improve/eng-intelligence/dashboards/ai-impact#driving-continuous-improvement).

![One of the AI Impact charts shows merged PR metrics for AI users vs. non-AI users.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/ai-users-mergedPRs-copilot.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=fbc2df3a789a706b0c55ad0b864c8fcc)

## Using the AI Impact Dashboard

### Prerequisites

Before getting started:

* You must have [GitHub integration](/ingesting-data-into-cortex/integrations/github) configured. See instructions below for each integration method:
  * Cortex GitHub app
    * If configured before October 14, 2025, you must [re-authorize your Cortex GitHub app](https://support.getcortexapp.com/hc/en-us/articles/41736643663387-Why-is-Cortex-requesting-that-I-re-authorize-the-GitHub-app-for-Copilot-metric-permissions) to accept two new permissions.
  * Custom GitHub App
    * Add the following permission to your custom GitHub App: `admin:org read`
  * Personal Access Token
    * Add the following permission to your PAT: `admin:org read`
* In Cortex, you must have the `View Eng Intelligence` permission to view the dashboard, and you must have the `Configure Eng Intelligence` permission to configure it.

### View the Dashboard

Navigate to [**Eng Intelligence > Dashboards**](https://app.getcortexapp.com/admin/eng-intelligence/dashboards) to see the full list of Cortex-built and [Custom Dashboards](/improve/eng-intelligence/dashboards/custom) available in your workspace. Click the **Copilot Dashboard**.

This Dashboard contains multiple charts that you can filter and compare with key engineering metrics:

> **Impact by team AI adoption rate**
>
> View the impact that a team's AI adoption rate has on their cycle time, deployment frequency, incident frequency, merged PRs, PR size, time to resolution, and work items completed.
>
> Hover over the data in the graph to see more information about a team and its metrics:
>
> ![Hover over the Team AI adoption rate chart to learn more about a metric point.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/team-ai-adoption-chart.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=cfbf0764f5a4e60c25b0296fb151b582)
>
> Eng Intelligence compares active users against Copilot seats once daily.

> **Copilot users vs. Non-Copilot users**
>
> See the impact that using AI, or not using AI, has on cycle time, merged PRs, PR size, time to resolution, and work items completed. Cortex automatically creates an "AI Usage" user label that is attached to any team member who was active in Copilot within the last 7 days.
>
> Hover over the data in the graph to see more information about the metrics:
>
> ![Hover over the chart to learn more about a metric point.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/ai-user-impact-chart.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=525e30e163492ddad040f15d6eeba807)

> **Copilot adoption over time**
>
> View your overall Copilot adoption metrics over time:
>
> ![See Copilot adoption metrics in the graph.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/copilot-adoption-graph.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=1d50405c74980c602bb2b29781aeeb35)

### Filter and configure the Dashboard

#### Overlay a data point

To overlay a data point, click the dropdown in the upper left corner of a chart:

![Click the dropdown in the upper left to choose a data point.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/select-metric-ai-charts.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=3acb605872536a793b4b36ffe0d07f21)

#### Filter the chart

You can filter at two levels:

* **Dashboard level** - Click **Filter** at the top of the dashboard to apply a filter across all charts at once. The Copilot dashboard supports **Domain** and **Team** as dashboard-level filters.
* **Chart level** - Click **Filter** in the upper-right corner of an individual chart to apply filters for group, owner, repository, user label, and more. Chart-level filters override dashboard-level filters for that chart.

## Driving continuous improvement

Use the AI Impact Dashboard to track and correlate key AI adoption metrics with engineering performance metrics. These insights allow you to identify issues in your processes, which enables the ability to take action and drive improvements.

**Example scenario**: You view your dashboard and notice that teams who have higher rates of AI adoption have a lower average cycle time (the time it takes for a single PR to go through the entire coding process). However, you also see a spike in incident frequency for those teams.

* **Identify the issue**: You conclude that their process is more efficient, but as a tradeoff, they're shipping code that causes more incidents. You brainstorm with the affected engineering teams to learn how their processes have changed since adopting AI. You learn that SonarQube code coverage is lower than it has been previously.
* **Take action**: You already have an [AI Readiness Scorecard](/solutions/ai-readiness/configure#step-2-configure-scorecards-to-track-ai-readiness-standards) launched, and you see that the rule "Test coverage minimum met" is failing. You can create an [Initiative](/standardize/scorecards/create#create-initiative-from-scorecard) on that Scorecard to ask developers to meet a particular rule by a specified deadline. In this case, you create an Initiative that asks the developers to pass the failing rule (i.e., they need to ensure higher than 80% test coverage) by the end of the month.
  * Initiatives and Scorecard tasks appear as to-do items on a developer's [homepage](/streamline/homepage) in Cortex.
* **Review the dashboard**: As developers work toward meeting the requirements, check back in on the dashboard for a real-time update into their progress.


# Custom dashboards
Source: https://docs.cortex.io/improve/eng-intelligence/dashboards/custom

Combine metrics from multiple sources into a unified view

> [!NOTE]
>
> Custom Dashboards is available to all customers as a Public Beta feature. You can provide us [feedback here](https://forms.gle/xazu6auWuMGqMKRt7).

Custom dashboards let you build shared views of the engineering metrics that matter most to your organization. Combine saved modules from across your data sources into a single, focused view, then share it with your team so everyone is working from the same picture.

Use custom dashboards to:

* **Aggregate metrics across sources** - Pull together modules from version control, deployments, incidents, project management, and more into one dashboard.
* **Tailor views by team or use case** - Build dashboards scoped to specific teams, workflows, or engineering goals, e.g. an OpEx review, a DORA deep-dive, a sprint health check.
* **Share insights across your org** - Dashboards are visible to anyone with the `View Eng Intelligence` permission, so stakeholders get the context they need without manual reporting.
* **Surface trends and drive action** - Spot bottlenecks, track progress toward goals, and make data-driven decisions from a single view.

**Example dashboards**

| Dashboard | What it tracks |
| - | - |
| **Team health** | PR cycle time, deployment frequency, and incident rate for a specific engineering team |
| **Delivery health** | Story points completed, PR throughput, and deploy frequency across a quarter  |
| **Incident response** | MTTR, incident frequency, change failure rate, and deployment volume |
| **OpEx review** | DORA metrics, on-call load, and SLA compliance for leadership reviews |
| **Platform reliability** | Change failure rate, rollback frequency, and time to resolution by service |
| **Sprint overview** | Work items completed, cycle time, and PR review turnaround for a given sprint |

## Creating a custom dashboard

### Prerequisites

1. You must have the `Configure Eng Intelligence` permission.
2. Make sure you have configured metric modules and saved them in Data Explorer.

**To create a custom dashboard**:

1. From the main sidebar, expand **Eng Intelligence**, then click **Dashboards**.
2. In the upper-right corner, click **Create Dashboard**.
3. In the Create dashboard side panel, do the following:
   1. Under **Dashboard name**, enter a name for the dashboard (required).
   2. Under **Description**, enter an overview of the dashboard.
   3. Under **Display icon**, select an icon to represent the dashboard.
   4. Click **Create dashboard**. The **Saved modules** side panel opens.
4. From the **Saved modules** side panel, select an existing metric module to add to your dashboard. After selecting a module, you're directed to the dashboard.
   * To create a new module, click **Create module** to open the Data Explorer, configure your metric, and save it as a module. Then navigate back to Dashboards to add it to your dashboard.
5. To add more modules, click **Add module**. Repeat as necessary.\


   ![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-dashboard-add.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=984c956cc29634ded23a6a2b84de3163)
6. To remove a module, click its **Remove icon**.

> [!TIP]
>
> You can add as many modules to a custom dashboard as you need.


# Managing custom dashboards
Source: https://docs.cortex.io/improve/eng-intelligence/dashboards/custom/managing-custom-dashboards



This article covers sharing, editing, and filtering custom dashboards. See [Custom dashboards](/improve/eng-intelligence/dashboards/custom/managing-custom-dashboards) for instructions on creating a dashboard.

## Sharing a custom dashboard

Dashboards are automatically visible within your organization to users with the `View Eng Intelligence` permission, so everyone can view the same insights and stay aligned.

**To create a share link to send to another user**:

1. From the main sidebar, expand **Eng Intelligence**, then click **Dashboards**.
2. Select the dashboard you want to share.
3. In the upper-right corner, click the **Overflow menu** icon.
4. Select **Share**.\


   ![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-dashboard-share.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=f84143d336b8f8a61c9353b91c5c15b8)

## Editing a custom dashboard

1. From the main sidebar, expand **Eng Intelligence**, then click **Dashboards**.
2. Select the dashboard you want to edit.
3. In the upper-right corner, click the **Edit**.
4. Make any necessary changes including removing and adding modules. See [Creating a custom dashboard](/improve/eng-intelligence/dashboards/custom/managing-custom-dashboards#creating-a-custom-dashboard) for more information.
5. Click **Save**.

## **Using dashboard-level filters**

Dashboard-level filters let you apply a consistent scope across all modules in a dashboard at once. Instead of setting the same team, date range, or domain filter on every module individually, you set it once at the top and it propagates to all applicable modules automatically.

### **In edit mode**

To add a dashboard-level filter, click **Add filter** at the top of the dashboard while in edit mode. Select one or more filters from the global filter list; your selections are saved as part of the dashboard definition.

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202026-06-24%20at%2002.21.53%20PM.png)

When you add a dashboard-level filter, Cortex will display a message confirming that it will override the same filter if it's also set on an individual module.

**Date filter defaults:**

* Dashboards created after this feature launched automatically include a date filter. You can remove it.
* Dashboards created before this feature launched do not have a date filter automatically applied.

### **In view mode**

Dashboard-level filters appear at the top of the dashboard. Setting a filter there applies it immediately to all modules that support it. If a filter isn't applicable to a module (for example, applying a Domain filter to an AI Adoption rate module), that module is unaffected.

You can still override a filter for an individual module as module-level filters take precedence over dashboard-level filters for that module.

If a dashboard-level date filter is set, individual module date filters are hidden. If no dashboard-level date filter is defined, module-level date filters remain visible.


# Data Explorer
Source: https://docs.cortex.io/improve/eng-intelligence/data-explorer

Formerly 'Metrics Explorer

Data Explorer is your window into the metrics that matter. Analyze trends over time, drill into individual data points, and uncover the patterns shaping your development process. Whether you're diagnosing a slowdown or looking for opportunities to improve, Data Explorer gives you the visibility to act with confidence.

Found a view you'll want to revisit? Save it as a **module** and skip the work of reapplying filters and display settings every time. Report modules make it effortless to keep an eye on the metrics you care about—like cycle time for a specific team or time period—and they double as building blocks for [custom dashboards](/improve/eng-intelligence/dashboards/custom), so the insights you've curated can power views across your organization.

## Using Data Explorer

### Step 1: Selecting a metric to view

Users with the `View Dev Metrics` permission can select a metric to view.

The Data Explorer provides three view options, allowing you to choose the format that best fits your analysis:

* **Chart** - A standard line chart designed for visualizing a single metric over time. Use this view when you want to track trends or fluctuations in one specific measurement.
* **Table** - A tabular layout that displays multiple metrics at once, including Scorecard scores, making it ideal for side-by-side comparisons and detailed analysis. The tabular view also supports a hierarchical, nested structure similar to the [Bird's Eye](/improve/reports/birds-eye) report for drilling into grouped data.
* **KPI** - A compact widget that shows a single metric with its current value, a trend comparison (directional arrow, percentage/absolute change), and an optional mini chart. This gives engineering leaders an at-a-glance, standardized way to highlight a key metric.

#### **Configuring chart view**

1. From the main sidebar, expand **Eng Intelligence**, then select **Data Explorer**.
2. In the right pane, select **Chart**.\


   ![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-chart.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=55c088544a40310d3d5db542be030ccb)
3. By default, the **cycle time** metric is displayed. To select a different metric, click the tab below **Data** in the right pane. The **Metrics** window opens.\


   ![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-default-metric.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=5a3e4663ee0f0e0de372a82bfe6d225f)
4. Select a metric to view.
   * Cortex organizes metrics into six categories: Custom, Deployment, Incident, Project management, Version control, and AI tools, each with its own set of available metrics. Refer to [Available metrics in Data Explorer](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer) for definitions.
5. Click **View metric**. The chart updates, reflecting the new metric.
   * By default, the data uses a time range of the last 30 days, but you can [select a different time range](/improve/eng-intelligence/data-explorer#filtering-by-time-range). Metrics can be [grouped by](/improve/eng-intelligence/data-explorer#grouping-metrics-chart-and-table-views) team, owner, repository, entity, and more.
6. Optionally, toggle off **Show table** in the right pane to hide the metric overview below the graph.

#### Configuring table view

1. From the main sidebar, expand **Eng Intelligence**, then select **Data Explorer**.
2. In the right pane, select **Table**.\


   ![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/de-table.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=7edd80d7a80274f915f5c5391d112cad)
3. In the right pane, click **Add column**. The **Metrics** window opens.
4. Select a metric to view.
   * Cortex organizes metrics into six categories: Custom, Deployment, Incident, Project management, Version control, and AI tools, each with its own set of available metrics. Refer to [Available metrics in Data Explorer](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer) for definitions.
   * Table view also supports three entity data categories: Custom data, Entity definition, and Entity metadata. Use these to bring entity attributes into the table alongside your metrics. Refer to [Entity data in table view](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer#entity-data-in-table-view) for definitions.
   * Table view also supports Scorecards as a metric. Select a Scorecard, then choose **Score %** or **Level** to add the result as a column alongside your metrics. Refer to [Scorecards in table view](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer#scorecards-table-view-only) for definitions.
5. Click **View metric**. The table updates, reflecting the new metric.
   * By default, the data uses a time range of the last 30 days, but you can [select a different time range](/improve/eng-intelligence/data-explorer#filtering-by-time-range). Metrics can be [grouped by](/improve/eng-intelligence/data-explorer#grouping-metrics-chart-and-table-views) team, owner, repository, entity, and more.
6. To remove a metric from the tabular view, click the **overflow menu icon** next to the metric's name, then select **Delete column**.\


   ![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/de-remove-column.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=d943370b15cb21d1c31f8ed927c88c97)

> [!NOTE]
>
> Entity data columns describe the entity's current state, so they aren't affected by the time range or time attribute filters. Those filters still apply to the metric columns in the same table.

#### **Configuring KPI view**

1. From the main sidebar, expand **Eng Intelligence**, then select **Data Explorer**.
2. In the right pane, select **KPI**.\


   ![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-kpi.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=b0cf9c0d60ca6b043c6084769ec920fb)
3. By default, the **cycle time** metric is displayed. To select a different metric, click the tab below **Metric** in the right pane. The **Metrics** window opens.
4. Select a metric to view.
   * Cortex organizes metrics into six categories: Custom, Deployment, Incident, Project management, Version control, and AI tools, each with its own set of available metrics. Refer to [Available metrics in Data Explorer](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer) for definitions.
5. Click **View metric**. The chart updates, reflecting the new metric.
   * By default, the data uses a time range of the last 30 days, but you can [select a different time range](/improve/eng-intelligence/data-explorer#filtering-by-time-range).
6. Optionally, toggle off the following card options:
   1. **Show module header** - Hides the card's header for a cleaner, more minimal look
   2. **Show chart preview** - Hides the mini chart when you only want the metric value and trend
   3. **Show trend** - Hides the trend indicator (arrow and percentage change). If toggled on, use the **Comparison format** drop-down menu to display the trend in percentage or absolute terms.

### Step 2: Filtering and grouping metrics

Users with the `View Dev Metrics` permission can filter and group metrics.

You can filter and group metrics by individual, entity, PR, or owner, and you can filter the chart/table by time range, teams, author, and repository. You can also sort the columns.

> [!NOTE]
>
> To filter or group metrics by individual people, you also need the `View Eng Intelligence User Dimensions` permission. Without it, you can still view metrics, but options for individual PR authors and reviewers, deployers, incident assignees, work item assignees, AI tool users, and entity owners don't appear in **Filter**, **Group by**, or autocomplete suggestions. Team- and entity-level options are still available. The Admin and Manager roles include this permission by default.

#### Filtering metrics

To filter by metrics such as entity, team, repo, or user, click **Filter** in the upper-right corner of the graph. If using the KPI view, **Filter** appears in the card's header.

![The 'Filter' option in Data Explorer.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-filter.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=878290a5cb24a6a61a56a1b97ffe6721)

Configure a single filter or a combination of filters. When you are done adding filters, click **Apply** at the bottom of the filter window.

When filtering by teams or domains, **Include child teams** **/** **Include child domains** is toggled on by default, so the full team hierarchy rolls up:

* **Entity owner (Team)** includes entities owned by the selected team and any of its nested sub-teams.
* **Team** includes contributors who belong to the selected team or any of its nested sub-teams.

Toggle this off to limit to direct ownership or membership only.

> [!NOTE]
>
> The **Team owner** filter works differently. It only includes entities owned directly by the selected team, never its child teams. To include child teams' entities, use **Entity owner (Team)** with **Include child teams** on.

See the [full list of filters](/improve/eng-intelligence/data-explorer/data-explorer-reference) and their definitions.

#### Filtering by time range

To filter by time period, click the **time range** filter in the upper-right corner of the graph. By default, **Last 30 days** is displayed. If using the KPI view, **time range** appears in the card's header.

![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/de-time-range.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=b5d4e54d5bdd99a7d7418ee4ca3eed6f)

Select a new time range and configure the dates. Optionally, toggle on **Exclude weekends** to remove Saturday and Sunday from aggregations and visualizations. Because activity typically dips on weekends, excluding them eliminates recurring noise and makes trends easier to spot. The graph automatically reloads.

To change the grouping of the time range in the graph, click **Display** in the upper-right corner of the graph:

![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-display.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=4419c698e6dee3b87594d561e15b086a)

You can choose whether to display the data grouped by day, week, or month.

#### Filtering by time attribute

A pull request has several dates attached to it: when it was opened, when its first commit landed, when it was merged, and so on. The **time attribute** filter tells Data Explorer which of these dates to use when placing each PR on the timeline. Changing it doesn't change the metric you're measuring; it changes which time bucket each PR falls into, and therefore which PRs appear inside your selected time range.

For version control and PR-related metrics, click the **time attribute** filter in the upper-right corner of the graph. If using the KPI view, the time attribute filter appears in the card's header.

![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/de-time-attribute.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=92e06eb3006609d5f381bc33911e907b)

**Example**

Say a PR was opened on May 28 and merged on June 3, and you're viewing a chart with a time range set for the last 30 days.

* With the time attribute set to **Open date**, the PR counts toward May.
* With it set to **Close/merge date**, the same PR counts toward June.

If the time range was "June only," that PR would appear when filtering by close/merge date but disappear when filtering by open date, even though nothing about the PR changed. When a PR seems to be missing from (or unexpectedly present in) a report, the time attribute is usually why.

**Available time attributes**

| Time attribute | Anchors the PR to... | Use it to answer... |
| - | - | - |
| **Open date** | When the PR was opened | ***How much work was started in this period?*** |
| **Close/merge date** | When the PR was merged or closed | ***How much work shipped in this period?*** (Best for throughput and "what did we deliver" reporting) |
| **First commit date** | The timestamp of the PR's first commit | ***When did coding actually begin, regardless of when the PR was opened?*** |
| **Date first authored** | When the PR was first authored | ***When did authoring begin for cycle-time analysis?*** |
| **First review date** | When the PR received its first review | ***When did review activity happen in this period?*** |
| **Approval date** | When the PR was approved | ***When did PRs get approved (as opposed to opened or merged)?*** |
| **Date last updated** | The most recent activity on the PR | ***Which PRs saw activity in this period, regardless of when they opened?*** |

> [!NOTE]
>
> For most throughput and delivery reporting, **Close/merge date** is the best defaultas it reflects work that actually shipped. Switch to **Open date** or **First commit date** when you care about when work started rather than when it finished.

#### Grouping metrics (chart and table views)

To group your metrics differently, click the **Group by** drop-down in the right pane and select an option:

![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-group-by.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=11ab8934d4caecb117ab913da4ded053)

When you select a grouping with an inherent hierarchy, such as Team, Entity owner, or Domain, a **Show hierarchy** toggle appears. Enable it to see metrics aggregated by hierarchy level and drill down into nested groups, similar to the hierarchy views in the [Bird's Eye](/improve/reports/birds-eye) and [All Scorecards](/improve/reports/all-scorecards) reports.

The **Group by** drop-down also includes a **Relationships** section, listing the custom entity relationship types defined in your catalog. Select a relationship type to roll metrics up through that relationship.

See the [full list of grouping options](/improve/eng-intelligence/data-explorer/data-explorer-reference#group-by-definitions).

> [!NOTE]
>
> The metrics segmented by team are based on the individual users within that team. In order to have data appear, the teams must have members and the team's [identity mappings](/configure/settings/managing-users/identity-mapping) must be configured.

#### Sorting the columns (chart and table views)

> [!NOTE]
>
> Sorting is only available if **Show hierarchy** is toggled off.

To sort data within the graph, click in the **Sort rows** field in the right pane. Select an option to sort by. Note that options differ depending on the metric you're viewing.

![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/de-sort.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=a9f8286c6f94591bec6088f134fdac56)

### Step 3: Saving the view

Users with the `Edit Eng Intel Dashboards` permission can save a view as a report.

After setting up a view with your preferred metric, filters, and time range, you can save it as a report in Cortex. Note that Cortex refers to these saved reports as **modules**.

1. While viewing a graph, click **Save As** in the upper-right corner of the page. The **Save module** side panel opens.
2. Below **Module name**, enter a name for the report (required).
3. Below **Description**, enter a description of the report.
4. Below **Display icon**, select an icon for the report.
5. Click **Save module**.
   The report is saved as a module and can be found via **Eng Intelligence > Modules**. From here you can:
   * Add it to a [custom dashboard](/improve/eng-intelligence/dashboards/custom)
   * Reopen it at any time without reconfiguring filters
   * Rename, update metric/filter settings, and re-save as needed
     * Locate the report, then click the **overflow icon**. Select **Edit** to reconfigure the graph or **Rename** to change the name of the report.
   * Create a duplicate of the report
     * Locate the report, then click the **overflow icon**. Select **Duplicate**.
   * Share a link with team members
     * Locate the report, then click the **overflow icon**. Select **Share**. The URL is copied to your clipboard. The URL query parameters include timestamps, so the shared Data Explorer page reflects the same results across different timezones.
   * Delete when no longer needed
     * Locate the report, then click the **overflow icon**. Select **Delete**.

> [!NOTE]
>
> To encourage transparency and shared focus, every saved module and edit is automatically available to all members of your Eng Intelligence team.

### Step 4: Exporting to CSV

Users with the `View Dev Metrics` permission can export data.

Chart and table views can be exported as a CSV file. Cortex runs the export on its own servers instead of in your browser, so the file contains every row in the view, not just the rows currently loaded on the page.

CSV exports follow the same `View Eng Intelligence User Dimensions` restriction as filtering and grouping. If you don't have the permission, the export doesn't break data out by individual people.

> [!NOTE]
>
> CSV export is available in chart and table views. To export the data behind a KPI view, switch to chart or table view for the same metric.

1. From the main sidebar, expand **Eng Intelligence**, then select **Data Explorer**.
2. Configure the view you want to export, including the metric, filters, and time range.
3. In the upper-right corner of the page, click **Export CSV**. A toast appears in the lower-right corner of the screen showing the status of the export.
4. Do one of the following:
   * Wait for the export to finish. When the toast shows a green check mark and **Check your downloads**, the file is available in your browser's downloads.
   * Click **Email me** in the toast. Cortex sends you the file when it's ready, so you can navigate away or close the page without losing the export. This is useful for large exports, which can take a while to build.

> [!NOTE]
>
> Exports are flat: one row per entity, regardless of how the view is grouped. If you've set a **Group by** option or toggled on **Show hierarchy**, the export still returns a single flat list of entities. Grouped and hierarchical exports aren't supported yet.

### Understanding aggregation types

When you view a metric in Data Explorer, you can choose how the individual data points (e.g. each PR's Time to Merge) are aggregated into a single headline number. The aggregation you choose changes the story the number tells, but it does **not** change which metric or which underlying dates are being measured.

> [!NOTE]
>
> #### **Aggregations are only comparable within the same metric**
>
> A P95 of 'Time to Merge' and a median of 'Cycle Time' measure different things over different date ranges, so their values can't be meaningfully compared. Before comparing two numbers, confirm that the metric name shown at the top of the module is the same for both;  changing the aggregation should not change the metric you're measuring.

| Aggregation | What it tells you |
| - | - |
| **Average** (mean) | The sum of all values divided by the number of values. Useful for a general sense of the typical result, but sensitive to outliers. |
| **Median** (P50) | The middle value—half of your data points are faster and half are slower. More resistant to outliers than the average. |
| **P95** | The value that 95% of your data points come in under. Represents the slow tail; the experience of your slowest 5%. |
| **Min / Max** | The single fastest or slowest value in the range. |
| **Sum** | The total across all values (used for count-style custom metrics). |
| **Latest** | The most recent data point in the selected time range, with no aggregation. Returns no value if the range has no data points. Available for custom metrics only. |

> [!NOTE]
>
> #### **Why P95 is usually higher than the median or average**
>
> Most PR-timing metrics are right-skewed, meaning the majority of PRs complete quickly, and a small number take much longer. For this kind of data, P95 will almost always be higher than both the median and the average, because P95 deliberately sits out in the slow tail while the average is pulled down by the fast majority.
>
> This is expected and correct. By definition, P95 is always greater than or equal to the median (P50) **for the same metric**. If P95 ever appears lower than the median or average, you are more than likely comparing two different metrics.


# Available metrics in Data Explorer
Source: https://docs.cortex.io/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer



> [!NOTE]
>
> Note that Cortex-provided metrics in Data Explorer sync on a scheduled basis, updating every four (4) hours. [Custom metrics](/improve/eng-intelligence/custom-metrics) have their own sync schedules.

## Accessing metrics in Data Explorer

Follow the steps below to access metrics in Data Explorer.

1. From the main sidebar, expand **Eng Intelligence**, then select **Data Explorer**.
2. In the right pane, click the tab below **Data**. The **Metrics** window opens.\


   ![The 'Data' section in Data Explorer.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-default-metric.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=5a3e4663ee0f0e0de372a82bfe6d225f)
3. Select a metric to view, then click **View metric**. The chart updates automatically based on the metric you selected.\


   ![The 'View metric' button in the Metrics window.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/de-metrics-window.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=7938c49073cf14465fa2a5666879b2bb)
4. Repeat steps 2 and 3 as necessary.

## Available metrics

### AI tools

> [!NOTE]
>
> AI tool metrics are available to cloud customers in the [beta program](/resources/beta).

AI usage metrics are pulled from [GitHub Copilot](/ingesting-data-into-cortex/integrations/github).

| Metric | Definition |
| - | - |
| **AI adoption rate** | The percentage of licensed seats that were active users of AI coding tools in a given time period. **Calculation**: `Copilot active users / Copilot total seats` |
| **Active AI users** | The number of users who used AI coding tools in a given time period. Cortex automatically labels users as `AI User` (active in the last 7 days) or `Non-AI User` (no Copilot activity in the last 30 days). **Calculation**: `Copilot active users` |

### Deployment metrics

Deploy metrics are pulled from the [Cortex deploys API](/api/rest/deploys).

| Metric | Definition |
| - | - |
| **Change failure rate** | The percentage of deployments that cause a failure in production. **Best practice**: Aim to reduce your change failure rate over time. A rate below 15% aligns with DORA's elite benchmarks and indicates strong software delivery performance. **Calculation**: `Number of rollbacks / number of deployments created` |
| **Deployment frequency** | The number of deployments over a given period of time. **Best practice**: Depending on your organization, a successful benchmark could be multiple deployments per day or per week. |
| **Rollback frequency** | The number of rollbacks over a given period of time. **Best practice**: While there isn't an explicit benchmark, you should aim to minimize rollback rates. A low rollback rate generally aligns with a low change failure rate. |

### Incident metrics

Incident metrics are pulled from [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty).

| Metric | Definition and calculation |
| - | - |
| **Incident frequency** | The number of incidents over a given period of time.When you drill in to metric points below, view data per incident: • Incident title • Status • Incident URL • Date triggered • Date resolved • Urgency • Time to resolution**Best practice**: There is no universal benchmark. It's recommended to track trends and establish baselines within your organization. |
| **Time to resolution** | The amount of time it takes for an incident to be resolved.When you drill in to metric points, view data per incident: • Incident title • Status • Incident URL • Date triggered • Date resolved • Urgency • Time to resolution**Best practice**: Benchmarks vary by system criticality. Aim for under one (1) day for less critical systems, under 1 hour for critical ones. **Calculation**: `Incident resolution time - incident opened time` |

### Project management metrics

Project management metrics are pulled from [Jira](/ingesting-data-into-cortex/integrations/jira).

> [!NOTE]
>
> Project management metrics do not support JQL entity mapping. If you configured a [default JQL query per entity](/ingesting-data-into-cortex/integrations/jira#set-a-default-jql-query-for-your-jira-integration), it is not applied when viewing, filtering, or segmenting these metrics in Data Explorer.

| Metric | Definition and calculation |
| - | - |
| **Story points completed** | The sum of story points completed in a given time period.When you drill in to metric points below the graph, view data per work item: • External key • Work item assignee • Assignee email • Work item title • Work item status • Work item type • Created date • Resolved date • Priority • Labels • Components • Story points completed**Best practice**: Establish a baseline per team, as story point values can be unique to each team. Use this metric to understand capacity trends. |
| **Work item lead time** | The time it takes from when a work item is created to when the work item is completed.When you drill in to metric points below the graph, view data per work item: • External key • Work item assignee • Assignee email • Work item title • Work item status • Work item type • Created date • Resolved date • Priority • Labels • Components • Status category • Work item lead time**Best practice**: Lower lead times indicate a smoother process. Track trends to identify process inefficiencies and improve throughput. **Calculation**: `Work item resolved date – Work item created date`. |
| **Work items completed** | The number of work items completed over a given period of time.When you drill in to metric points below the graph, view data per work item: • External key • Work item assignee • Assignee email • Work item title • Work item status • Work item type • Created date • Resolved date • Priority • Labels • Components**Best practice**: Review this measure alongside how many story points have been completed; this enables you to balance both quantity and effort, ensuring teams aren't favoring lower value tasks in exchange for higher numbers of items completed. |
| **Work items created** | The number of work items created over a given period of time.When you drill in to metric points below the graph, view data per work item: • External key • Work item assignee • Assignee email • Work item title • Work item status • Work item type • Created date • Resolved date • Priority • Labels • Components**Best practice**: Monitor this metric alongside delivery rates. If items are created faster than completed, it signals queue backlogs. |

### Version control metrics

Version control metrics are pulled from [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), and [GitLab](/ingesting-data-into-cortex/integrations/gitlab).

> [!NOTE]
>
> Pull request–related metrics include PRs from any branch.

| Metric | Definition and calculation |
| - | - |
| **Cycle time** | The date a PR is authored to when the PR is merged. This represents the time it takes for a single PR to go through the entire coding process. Falls back to first commit date if authored date is not available. Note: This metric is not supported for [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) or [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket). When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • First commit date • Date closed • Cycle time**Best practice**: Aim for lower cycle times to ensure a faster feedback loop and reduced context switching. Rather than benchmarking the overall cycle time, set benchmarks for the individual parts of the cycle (time to open, time to approve, time to first review, time to merge). |
| **Closed PRs** | The number of PRs closed in a given time period.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • Date closed**Best practice**: A high ratio of merged-to-closed PRs signals an effective review cycle. |
| **Merged PRs** | The number of PRs merged in a given time period.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • Date closed**Best practice**: A high ratio of merged-to-closed PRs signals an effective review cycle. |
| **Number of comments per PR** | The number of comments on a pull request.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • First commit date • Number of comments per PR**Best practice**: This measure indicates review depth and collaboration. A lower number may signal superficial reviews. |
| **Number of unique PR authors** | The number of unique PR authors.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • First commit date • Date opened • Time to open • This is the time between the first commit date and the date opened.**Best practice**: A larger number across projects can signal distributed ownership, while a consistently low number can point to bottlenecks or team burnout. |
| **Opened PRs** | The number of PRs opened in a given time period.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • Date closed**Best practice**: Persistent backlog can indicate process inefficiencies, such as a slow review process. |
| **PR reviews count** | The number of reviews on a PR.When you drill in to metric points below the graph, view more data: • PR name • Reviewer • Review date**Best practice**: A higher number can indicate complex changes or low initial quality. A lower number could indicate approvals without thorough review and validation. |
| **PR size** | The number of lines of code modified in a PR.Note: This metric is not supported for [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) or [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket).When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • Number of lines added • Number of lines deleted • PR size**Best practice**: Smaller PRs lead to faster reviews, fewer mistakes, and increased velocity. Aim for less than 400 lines, but adjust this benchmark as needed to improve review quality and velocity. |
| **Success rate** | The percentage of PRs that are opened and eventually merged in a given time frame.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • Date opened • Date closed**Best practice**: Higher success rates can indicate better quality code and reviews, but note that it is also important to understand the reasoning when a PR is rejected. |
| **Time to approve** | The time from the first review to the time it’s approved. This represents how long engineers are spending reviewing code. If the first review is an approval, this time will be 0 as the timestamps will be the same.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • Review date • Approval date • Time to approve • This is the time between the review date and the approval date.**Best practice**: It is recommended to keep review time under 24 hours to maintain velocity and avoid a backlog of PRs. |
| **Time to first review** | The time a PR is open to when the PR gets it’s first review (comment or approval). This represents how long PRs are waiting idol before someone starts reviewing it.When you drill in to metric points below the graph, view data per PR. • PR name • Author • PR status • Date opened • First review time • Time to first review • This is the time between the open date and the first review time.**Best practice**: It is recommended to target first review within 24 hours to ensure prompt feedback and smooth throughout. |
| **Time to merge** | The time from when the PR is approved to when it’s merged.When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • Approval date • Date closed • Time to merge • This is the time between the approval date and the date closed.**Best practice**: There is not an explicit benchmark for this metric, but note that reducing this time to under an hour boosts code velocity. Using a tool that enforces automated merges can cut down delays. |
| **Time to open** | The date a PR is authored to when the PR is opened. This represents the time spent coding. Falls back to first commit date if authored date is not available.Note: This metric is not supported for [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) or [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket).When you drill in to metric points below the graph, view data per PR: • PR name • Author • PR status • First commit date • Date opened • Time to open • This is the time between the first commit date and the date opened.**Best practice**: There is not an explicit benchmark for this metric, but note that increasing the time to open depends on an efficient triage of work; focus on minimizing idle time before work starts. |

### Custom metrics

You can view [custom metrics](/improve/eng-intelligence/custom-metrics) in Data Explorer alongside Cortex's out-of-the-box metrics, appearing in the category selected at creation. Custom metrics are displayed as raw numeric values and can be aggregated using the following operations: average, latest, max, median, min, p95, and sum.

### Entity data in table view

The **Table** view supports three categories of entity data in addition to metrics. Unlike metrics, these columns aren't time series; they show the entity's current values.

| Category | What it provides |
| - | - |
| **Custom data** | Any custom data key defined on your entities. Cortex surfaces keys from all sources: the entity descriptor (`x-cortex-custom-metadata`), the custom data API, and custom webhook integrations. Useful for columns like deployment environment or compliance status. |
| **Entity definition** | Fields from the schema of a custom entity type. Use this to report on attributes that only exist on your own entity types. |
| **Entity metadata** | Cortex's built-in entity attributes, such as name, tag, description, entity type, and owner. |

**Example reports**

You can now create the following common reports in Eng Intelligence, without CQL, and add them to saved modules and dashboards.

| Report | What it provides |
| - | - |
| **Service inventory** | See what exists in your catalog and how it's classified, without opening each entity. Add **name**, **entity type**, and **description** from entity metadata, then add whichever custom data keys you use to classify services, such as a tier or an ID from another system of record. |
| **Ownership** **audit** | Check who owns what. Add **owner** from entity metadata next to a metric like cycle time or deploy frequency to easily see who owns each entity or identify entities without owners. |
| **Migration and compliance tracking** | Track a rollout across your catalog. If you record **status** as custom data, such as a migration flag or a runtime version, add that key as a column next to deployment or PR metrics. You'll see which parts of the catalog have moved and which have stalled. |

Refer to [Adding entity data to table view](/improve/eng-intelligence/data-explorer#configuring-table-view) for more information.

### Scorecards **(table view only)**

Table view supports Scorecard results as a metric, so a Scorecard column can sit next to delivery data in the same report. Compare a service's Scorecard score against its cycle time, or track migration progress across every entity in one view.

Every Scorecard in your workspace appears in the **Metrics** window, under **Cortex (Table only) > Scorecards**. Select a Scorecard, choose a data point, then click **Select data**.

| Data point | What it provides |
| - | - |
| **Score %** | The entity's current score as a percentage, with the points earned out of the points available, such as `67% (2/3 pts)`. |
| **Level** | The level the entity has reached on the Scorecard's ladder, such as **Bronze**. Entities that haven't reached a level show **No level**. |

Each column holds one data point. To show both the score and the level for the same Scorecard, add a second column and select the other data point. Columns are named for the Scorecard and the data point, such as **Git Migration (Score %)**.

> [!NOTE]
>
> Scorecard results are evaluated per entity, so adding a Scorecard column sets **Group by** to an entity-based option. **Entity**, **Group**, **Domain**, **Entity type**, **Entity owner**, and relationship groupings stay available. Team and user groupings aren't available while a Scorecard column is in the table.

> [!NOTE]
>
> Scorecard columns show current results rather than a time series, so the time range filter doesn't apply to them. It still applies to the metric columns in the same table. Historical Scorecard data isn't supported yet.


# Data Explorer reference
Source: https://docs.cortex.io/improve/eng-intelligence/data-explorer/data-explorer-reference



Filter options vary depending on the metric you're viewing. For example, the **Opened PRs** metric shows version control filters, while **Story points completed** shows project management filters.

For information on selecting a metric, see [Available metrics in Data Explorer](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer#accessing-metrics-in-data-explorer).

For information on accessing the filters listed below, refer to [Filtering and grouping metrics](/improve/eng-intelligence/data-explorer#step-2-filtering-and-grouping-metrics).

> [!NOTE]
>
> Filters and 'group by' options for individual people, such as **User**, **Assignee**, **Deployer**, **Incident assignee**, and **Entity owner** when set to a user, only appear if you have the `View Eng Intelligence User Dimensions` permission. Learn more in [Custom roles](/configure/settings/managing-users/permissioning/custom-roles#available-permissions-for-custom-roles).

## Filter operators and selectors

Some filters support operators and/or selectors. Select an operator/selector from the drop-down menu next to the filter name, then enter a value or values to define the range or condition.

### Numeric operators

Available numeric operators:

* Equals, Does not equal, >, ≥, \<, ≤, Is between, Is empty, Is not empty

Numeric operators are found on the following filters:

* **Version control** - Lines added, Lines deleted, Files changed, Number of comments, Commits, Cycle time, PR size
* **Deployment** - Duration
* **Incident** - Time to resolution
* **Project management** - Story points, Time spent, Original estimate, Remaining estimate, Number of comments

### String operators

Available string operators:

* Is, Is not, Is empty, Is not empty, Contains, Excludes

String operators are found on the following filters:

* **Teams & Users** - Inherited team, User, Team, User label, User label name, Assignee, Assignee team, Assignee user label, Deployer, Incident assignee
* **Entity** - Inherited domain, Inherited team owner, Domain, Entity, Entity type, Group, Entity owner
* **Version control** - Label
* **Deployment** - Environment, Status
* **Project management** - Component, Label, Sprint, Status, Work item type

> [!NOTE]
>
> Because they can never be empty, the following three filters have a slightly reduced set of operators \*\*(\*\*no **Is empty** / **Is not empty**):
>
> * **Version control** - Repository, Status
> * **Project management** - Project
>
> One filter has its own set (**Equals**, **Does not equal**, **Is empty**, **Is not empty**):
>
> * **Version control** - Draft
>
> The **Scorecard** filter also has its own set (**Is**, **Is not**, **Is empty**, **Is not empty**):
>
> * **Scorecard** - Level

### Role selectors

The Author/Reviewer role selector is found on the following filters:

* **Version control** - User, Team, User label, User label name

## Example filter scenarios

Filters are most useful when you combine them to answer a specific question. A few common examples:

**Version control**

* Filter **Cycle time** by **>** 3 days to find PRs that are taking longer than expected to ship. This can help you spot patterns like review bottlenecks.
* Filter **Number of comments** by **Equals** 0 to find PRs that shipped with no review comments, a possible quality or risk signal.
* Filter **PR size** by **>** 1,000 lines, or **Files changed** by **>** 10, to see the cycle time for your largest PRs and understand how PR size affects delivery speed.
* Filter **Draft** by **Equals** true combined with **Cycle time** by **>** 7 days to catch PRs that have been sitting in draft for a long time, work that's stalled before it even reaches review.

**Project management**

* Filter **Story points** by **≥** 8 to surface large work items that may need to be broken down into smaller pieces.
* Filter **Work item type** by **Is** "Bug" combined with **Time spent** by **>** 3 days to see which bugs are consuming the most engineering time.

**Incidents**

* Filter **Time to resolution** by **>** 12 hours to identify incidents where response is breaking down.

**Deployments**

* Filter **Duration** by **>** 30 minutes to spot patterns leading to slow deployments.
* Filter **Environment** by **Is** "Staging" combined with **Status** by **Is not** "Success" to catch deployments failing in staging before they'd ever reach production.

**Teams and users**

* Filter **User label** by **Is** "AI User (last 7 days)" to compare cycle time or PR throughput between people using GitHub Copilot and those who aren't.
* Filter **Team** with the **Reviewer** role selector to see how much review load a team is carrying across the org, not just on their own PRs.

**Entity**

* Filter **Entity type** by **Is** "Service" combined with **Group** by **Is** "Tier 1" to focus metrics on your most critical production services only.

**Scorecards (table view only)**

* Filter **Level** by **Is** "No level" to find entities that haven't reached the first level of a Scorecard yet, a quick way to see where adoption has stalled.
* Filter **Level** by **Is not** "Level 3" alongside **Entity owner** to see which teams still have work left on a migration Scorecard.

## Filter definitions

### Teams and users

The filters in this section focus on scoping data to specific people or teams. Available filters are dependent on the metric being viewed.

| Filter | Definition |
| - | - |
| **Assignee** | View data for work items assigned to a specific user. |
| **Assignee team** | View data for work items assigned to users belonging to a specific team. |
| **Assignee user label** | View data for work items assigned to users with a specific [user label](/improve/eng-intelligence/eng-intelligence#group-by-user-label). |
| **Deployer** | View data for deployments performed by a specific user. |
| **Group** | View data only for entities associated with a specific [group](/ingesting-data-into-cortex/entities-overview/entities/groups). |
| **Incident assignee** | View data for incidents assigned to a specific user. |
| **Individual owner** | View data for metrics on entities owned by a specific user. For example, if Service X is owned by Marco, filtering by Marco only shows data for Service X even if the work was performed by someone else. |
| **Inherited team** | View data for entities whose team is inherited from a parent entity in the hierarchy. |
| **Team** | View data for a specific team. • For version control metrics, filters by the team of the PR author or reviewer (based on the **Version control team types** setting). • For deployment metrics, filters by the team of the deployer. • For incident metrics, filters by the team of the incident assignee. |
| **Team owner** | View data for metrics on entities owned by a specific team. This only includes entities owned directly by the selected team, not its child teams. To include child teams' entities, use **Entity owner** with **Include child teams** on. |
| **User** | View data authored by a specified user. |
| **User label** | View data authored by users with a specific [user label](/improve/eng-intelligence/eng-intelligence#group-by-user-label). Cortex automatically creates an AI Usage label for GitHub Copilot usage with values **AI User (last 7 days)** and **Non-AI User (last 7 days)**. |
| **User label name** | View data authored by users with a specific [user label](/improve/eng-intelligence/eng-intelligence#group-by-user-label) value. |

### Entity

The filters in this section focus on scoping data to specific entities, entity types, or the groups they belong to.

| Filter | Definition |
| - | - |
| **Inherited domain** | View data only for entities whose domain is inherited from a parent entity in the hierarchy. |
| **Inherited team owner** | View data only for entities whose team owner is inherited from a parent entity in the hierarchy. |
| **Domain** | View data only for entities belonging to a specific domain. |
| **Entity** | View data only for a specific entity. |
| **Entity type** | View data only for specific types of entities (such as services or teams). |
| **Group** | View data only for entities associated with a specific [group](/ingesting-data-into-cortex/entities-overview/entities/groups). |
| **Entity owner** | View data only for entities owned by a specific user or team. When you filter by a team, **Include child teams** is on by default, so entities owned by the team's child teams are included. Toggle it off to see only the selected team's entities. |

### **Version control**

The filters in this section are specific to version control metrics and let you scope data by pull request attributes such as status, label, and repository.

| Filter | Definition |
| - | - |
| **Label** | View data only for PRs tagged with a specific label. |
| **Repository** | View data only for a specific repository. |
| **Status** | View data for PRs in specified statuses. |
| **Lines added** | View data for PRs with a specific number of lines added. |
| **Lines deleted** | View data for PRs with a specific number of lines deleted. |
| **Files changed** | View data for PRs with a specific number of files changed. |
| **Number of comments** | View data for PRs with a specific number of comments. |
| **Commits** | View data for PRs with a specific number of commits. |
| **Draft** | View data filtered by whether PRs are drafts or not. |
| **Bot generated** | View data filtered by whether PRs were generated by bots or not. |
| **Cycle time** | View data for PRs within a specific cycle time range. |
| **PR size** | View data for PRs within a specific size range (based on total lines of code modified). |

### **Deployments**

The filters in this section are specific to deployment metrics and let you scope data by attributes such as deployment status and environment.

| Filter | Definition |
| - | - |
| **Environment** | View data only related to a specific environment sent via the [deploys API](/api/rest/deploys). |
| **Status** | View data for deployments in specified statuses. |
| **Duration** | View data for deployments within a specific duration range. |

### **AI tools**

There are no AI-specific filters. Only **Teams & Users** and **Entity** filters apply to AI tools metrics.

### **Project management**

The filters in this section are specific to project management metrics and let you scope data by work item attributes such as status, type, sprint, and project.

> [!NOTE]
>
> [Unique defaultJQL configurations](/ingesting-data-into-cortex/integrations/jira#set-a-default-jql-query-for-your-jira-integration) per entity aren't supported for filtering or segmenting data in Data Explorer.

| Filter | Definition |
| - | - |
| **Component** | View data only for work items assigned to a specific component. |
| **Label** | View data only for work items tagged with a specific label. |
| **Project** | View data only for work items belonging to a specific project. |
| **Sprint** | View data only for work items assigned to a specific sprint. |
| **Status** | View data for work items in specified statuses. |
| **Work item type** | View data for work items of a specific type. |
| **Story points** | View data for work items with a specific story point value or range. |
| **Time spent** | View data for work items with a specific amount of time logged. |
| **Original estimate** | View data for work items with a specific original time estimate. |
| **Remaining estimate** | View data for work items with a specific remaining time estimate. |
| **Number of comments** | View data for work items with a specific number of comments. |

### **Incidents**

The filters in this section are specific to incident-related metrics.

> [!NOTE]
>
> **Team** and **user** filters are only supported for PagerDuty.

| Filter | Definition |
| - | - |
| **Status** | View data for incidents in specified statuses. |
| **Urgency** | View data for incidents in specified urgencies. |
| **Time to resolution** | View data for incidents within a specific time-to-resolution range. |

### Custom metrics

The filters in this section are specific to the custom metrics you created in Cortex.

| Filter | Definition |
| - | - |
| **Inherited domain** | View data only for entities whose domain is inherited from a parent entity in the hierarchy. |
| **Inherited team owner** | View data only for entities whose team owner is inherited from a parent entity in the hierarchy. |
| **Domain** | View data only for entities belonging to a specific domain. |
| **Entity** | View data only for a specific entity. |
| **Entity type** | View data only for specific types of entities (such as services or teams). |
| **Group** | View data only for entities associated with a specific [group](/ingesting-data-into-cortex/entities-overview/entities/groups). |
| **Entity owner** | View data only for entities owned by a specific user or team. When you filter by a team, **Include child teams** is on by default, so entities owned by the team's child teams are included. Toggle it off to see only the selected team's entities. |

### Scorecard **(table view only)**

The filter in this section applies to table view when a Scorecard column is in the report. Refer to [Scorecards in table view](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer#scorecards-table-view-only) for more information.

| Filter | Definition |
| - | - |
| **Level** | View data only for entities at a specific level on the Scorecard's ladder. Levels are listed by position, with the level name in parentheses, such as **Level 1 (Bronze)**. Select **No level** to find entities that haven't reached the first level yet. You can select more than one value. |

## 'Group by' definitions

'Group by' options vary depending on the metric you're viewing. For example, the **Cycle time** metric shows version control group by options, while **Story points completed** shows project management group by options.

For information on selecting a metric, see [Available metrics in Data Explorer](/improve/eng-intelligence/data-explorer/available-metrics-in-data-explorer).

For information on grouping metrics, refer to [Grouping metrics](/improve/eng-intelligence/data-explorer#grouping-metrics-chart-and-table-views).

### **Teams and users**

The 'group by' options in this section let you segment data by specific people or teams. Available options are dependent on the metric being viewed.

| Group by | Definition |
| - | - |
| **Team** | Group data by team. • For version control metrics, groups by the team of the PR author or reviewer (based on the **Version control team types** setting). • For deployment metrics, groups by the team of the deployer. • For incident metrics, groups by the team of the incident assignee. |
| **User** | Group data by individual user. |
| **User label** | Group data by [user label](/improve/eng-intelligence/eng-intelligence#group-by-user-label). |

### **Entity**

The 'group by' options in this section let you segment data by entity-related attributes such as entity type, domain, or group.

| Group by | Definition |
| - | - |
| **Entity** | Group data by individual entity. |
| **Group** | Group data by the [group](/ingesting-data-into-cortex/entities-overview/entities/groups) the entity belongs to. |
| **Domain** | Group data by the domain the entity belongs to. |
| **Entity type** | Group data by entity type (such as services or teams). |
| **Entity owner** | Group data by the user or team that owns the entity. |

### **Version control**

The 'group by' options in this section are specific to version control metrics and let you segment data by pull request attributes.

| Group by | Definition |
| - | - |
| **Repository** | Group data by repository. |
| **Status** | Group data by PR status. |
| **Label** | Group data by PR label. |
| **Author** | Group data by PR author. |
| **Reviewer** | Group data by PR reviewer. |

### **Deployments**

The 'group by' options in this section are specific to deployment metrics and let you scope data by attributes such as environment.

| Group by | Definition |
| - | - |
| **Environment** | The environment sent via the [deploys API](/api/rest/deploys). |

### **AI tools**

There are no AI-specific 'group by' options. Only **Teams & Users** options apply to AI tools metrics.

### **Project management**

The 'group by' options in this section are specific to project management metrics and let you segment data by project attributes.

| Group by | Definition |
| - | - |
| **Project** | Group data by project. |
| **Sprint** | Group data by sprint. |

### Incidents

There are no incident-specific 'group by' options. **Teams & Users** and **Entity** options apply to incident metrics.

### Custom metrics

The 'group by' options in this section are specific to the custom metrics you created in Cortex.

| Group by | Definition |
| - | - |
| **Domain** | The domain associated with the entity. |

### Scorecards **(table view only)**

There are no Scorecard-specific 'group by' options. Because Scorecard results are evaluated per entity, adding a Scorecard column limits grouping to the **Entity** options and relationship groupings. Team and user options aren't available while a Scorecard column is in the table.

### Relationships

The 'group by' options in this section list the custom entity relationship types defined in your catalog. Each relationship type you've configured (for example, a service-to-repository or account-to-resource mapping) appears as its own grouping option. Select a relationship type to group and roll up metrics for entities connected through that relationship.

Filtering by relationship isn't supported yet; these options are available for grouping only.


# DORA Dashboard
Source: https://docs.cortex.io/improve/eng-intelligence/dora-dashboard



The DORA framework (DevOps Research and Assessment) is a set of metrics that help teams measure software delivery performance. Integrated into your Engineering Operations Platform, DORA metrics give engineering teams clear insights into how fast, reliable, and efficient their development practices are. This empowers teams to track progress, identify bottlenecks, and drive continuous improvement — all within the same place they manage services and deploy code. Read more about these metrics in the [dora.dev guide](https://dora.dev/guides/dora-metrics-four-keys/).

Use the DORA Dashboard in Cortex to evaluate the speed and stability of your software delivery process. Visualize your team’s success across the software process and get a clear view of cycle time, deployment frequency, change failure rate, and time to resolution.

![The DORA dashboard shows graphs for the key DORA metrics.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/dora-dashboard.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=a1903041a0c2fa1c0b1f32d161804a9f)

> [!TIP]
>
> Looking for additional resources on enforcing DORA standards in Cortex?
>
> * See [Solutions: DORA Metrics](/solutions/dora) for guidance on using Cortex features to improve your DORA metrics.
> * Check out the [Cortex Academy "Operationalizing DORA Metrics" course](https://academy.cortex.io/courses/cortex-solutions-operationalizing-dora-metrics), available to all Cortex customers and POVs.
> * See Cortex's "Operationalizing DORA Metrics" webinar with Google Cloud's DORA program leader, Nathen Harvey, and learn about the key takeaways [in our blog](https://www.cortex.io/post/from-insight-to-impact-key-takeaways-from-our-dora-webinar-with-nathen-harvey).

## Using the DORA Dashboard

To view the dashboard, click **Eng Intelligence > DORA Dashboard** in the main nav.

### Adjust the time range

By default, the dashboard displays data from the last last month. To change the date range, click Last month and select a new date range.

### **Filtering the DORA Dashboard**

You can filter at two levels:

* **Dashboard level** - Click **Filter** at the top of the DORA Dashboard to apply a filter across all charts at once. The DORA Dashboard supports **Domain**, **Team Owner**, and **Team** as dashboard-level filters.
* **Chart level** - Click **Filter** in the upper-right corner of an individual chart to apply filters for group, owner, repository, user label, and more. Chart-level filters override dashboard-level filters for that chart.

## Metric visualizations

You can select a different operation for the Cycle time and Time to resolution graphs. Options include average, sum, max, min, P95, and median. Both graphs display the average by default.

### Cycle time

Cycle time represents the time it takes for a single PR to go through the entire coding process. Shorter cycle times indicate a more agile team that is able to quickly respond to changing needs.

**Calculation**: The time between the first commit on a PR to when the PR is merged.

![Cycle time represents the time it takes for a single PR to go through the entire coding process.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/cycle-time.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=cb0a6581ccbc8f0f0f3de17d9b8da220)

**Best practice**: Aim for lower cycle times to ensure a faster feedback loop and reduced context switching. Rather than benchmarking the overall cycle time, set benchmarks for the individual parts of the cycle (time to open, time to approve, time to first review, time to merge).

Note: This metric is not supported for [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) or [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket).

### Deployment frequency

Deployment frequency measures how often your team successfully releases code to production, serving as a key indicator of your delivery velocity and operational maturity. This DORA metric reflects your team's ability to deliver value continuously and respond quickly to market demands.

**Calculation**: The number of deployments over a given period of time.

![Deployment frequency represents how often code is deployed to a production environment](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/deployment-frequency.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=951414b615525616f51d5138089550f1)

**Best practice**: Depending on your organization, a successful benchmark could be multiple deployments per day or per week.

### Change failure rate

Change failure rate measures the percentage of deployments that result in production failures, serving as a critical indicator of deployment stability and code quality. This DORA metric reveals how often your releases introduce bugs, outages, or performance issues that impact users.

**Calculation**: `Number of rollbacks / number of deployments created`.

![The change failure rate graph shows the percentage of deployments that result in a failure in production.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/dora-change-failure.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=384de548d1c8e058423a12ac6c3c38fb)

**Best practice**: Aim for a failure rate less than 15%.

### Time to resolution (MTTR)

Time to resolution measures how quickly your team recovers from production failures, reflecting your incident response capabilities and system resilience. Also known as mean time to recovery (MTTR), this metric indicates how well-prepared your team is to handle inevitable production issues.

**Calculation**: `Incident resolution time - incident opened time`.

![The time to resolution graph shows how long it takes a team to recover from failure in production.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/dora-mttr.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=64dd60df7fc09089ca831d7a10140dc1)

**Best practice**: This benchmark may differ depending on how critical a system is. For less critical systems, aim for a measure of less than 1 day. For critical systems, aim for under 1 hour.


# Velocity Dashboard
Source: https://docs.cortex.io/improve/eng-intelligence/velocity-dashboard



The Velocity Dashboard provides a one-stop-shop into your software development lifecycle helping you and your teams understand any bottlenecks in your process. Get a clear view of PR cycle time to identify bottlenecks and spot inefficiencies, compare pull request size against commit activity, and visualize your team’s success rate across the entire review process — all in one place.

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202025-07-23%20at%202.56.04%E2%80%AFPM.png)

## Using the Velocity Dashboard

To view the dashboard, click **Eng Intelligence > Velocity Dashboard** in the main nav.

### Adjust the time range

By default, the dashboard displays data from the last 7 days. To change the date range, click **Last 7 days** and select a new date.

### Apply a filter option

You can apply filters across for team, owner, repository, user label, and more to narrow down the set of data you are reviewing. To select filters, click **Filter** in the upper right corner of a graph.

### Drill down

For each metric, click on the card to drill down into the data for further analysis. After clicking into the card, you can segment the data and drill down further to view a list of data points:

![Click a metric card to see a visual and data that can be segmented. Drill further into that data to get a list of data points.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/drill-down-diagram.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=633b7174415dff574644ac6ee483e687)

## Cycle time breakdown

Cycle time measures the complete journey of a pull request from first commit to merge into your main branch. Understanding this end-to-end process is crucial for identifying bottlenecks and optimizing your development workflow.

Note: Cycle Time and Time to Open metrics are not supported for [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) or [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket).

The four stages of cycle time:

* **Time to open:** Development phase: First commit to PR creation
  * **Best practice**: There is not an explicit industry benchmark for this metric, but note that increasing the time to open depends on an efficient triage of work; focus on minimizing idle time before work starts.
* **Time to approve:** Review process: First review to final approval
  * **Best practice**: It is recommended to keep review time under 24 hours to maintain velocity and avoid a backlog of PRs.
* **Time to first review:** Waiting period: PR opened to initial reviewer engagement
  * **Best practice**: It is recommended to target first review within 24 hours to ensure prompt feedback and smooth throughout.
* **Time to merge:** Merge process: Approval to successful merge
  * **Best practice**: There is not an explicit benchmark for this metric, but note that reducing this time to under an hour boosts code velocity. Using a tool that enforces automated merges can cut down delays.

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202025-07-23%20at%203.05.09%E2%80%AFPM.png)

### Key insight

Most teams discover that one of these four areas makes up 50-60% of their overall cycle time, providing a clear picture of a focus area to improve overall velocity.

### Cycle time best practices

* Set SLA targets for each stage (e.g., first review within 1 business day)
* Implement automated code review assignments to eliminate reviewer uncertainty
* Use draft PRs for work-in-progress to separate development time from review time
* Track P95 metrics to identify and address outlier PRs that skew team performance

### Visualization options

Choose from multiple statistical views (average, sum, max, min, P95, median) to analyze your data. The default average view provides a balanced perspective, while P95 highlights outliers that might indicate systemic issues.

## Cycle time x PR size

Pull request size directly impacts development velocity. Larger PRs consistently correlate with longer cycle times across every stage of the development process - from initial review to final merge. This visualization helps you understand how PR size affects efficiency throughout your development lifecycle.

Compare your pull request size to:

* Time to open
* Time to first review
* Time to approve
* Time to merge
* Overall cycle time

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202025-07-23%20at%203.24.17%E2%80%AFPM.png)

### Key insight

Smaller PRs move faster. They're easier to review, less likely to introduce conflicts, and require fewer revision cycles. Teams that maintain smaller, focused PRs typically see 2-3x faster cycle times and higher code quality.

### PR size best practices

Aim for PRs under 400 lines of code. Break larger features into smaller, logical chunks that can be reviewed and merged independently.

### Visualization options

Outliers are excluded by default. To include them, toggle on the **Show outliers** option.

## PR success rate

PR success rate measures the percentage of pull requests that successfully make it from creation to merge, providing critical insight into development efficiency and process waste. A high success rate indicates focused development work, while a low rate suggests potential issues with planning, scope creep, or unclear requirements.

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202025-07-23%20at%203.27.14%E2%80%AFPM.png)

### Key insights

A sudden drop in success rate often correlates with rushed feature development, unclear requirements, or experimental work that should happen in separate branches. High-performing teams maintain consistent success rates even during periods of increased PR volume.

### PR success best practices

* Target a PR success rate above 80% for optimal efficiency
* Review closed (unmerged) PRs weekly to identify patterns and root causes
* Implement clearer definition-of-done criteria before starting development
* Use draft PRs for experimental work to separate exploration from production-ready code
* Track success rate alongside cycle time - both metrics together reveal process health
* Consider feature flags for risky changes instead of abandoning PRs

### Visualization options

Switch between viewing open, closed or merged PRs against success rate.


# Initiatives and Action items
Source: https://docs.cortex.io/improve/initiatives

Drive action on the standards set in Scorecards

While [Scorecards](/standardize/scorecards) allow you to set benchmarks, Initiatives help you set targeted goals to meet specific standards within a specified deadline. Set a clear goal (e.g., "90% of services are production-ready by Q3"), attach a deadline, assign owners, and Cortex will automatically notify users and track progress for you.

Initiatives offer a streamlined view into the most critical tasks, improving not just the efficiency of your team members, but the accountability of your teams as well.

See [examples of Initiatives](/improve/initiatives#initiative-examples) or [ask Cortex MCP](/improve/initiatives#using-cortex-mcp-for-initiative-ideas) to help you get started.

> [!TIP]
>
> Looking for a quick introduction to Initiatives? Check out the [Cortex Academy "Intro to Initiatives" course](https://academy.cortex.io/courses/introduction-to-initiatives), available to all Cortex customers and POVs.

### Using Cortex MCP for Initiative ideas

Not sure where to start? Use [Cortex MCP](/get-started/cortex-ai-assistant/mcp) to ask questions in natural language and receive detailed responses that take your environment into account.

For example, you might use the following prompt: *I want to run an initiative to migrate our company to using GitHub Actions. Help me figure out how to do this in Cortex.*

* The MCP will respond with a detailed plan, an implementation timeline, best practices, and a list of next steps.

See [Cortex MCP](/get-started/cortex-ai-assistant/mcp) for configuration instructions.

## Initiatives overview

In the video below, learn how [Scorecards](/standardize/scorecards), [Initiatives](/improve/initiatives), and [Reports](/improve/reports) can be used together to drive business goals.

[YouTube video player](https://www.youtube.com/embed/oIWbMlK7Qh4)

## Create an initiative

### Prerequisites

Before getting started:

* You should have already [created a Scorecard](/standardize/scorecards) or have an existing Scorecard in mind that you plan to launch an Initiative on; Initiatives are targeted goals tied to a Scorecard. The Scorecard must be published and not in draft mode.
* You must have the `Edit Initiatives` permission.
* [Configure notifications](/configure/settings/notifications) for Initiatives to ensure that the right people are alerted to new Initiatives and approaching deadlines. Learn more about notification types below.

#### Initiative notifications

Expand the tile below to learn more about the different types of Initiative notifications and to ensure you are configuring notifications to be sent to the expected recipient. It is possible to send notifications to entity owners, to team entity owners, or only to the communications channel associated with the entity.

> **Expand to learn more about Initiative notifications**
>
> Users with the `Configure workspace notification settings` permission can configure notifications for Initiatives under [Settings > Notifications](https://app.getcortexapp.com/admin/settings/notifications). These global workspace settings override the [individual toggle that you can enable during Initiative creation](/improve/initiatives#step-1-configure-the-initiatives-basic-details); if someone has disabled the workspace notification option for "Initiative custom scheduled reminders" and "Initiative reminders," then you will not be able to trigger notifications for Initiative reminders via the toggle during creation of the Initiative.
>
> Also note that users must opt in to Initiative-related notifications in their [personal notification settings](/configure/settings/notifications#adjusting-your-personal-notification-subscriptions).
>
> Where a notification is sent depends on the type of notification you enable, as described below.
>
> **Initiative creation notifications**
>
> The "Enable notifications" toggle that appears during Initiative creation does not apply to Initiative creation notifications; it only applies to Custom Initiative reminders. The "Initiative creation" notification is configured under [Settings > Notifications](https://app.getcortexapp.com/admin/settings/notifications).
>
> When an entity is included in a newly-created Initiative (not in draft format), you can configure notifications to be sent based on:
>
> * Users who own the entity: Enable **Users > Initiative creation**.
>   * For the individual user who owns the entity, notifications will be sent to them when an Initiative is launched via email, Slack, or MS Teams, depending on your notification settings.)
> * Team members who own the entity: Enable **Team-based > Initiative creation.**
>   * For the team who owns the entity, notifications will be sent to the team members when an Initiative is launched (via email, Slack, or MS Teams, depending on your notification settings.)
> * The entity's associated Slack channel: Enable **Entity-based > Initiative creation**.
>   * A notification will go to the Slack channel associated with the entity.
>
> **Initiative reminder notifications**
>
> If "Initiative reminder" notifications are enabled in [Settings > Notifications](https://app.getcortexapp.com/admin/settings/notifications), users will receive reminders of pending action items 7 days and 1 day before the due date. This date will also be reflected in action items on the [engineering homepage](/streamline/homepage).
>
> You can configure reminders for approaching deadlines based on:
>
> * Users who own an entity that is included in the Initiative: Enable **Users > Initiative reminders**.
>   * When an entity is part of an Initiative, for the individual user who owns the entity, notifications will be sent to them when an Initiative is launched. Notifications can be sent via email, Slack, or MS Teams, depending on your notification settings.
> * Team members who own the entity: Enable **Team-based > Initiative reminders.**
>   * When an entity is part of an Initiative, for the team who owns the entity, notifications will be sent to the team members when an Initiative is launched (via email, Slack, or MS Teams, depending on your notification settings.)
> * The entity's associated Slack channel: Enable **Entity-based > Initiative reminders**.
>   * When an entity is part of an Initiative, a notification will go to the Slack channel associated with the entity.
>
> **Custom Initiative reminder notifications**
>
> While configuring an Initiative, you have the option of setting of custom timeframes for Initiative reminders:
>
> ![](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/custom-initiative-reminders.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=61b3b80f066c3bc198fd1c53aae31573)
>
> If you enable a custom notification during the creation of an Initiative, you must also have the global workspace notification for "Initiative custom scheduled reminders" enabled.
>
> When these notification settings are enabled:
>
> * If a user owns an entity that is a part of the Initiative, they will receive progress notifications at the interval you specified while configuring the Initiative (as shown in the screen shot above).

### Step 1: Configure the Initiative's basic details

1. Click **Create Initiative** in the upper right corner of the Initiatives page.

   ![](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/create-initiative-scorecard.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=0d174b221345f7fb6c8c4d3b41e4921c)
2. Choose the Scorecard that the Initiative is attached to.
3. Start configuring the form:
   * **Name**: Add a descriptive name, e.g., `Improve DORA metrics by Q3`.
   * **Description**: Enter a description to help make the Initiative's goal clear.
   * **Notifications**: Optionally click the toggle to enable progress notifications for the Initiative's due date. These notifications are sent to users who own an entity that is part of this Initiative if the entity has not yet completed the goal. The first reminder notification will send the next time that 3 p.m. UTC is reached after the notification schedule has been created.
     * Configure how often to send progress notifications. You can also designate one or more reply-to email addresses.
     * Note that [global workspace settings](/configure/settings/notifications#setting-notifications-for-the-entire-workspace) override this option; if all Initiative reminder notifications are disabled globally, then this setting will not trigger reminder notifications.

       ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/initiative-notifications.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=d18765aff4bf28a13afbbe8cf667a623)

> [!TIP]
>
> Progress notifications can enhance both short-term and long-term Initiatives. For example:
>
> * Initiative owners can set daily progress notifications for short-term Initiatives so users have clear goals each day for completing time-sensitive action items.
> * Initiative owners can set bi-weekly or monthly progress notifications for an ongoing, long-term Initiative so users continue to make progress on action items over time.

### Step 2: Define the Initiative's goal

1. In the Initiative creation form under **Define goal,** select the level or rules to prioritize. The levels and rules available are based on the associated Scorecard.

   ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/level-goal.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=9bba80af7d4a045b43a1a311a1e8557e)

   * **Scorecard level**: To satisfy level-based Initiative, owners must meet all of the rules for a level. This is a good option if your goal is to bump all entities up to a similar level on your ladder.
     * For example, to get all entities into a production-ready state, you might use a level-based Initiative to motivate your team to configure PagerDuty and add runbooks for every entity they own by the end of the quarter.
   * **Rules**: Choose this option to focus on specific rules. This may be a better option if you have targeted goals that your team needs to achieve.
     * For example, if most of your entities are already in a production-ready state, you might only need PagerDuty to be set up for some of your entities.
2. Under **Due date**, select a deadline for the Initiative.
   * If notifications are enabled, users will receive reminders of pending action items 7 days and 1 day before the due date. This date will also be reflected in action items on the [dev homepage](/streamline/homepage).

### Step 3: Finish the Initiative configuration

1. Under **Apply to specific entities**, add one or more entity types that this Initiative should apply to. If left blank, it will apply to all entities.
2. Optionally, click to expand **Advanced options** and further refine which entities this Initiative applies to. You can include or exclude groups, or add a CQL expression.
3. Choose whether to keep your Initiative in draft form, visible only to users with the `Edit Initiatives` permission.
   * To keep it in draft form, enable the toggle next to **Save as draft**.
   * Initiatives in draft status will not appear on entity pages or in actions on the [dev homepage](/streamline/homepage), and will not trigger notifications.
4. Click **Create Initiative**.

When you create an Initiative, all of the owners with outstanding action items will be notified by Cortex. Users who own an entity that's already met the rule or achieved the action item will not be notified. Those who own multiple entities will receive a notification outlining any entities with an outstanding action item.

The new Initiative will also appear on the [Initiatives page](https://app.getcortexapp.com/admin/initiatives).

## Edit Initiatives

You must have the `Edit Initiatives` permission.

To edit an Initiative:

1. Navigate to an Initiative page then click **Edit** in the upper right corner.

   ![](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/edit-initiative.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=8201ebf073e743c6a45e2c7132a498c0)
2. Make any desired changes.
3. At the bottom of the page, click **Save Initiative**.

## View Initiatives

You must have the `View Initiatives` permission.

> **View the Initiatives list**
>
> **View the Initiatives list**
>
> To view Initiatives, navigate to [**Scorecards > Initiatives**](https://app.getcortexapp.com/admin/initiatives) in the main nav.
>
> ![Click Initiatives in the main nav.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/initiatives.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=064b5d98245acf107cc14099aeb4d207)
>
> By default, the page displays a list of active Initiatives at your organization, including their description, associated Scorecard, progress level, and deadline. To view expired Initiatives, click the **Expired** tab.

> **View individual Initiatives**
>
> **View individual Initiatives**
>
> From the Initiatives list, click into an Initiative to view its details page.
>
> ![The Initiatives page displays failing entities by default.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/initiative.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=1345740a88f97793b9658c1c9ef5848a)
>
> By default, this page will open to the **Failing** tab, where you can see each entity's progress in the Initiative. Each row displays how many rules out of the total are passing for that entity. Click an entity to expand the view and see which rules are failing:
>
> ![Click an entity to view its failing rules.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/expand-entity-initiative.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=863fbfdc09dfd74d5399f0ac7c4646d5)
>
> Once entities have completed all action items, they will appear under the **Passing** tab.

> **View your Initiative action items**
>
> **View Initiative action items**
>
> You can find all outstanding tasks for Initiatives related to entities you own on the [Engineering homepage](/streamline/homepage) in **Action items**:
>
> ![Click Action items on the dev homepage.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/action-items%20%281%29.jpg)
>
> This section lists the entity, the failing rule, the associated Scorecard or Initiative, the due date (if it's linked to an Initiative), and the priority based on Scorecard level.
>
> By default, action items are sorted by priority level. Tasks with deadlines are sourced from Initiatives; those without deadlines are sourced from failing Scorecard rules.
>
> **Filter and sort action items**
>
> ![Filter and sort in the upper right side of the Action Items section.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/filter-action-items%20%281%29.jpg)
>
> * In the upper right corner of the list, click **Priority** to choose a different sorting method. You can select priority, name, source, or rule.
>
> * To filter by Scorecard, Initiative, or group, click **Filter**.
>
> * To group actions by entity, click Display then enable the toggle next to **Group by entity**.
>
> > [!TIP]
> >
> > Grouping by entity gives a clearer view of how many tasks are associated with each entity, giving developers an easy target for improvements.

## Initiative examples

See the examples below to learn common ways our customers drive organizational change with Initiatives.

> **Ensure services have active on-call rotations in 30 days**
>
> Your Scorecard may have a rule that measures whether each service has an on-call rotation configured through PagerDuty.
>
> To make sure that all services actually have active on-call rotations within 30 days, you could create an Initiative with a due date in 30 days.
>
> * Entity owners will see the Initiative tasks listed on their [engineering homepage](/streamline/homepage) under "Tasks."
> * If [notifications are enabled](/improve/initiatives#expand-to-learn-more-about-initiative-notifications), reminders will be sent to Slack or MS Teams when the Initiative is due in 7 days and again when the Initiative is due in 1 day.

> **Complete 'Bronze' level for Incident Preparedness in the next 2 weeks**
>
> While viewing your Incident Preparedness Scorecard, you notice that the Bronze level rules have not yet been met for many entities:
>
> ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/incident-initiative-example.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=d0b68e02130ffbaff725e26ae19d6067)
>
> To encourage your team to reach the baseline standards for their entities, you decide to create an Initiative. It includes:
>
> * A goal of completing the Bronze level items in your Scorecard by the next two weeks
> * Notifications enabled, with progress notifications configured to be sent daily to users
>
> ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/incident-prepared-initiative.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=8c1b42e5c86afe5657767ab4f0ea12b6)

> **Ensure services have CI workflow for migration process by end of month**
>
> Your organization is migrating to GitHub Actions to standardize CI/CD and get better visibility into engineering processes. You have already created a Scorecard to track the migration process. It includes rules that check whether repositories have a `.github/workflows/` file or not, whether they have a CI workflow, whether they use dependency caching, and more.
>
> To motivate your teams to get the migration finished more quickly, you create an Initiative connected to your migration Scorecard. The Initiative is for the rule "Has CI workflow":
>
> * **Initiative name**: Ensure services have CI workflow by November
> * **Description**: To move our migration forward, let's work toward ensuring services have a CI workflow this month.
> * Notifications are enabled to ensure that the entity owners are alerted of this action item. In the example screen shot below,, the progress notifications are configured to be sent once a day.
>
>   ![Basic configurations are in place for an Initiative called 'Ensure services have CI workflow by November.'](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/migration-init-example.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=0315131a19faed5b66747501551549e3)
> * **Define goal**: The goal is set to the "Has CI Workflow" rule and has a due date of November 1.
>
>   ![The goal is set to the 'Has CI Workflow' rule and has a due date of November 1](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/migration-init-goal-example.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=a086c364370044b9a3fa4c96791f8989)

> **Accelerate migration to K8s**
>
> Cortex customer LetsGetCheck cut their Kubernetes migration timeline from 24 months down to 16 months by targeting goals with Initiatives. [Read the full case study here](https://www.cortex.io/case-studies/letsgetchecked).
>
> If you are migrating to Kubernetes, you might follow a process similar to the following example:
>
> 1. Launch a Scorecard to measure Kubernetes readiness.
>    * It might include rules such as "Has a Helm chart," "Uses supported base image," "Runs in cluster."
> 2. Several months in to your migration, you notice that the team isn't making progress in the timeframe you expected. They have completed most of the Bronze and Silver level rules in the Scorecard, but many entities have not achieved the Gold level rules yet.
> 3. You decide to launch an Initiative connected to the Scorecard to ensure that you meet your business goals of being migrated by the end of the fiscal year:
>    * **Title**: Accelerate Kubernetes migration
>    * **Description**: Track and accelerate migration of services to Kubernetes
>    * **Define goal**: Complete the Gold level of the Kubernetes Readiness Scorecard, due in 2 months.
>      * This effectively asks your developers to accomplish all of the Scorecard's rules by the deadline you specify.
>    * **Notifications**: Enable notifications and send progress updates every week.
> 4. If an entity has not achieved the rules in the Gold level of the Scorecard, then that entity's owner will see action items listed on their [engineering homepage](/streamline/homepage) and they will automatically receive a weekly progress update from the Initiative.

> **Ensure continuous SOC-2 compliance**
>
> If you are working toward organizational SOC-2 compliance, you might follow a process similar to this example:
>
> 1. Launch a SOC-2 compliance Scorecard with rules reflecting control requirements.
>    * Cortex has a pre-built SOC-2 compliance Scorecard template available in-app.
> 2. Attach a SOC-2 readiness Initiative to the Scorecard. In the Initiative, require the Gold level rules of your Scorecard to be completed for every service by the end of the quarter.
> 3. After completing the SOC-2 audit, reuse the same Scorecard and Initiative frameworks for the next cycle.
>    * This helps you stay prepared and avoid the last-minute scramble every year.

> **Ensure AWS resources are off EOL versions by specified date**
>
> You can use an Initiative to manage and drive an AWS End-of-Life (EOL) migration by combining resource cataloging, Scorecards, and Initiative tracking. Here’s how you would approach it:
>
> 1. Ensure all relevant AWS resources (such as RDS, Lambda, ElastiCache, etc.) are imported into your resource catalog. Learn about [importing AWS entities here](/ingesting-data-into-cortex/integrations/aws).
> 2. Set up a Scorecard to automatically audit and score your AWS resources for EOL risk. This helps you quickly identify which resources need to be updated or migrated.
> 3. Create an Initiative in Cortex linked to your EOL scorecard. Set a clear target for the title (e.g., “All AWS resources must be off EOL versions by \[date]”).
>    * If a resource is not off the EOL version, then that resource's owner will see this as an action item listed on their [engineering homepage](/streamline/homepage). If you enabled notifications, they will receive reminders as the deadline approaches.
> 4. Use [reports](/improve/reports) to monitor progress in real time. Owners of non-compliant resources will receive notifications and reminders, and you can track which teams or services are lagging behind. This ensures accountability and helps drive the migration to completion.\\

> **Manage package upgrades quickly**
>
> Cortex Initiatives provide a structured, automated, and transparent way to manage package upgrades, ensuring visibility, accountability, and timely completion across all affected services. For example, if you need to migrate everyone from version 1 to version 1.1 of an internal library, you can set up an Initiative to track and drive the upgrade to completion:
>
> 1. Launch a Scorecard or CQL report: Identify which services are on the old version and which have already upgraded. This allows you to automatically audit the state of package usage across your organization.
> 2. Launch an Initiative on the Scorecard with a name like "100% of services must be on version 1.1 by end of quarter."
>    * If an entity has not achieved the rules specified in the Initiative, then that entity's owner will see action items listed on their [engineering homepage](/streamline/homepage) reminding them to get their service upgraded.
> 3. Monitor progress in real time via [reports](/improve/reports), where you can track which teams or services are lagging behind. This ensures accountability and helps drive the migration to completion.

## Troubleshooting and FAQ

#### Why didn't I receive a notification for an Initiative?

This can happen if your Initiative was created in draft format. When the Initiative is published, it will start to trigger [notifications](/configure/settings/notifications). You should also ensure that you enabled the right notification type for your use case. For example, if you only enable the Entity-based option for Initiative reminders, then notifications will go only to the channel associated with the entity; the entity owners would not necessarily be notified. Learn more about [Initiative notifications](/improve/initiatives#initiative-notifications) above.


# Creating issues based on Initiatives
Source: https://docs.cortex.io/improve/initiatives/issue-config



By integrating your issue tracking tools with Cortex, you can take Initiatives and action items to the next level. Through integrations with tools like Jira, ClickUp, Azure DevOps, and GitHub, you can automatically create issues for outstanding action items based on Initiatives in Cortex.

## How to create issues based on Initiatives

To automatically create issues based on Initiatives, you’ll need to set up an issue configuration. An issue configuration combines a set of filters and a configuration for an issue tracking tool integration. For example, an issue configuration could comprise the entity types that the config applies to and the Jira projects the issues should go into. This flexibility allows managers to be sure that issues for their teams end up in the right place.

### Prerequisites

An integration with an issue tracking tool (Jira, ClickUp, Azure DevOps, or GitHub) must be set up before you can create an issue configuration.

### Create an issue configuration

When using issue configurations, think about what makes the most sense for your team. You can create just one configuration for an Initiative, so that all Cortex-created issues are directed to a single project for team members to pick up from there.

There’s also no limit to the number of configs you can add. By setting up multiple configurations, you can automate which project each set of issues belongs to, minimizing the manual work involved in managing issues.

Expand the tabs below for instructions on creating an issue for each issue tracking tool option.

> **Azure DevOps**
>
> 1. Navigate to the Initiative you want to work with. Under its **Issue configs tab**, click **Create issue config**.
>
> ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/issue-config-tab.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=1acba909067307c831756b3d900dadb3)
>
> 2\. Configure the issue form:
>
> * **Issue config name**: Enter a descriptive name for the issue configuration.
>   * The name can help users understand which team the issue belongs to and the project the issues should be assigned to.
> * **Integration**: Select Azure DevOps.
> * **Azure DevOps configuration:** Select the Azure DevOps configuration alias you want to use if you have multiple in your workspace.
> * **Work item type**: Select a work item type.
>   * Azure DevOps [work item types](https://learn.microsoft.com/en-us/azure/devops/boards/work-items/about-work-items?view=azure-devops\&tabs=agile-process) are designed to distinguish and categorize different types of work to introduce more structure into the process.
> * **Sub-item type**: Select a sub-item type.
>   * Note that the sub-item type can only apply to child issues.
>   * Additional optional fields differ depending on the issue type and sub-item type selected and your Azure DevOps instance requirements for new issues.
> * **Apply to specific entities**: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
>   * **Advanced options**: Further refine entity selecting by applying filters for groups or a CQL expression.
>
> 3. Click **Create issue config**.

> **ClickUp**
>
> Note that additional fields differ depending on your ClickUp instance requirements for new issues. If fields are required in ClickUp, you must populate these fields for your issue configuration.
>
> 1. Navigate to the Initiative you want to work with. Under its **Issue configs tab**, click **Create issue config**.
>
> ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/issue-config-tab.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=1acba909067307c831756b3d900dadb3)
>
> 2\. Configure the issue form:
>
> * **Issue config name**: Enter a descriptive name for the issue configuration.
>   * The name can help users understand which team the issue belongs to and the project the issues should be assigned to.
> * **Integration**: Select ClickUp.
> * **Inherit project from entity YAML**: When this toggle is enabled, the issue will use the ClickUp list defined in a given entity's YAML.
> * **Default space**: Choose a space where the Cortex-created issues will be directed.
> * **List**: Select a ClickUp list.
> * **Tag**: Select a tag.
> * **Priority**: Select a priority for this issue.
> * **Add entity tag**: Toggle this setting on to add an entity tag to the issue.
> * **Apply to specific entities**: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
>   * **Advanced options**: Further refine entity selecting by applying filters for groups or a CQL expression.
>
> 3. Click **Create issue config**.

> **GitHub**
>
> 1. Navigate to the Initiative you want to work with. Under its **Issue configs tab**, click **Create issue config**.
>
> ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/issue-config-tab.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=1acba909067307c831756b3d900dadb3)
>
> 2\. Configure the issue form:
>
> 1. **Name**: Enter a descriptive name for the issue configuration.
>
> * The name can help users understand which team the issue belongs to and the project the issues should be assigned to. **Use issue defined in entity yaml**: When this toggle is enabled, the issue will use the GitHub issue defined in a given entity's YAML.
>
> 2. **Integration**: Select GitHub.
>
> 3. **Labels**: Select or create a label.
>
> 4. **Apply to specific entities**: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
>
> * Advanced options: Further refine entity selecting by applying filters for groups or a CQL expression.
>
> 3. Click **Create issue config**.

> **Jira**
>
> 1. Navigate to the Initiative you want to work with. Under its **Issue configs tab**, click **Create issue config**.
>
> ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/issue-config-tab.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=1acba909067307c831756b3d900dadb3)
>
> 2\. Configure the issue form:
>
> * **Issue config name**: Enter a descriptive name for the issue configuration.
>   * The name can help users understand which team the issue belongs to and the project the issues should be assigned to.
> * **Integration**: Select `Jira`.
> * **Inherit project from entity YAML**: When this toggle is enabled, the issue will use the Jira project defined in a given entity's YAML.
>   * You will be able to select a fallback default project, and choose the issue type. If that issue type does not exist in the project defined on the entity's YAML, Cortex will fallback to a 'task' type.
> * **Default Jira project**: Select the Jira project where Cortex-created issues will be directed.
> * **Jira configuration:** Select a Jira configuration alias.
>   * If you have multiple Jira integrations in your workspace, select the one you want to set up the issue config in.
> * **Issue type**: Select a Jira issue type.
>   * Jira [issue types](https://support.atlassian.com/jira-cloud-administration/docs/what-are-issue-types/) are designed to distinguish and categorize different types of work to introduce more structure into the process.
>   * Additional optional fields differ depending on the issue type selected and your Jira instance requirements for new issues. If fields are required in Jira, you must populate these fields for your issue configuration.
> * **Subtask issue type** - Choose whether Cortex creates a Jira subtask for each action item in the Initiative.
>   * **Create a subtask for each action item** - When this toggle is enabled, Cortex creates a parent issue plus one subtask per action item. Select a **Subtask issue type** for those subtasks.
>   * The subtask issue type only applies to child issues.
>   * Additional optional fields differ depending on the subtask issue type you select and your Jira instance's requirements for new issues. If fields are required in Jira, you must populate them for your issue configuration.
> * When this toggle is disabled, Cortex creates only the parent issue and adds the action items to its description. This is useful when an Initiative has a single rule, where a subtask would duplicate the parent issue.
> * **Apply to specific entities**: Optionally choose to include or exclude specific entity types. By default, the issue will apply to all entities in an Initiative.
>   * **Advanced options**: Further refine entity selecting by applying filters for groups or a CQL expression.
>
> 3. Click **Create issue config**.\\

### Automatic issue creation in your issue tracking tool

After saving the issue configuration, Cortex will automatically create a corresponding issue in your issue tracking tool for you. Cortex will create a single parent task for each entity, and each failing rule will be created as a subtask. This makes it easy for you to track the aggregate data while maintaining visibility into all failing rules.

## Closing and reopening issues

Once an entity passes an action item, Cortex will attempt to close out the corresponding issue. If Cortex is unable to close a issue, a comment will be left notifying you that an action item is now **Passing**. Cortex will go through this process any time a Scorecard is refreshed and rules are reevaluated.

If a new rule is added to an Initiative, a new issue will be created opened based on the configuration you’ve defined. Cortex will also reopen issues for existing configurations if a passing action item reverts to failure, including issues that have been manually closed by a user.

## Viewing and editing issue configurations

You can modify or delete your configurations.

To edit an existing configuration:

1. Navigate to the Initiative and click the **Issue configs** tab.
2. On the right side of the issue config, click the 3 dots icon, then click **Edit config**.

   ![Next to an issue config, click the 3 dots then select 'Edit config.'](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/edit-issue-config.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=ac30848dd48bd66a4705e9eaf7533622)
3. Make changes to the configuration.
   * The integration option will be grayed out, but you can edit the other fields.
4. Click **Save issue config**.

To delete an existing configuration:

1. Navigate to the Initiative and click the **Issue configs** tab.
2. On the right side of the issue config, click the 3 dots icon, then click **Delete config**.


# Configuring OpEx Review
Source: https://docs.cortex.io/improve/opex-review/configuring-opex

Steps for configuring OpEx Review

PUBLIC BETA

You control what metrics the agent pulls and how often it generates an analysis. Add the metrics you want to track under each [DRIVE pillar](/solutions/drive-framework/the-drive-pillars) then drag to reorder them or edit and remove any metric from its row. Choose which parts of your organization the report covers and set a generation cadence. Save the configuration, and the agent starts generating reports on that schedule.

> [!NOTE]
>
> As a Public Beta feature, OpEx Review is still evolving, and some options may change. Share feedback with your Customer Success Manager or through the in-product feedback controls.

## Configuring OpEx Review

`Admins` and users with the `Configure OpEx` permission can configure OpEx Review.
Before you run OpEx Review, decide which metrics it should include. Cortex pre-populates some metrics based on the integrations you've installed: deployment frequency, cycle time, incident frequency, and time to resolution. Follow the steps below to replace these metrics or select new ones.

1. From the main sidebar, select **OpEx Review**.
2. In the upper-right corner of the page, click **Edit**.
3. On the **Edit report** page, configure the following:
   1. In the **Set report scope** section:
      1. **Report type** - Select a report type from the dropdown. This controls how the report is organized and which teams get a separate report of their own.
         1. **Team report** (default) - Metrics are broken down by team throughout the report. All teams in your workspace are included by default, so you can compare teams and drill into any of them from one place. You don't need to select teams individually to see per-team metrics. The report breaks down by team either way. Select **Specific teams** when you want one of the following:
            * To narrow the report to part of your organization, choose a single high-level team, e.g. Engineering. Its child teams are included automatically and roll up into it.
            * To give teams their own reports, choose up to 10. Each one gets a dedicated report with insights written about that team, alongside the aggregate report covering all of them.
         2. **Domain report** - Works the same way, organized by domain instead of team. All domains are included by default. Select **Specific domains** when you want one of the following:
            * To narrow the report to part of your organization, choose a single high-level domain. Its child domains are included automatically and roll up into it.
            * To give domains their own reports, choose up to 10. Each one gets a dedicated report with insights written about that domain, alongside the aggregate report covering all of them.
   2. In the **Choose metrics** section:
      1. Metrics are grouped into six sections: Overview (Are there things we want to highlight?), then the five DRIVE pillars—Delivery, Reliability, Initiatives, Vigilance, and Efficiency. Overview sits above the pillars and holds what you want read first. Cortex starts you off with default metrics for the Delivery and Reliability pillars when the required integrations are installed. Adjust those defaults and add metrics to any section you want to track.
         1. Click **Add metric**. The **Metric definition** side panel opens.
            1. Select a metric from the dropdown. You can choose any out-of-the-box Eng Intelligence metric, custom metric, or Scorecard. If you have a Datadog integration, you can also add an SLO summary to the report alongside your metrics.
            2. Click **View metric**. The metric is added to the pillar.
            3. If you're running a team report, an extra option appears in the side panel. Select **Entity owner (Team)** or **Team (Author)** to define what "team" means for each metric. You can set this per metric, so a single report can use ownership for reliability and authorship for delivery.
               * Choose **Entity owner (Team)** when you're asking about the health of what a team owns. This is usually the right choice for reliability and quality metrics, where you want incidents and failures to land with the team responsible for the service, regardless of who touched it last.
               * Choose **Team (Author)** when you're asking about what a team is producing. This is usually the right choice for delivery metrics like deployment frequency and cycle time, where you want to see a team's own output rather than activity on their services by others.
               * **Example**
                 * An engineer on the Platform team opens a pull request against a service owned by the Payments team.
                   * With **Team (Author)**, the PR counts toward Platform.
                   * With **Entity owner (Team)**, it counts toward Payments.
            4. Optionally, select an **Operation** to set how the metric's data points are combined into a single value for the report period. Options include **Average**, **Sum**, **Max**, **Min**, **Median**, and **P95**.
               * For custom metrics, you can also select **Latest**. Instead of combining data points across the report period, **Latest** returns the most recent data point within it. If the period has no data points, the metric shows no value.
               * Use **Latest** for status-style custom metrics where only the current state matters, e.g. a metric that records `1` when a team's on-call rotation is set up and `0` when it isn't. Averaging that kind of metric across the period would blur the team's actual current state.
               * **Latest** isn't available for out-of-the-box Eng Intelligence metrics or Scorecards.
            5. Optionally, add **filters** to narrow this metric's query. Because filters are per metric, you can add the same metric more than once and split each copy differently, e.g. Sev 0 incidents in one card and Sev 1 in another.
         2. To reorder metrics within or between pillars, drag them by the **grip icon**. To edit or remove a metric, click the **pencil** or **trash icon** in its row.
         3. Repeat as necessary.
   3. In the **Set schedule** section:
      1. Select how often the report should be generated. By default, reports are set to generate every two (2) weeks on Monday.
         1. **Start date** - The date report generation begins.
         2. **Report period** - How much data prior to each run date the report includes, in days or weeks. This also sets the cadence, so a two-week period generates a report every two (2) weeks.
         3. **Repeat on** - The day of the week the report generates.
4. Do one of the following:
   1. Click **Generate now** to run the report immediately. The configuration is saved automatically. A confirmation window opens showing the run date and the period the report covers. Click **Generate**.
   2. Click **Save and close** to save the configuration without running a report.

> [!NOTE]
>
> Manually generated reports can only be produced once a day. The limit resets at midnight UTC. Scheduled runs do not count against the limit. If a run is already in progress, **Generate now** is unavailable until it completes.

### What happens after you save

The agent runs analyses on the schedule you set, beginning on your selected start date. You don't need to do anything between runs.

Each report covers the window ending on its run date and extending back by the report period value. Because that same value sets the cadence, consecutive reports run back to back with no gaps or overlap. The report summary in the left pane of the **Edit report** page shows the exact dates the next report will cover.

![The 'Report summary' section.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-report-overview.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=c9714dfd1dc7d28916652a0f978c6d6d)

Report dates are shown in UTC so they match the dates queried, and scheduled runs start at midnight UTC on the day you choose.

While the agent generates the report, a status banner appears at the top of the OpEx Review page showing the period the upcoming report will cover. When generation finishes:

* If you started the run with **Generate now**, the report opens automatically.
* If it was a scheduled run, click **View latest report** in the banner.

### Changing the configuration later

You can edit the configuration at any time. However, the change does not take effect the same way in every view:

* The **summary** of an already-generated report doesn't change. It's a snapshot of what the configuration tracked when that report ran. Newly added metrics appear in the summary starting with the next generated report.
* The **Metrics by** and any custom dashboard tabs rebuild from your current configuration, so past reports show your new metrics there too.

Once Cortex generates your first report, see [Using the OpEx Review report](/improve/opex-review/using-opex) to read the executive briefing, break metrics down by team, and share the report.


# OpEx Review FAQ
Source: https://docs.cortex.io/improve/opex-review/opex-faq

Frequently asked OpEx Review questions

PUBLIC BETA

These answers cover common questions about how OpEx Review works, what data it uses, and how that data is stored and secured.

## Getting started

> **What do I need to get started?**
>
> To get started, Cortex recommends configuring at least 1-2 metrics in Delivery, 1-2 metrics in Reliability, and 1-2 Scorecards in Initiatives or Vigilance. This requires deployment, version control (for pull requests), and incident data flowing into Cortex from the following supported tools:
>
> | Pillar | Metric | Supported tools | Fallbacks |
> | - | - | - | - |
> | Delivery | Deployments | A CI/CD pipeline that calls the [Cortex deploys API](/api/rest/deploys) | Merged pull requests (version control), story points completed (Jira) |
> | Delivery | Cycle time | GitHub or GitLab | Time to first review (Bitbucket and Azure DevOps), work item lead time (Jira) |
> | Reliability | Incidents | PagerDuty or incident.io | Work items created, filtered by `type = incident` (Jira) |
> | Reliability | Time to resolution | PagerDuty or incident.io | Change failure rate (from deployments), though it's a less reliable signal |
> | Initiatives or Vigilance | 1-2 Scorecards | Scorecards configured in Cortex | None |
>
> For setup steps, see [Configuring OpEx Review](/improve/opex-review/configuring-opex).

## Data sources

> **What data feeds the report?**
>
> The report uses all datasets available in [Eng Intelligence](/improve/eng-intelligence):
>
> * Version control
> * Deployments
> * Incidents
> * Work items
> * AI tooling
> * Custom metrics
> * Scorecard scores
>
> Additional Cortex data may become available to OpEx Review over time.

> **How are production and non-production deployments distinguished?**
>
> Deployments can include optional environment information, which is used to separate production metrics from non-production metrics. To send environment information with your deployments, use the [Cortex deploys API](/api/rest/deploys).

> **Does generating a report query my source systems or affect rate limits?**
>
> No. Cortex ingests and stores data from your integrations, and the report queries that stored data rather than your source systems. Generating a report adds no load or rate-limit pressure on your tools.

> **Will reliability, observability, and security metrics be added?**
>
> Additional Cortex data may become available to OpEx Review over time.

## Data storage and security

> **What data does Cortex store, and how is it secured?**
>
> Cortex stores the engineering metadata it ingests using the credentials you provide. That data is tenant-isolated and encrypted. Cortex maintains SOC 2 and ISO 27001 compliance.

> **Does Cortex store my source code?**
>
> No. Cortex stores engineering metadata and event data, such as pull request, deployment, and work item metadata, Scorecard scores, and trace events. It doesn't store your source code or codebases.

> **How long is data retained?**
>
> Cortex retains out-of-the-box Eng Intelligence metrics for at least 6 months and custom metrics for at least 24 months. If you need a longer retention period, contact your Customer Success Manager.

## How insights are generated

> **How are highlights and concerns identified?**
>
> The agent works through a multi-step process across your engineering metadata and org structure:
>
> * It retrieves your data through structured calls, so every figure traces back to a real query result.
> * It evaluates that data within the DRIVE framework (Delivery, Reliability, Initiatives, Vigilance, and Efficiency).
> * It ties each signal to the teams, services, and domains responsible, using your catalog and ownership data, and rolls results up the way your organization is structured.
> * It compares trends against historical baselines, so the report surfaces meaningful changes rather than normal week-to-week noise.
>
> The result is a prioritized, leadership-ready readout of what mattered most in the period, why it matters, and where to focus.

> **How are AI-generated insights validated to prevent hallucinations?**
>
> Every metric in the report comes from Cortex's query engine through structured calls. Before each report is created, a grounding step checks each AI-generated insight against the underlying data.

> **Which AI provider powers OpEx Review?**
>
> OpEx Review is powered by Anthropic's Claude, using different models for different tasks.

## Using Cortex AI in OpEx Review

> **What can I ask Cortex AI in OpEx Review?**
>
> Cortex AI is built for follow-up questions on whatever metric or insight you're looking at, such as which teams are driving a change, how a metric compares to last quarter, or what a threshold means. Suggested prompts in the chat give you a place to start.
>
> For more examples, see [What you can ask](/improve/opex-review/using-opex-ai-chat#what-you-can-ask).

> **What should I expect from a Cortex AI response?**
>
> Responses are short (typically two to four sentences or a brief bulleted list) and are meant to be discussed in your OpEx meeting. They call out specific teams or services, suggest a next step when there is one, and link to a relevant data source so you can dig in further.
>
> Cortex checks any metric it surfaces against the query engine, but as with any AI-generated summary, it's worth double-checking a number before it drives a decision. For more information, see [What to expect from a response](/improve/opex-review/using-opex-ai-chat#what-to-expect-from-a-response).

## Follow-ups

> **How is the follow-up completion rate calculated?**
>
> The completion rate is the share of follow-ups from prior reports that have been completed. A follow-up added during a review starts counting in the next report, and open follow-ups keep carrying over until they're completed. For more, see ['Follow-ups' tab](/improve/opex-review/using-opex#follow-ups-tab).

> **Does assigning a follow-up notify the assignee?**
>
> No. Assigning a follow-up doesn't yet send a notification and doesn't give the assignee access to OpEx Review. To see the follow-up, they need the `View OpEx` permission. For more, see [Tracking follow-ups](/improve/opex-review/using-opex#tracking-follow-ups).


# Using the OpEx Review report
Source: https://docs.cortex.io/improve/opex-review/using-opex



PUBLIC BETA

Each OpEx Review covers a single reporting period. The **Executive briefing** tab provides a recap narrating what changed across the five DRIVE pillars, and the **Metrics by** tab breaks those same metrics down by team or domain. The **Follow-ups** tab tracks the action items that come out of the review. Your own custom dashboards can be added as additional tabs.

Because each report is tied to a fixed reporting period, you can share a link to the exact report you're viewing, or pull up a past period next to the current one.

> [!NOTE]
>
> As a Public Beta feature, OpEx Review is still evolving, and some options may change. Share feedback with your Customer Success Manager or through the in-product feedback controls.

## Reading a report

Users with the `View OpEx` permission can view a report.

To access a report, select **OpEx Review** from the main sidebar. Under the page title, the header shows when the current report was generated, how often it generates, and when the next report is due.

![View of the OpEx Review page with header highlighted.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-report-generic.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=ddc8f08696c6e1a4ae38593171704ba4)

### Report tabs

#### 'Executive briefing' tab

The agent-generated executive briefing contains an overall summary and insights into each DRIVE metric.

On the **Executive briefing** tab, you'll find an overview of the period's highlights and concerns, plus the option to ask Cortex AI anything about the report.

![The 'Executive briefing' tab in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-exec-briefing-tab.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=62b8fc60826631d255234e83f20ddc56)

The summary includes a short synopsis of the cycle: what improved, what regressed, and where to focus.

#### 'Metrics by' tab

The **Metrics by** tab presents your report's metrics as a table, with one row per team or domain depending on the report's scope, and a column for each metric the report tracks. Unlike the **Executive briefing** tab, the table isn't a snapshot. Cortex rebuilds it from your current report configuration each time you open it, so it always reflects what the review tracks rather than a stale export.

![The 'Metrics by' tab in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-metrics-by-tab.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=71310c66515cd85919c1be048bc23e79)

* Expand a team or domain to see its children and find where a number is actually coming from.
* Click the card title to open the table as a standalone module. The report's dates carry over.

  ![The card title, highlighted, in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-card-title.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=ab3f7897732da581729d80e06c332cbc)
* Click the **Filter** icon in a card's upper-right corner to narrow that card by entity, entity type, group, domain, or entity owner.
* Click any metric value to drill down to the trace view, showing the records behind that number.

  ![A metric value, highlighted, in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-card-value-number.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=530bcc38116dc9518b605074535782ff)

#### 'Follow-ups' tab

The **Follow-ups** tab tracks the action items that come out of your reviews. It splits them into two lists:

* **Added this report** - Follow-ups created since this report was generated. The date range next to the heading runs until the next report.
* **Outstanding follow-ups** - Follow-ups carried into this review: every open follow-up, plus any completed since the previous report was generated.

Above the **Outstanding follow-ups** list, cards show the number of open and completed follow-ups and the completion rate. The completion rate is the share of follow-ups from prior reports that have been completed. A new follow-up starts counting toward the completion rate in the next report. Click the **Open follow-ups due** or **Completed follow-ups** card to show only those follow-ups in the list.

Each list shows the follow-up, its assignee, who created it and when, and the review cycle it's tracked against. To find a follow-up in either list:

* Click **All statuses** to show all, open, or completed follow-ups.
* Click the sort control to sort by assignee, creator, created date, or review cycle. The list is sorted by review cycle by default.
* Click **Filter** to narrow the list by assignee, creator, or review cycle.
* Use the search bar to find a follow-up by its text.

To add and manage follow-ups, see [Tracking follow-ups](/improve/opex-review/using-opex#tracking-follow-ups).

### Selecting a reporting period

The dropdown in the upper-left corner of the page lists each report by the dates it covers, with the most recent labeled **Latest**. Select a period to view that report.

![The 'Reporting period' dropdown in the upper-left corner of the page.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-reporting-period-dropdown.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=50072aafbd8d7c88d443d951ef839000)

### Selecting a team or domain

If the report you're viewing is filtered to specific teams or domains, an additional dropdown appears next to the reporting period. Click the dropdown and select one of the following:

* **Aggregate report** - All selected teams or domains rolled up together
* **An individual team or domain** - That group's own narrated summary

If your report covers your whole organization, there's only one report per period. To change which teams or domains a report covers, see [Configuring OpEx Review](/improve/opex-review/configuring-opex).

### Pillars and metrics

On the **Executive briefing** tab, to the right of the summary, metrics are grouped into the **Overview** section and the five DRIVE pillars. Metrics can be KPIs (deployments, incidents, cycle time), Scorecards, or SLOs from Datadog.

![Pillars and metrics, highlighted, in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-pillars-metrics.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=5060b4bc2ab3a0645b888a1cebfec7e9)

For KPIs, each metric card shows:

* The current value for the report period, with the change from the prior period beside it
* A chart of the metric over the last 12 report periods, with completed periods in gray and the report's period in purple
* A shaded band showing the range the metric normally sits in.
* An AI insight interpreting the result

For Scorecards, each metric card shows:

* The distribution of levels of ladder-based scorecards, or the average score for point-based scorecards.
* An AI insight interpreting the result

For Datadog SLOs, each metric card shows:

* How many SLOs are Passing, At risk, Failing, or have No data, as counts and a distribution bar
  * The change in each count since the previous period
  * Click a status, or the summary itself, to open the full SLO list. See Drilling into SLOs.

KPIs and Scorecards also include an AI insight interpreting the result, along with a link to Ask Cortex AI so you can dig into what's behind a trend and ask follow-up questions. See [Digging deeper with Cortex AI](/improve/opex-review/using-opex#digging-deeper-with-cortex-ai) below.

Insights name specific teams and numbers rather than restating the metric. In the example above, the deploy frequency insight identifies which three teams drove the volume and offers a read on whether the dip reflects scope changes or a pipeline problem.

### Drilling into a KPI

On the **Executive briefing** tab, click a metric's value on any card to open a side panel scoped to the report's period and teams.

![A metric's value, highlighted, in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-card-value-drill.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=d090045c3705a536f54ebb220d7021ea)

In the side panel:

* Select the **Explorer** tab to view a chart of the metric over time, with a breakdown table below it.
* Select the **Trace view** tab to view a list of the underlying records behind the number.
* At the top of the panel:
  * Click the date range to adjust it
  * Click **Filter** to narrow the scope
  * Click the **Group by** dropdown to slice the data differently
  * Click the **expand icon** to open the metric in Data Explorer

![The side panel, opened, when a metric value is drilled into.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-side-panel-explorer.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=ce330c570fc6e218e53ddd64a913716f)

> [!NOTE]
>
> Scorecard-backed metrics don't yet support drill-down.

### Drilling into Datadog SLOs

On the **Executive briefing** tab, click any number on the SLO summary to open a side panel listing every SLO the report measured. Clicking a status (Passing, At risk, Failing, or No data) opens the panel already filtered to it.

The list opens sorted by least error budget remaining, so the SLOs closest to breaching are at the top. A blown budget goes negative and sorts above everything healthy.

Each row shows the SLO's name, entity, target, status, and error budget left. Click a column header to re-sort.

At the top of the panel:

* Click Group by to group the table by Service or Group, or leave it on No grouping
* Click Filter to narrow by Status or Service
* Use Search SLOs to find an SLO by name
* Click the SLO Name to open the SLO in Datadog

> [!NOTE]
>
> The panel reads the SLO data captured when the report generated, so the numbers match the report rather than the vendor's current state.

> [!NOTE]
>
> Scorecard-backed metrics don't yet support drill-down.

### Digging deeper with Cortex AI

When a metric raises a question the report doesn't answer, ask Cortex AI without leaving the report.

On the **Executive briefing** tab, ask Cortex AI directly from the summary area on the left or click **Ask Cortex AI** on a metric card. Enter your question in the Ask Cortex AI field, then press **Enter**.

!['Ask Cortex AI', highlighted at the bottom of the summary and in a metric card.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-ask-cortex-ai.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=ebb7eb4da48fd2ca59e02e6f14a9c242)

Cortex AI can query further breakdowns by team, entity, or time period, so it isn't limited to the insight you started from. For what you can ask and what to expect from a response, see [Using Cortex AI in OpEx Review](/improve/opex-review/using-opex-ai-chat).

### Sharing a report

The **Share** button copies a link to the exact report you're viewing, including the reporting period, the team or domain selected, and the tab you're on.

1. Open the report, period, and team you want to share.
2. Click **Share** in the upper-right corner of the page. The link is copied to your clipboard.

   ![The share icon in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-share-button.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=5b2bd807d9d9d030098175f9bdb2dfdb)

Anyone you share the link with needs the `View OpEx` permission to access the report.

## Commenting on a report

Comments let your team discuss a report right next to the numbers. You can comment on the summary, a highlight or concern, or any metric card, then reply in threads, mention teammates, and react with emoji. Each reporting period's report keeps its own comments.

Users with the `View OpEx` permission can read comments. To add, reply to, or resolve comments, you also need the `Edit OpEx Comments` permission. Managers and admins have it by default.

### Adding a comment

1. On the **Executive briefing** tab, click the **comment icon** next to the summary, a highlight or concern, or in the upper-right corner of a metric card. If an item already has comments, the icon shows how many.
2. Enter your comment. To mention a teammate, team, entity, Scorecard, or Workflow, type `@` and select it from the list. You can also include links.
3. Click **Comment**.

Each new comment starts its own thread, and an item can have several threads. Threads appear beside the item they belong to.

### Replying and reacting

* To reply to a thread, click **Reply** below it.
* To react to a comment, hover over it, click the **Add reaction** icon, then select an emoji. To add your own reaction to an existing one, click that reaction.
* If a thread has a lot of replies, click **Show replies** to expand it.

### Managing a comment

Hover over a comment, then click the **More actions** icon to see what you can do with it:

* **Share** - Copies a link to the comment.
* **Edit** - Updates your comment. Edited comments are labeled **(edited)**.
* **Delete** - Removes your comment.

You can only edit or delete comments you wrote. If you delete a comment by mistake, click **Undo** in the confirmation that appears.

### Resolving a thread

When a discussion is settled, hover over the thread's first comment and click **Resolve**. Resolved threads move to the **Resolved** tab in the **Comments** panel. To reopen a thread you just resolved, click **Undo** in the confirmation that appears.

### Viewing all comments on a report

Click **Comments** in the upper-right corner of the report to see the latest comments on the report, then click **Show all** to open the **Comments** side panel.

In the side panel, you can:

* Filter comments by author with the **All authors** dropdown.
* Search comment text.
* Switch between the **Open** and **Resolved** tabs.

Unread comments are marked with a dot.

### Getting notified about comments

Cortex can notify you when someone mentions you in a comment, and when there's activity on a thread you're part of. Both are on by default. Follow the steps below to choose which of these you get.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Preferences** section, then select **My notifications**.
4. From the **Personal** tab, scroll to the OpEx section, then adjust the settings. For more information, see [Notifications](/configure/settings/notifications#adjusting-your-personal-notification-subscriptions).

If you get a comment notification in Slack, you can reply to it in Slack. Your reply is posted to the thread as a comment.

## Tracking follow-ups

Use follow-ups to capture the action items that come out of a review, assign an owner, and check on them at the next review.

Users with the `View OpEx` permission can see follow-ups. Users with the `OpEx comments` permission can add, edit, complete, reopen, and delete them.

**To add a follow-up**:

1. From any tab of the report, click **Add follow-up**.
2. Enter a description of the action item.
3. Optionally, assign it to anyone in Cortex and add a link, such as a ticket or doc.
4. Click **Save**.

> [!NOTE]
>
> Assigning a follow-up doesn't notify the assignee or give them access to OpEx Review. To see the follow-up, they need the `View OpEx` permission.

**To manage a follow-up**:

On the **Follow-ups** tab, find the follow-up, then do any of the following:

* **Edit** - Change the description, assignee, or link.
* **Complete** - Mark the action item as done.
* **Reopen** - Move a completed follow-up back to open.
* **Delete** - Remove the follow-up from the review.

Open follow-ups stay on the list from one review to the next, and each shows how many reviews it has carried over.

## Managing dashboard tabs

Users with the `Configure OpEx` permission can change the report's tabs.
You can add your own charts, KPI cards, and modules by pulling in any existing custom dashboard as a tab, so everything the meeting needs lives on one page. Dashboard tabs stay pinned to the report's period, but the data inside them is always current, not a snapshot.

![Custom tabs in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-additional-tabs.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=5fb3f7c643a88f750d7fd0c03e15bd48)

**To add a dashboard tab**:

1. Click the **gear icon** in the upper-right corner of the page.

   ![The gear icon in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-gear-icon.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=e577762187408e0bcef33f33b34c94aa)
2. In the **Edit tabs** side panel, click **Add dashboard**.
3. Search for and select the dashboard you want to add.
4. Drag a tab by its grip icon to reorder.
5. Click **Apply to report**.

**To manage a dashboard tab**:

1. Click the **gear icon** in the upper-right corner of the page.

   ![The gear icon in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-gear-icon.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=e577762187408e0bcef33f33b34c94aa)
2. In the **Edit tabs** side panel, click the **overflow menu icon** next to the tab you want to manage.
3. Do any of the following:
   1. **Edit dashboard** - Opens the dashboard in Eng Intelligence for editing.
   2. **Rename dashboard** - Changes the dashboard and tab name.
   3. **Share dashboard** - Copies a link to the dashboard. To share the whole report instead, click **Share** in the upper-right corner of the page.
   4. **Duplicate dashboard** - Creates a copy and adds it as a new tab.
   5. **Remove dashboard** - Removes the tab from the report. The dashboard itself isn't deleted.


# Using Cortex AI in OpEx Review
Source: https://docs.cortex.io/improve/opex-review/using-opex-ai-chat



RESEARCH PREVIEW

Cortex AI is Cortex's AI-powered chat assistant. It answers questions about your engineering data in plain language, using the same data that powers your Scorecards, dashboards, and reports. During an OpEx meeting, leaders often ask questions that no one in the room can answer on the spot, like which team is driving a spike or how a metric compares to last quarter. Normally, those questions become post-meeting follow-ups, and the discussion loses momentum. Cortex AI lets you ask the question and get an answer without leaving the report.

> [!WARNING]
>
> **Cortex AI is not limited to the entities you can see**
>
> * Anyone with the Enable AI Chat permission can ask about any metric or scorecard score for any entity in your workspace, including ones hidden from them elsewhere in Cortex.
> * Your own conversations stay private.
>
> ​Treat the `Enable AI Chat` permission as access to your organization's engineering data as a whole, and grant it accordingly.

> [!NOTE]
>
> **Cortex AI chat is in Research Preview**
>
> * Responses can be slow, especially for questions spanning many teams or entities.
> * Not all Cortex data is reachable from chat yet, so it can't answer every question about your organization.
> * It can't take action on your behalf. It won't create or edit Scorecards, Initiatives, Dashboards, or Workflows, and it won't change the report's content or filters.
>
> We're actively working on improvements. Share feedback with your account team or through the in-product feedback controls.

## Accessing Cortex AI

You can chat with Cortex AI from the summary section on the **Executive briefing** tab or from a metric card.

`Admins` and users with the `Enable AI Chat` permission can access Cortex AI.

**To access Cortex AI via the summary section**:

1. From the main sidebar, select **OpEx Review**.
2. From the **Executive briefing** tab, locate the summary section on the left side of the page.
3. At the bottom of the summary, do one of the following:
   1. Select a pre-populated question.
   2. Enter your question in the **Ask Cortex AI** field, then press **Enter**.

      ![Cortex AI options at the bottom of the summary, in OpEx Review.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-cortex-ai-summary.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=09b18dda8f872b933d5af621b693f174)

**To access Cortex AI via a metric card**:

1. From the main sidebar, select **OpEx Review**.
2. From the **Executive briefing** tab, locate the metric card you want to dig into.
3. At the bottom of the card, click **Ask Cortex AI**. The side panel opens with the metric summary pre-populated.

   ![Opex Ask Cortex Ai (1)](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/opex-ask-cortex-ai%20\(1\).png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=99715e2f46e8dcc7882b7d70a579bed4)
4. Do one of the following:
   1. Select a pre-populated question.
   2. Enter your question in the **Ask Cortex AI** field, then press **Enter**.

Cortex AI has access to the same data behind the insight, plus the ability to query further breakdowns, such as by team, entity, or time period, so it isn't limited to just restating the insight you started from.

Each chat is tied back to the metric it came from. If you open the panel again later, or view it as a full chat from the Cortex AI section in the main sidebar, you'll see a note showing which report and metric it was forked from, with a link back to that report.

## What you can ask

Cortex AI is built for follow-up questions on whatever metric or insight you're looking at, for example:

* ***Which teams or services are driving this increase?***
* ***How does this compare to last quarter?***
* ***What changed in the last two weeks?***
* Why a specific team's metric moved (for example, ***Why did Platform Engineering's deploy frequency drop?***)
* How two teams or time periods compare
* What a metric or threshold means, useful for less technical leaders in the room

See the [Cortex AI prompt library](/get-started/cortex-ai-assistant/library) for a full list of prompt patterns organized by use case and role.

## Drafting follow-ups with Cortex AI

When a discussion turns into an action item, ask Cortex AI to draft a [follow-up](/improve/opex-review/using-opex#tracking-follow-ups), for example ***Create a follow-up for Platform Engineering to look into the cycle time increase.***

Cortex AI drafts the follow-up as a card showing the action item, the assignee, and the review it will be tracked against. Review the draft, then click **Save follow-up**. Cortex AI doesn't create the follow-up until you save it.

To draft follow-ups in chat, you need the `Edit OpEx Comments & Follow-ups` permission in addition to `Enable AI Chat`.

## What to expect from a response

Answers are intended to be discussed in your OpEx meeting. Responses are typically two to four sentences, or a short bulleted list. Responses are designed to:

* Call out specific teams or services by name where relevant
* Suggest a next step when there is one
* Link to a relevant data source, such as an entity page, filtered view, or Data Explorer, if it helps to dig in further

Cortex checks any metric it surfaces against the query engine, but as with any AI-generated summary, it's worth double-checking a number before it drives a decision.

## Who can see your chats

Your conversations are private to you. Nobody else in your organization can see them, including admins, and they aren't visible to anyone you send the URL to; a conversation link only opens for the person who created it.


# Reports
Source: https://docs.cortex.io/improve/reports



Use reporting in Cortex to track entity performance against [Scorecards](/standardize/scorecards), analyze Scorecard performance over time, and more. Reports apply to published Scorecards in your workspace.

Cortex offers several built-in reports:

* [**Executive**](/improve/reports/executive-report) - A high-level view of owned and unowned entities, deploys, endpoints, and Scorecard performance.
* [**All Scorecards**](/improve/reports/all-scorecards) - An aggregation of Scorecard reports, allowing you to quickly see which entities are meeting standards and which need more attention.
* [**Birds eye**](/improve/reports/birds-eye) - A hierarchy-aware entity performance report that visualizes Scorecard data as a heat map.
* [**Progress**](/improve/reports/progress-report) - A graph showing how performance of a Scorecard has changed over time.
* [**Report card**](/improve/reports/report-card) - A high-level overview of any given Scorecard with the ability to visualize key performance indicators and top or bottom performers.

Cortex also offers [CQL reports](/standardize/cql/cql-reports), allowing you to use Cortex Query Language (CQL) to query raw data in Cortex and build a custom report.

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy course on [Reports](https://academy.cortex.io/learn/course/cortex-reports).

## Reports overview video

In the video below, learn how Scorecards, Initiatives, and Reports can be used together to drive business goals.

[YouTube video player](https://www.youtube.com/embed/oIWbMlK7Qh4)

## Accessing reports

From the main sidebar, expand **Reports** to see the list of available reports:

![The 'Reports' tab in the main sidebar.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/reports-section.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=ba9335c523688a94c18908950922f649)

### Accessing reports from Scorecards

You can also access reports directly from a Scorecard, under the **Reports** tab:

![Click the Reports tab in a Scorecard to access reports.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/reports-in-scorecards.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=ef67ba087ffbdd33f9eb5f41a89b8fd8)

## Troubleshooting and FAQ

See frequently asked questions below.

**Why don't I see all of my expected Scorecards in a report?**

Reports only apply to published Scorecards; they do not apply to draft Scorecards. If a Scorecard does not appear in your report, check if it's in draft form.


# All Scorecards report
Source: https://docs.cortex.io/improve/reports/all-scorecards



The **All Scorecards report** gives you a consolidated view of performance across multiple Scorecards, so you can quickly see which areas are meeting standards and which need further attention. You can view entity relationships, teams, services, domains, and groups in a hierarchical view, and expand or collapse levels to understand org-wide trends and individual entity performance across multiple Scorecards simultaneously.

> [!TIP]
>
> This report is especially helpful for platform or SRE teams who want to identify which services or domains are consistently out of compliance across different types of standards.

## Using the All Scorecards report

Users with the `View Reports` permission can view and filter the All Scorecards report.

The report is automatically generated when you navigate to the **All Scorecards** page in Cortex.

**To access the All Scorecards report**:

1. From the main sidebar, expand **Reports**.
2. Select **All Scorecards**.

   The report displays entities, their average score across all Scorecards, and their individual scores per Scorecard. Click into a Scorecard to view more information.\


   ![The All Scorecards report in Cortex.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-scorecards.jpeg?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=c7d283dd5d691ba14b66e4f506e1a58e)

> [!NOTE]
>
> **Switching between legacy and new views**
>
> Use the **Switch to legacy view** or **Switch to new view** link below the report header to toggle between experiences.

### Displaying Scorecards

By default, the report displays all published Scorecards. Follow the steps below to customize which Scorecards appear in the list. Your selection is saved and will be remembered the next time you access the report.

1. From the main sidebar, expand **Reports**.
2. Select **All Scorecards**.
3. Click the **Scorecards filter**.\


   ![The Scorecards filter at the top of the Scorecards list.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scorecards-filter.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=8f72fed048d95348a93c43580227843f)
4. Toggle off the Scorecards you don't want to appear in the list.
5. Optionally, if you don't want any Scorecards to appear, click **Show none**.
6. Click **Done**.
7. Optionally, click **Name** to reorder the list in descending alphabetical order.
8. Optionally, click **Display** to toggle off point calculations, e.g. "34/50". Point calculations are shown alongside score percentages in each Scorecard column.

### Grouping Scorecards

By default, the report displays a flat view, though scores can be aggregated hierarchically by grouping on a dimension. Once grouped, expand and collapse levels to navigate the hierarchy. Any entities without the selected relationship defined appear under an ungrouped category.

Available grouping options depend on your Scorecard and catalog configurations. For example, entity relationships appear as grouping options when their children are entities within at least one Scorecard.

**To group Scorecards**:

1. From the main sidebar, expand **Reports**.
2. Select **All Scorecards**.
3. In the upper-left corner, click **Group by**.\


   ![The 'Group by' option in the upper-left corner of the Scorecards list.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scorecards-group-by.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=8d4ce57e800a7a7acdc1c33226da64ad)
4. Select one of the following grouping options:
   1. **Domain** - If selected, only domain entities appear in the list.
   2. **Group** - If selected, Scorecards are listed alphabetically by group.
   3. **Team** - If selected, only team entities appear in the list.
   4. **Individual owner** - If selected, Scorecards are listed alphabetically by owner.
   5. **Relationship** - If selected, Scorecards are listed alphabetically by relationship.

### Filtering the report

To narrow down the content in your report, click **Filter** and select from the following options. Note that filter options depend on your Scorecard and catalog configurations.

1. From the main sidebar, expand **Reports**.
2. Select **All Scorecards**.
3. In the upper-right corner, click **Filter**.\


   ![The 'Filter' option in the upper-right corner of the Scorecards list.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scorecards-filter-icon.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=49b2289b85e6dcd8deb0ac4c6d399f4f)
4. Filter by the following:
   * **Domain** – Filter by one or more domains. The **Include child domains** toggle is enabled by default, so filtering by a parent domain automatically includes its child domains.
   * **Entity** – Filter by specific entities. You can filter for entities within Scorecards or any direct parent of those entities. Filtering is not yet supported for grandparents or other entities higher up in the hierarchy.
   * **Entity Type** – Filter by entity type, i.e. services, resources, or custom entity types.
   * **Group** – Filter by custom groups.
   * **Individual: Owner** – Filter by entity owners.
   * **Level** – Filter by Scorecard level.
   * **Team** – Filter by one or more teams. The **Include child teams** toggle is enabled by default, so filtering by a parent team automatically includes its child teams.

> [!NOTE]
>
> Domain and Team filters work for entities that belong to the selected domains or teams. If your Scorecard includes domain/team entities as their primary entity type, use the **Entity Type** filter to filter for a specific domain/team instead.

### **Understanding scores**

Each Scorecard appears as a column showing score percentages. Entities earn points by passing rules, with each rule weighted based on significance. The score percentage reflects total points earned divided by total possible points.

When viewing individual entity rows, each Scorecard column displays that entity's score percentage. When rows are aggregated (by team, domain, etc.), points are summed across all entities in that group to calculate the aggregate score percentage for each Scorecard.

The total score across all selected Scorecards is calculated by summing points earned across all Scorecards and dividing by the total possible points across all Scorecards.

### Sharing the report

You can share the All Scorecards report:

* **Send a link** - Click **Share** from the report to copy the URL to your clipboard. You can share the link with anyone who has access to view the report in your Cortex workspace.
* **Export as CSV** - In the upper right corner of the page, click **Export CSV** to download a CSV file of the report data. For large reports, click **Send email** to have the CSV delivered to your Cortex login email instead of waiting for the download.


# Bird's eye report
Source: https://docs.cortex.io/improve/reports/birds-eye



> [!NOTE]
>
> Legacy Bird's eye report documentation can be found [here](/improve/reports/birds-eye/legacy-birds-eye-report).

The [Bird’s eye report](https://app.getcortexapp.com/admin/reports/birdseye) provides deep insights into how entities are performing by visualizing Scorecard data as a heat map. This report is designed to give you a complete view of Scorecard performance across your organization and service hierarchies, helping you quickly identify and drill into hot spots.

You can find the Bird's eye report in the main nav under **Reports > Bird's eye**.

## Using the Bird's eye report

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202026-03-23%20at%2012.11.13%E2%80%AFPM.png)

### Applying a grouping

By default, the report shows a flat view. To aggregate scores hierarchically, select **Group by** and choose your rollup dimension: Domain, Group, Level, Team, Individual: Owner, or Entity Relationships. Once grouped, navigate through the hierarchy by expanding and collapsing levels. Entities without the selected relationship defined appear under an ungrouped category.

Available grouping options depend on the Scorecard's entities and your catalog configuration. For example, entity relationships appear as grouping options when their children are entities within the Scorecard.

### Drilling down

Hover over an entity and click the more options menu to:

* Go directly to the entity's details page
* Preview the entity to get score statistics and the result of each rule evaluation
* Focus and clear other entities from your view

### Applying a filter

To narrow down the content in your report, filter your report by Domain, Entity, Entity Type, Group, Level, Team, or Individual: Owner.

Available filter options depend on the Scorecard's entities and your catalog configuration. For\

example, Domain appears as a filter option when your Scorecard contains domains or entities assigned to domains.

* **Domain –** Filter by one or more domains. The "Include child domains" toggle (on by default) ensures child domains are included when filtering by a parent domain.
* **Entity** – Filter by specific entities. You can currently filter for entities within the Scorecard or any direct parent of those entities. Filtering is not yet supported for grandparents or other entities higher up in the hierarchy
* **Entity Type** – Filter by entity type (e.g., services, resources, custom entity types)
* **Failing Rules** – Filter by entities that are failing specific rules within the Scorecard
* **Group** – Filter by custom groups
* **Level** – Filter by Scorecard level (only available if the Scorecard is level-based)
* **Individual: Owner** – Filter by entity owners
* **Team** – Filter by one or more teams. The "Include child teams" toggle (on by default) ensures child teams are included when filtering by a parent team.

> [!NOTE]
>
> Domain and Team filters work for entities that belong to the selected domains or teams. If your Scorecard includes domain/team entities as their primary entity type, use the Entity Type filter to filter for a specific domain/team instead.

### Understanding scores

#### **Point-based Scorecards**

Entities earn points by passing rules, with each rule weighted based on significance. The score percentage shown reflects total points earned divided by the total possible points. When rows are aggregated (by team, domain, etc.), points are summed across all entities in that group to calculate the aggregate score percentage.

#### **Level-based Scorecards**

Levels (such as Bronze, Silver, and Gold) are achieved by passing all rules within that level. Level-based Scorecards display the entity's current level along with its points and score percentage. Aggregated rows show a level distribution visualizing how many entities fall into each level, along with the summed points and score percentage.

### Switch between legacy and new views

Use the *Switch to legacy view* or *Switch to new view* link below the report header to toggle between experiences.

## Sharing the Bird's eye report

You can share the Bird's eye report:

* **Send a link** - Click **Share** from the report to copy the URL to your clipboard. You can share the link with anyone who has access to view the report in your Cortex workspace.
* **Export as CSV** - In the upper-right corner of the page, click **Export CSV** to download a CSV file of the report data.
  * Large reports can take a while to download. While the download is in progress, click **Email me** in the notification in the lower right corner of the page to have the CSV sent to your Cortex login email instead.


# Executive report
Source: https://docs.cortex.io/improve/reports/executive-report



The [**Executive report**](https://app.getcortexapp.com/admin/reports/executive) offers a high-level view of everything happening in your organization — at a glance, you can see services, resources, deploys, [Scorecard](/standardize/scorecards) performance, domains, and teams.

You can find the Executive report in the main nav under **Reports > Executive**.

> [!TIP]
>
> Use this report to answer questions such as: How are we progressing as an organization? Where are our biggest risks? How do we prioritize platform or compliance work?

## Using the Executive report

### Generate an Executive report

A report is automatically generated when you navigate to **Reports > Executive**. By default, the timeframe is set to the last month, but you can [choose a different timeframe](/improve/reports/executive-report#filter-the-report).

### Report overview

The report’s Overview section provides key stats. Click into any of these tiles in the report to view more information:

* The total number of entities
* The number of teams and number of domains
* The number of endpoints
  * This count helps you better understand the network of your dependencies.
* The number of deploys

  ![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/exec-report-deploys.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=00156543a70ed8a4770679efece5d4ee)
* The number of groups
* The number of unowned entities
  * These will display as red when at least one unowned entity exists in your catalog.

![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/executive-report.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=10494fc5fefea831c1183f8592d9ee46)

### Filter the report

While the Executive Report provides a view of your whole organization by default, you have the ability to filter by **Teams** or **Departments**. Click **Filter** in the upper right corner of the page.
By default, the data is displayed for the last month. To change the timeframe, click **Last month** in the upper right corner and select a new range.

### Scorecards section

#### Scorecards overview tab

The Scorecards section gives you a snapshot of the average scores for your organization’s active Scorecards, and Scorecards progress shows you how scores have improved over time.

![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/exec-report-scorecards.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=59c941516ee5507fe6a6dae164294214)

The Leaderboard displays the average Scorecard score for each team; by default, this will display the aggregate of all Scorecards, but you can use the dropdown to view the Leaderboard by specific Scorecards.

#### Scorecards Insights tab

In the Insights tab, see the top-performing entities and the most at-risk entities per Scorecard:

![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/exec-report-insights.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=a653fccf7810aeb67a42da7409b4af10)

### Deploys section

Under Deploys, you can track the number of deploys over time. By default, this will evaluate All deploys, but you can unselect specific deploy groups, such as production, staging, and development.

![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/exec-deploys.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=79e891590ded6efee4e02f4f642c6412)


# Progress report
Source: https://docs.cortex.io/improve/reports/progress-report



The [Progress Report](https://app.getcortexapp.com/admin/reports/progress) shows you how performance on any given Scorecard has changed over time.
You can find the Progress report in the main nav under **Reports > Progress**.

> [!TIP]
>
> Use the Progress report to show how recent process changes or investments have paid off, or where progress has stalled.

## Using the Progress report

### Generate a Progress report

Select a Scorecard from the list, then a report is automatically generated based on that Scorecard.

![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/progress-report.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=c72716864c134c44ffc1462607e200a7)

By default, the report displays data from the last month. To change the time range, click **Last month** in the upper right corner.

### Change the report grouping

By default, the report displays average performance across all rules. You can also group by Team, owner, or group to see how different parts of your organization are performing over time. To change the group, click the **View by** dropdown in the upper left corner.

![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/progress-report-grouping.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=75be20cddcac9b502a8257162b5a2b0a)

When you group, the page displays the data as a line graph and as a table. The table displays the average score, median score, lowest score, and highest score for entities that belong to a team or domain.

![The progress report displays a graph and data in the table.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/progress-team.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=c59d271917418ed7f8df9ac35657cef2)

### Filter the report

In the upper left corner, click the **Rules** dropdown to select a specific rule and see its performance more granularly.

![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/progress-rules-filter.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=2827a3e4eba0bf8bfb8ca49586829d74)

In the upper right corner, click **Filter** to select a specific entity to filter the report by.

![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/progress-filter.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=d1a8bba76d7ba6a0c698afa80bea67f8)

### Share the Progress report

You can share the Progress report:

* **Send a link**: Click **Share** in the upper right corner of the report to copy the URL to your clipboard. You can share the link with anyone who has access to view the report in your Cortex workspace.
  * The pre-configured link will display your report with the full breadcrumb trail. This not only gives others the same insights and understanding, but also provides an opportunity for team members to explore the data further on their own.
* **Export as CSV**: In the upper right corner of the page, click **Export CSV** to download a CSV file of the report data.


# Report card
Source: https://docs.cortex.io/improve/reports/report-card



The [Report Card](https://app.getcortexapp.com/admin/reports/reportcard) provides a high-level overview of any given [Scorecard](/standardize/scorecards), making it easy to visualize key performance indicators and the top and bottom performers.

You can find the Report card in the main nav under **Reports > Report card**.

> [!TIP]
>
> The Report card can be a helpful visual for engineering team retro meetings, as it summarizes wins and opportunities.

## Using the Report card

### Generate a Report card

Select a Scorecard from the list, then a report is automatically generated based on that Scorecard.

### Report card metrics

The Report card breaks performance down into several categories:

* **Top entities** shows up to five entities with the highest scores in the selected Scorecard. This section shows each entity's name, tag, and score.
* **Worst entities** shows up to five entities with the lowest scores in the selected Scorecard. This section shows the entity's name, tag, and score.

  ![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/report-card-top.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=a41ec283018ffb1d105bb1ca21d72a70)
* **Most improved** shows up to five entities that have improved the most in the selected Scorecard. This section shows each entity's name, tag, and score. You can also see how many places each entity has moved in rank among all entities.
* **Worst drops** shows up to five entities that have dropped the most in score. This section shows each entity’s name, tag, and score. You can also see how many places the entity has moved in rank among all entities in the Scorecard.

  ![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/report-card-middle.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=be07c77baf397d4c883782d9471c8dc7)
* **Most moved** shows rules with the greatest percentage change in entities failing the specific rule. This section shows the rule definition and the percent change. In this case, a negative change is a good thing — it means fewer entities are failing that rule (in other words, more entities are passing the rule).
* **Rules with highest risk** shows the rules with the lowest passing rates. This section shows the rule definition and the percent of entities failing a given rule.

  ![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/report-card-bottom.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=b788e5e143d01d98f0d28a501b64d066)

> [!TIP]
>
> Negative percentages in the **Most moved** section are a good thing - this means fewer entities are failing a given rule.


# Home
Source: https://docs.cortex.io/index

Code is no longer the bottleneck. Everything else is.

Code is no longer the bottleneck. Everything else is.

Cortex is the EngOps Platform that keeps your entire engineering organization moving as one—fewer incidents, faster recovery, and developers spending time building instead of battling friction.

Ask Cortex AI

Welcome to Cortex

Catalog your services, set engineering standards, and automate the work that connects them.

![Get started](https://mintcdn.com/cortex-290c0c42/vCS5fJP4w7e-qy0s/images/homepage-get-started.png?fit=max\&auto=format\&n=vCS5fJP4w7e-qy0s\&q=85\&s=10141647c9910c3dc3fa7a71075389bc)

## [Get started](https://docs.cortex.io/get-started/quickstart)

Configure your workspace, connect your data, and learn how Cortex works

Product Docs

![Build with the API](https://mintcdn.com/cortex-290c0c42/vCS5fJP4w7e-qy0s/images/homepage-api.png?fit=max\&auto=format\&n=vCS5fJP4w7e-qy0s\&q=85\&s=0f4a197e6114a12b1bb78de4a67e8b64)

## [Build with the API](https://docs.cortex.io/api)

Use the REST API to automate work with entities, Scorecards, custom data, and more

API Reference

![Best practices](https://mintcdn.com/cortex-290c0c42/vCS5fJP4w7e-qy0s/images/homepage-cookbooks.png?fit=max\&auto=format\&n=vCS5fJP4w7e-qy0s\&q=85\&s=7ffbf7b3f1413a013fea266b31ef56af)

## [Best practices](https://docs.cortex.io/guides)

Follow proven, step-by-step recipes to tackle your engineering goals

Cookbooks

<ul />

Explore Cortex

A tour of what Cortex does, from your catalog to Scorecards to the API.

<ul />

Resources

> **[Cortex Academy](https://academy.cortex.io)**
>
> Self-paced learning hub featuring a variety of courses that cover Cortex basics and best practices

> **[Engineering blog](https://builders.cortex.io)**
>
> Deep, technical posts from Cortex engineers on agents, sandboxing, and operating engineering at scale

> **[Contact support](https://support.cortex.io/)**
>
> Get help from the Cortex Customer Engineering team via email, an in-app ticket, or your Slack channel


# Catalogs overview
Source: https://docs.cortex.io/ingesting-data-into-cortex/catalogs

Using catalogs to organize and manage entities in Cortex

A catalog is a defined selection of [entities](/ingesting-data-into-cortex/entities-overview). Use catalogs to track and store information about all the components that make up your infrastructure, from services and domains to Amazon Web Services (AWS) resources like S3 buckets and RDS instances, Google Cloud resources, and Azure resources.

Entities are [defined by YAML files](/ingesting-data-into-cortex/entities-overview/entities/yaml), but catalogs aren't. You create catalogs in the Cortex UI. Think of a catalog as a folder containing a collection of entities, with each entity defined by its own YAML file. Since an entity can belong to multiple catalogs, you can also think of a catalog as a filter that determines which entities get grouped together.

In the screenshot below, the **Services** page contains a list of all entities that belong to the `service` catalog:

![The services catalog displays a list of services.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/service-entities-list.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=49495edb256969184a494d8f71ce1f73)

Watch the video below for an overview of how Cortex helps you build and catalog your engineering operations assets, improving visibility, adoption, and productivity.:

[YouTube video player](https://www.youtube.com/embed/A5w6ebxGbeg)

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy [course on Catalogs](https://academy.cortex.io/courses/introduction-to-catalogs).

## Working with catalogs

By default, Cortex comes with four built-in catalogs:

* **Services** - Contains all [service entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services).
* **Infrastructure** - Contains all entities representing your infrastructure assets.
  * Cortex pulls in resources directly from [AWS](/ingesting-data-into-cortex/integrations/aws), [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources), or [Google Cloud](/ingesting-data-into-cortex/integrations/google), as their corresponding types out of the box. These resources are automatically added to the Infrastructure catalog.
* **Domains** - Contains all [domain entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains) and their children entities (regardless of entity type), and displays them in a hierarchical view.
* **Teams** - Contains all [team entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams) and displays them in a hierarchical view alongside a leaderboard based on Scorecards.

You can rename these catalogs to fit your own taxonomy. Keep in mind that custom names for default catalogs won't override references to their default names elsewhere in the app. If you want more flexibility, create additional custom catalogs instead.

### Catalog types

Cortex supports two types of catalogs: entity type catalogs and relationship type catalogs.

* **Entity type catalogs** define entity inclusion criteria using filters for entity type, tags, or groups. For example, the built-in **Service** catalog is configured to include entities of type `service`.
* **Relationship type catalogs** group entities based on a specific [entity relationship type](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types). These catalogs support visualizing hierarchical relationships and let different entity types relate to one another. For example, the built-in **Domain** catalog includes entities connected through a parent/child domain relationship. It displays every entity in the domain hierarchy, including entity types that aren't domains.


# Managing catalogs
Source: https://docs.cortex.io/ingesting-data-into-cortex/catalogs/managing-catalogs



This article covers how Cortex assigns entities to catalogs automatically, plus how to create, edit, delete, and track changes to your own catalogs.

## Adding an entity to a catalog

After Cortex imports or creates an entity, it automatically assigns the entity to a catalog based on that catalog's entity type criteria. When you [create a custom catalog](/ingesting-data-into-cortex/catalogs/managing-catalogs#creating-a-custom-catalog), you can define its entity type criteria.

Default catalogs come with preset entity type criteria:

* The **Services** catalog contains `service` entities.
* The **Domains** catalog contains `domain` entities.
* The **Teams** catalog contains `team` entities.
* The **Infrastructure** catalog contains any entity that isn't type `service`, `domain`, or `team`.

[Custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types) belong to the **Infrastructure** catalog by default. To move a custom entity type to a different catalog, add it there directly.

## Creating a custom catalog

Users with the `Edit Catalogs` permission can create, edit, or delete catalogs

You can create catalogs in the Cortex UI. For each catalog, you set the criteria that determine which entities belong to it. You can also define custom entity types to categorize the entities in your catalogs.

Because catalogs aren't defined by a YAML file, you can't create them through a GitOps workflow.

**To create a new catalog**:

1. From the main sidebar, expand **Catalogs**, then select **All catalogs**.
2. In the upper-right corner, click **Create catalog**.
3. On the **Create new catalog** page, do the following:
   1. In the **Details** section:
      1. Under **Catalog name**, enter a new name for the catalog (required).
      2. Under D**escription**, enter an overview of the catalog.
      3. Under **URL**, enter a custom URL for the catalog. By default, the URL matches the catalog name. If the URL is updated, the latest URL will be activated immediately, and any previous URL navigates to the catalog list page as a fallback.
         * **Example** - For a catalog named "ML Models", the auto-generated slug might be `ml-models`, resulting in a URL like: `https://app.getcortexapp.com/admin/catalog/ml-models` . You could customize the slug to something like `machine-learning`, giving you: `https://app.getcortexapp.com/admin/catalog/machine-learning`.
      4. Under **Display icon**, select an icon to represent the catalog.
   2. In the **Catalog filter** section:
      1. From the **Entity type** tab, select one or more entity types to include their respective entities in the catalog. You can select entity types manually, or use advanced options like a `CQL` expression. Every entity that matches the criteria you set here is automatically included. Choose one filter type: entity type or relationship type.
         * Optionally, expand **Advanced options** to refine entity selection by applying additional filters for groups or a `CQL` expression. You can also skip other filters entirely and use a `CQL` expression alone to define the entity type selection.
      2. From the **Relationship type** tab, select a relationship type to filter which entities appear on the catalog page.
4. By default, **Draft** is toggled on. If you're ready to publish your changes, toggle it off.
5. Click **Create**.

New catalogs are found under **Catalogs > All catalogs**, automatically populated with entities that match your criteria. Catalogs with a relationship type filter display as a hierarchy.

## Editing a catalog

Users with the `Edit Catalogs` permission can edit a catalog's name, description, URL, display icon, and filter type.

1. From the main sidebar, expand **Catalogs**, then select the catalog you want to edit.
2. In the upper-right corner, click **Edit catalog**. The **Edit catalog** page opens.
3. Refer to step 3 in [Creating a custom catalog](/ingesting-data-into-cortex/catalogs/managing-catalogs#creating-a-custom-catalog) for detailed information.
4. Optionally, toggle on **Draft** to save your changes without publishing them.
   * When you're ready to publish, toggle off **Draft**, then click **Save**.
5. Click **Save**.

## Deleting a catalog

Users with the `Edit Catalogs` permission can delete a catalog.

> [!WARNING]
>
> You should only delete a catalog if you're absolutely sure it's no longer needed. Deleting a catalog does NOT delete the entities in that catalog.

1. From the main sidebar, expand **Catalogs**, then select the catalog you want to delete.
2. In the upper-right corner, click **overview menu icon**.
3. Select **Delete catalog**. The **Delete catalog** window opens.
4. Click **Delete**.

## Tracking catalog changes

Use the [audit log](/configure/settings/audit-logs) to track changes made to any of your catalogs. Catalog updates are listed as `CATALOG` in the **Object type** column. The **Action type** column indicates whether a catalog was created, deleted, or updated.


# Viewing catalogs
Source: https://docs.cortex.io/ingesting-data-into-cortex/catalogs/viewing-catalogs



This article explains how to view, search, filter, and sort catalogs.

## Configuring the catalog display in the main sidebar

Users with the `Configure Appearance Settings` permission can configure the catalog display.

By default, catalogs appear in alphabetical order in the main sidebar, but you can manually reorder them.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. Locate the **Workspace** section, then select **Main sidebar**.
4. From the **Catalogs** tab, drag and drop catalogs into your preferred order.

   ![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/main-sidebar-display.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=c73efe1c29de33d5776aa49df90bffad)
5. Click **Save changes**.

## Viewing catalogs

### Accessing catalogs

Users with the `View Catalogs` permission can view a catalog's entities list. To access an entity list, expand **Catalogs** from the main sidebar:

![The 'Catalogs' tab in the main sidebar.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-catalogs.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=16ddf74fb5839f6c1428fb56273686cd)

### Viewing all catalogs

The **All catalogs** page shows the same list of catalogs as the **Catalogs** dropdown in the main sidebar. It includes a search bar and a sort by name function, as well as a toggle for displaying or hiding drafts (click **Display**). From this page, you can create new catalogs and edit existing ones.

![The search and filter options on the 'All catalogs' page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-catalogs-options.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=987884cd2da911d1f4f520cc828697da)

### Viewing all entities

The **All entities** page includes every entity across all catalogs and entity types. To view all entity types, select the **Entity types** tab at the top of the page.

![The 'All entities' page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-entities.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=e0d2cd14ba8ff37c734ace2a3d84627a)

Like the **All catalogs** page, **All entities** includes search, filter, and sort options.

> [!NOTE]
>
> Select the **All** tab to view all entities in your workspace. Select the **Mine** tab to view only entities you own, either as an individual owner or as a member of a team that owns them. In the Teams catalog, **Mine** shows the teams you're a member of. Cortex saves your selection and restores it the next time you open this page.
>
> ![The 'All' and 'Mine' tabs located on the main entities page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-mine-entities.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=90324dcacca6f6293cf40416e793a89f)

### Viewing a specific catalog

Select a catalog to view all of its entities:

![The 'Domains' catalog.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/domains-catalogs.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=30a488c58e5350a305d9138b9bcd3fea)

### Searching across and filtering entities

Cortex offers several ways to search and filter entities, and the available options depend on the entity type you're viewing. For details on search and filter options for each entity type, see:

* [Services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#searching-across-and-filtering-services)
* [Domains](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains#searching-across-and-filtering-domains)
* [Teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/viewing-teams#searching-across-and-filtering-teams)

![The 'Display' option at the top of a catalog.](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/catalog-display.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=6313b591aa5fd36284229bee0c02399f)

At the top of a catalog, click **Display** to turn on options like showing archived entities or switching between hierarchical and list views (availability depends on entity type). Click **Filter** to narrow the list by associated Git repository, unowned entities, AWS account ID or region, domain, entity type, group, team, or user.


# Entities overview
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview



Entities are the foundational building blocks for representing your software ecosystem. Each entity models a distinct software construct—like a service, library, or team—giving your organization a shared, structured way to describe what exists and how it fits together. A defined collection of entities forms a [catalog](/ingesting-data-into-cortex/catalogs): a single source of truth that everyone, from engineers to leadership, can rely on.

Entities are designed to be both flexible and interconnected. They're defined in YAML so they're portable and version-controlled, enriched through integrations that pull in live data from the tools you already use, and measured against standards through Scorecards to drive quality and consistency over time.

Every entity has a dedicated page that brings its data together in one place, making it easy to understand context, ownership, and health at a glance. See [Entity details](/ingesting-data-into-cortex/entities-overview/entities/details) for more information.

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy course on [Catalogs, Entities, and Relationships](https://academy.cortex.io/courses/understanding-understanding-catalogs-entities-and-relationships).

## Catalog and entities overview video

The video below shows how Cortex catalogs your engineering assets to improve visibility, adoption, and productivity:

[YouTube video player](https://www.youtube.com/embed/A5w6ebxGbeg)

## Entity types

Choose from the default entity types or [define your own](/ingesting-data-into-cortex/entities-overview#custom-entity-types).

### **Default entity types**

Cortex provides a set of built-in entity types that cover the most common building blocks of a software organization. These defaults give you a strong foundation out of the box, so you can start cataloging your ecosystem without needing to design a schema from scratch.

| Entity type | Purpose | Typical use |
| - | - | - |
| **Services** | Represent codebase-like modules | Microservices, libraries, components |
| **Domains** | Group entities into logical units | Product areas, business capabilities, system boundaries |
| **Teams** | Represent the 'people side' of your catalog | Ownership, membership, contact info |
| **Cloud resources** | Sync infrastructure into your catalog | AWS, Azure, and Google Cloud resources |

**Services** are the core of your catalog and the default entity type. Use them to represent any codebase-like module, e.g. microservices, libraries, components, and similar building blocks. Services are typically where the majority of your catalog activity happens, since they connect to code, deployments, ownership, and quality standards. See [Adding services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services).

**Domains** let you group services, resources, and other domains into hierarchical, logical units. They're useful for modeling how your organization actually thinks about its software—by product area, business capability, or system boundary—and for rolling up insights across related entities. See [Adding domains](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains).

**Teams** represent the people side of your catalog. Use them to capture team membership, ownership relationships, and contact information, so it's always clear who's responsible for what. See [Adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams).

**Cloud resources** can be pulled in directly from your cloud providers and represented as their corresponding entity types, keeping your catalog in sync with what's actually running in your infrastructure:

* For **AWS**, choose which resource types to include in your [AWS integration settings](https://app.getcortexapp.com/admin/settings/aws?activeTab=settings).
* For **Azure**, choose which resource types to include in your [Azure Resources integration settings](https://app.getcortexapp.com/admin/settings/azureresources).
* For **Google Cloud**, see the list of [supported entity types](/ingesting-data-into-cortex/integrations/google#supported-google-entity-types).

### **Custom entity types**

While Cortex's built-in entity types cover most common needs, every organization has its own way of modeling its software ecosystem. Custom entity types let you extend your catalog to reflect the concepts that matter to your teams, whether that's APIs, data pipelines, ML models, or anything else you want to track.

You can create unlimited custom entity types through the Cortex UI or API. Once a type is defined, you can begin adding entities of that type using the UI, API, or GitOps, just like you would with built-in types.

See [Adding custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types) for more information.


# Managing entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities



This article provides an overview of how to manage entities in Cortex. For an overview of how entities work, see [Entities overview](/ingesting-data-into-cortex/entities-overview).

## Adjusting general settings for entities

Admins and users with the `Configure Settings` permission can adjust system-wide settings for entities under **Settings > Entities > General.** See [Entity settings](/configure/settings/entity-settings).

## Defining entities with YAML

Every entity in your Cortex catalog is defined by a YAML file known as the Cortex entity descriptor (or *Cortex YAML*, named after the `cortex.yaml` file used in the [GitOps approach](/ingesting-data-into-cortex/entities-overview/entities#managing-entities-via-gitops)). This applies whether you manage entities through the UI or GitOps—the descriptor is the underlying source of truth either way.

You can extend an entity by adding metadata to the `info` section of its descriptor. Throughout the docs, you'll see snippets prefixed with `x-cortex-*`; these are descriptor blocks that belong inside `info` and unlock additional Cortex functionality.

See [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml) for more information.

## Unique identifiers for entities

### **Cortex tag**

The Cortex tag (formerly the *entity tag*) is a customizable, unique identifier used to reference an entity throughout Cortex. It's defined by the `x-cortex-tag` value in an entity's YAML file and powers core functionality like declaring dependencies between entities.

Each Cortex tag must be globally unique across all entities in your workspace.

**Changing a Cortex tag**

Editing an entity's `x-cortex-tag` doesn't rename the existing entity, it creates a new one. Cortex generates a new entity with the updated tag and leaves the original entity untouched, regardless of whether the change is made through the UI editor, the API, or GitOps. Both entities continue to exist in your catalog until you archive or delete the original.

**Reusing a Cortex tag**

A Cortex tag can only be associated with one entity at a time. To reuse a tag that's already in use, the entity currently holding it must be [archived](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities) first.

**Using forward slashes in a Cortex tag**

Cortex tags may contain forward slashes (`/`), including leading, trailing, and consecutive slashes, e.g.  `payments/checkout` or `/services/payments-api`).

When you reference a tag that contains forward slashes in an API request path, URL-encode each slash as `%2F`. Cortex matches the tag exactly as encoded—including any leading, trailing, or consecutive slashes—and does not collapse repeated slashes.

For example, to archive an entity whose tag is `/services/payments-api`:

```
PUT https://api.getcortexapp.com/api/v1/catalog/%2Fservices%2Fpayments-api/archive
```

> [!NOTE]
>
> Tags containing slashes (including consecutive slashes such as `//`) are supported through the API only. The Cortex UI does not support creating or editing tags with leading, trailing, or consecutive slashes, so behavior between the API and UI differs by design.

### **Cortex ID**

The Cortex ID (CID) is a unique, immutable identifier assigned to every entity in Cortex. Unlike the Cortex tag, which you define and can change, the CID is automatically generated, fixed for the life of the entity, and 18 characters long, making it ideal for historical tracking, reporting, and any system of record outside of Cortex.

You can use the CID anywhere you'd reference an entity: in the API, in CQL queries, throughout the app, and with the Cortex AI Assistant.

**Where to find the CID**

The CID appears in an entity's URL and at the top of its details page. It doesn't appear in the entity's YAML file, since it can't be modified.

![The Cortex ID (CID) is highlighted in the entity's URL and at the top of the entity's details page.](https://mintcdn.com/cortex-290c0c42/z5k1sDZlDmCOZ-iP/images/cid-example.png?fit=max\&auto=format\&n=z5k1sDZlDmCOZ-iP\&q=85\&s=af5b7a12b1422281e7fe63ae67a3c32e)

## Managing entities via GitOps

Accounts are configured to edit entities through the UI by default. It's strongly recommended to start with the UI editor, which includes a built-in YAML editor, then moving to GitOps when you're ready to scale.

Follow the steps below to enforce GitOps-only creation and editing of entities.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then click **GitOps**.
4. From the **Entities** tab, scroll to **Options by entity type**.
5. Do the following:
   1. To only allow editing of entities via GitOps, toggle off **Enable UI editing for new entity types**.
   2. To only allow creation of entities via GitOps, toggle off **Enable UI importing for new entities**.
   3. To override these settings for a specific entity type, disable the **UI editing** and **UI importing** toggles next to that type in the list. This enforces a GitOps-only approach for that entity type.

      ![Entity types list with UI editing and UI importing toggles disabled for a selected type.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/gitops-entity-editing.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=611de6fbe26111fb8d3f2fbef6d276d6)

#### Things to keep in mind when using GitOps

When using GitOps, you can define any number of entities in any repository.

* Domain definitions should live in the `.cortex/domains` directory in your repository.
* Team definitions should live in the `.cortex/teams` directory in your repository.

Entity definitions can live in one central repository, or alongside the service they describe in that service's own repository.

See the single repository example below:

```
.
└── .cortex
    ├── catalog
    │   ├── database.yml
    │   ├── s3-bucket.yml
    │   ├── auth-service.yml
    │   └── billing-service.yml
    ├── domains
    │   ├── billing-domain.yml
    │   └── health-domain.yml
    ├── teams
    │   ├── eng-team.yml
    │   └── sre-team.yml
```

See [Using GitOps for Cortex](/configure/gitops) for more information.

## Adding entities to catalogs

Each catalog has entity type criteria that determine which entities it includes. When an entity is created or imported, it's automatically added to any catalog whose criteria it meets. You set these criteria when [creating a custom catalog](/ingesting-data-into-cortex/catalogs#custom-catalogs).

Default catalogs have their entity type criteria set automatically:

* The **Services** catalog contains `service` entity types
* The **Domains** catalog contains `domain` entity types
* The **Teams** catalog contains `team` entity types
* The **Infrastructure** catalog contains any entities that are *not* the types `service`, `domain`, or `team`.
  * Its catalog filter is set to exclude the types `service`, `domain`, and `team`:

    ![Image of an entity's catalog filter.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/infrastructure-types.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=2ab69269c569237a0afac7ad38ead140)
  * By default, any [custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types) you create belong to the Infrastructure catalog. If you don't want an entity type to belong to this catalog, you can add the entity type to a different catalog.

To learn more about adding each type of entity to Cortex, see:

* [Adding services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services)
* [Adding domains](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains)
* [Adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams)
* [Adding custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types)

### Managing entities across catalogs

The **All entities** page lists every entity that's been imported into Cortex, regardless of type. To open it, expand **Catalogs** in the main sidebar and select **All entities**. The page opens to the **Mine** tab if you own any entities, and defaults to the **All entities** tab otherwise.

Each row shows the entity's name and tag. Most workspaces start with just a few dozen entities, but catalogs often grow to hundreds (or thousands!) of entities over time as more of your ecosystem is brought into Cortex.

#### Searching across and filtering entities

![The search and filter options in the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/filter-entities.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=513cf0089838d01d69dec9aae0b12eff)

There are several ways to search and filter your entities list.

1. From the main sidebar, expand **Catalogs**, then select **All entities.**
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Do any or all of the following:
   * To find specific entities, use the search bar in the upper-right corner of the entities list and type to search.
   * Click **Name** to select whether you want to sort by name or identifier, and whether to sort by ascending or descending order.
   * Click **Display** to choose whether to show archived entities in the list, and select which columns to display alongside entities.
     * **Incidents** - Displays how many active incidents are associated with a given entity. This information is pulled from FireHydrant, incident.io, PagerDuty, and Rootly.
     * **Health** - When you click into this column in an entity's row, you can view more information about:
       * **Monitors** - Shows how entities are performing against monitors you’ve created in your APM. When an entity is passing all monitors, this cell will display `All OK`; otherwise, it displays `Failing`, `Warning`, or `No Data`, along with how many monitors the entity is not hitting. This information is pulled from Datadog.
       * **Error rate** - Shows the percentage of transactions that result in a failure during a pre-specified window. This information is pulled from New Relic.
       * **Apdex (Application Performance Index)** - Ratio of the number of satisfied and tolerating requests to the total number requests made. This information is pulled from New Relic.

         ![Shows the health and incidents columns on the entities page.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/health-kpis.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=4016a05fcf550b7189835f1d019b4d19)
     * Columns that rely on an integration display **Not connected** when the integration hasn't been set up. If the integration is connected but the entity has no associated data or configuration, the cell displays **None** instead.
   * Click **Filter** to narrow down your list by associated Git repository, unowned entities, AWS account ID or region, domain, entity type, group, team, or user.

#### Viewing entity types

Select the **Entity types** tab to view all entity types in your workspace. Click any entity type to see more details about it.

![The 'Entity types' tab shows all entity types in your organization.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/entities-entity-types-tab.png?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=405de7ae9ef319d383dbdbe287a03762)

Built-in entity types are marked with a Cortex logo. Hover over the logo to see a "Powered by Cortex" banner. Any other types in the list are custom entity types created for your workspace. To learn more about creating your own, see [Adding custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types).

![The 'Powered by Cortex' icon appears next to a built-in entity in the Entities list.](https://mintcdn.com/cortex-290c0c42/z5k1sDZlDmCOZ-iP/images/powered-by-cortex.png?fit=max\&auto=format\&n=z5k1sDZlDmCOZ-iP\&q=85\&s=a7556e0ea8bdafa44b635023a7ff4a06)

#### Changing an entity's type

Entities can be reclassified to a different type as their role in your catalog evolves. For example, an entity originally created as a service could later be changed to a domain. This gives you flexibility to restructure your catalog as your organization changes—useful when entities were initially imported under the wrong type, or when you want to consolidate, split, or rethink how parts of your ecosystem are modeled.

Admins or users with the `Configure Settings` permission can change an entity's type.

**Prerequisites**

1. Toggle on the option to change an entity type:
   1. From the main sidebar, click your avatar in the bottom-left corner.
   2. Click **Settings**.
   3. From the **Settings** menu, locate the **Workspace** section, then click **Entities**.
   4. Click **General**.
   5. In the **Entity settings** section, toggle on **Enable changing entity type**.

> [!NOTE]
>
> If you'd rather keep entity types fixed after creation, keep this option toggled off to enforce stability across your catalog.

**To change an entity's type**:

> [!WARNING]
>
> Changing an entity's type could result in broken dependencies and hierarchies.

Update the entity YAML. Change the `x-cortex-type` field in the entity's YAML descriptor to the new type. This can only be done via YAML, not through the UI.

A **Cannot change the type of the entity** error means the **Enable changing entity type** option is disabled. Turn it on to allow the change. See the prerequisite section above.

> [!NOTE]
>
> Deleted entities can be re-created with a different type, regardless of this setting.

#### Viewing relationship types

Software ecosystems are rarely flat. Services depend on each other, teams own different parts of the stack, and domains nest inside larger business areas. Relationship types let you capture these connections in Cortex, so your catalog reflects how your organization actually fits together.

A relationship type defines how two entities relate to one another and which entity types are allowed as the source and destination of that relationship. Cortex supports a few different ways to model these connections:

* **Entity relationships** - Custom relationships you define between any entity types, either hierarchical or cyclical.
* **Team hierarchies** - Hierarchical relationships between team entities, including ownership over other entities.
* **Domain hierarchies** - Hierarchical relationships between domain entities, with optional ownership inheritance from higher levels of the hierarchy.
* **Dependencies** - Cyclical relationships between non-team entities, used to model how services and resources rely on each other.

Together, these relationship types give you a flexible way to represent both the structural and operational connections across your workspace.

To view all relationship types, expand **Catalogs** in the main sidebar and select **All entities**. Select the **Relationship types** tab.

!['Relationship types' tab in Cortex showing the list of defined entity relationships](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/relationship-types-tab.png?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=ab8072924a86b0d6c88d5dab13c6b72c)

See [Defining relationship types](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types) for more information.

## Archiving entities

Entities can be deleted outright, but archiving is often the better choice as it removes entities from active use while preserving them for historical reference.

For hands-off maintenance, [configure auto-archival](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive) to automatically archive entities when they're no longer detected in your integrations or when their YAML files are deleted. Entities can also be archived manually through the Cortex UI or API. See [Archiving entities](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities).


# Adding entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities



Entities are the foundational building blocks that represent the components of your software ecosystem—services, domains, teams, and more—giving your organization a shared way to describe what exists and how it connects. Defined in YAML and enriched with live data from your existing tools, entities come together to form a catalog that serves as a single source of truth.

Cortex provides a set of built-in entity types that cover the most common building blocks of a software organization. These defaults give you a strong foundation out of the box, so you can start cataloging your ecosystem without needing to design a schema from scratch.

Learn how to add built-in entity types and how to create your own custom entity types in the sections below:

* [Services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services)
* [Domains](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains)
* [Teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams)
* [Custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types)
* [Define dependencies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies)

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy course on [Catalogs, Entities, and Relationships](https://academy.cortex.io/courses/understanding-understanding-catalogs-entities-and-relationships).


# Adding services
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services



Services are a default entity type in Cortex used to represent the codebase-like modules that make up your software ecosystem—microservices, libraries, components, etc. All entity types in Cortex, including services, are defined by a `cortex.yaml` file, which declares the entity's identity, ownership, dependencies, and links to the tools that support it (CI/CD, observability, on-call, documentation, and more). Once defined, a service becomes a first-class entity in your catalog, automatically enriched with live data pulled from your integrations.

Services are typically the most numerous entity type in a catalog and the closest match to how engineering teams already think about their work: as discrete units of code that do something specific, owned by someone, deployed somewhere, and depended on by other things. Modeling them consistently gives your organization a single place to answer questions that otherwise require digging through multiple tools—who owns this, what it depends on, whether it meets your standards, and where it runs. The result is a shared understanding that connects day-to-day engineering work to broader goals around quality, ownership, and operational maturity.

## Adding service entities to Cortex

Users with the `Edit Catalog` and `Edit Services` permissions can add service entities to Cortex.

When configuring an entity, you can't add archived teams as owners or archived entities as dependencies, parents, or children.

Services can be added manually, imported, defined in YAML via GitOps, or created via the API.

### Importing services from an integration

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Import discovered entities**.

   ![The 'Import discovered entities' tile is displayed.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/import-method.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=423e270a5aa4b7a19e4ab2662d3f81b2)
4. Select the integration to import from. The **Select entities to import** page is displayed.
5. A list of entities from the integration are displayed. Select the checkboxes next to the entities you want to import. Use the search bar to find entities by name, or click the **Filter icon** in the upper-right corner of the results list to filter by entity type. For Azure DevOps integrations, you can also filter by project name. Search and filters run server-side, so they stay responsive even with large catalogs.

   ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/import-services.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=4dad38f81f97976718cee6f8d20a232e)
6. In the bottom-right corner, click **Next step**. The **Edit details** page is displayed.
7. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
   1. From the **Type** drop-down menu, select **Service.**
   2. In the **Details** section:
      1. Under **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). It's a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Under **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Repository** section:
      1. From the **Provider** drop-down menu, select the repo provider.
      2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
      3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
      4. Under **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
   4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
      * Cortex may recommend owners [based on your catalog data](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations). You can accept or reject the recommendations.
   5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Dependencies** section, click **Add entity** to select an entity or entities that this entity depends on. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
8. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.

   ![The 'Next entity' link in the bottom-right corner of the page.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/services-next-entity.png?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=474ea9b95201cd9e12daa01d28f154d2)
9. Click **Confirm import**. The entity is imported into Cortex.

### Manually adding services

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Create entities manually**. The **Edit details** page is displayed.
4. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
   1. From the **Type** drop-down menu, select **Service.**
   2. In the **Details** section:
      1. Below **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Below **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Repository** section:
      1. From the **Provider** drop-down menu, select the repo provider.
      2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
      3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
      4. Below **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
   4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
      * Cortex may recommend owners [based on your catalog data](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations). You can accept or reject the recommendations.
   5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Dependencies** section, click **Add entity** to select an entity or entities that this entity depends on. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
5. Optionally, if you'd like to add another entity, click **Add entity** in the upper-right corner of the page.
6. Click **Confirm import**. The entity is imported into Cortex. If there are any errors, a banner appears at the bottom of the page with the errors that need to be fixed.

### Adding a service in YAML via GitOps

Before creating a service entity via GitOps, be sure UI-based editing is disabled in Cortex. See [Managing entities via GitOps](/ingesting-data-into-cortex/entities-overview/entities#managing-entities-via-gitops).

**Service entity descriptor**

A blank spec file has the OpenAPI version, along with an `info` section that contains some basic details.

```yaml theme={null}
openapi: 3.0.1
info:
  title: Account Service
  description: Manages user account lifecycle, authentication state, and organization membership. Used by the API gateway, billing service, and frontend clients.
  x-cortex-tag: account-service
  x-cortex-type: service
```

**Required fields**

The following fields are required under `info`: `title`, `x-cortex-tag`, and `x-cortex-type`. The description is optional, but highly recommended as a best practice.

> **Expand to see the example YAML**
>
> ```yaml theme={null}
> openapi: 3.0.1
> info:
>   title: Chat Service
>   description: Chat service is responsible for handling the chat feature.
>   x-cortex-tag: chat-service
>   x-cortex-type: service
>   x-cortex-parents: # parents can be of type domain only
>   - tag: notifications-domain
>   - tag: support-domain
>   x-cortex-groups:
>   - python
>   x-cortex-owners:
>   - type: group
>     name: Delta
>     provider: OKTA
>     description: Delta Team
>   x-cortex-slack:
>     channels:
>     - name: delta-team
>       notificationsEnabled: true
>       description: This is a description for the delta-team Slack channel # optional
>   x-cortex-link:
>   - name: Chat ServiceAPI Spec
>     type: OPENAPI
>     url: ./docs/chat-service-openapi-spec.yaml
>   x-cortex-custom-metadata:
>     core-service: true
>   x-cortex-dependency:
>     - tag: authentication-service
>     - tag: chat-database
>   x-cortex-git:
>     github:
>       repository: org/chat-service
>   x-cortex-oncall:
>     pagerduty:
>       id: ASDF1234
>       type: SCHEDULE
>   x-cortex-apm:
>     datadog:
>       monitors:
>         - 12345
>   x-cortex-issues:
>     jira:
>       projects:
>         - CS
> ```

### Adding a service via the Cortex API

You can create, update, and delete services using the Cortex API. See [Catalog entities](/api/rest/catalog-entities) for more information.

## Viewing services

The **Services catalog** page lists every service entity that's been imported into Cortex. To open it, expand **Catalogs** in the main sidebar and select **Services**. Each row shows the entity's name and tag.

![Overview of the Services page in the Cortex UI.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/view-services.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=3c2aa9ca2d48ab8cd24ab79ff4d839f0)

> [!NOTE]
>
> Select the **All** tab to view all entities in your workspace. Select the **Mine** tab to view only entities you own, either as an individual owner or as a member of a team that owns them. In the Teams catalog, **Mine** shows the teams you're a member of. Cortex saves your selection and restores it the next time you open this page.
>
> ![The 'All' and 'Mine' tabs located on the main entities page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-mine-entities.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=90324dcacca6f6293cf40416e793a89f)

### Searching across and filtering services

![The search and filter options in the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/services-search-filter.png?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=e72a95b225ef4f55115873edfe42c0e2)

There are several ways to search and filter your services list.

1. From the main sidebar, expand **Catalogs**, then select **Services.**
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's services.
   * Select the **Mine** tab to search and filter only the services you or your teams own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Do any or all of the following:
   * To find specific services, use the search bar in the upper-right corner of the page and type to search. The search bar shows which fields you can search on and which field your query is matching. For more information, see [Using search in Cortex](/configure/settings/search#using-the-catalog-search-bar).
   * Click **Name** to select whether you want to sort by name or identifier, and whether to sort by ascending or descending order.
   * Click **Display** to choose whether to show archived services in the list, and select which columns to display alongside services.
   * Click into a row to learn more about:
     * **Incidents** - Displays how many active incidents are associated with a given service. This information is pulled from FireHydrant, incident.io, PagerDuty, and Rootly.
     * **Health** - When you click into this column in an service's row, you can view more information about:
       * **Monitors** - Shows how services are performing against monitors you’ve created in your APM. When a service is passing all monitors, this cell will display `All OK`; otherwise, it displays `Failing`, `Warning`, or `No Data`, along with how many monitors the service is not hitting. This information is pulled from Datadog.
       * **Error rate** - Shows the percentage of transactions that result in a failure during a pre-specified window. This information is pulled from New Relic.
       * **Apdex (Application Performance Index)** - Ratio of the number of satisfied and tolerating requests to the total number requests made. This information is pulled from New Relic.

         ![Shows the health and incidents columns on the entities page.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/health-kpis.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=4016a05fcf550b7189835f1d019b4d19)
     * Columns that rely on an integration display **Not connected** when the integration hasn't been set up. If the integration is connected but the entity has no associated data or configuration, the cell displays **None** instead.
   * Click **Filter** to narrow down your list by by domain, entity type, group, owner, or team.

## Editing a service entity

Users with the `Edit Catalog` and `Edit Services` permissions can edit service entities.

Service entities can be modified at any time. Follow the steps below to edit a service entity.

1. Navigate to the entity's page.
2. In the upper-right corner, click **Configure entity**.

   The entity details page opens.
3. In the upper-right corner, select either **UI editor** or **YAML editor**.
4. Make your changes. Note that the Cortex tag is uneditable.
5. Click **Save changes**.

   The service entity is updated.

> [!NOTE]
>
> It's possible to change the entity type via the Cortex YAML. See [Changing an entity's type](/ingesting-data-into-cortex/entities-overview/entities#changing-an-entitys-type) for more information.


# Defining dependencies
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies



In Cortex, you can define outgoing dependencies on other entities, and for some integrations Cortex can discover them automatically. Defining dependencies lets you notify owners when a dependency deprecates its API or ships a backwards-incompatible change, and lets you visualize dependencies in a [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph). Incoming dependencies are inferred automatically from your outgoing definitions.

## Automated dependency notifications

> [!NOTE]
>
> This feature is available in beta. Please reach out to your Cortex Customer Success Manager for access.

Cortex can automatically discover dependencies from the following integrations:

* [AWS](/ingesting-data-into-cortex/integrations/aws)
* [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources)
* [Datadog](/ingesting-data-into-cortex/integrations/datadog)
* [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace)
* [Google Cloud](/ingesting-data-into-cortex/integrations/google)
* [New Relic](/ingesting-data-into-cortex/integrations/newrelic)

When a dependency deprecates its API or makes backwards incompatible changes, Cortex surfaces these issues via these methods:

* Breaking API changes are listed in your Cortex workspace. To access:
  1. From the main sidebar, click your avatar in the bottom-left corner.
  2. Click **Settings**.
  3. From the **Settings** menu, locate the **Logging** section, then click **Breaking API changes**.
* When a PR introduces breaking OpenAPI changes that affect downstream dependencies Cortex knows about, Cortex attempts to comment on it automatically.
* If a breaking change is merged to the default branch, Cortex alerts dependency owners via Slack that a breaking change was merged.

## Defining dependencies

Users or API keys with the `Edit Entities` permission can define dependencies.

Dependencies can be defined in the Cortex UI, manually via an entity's YAML descriptor, or from the API.

### Defining dependencies via the Cortex UI

1. Navigate to the entity where you need to define a dependency.
2. In the upper-right corner of the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details), click **Configure entity**.
3. From the left entity sidebar, click **Dependencies**.

   ![The 'Dependencies' tab in the left entity sidebar.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/depend-define.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=4eada65592a5c494abf6d43762c85061)
4. Click **Add entity**.
5. In the **Dependency** sidebar, do the following:
   1. From the **Entity** drop-down menu, select an entity (required).
   2. From the **Endpoints** drop-down menu, select an endpoint. For an endpoint to populate in this dropdown, it must first be defined as a path in the entity's YAML file. See [Setting an endpoint for a dependency](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies#setting-an-endpoint-for-a-dependency) for more information.
   3. From the **Description** drop-down menu, enter a description for the dependency.
6. Click **Add**.

#### **Setting an endpoint for a dependency**

When manually defining a dependency, you can only select endpoints from the dropdown that are already defined as paths in the target entity's YAML file. For example, to make the `GET /v1/payments` and `POST /v1/refunds` endpoints selectable, the payments service would need the following in its OpenAPI spec:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Payments Service
  description: Handles payment processing and refunds
  x-cortex-tag: payments-service
  x-cortex-type: service
paths:
  /v1/payments:
    get:
      description: List payments
      responses:
        "200":
          description: A list of payments
      deprecated: false
  /v1/refunds:
    post:
      description: Issue a refund
      requestBody:
        description: Refund details
        required: true
      responses:
        "201":
          description: Refund created
      deprecated: false
```

In the UI, the paths now appear in the **Endpoints** drop-down menu:

![Paths in the Endpoints drop-down menu.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/depend-endpoints.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=387ca360b4e61713d84dafb69dbe8faf)

### **Defining dependencies in the entity descriptor**

The `x-cortex-dependency` field allows you to define a list of outgoing dependencies. A dependency should be directed towards an outgoing service or resource, or more granularly, to a specific endpoint of that entity.

```yaml theme={null}
info:
  x-cortex-dependency:
    - tag: braavos
      method: GET
      path: /2.0/users/
      description: Ensure user has payment information configured
      metadata:
        tags:
          - billing
          - identity
        prod: true
```

| Field | Description | Required? |
| - | - | - |
| **tag** | The `tag` of the entity this entity depends on, i.e. the callee. See `x-cortex-tag` | |
| **method** | HTTP method *if* depending on a specific endpoint | Required if `path` is present |
| **path** | The actual endpoint this dependency refers to | Required if `method` is present |
| **description** | A description of the dependency. | |
| **metadata** | JSON metadata tags for the relationship. Supports arbitrary objects. | |

### **Defining dependencies via the API**

See the [API docs](/api/rest/dependencies) for authentication details.

> [!WARNING]
>
> YAML is the source of truth. If a dependency has already been set through the `cortex.yaml`, the API returns an error.

Endpoints are optional. A dependency optionally references an endpoint (`method` and `path`) of the callee, and this must already be defined in the callee's `cortex.yaml` within the `paths` field. If no endpoint is referenced it is assumed that the caller depends on **all** endpoints of the callee.

For all requests, `method` and `path` are optional; however, if one is present, the other must also be present.

When interacting with an existing dependency, the `method` and `path` must be specified correctly to identify it.

| Field | Description | Required? |
| - | - | - |
| **callerTag** | The `tag` of the caller. | |
| **calleeTag** | The `tag` the caller depends on. | |
| **method** | HTTP method *if* depending on a specific endpoint | Required if `path` is present |
| **path** | The actual endpoint (as defined in the OpenAPI file) the caller depends on | Required if `method` is present |
| **description** | A description of the dependency. | |
| **metadata** | JSON metadata tags for the relationship. Supports arbitrary objects. | |

```json theme={null}
{
  "callerTag": "payments-service",
  "calleeTag": "braavos",
  "path": "/2.0/users/",
  "method": "GET",
  "description": "Ensure user has payment information configured",
  "metadata": {
    "tags": ["billing", "identity"],
    "prod": true
  }
}
```

#### **Creating a dependency**

`POST /api/v1/catalog//dependencies/?method=&path=`

```json theme={null}
{
  "description": "Ensure user has payment information configured",
  "metadata": 
}
```

#### **Retrieving a dependency**

`GET /api/v1/catalog//dependencies/?method=&path=`

#### **Updating a dependency**

`PUT /api/v1/catalog//dependencies/?method=&path=`

> [!WARNING]
>
> `PUT` replaces the entire object. The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON is interpreted as `null`.

```json theme={null}
{
  "description": "Ensure user has payment information configured",
  "metadata": 
}
```

#### **Deleting a dependency**

`DELETE /api/v1/catalog//dependencies/?method=&path=`

#### **Creating or updating dependencies in bulk**

`PUT /api/v1/catalog/dependencies`

> [!WARNING]
>
> `PUT` replaces the entire object The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON is interpreted as `null`.

```json theme={null}
{
  "values": {
    "my-service": [
      {
        "tag": "braavos",
        "path": "/2.0/users/",
        "method": "GET",
        "description": "ensure user has payment information configured",
        "metadata": 
      }
    ],
    "my-other-service": [
      {
        "tag": "payments-service",
        "path": "/1.0/widget/",
        "method": "GET",
        "description": "get widget",
        "metadata": 
      }
    ]
  }
}
```

## Syncing dependencies manually

Users with the `Enable Entity Dependency Discovery` permission can manually sync dependencies.

> [!NOTE]
>
> Cortex automatically syncs AWS dependencies every day at 8:00 a.m. UTC. All other dependencies sync at 12:00 a.m. UTC.

**To sync dependencies manually**:

1. From the main sidebar, expand **Tools**, then select **Relationship graphs**.
2. In the upper-right corner of the page, click the **overflow menu icon**, then click **Sync dependencies**.\


   ![The overflow menu icon in the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-overflow.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=0109c08c6f7f1f22e59b185459c63f28)

## Troubleshooting and FAQ

**What if I have multiple dependency sources?**

When leveraging multiple dependency sources (such as Datadog and a catalog entity's YAML), all the sources are merged together and de-duplicated.

For example, if an entity YAML indicates `X->Y` and Datadog indicates `X->Y` and `X->Z`, two edges are presented (`X->Y` and `X->Z`).


# Adding domains
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains



Domains are a default entity type in Cortex used to group entities into hierarchical units. You can group by product area, functionality, systems, business units, or something unique to your organization. With this feature, you can cluster entities into a single, hierarchical domain that can include both parents and children.

You can define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace. This hierarchy is available to view in the Domains catalog, on a domain entity's details page, and in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph). The domain hierarchy can also be used to configure ownership inheritance, helping you keep track of ownership in case of personnel changes at your organization.

## Adding domain entities to Cortex

Users with the `Edit Catalog` and `Edit Domains` permissions can add domain entities to Cortex.

When configuring an entity, you can't add archived teams as owners or archived entities as dependencies, parents, or children.

Domains can be added manually, imported, defined in YAML via GitOps, or created via the API.

For simplicity, it's recommended to add the highest-level domain first, then select it as the parent for subsequent domains. However, you can add parents and children to any domain at any point.

### Importing domains from an integration

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Import discovered entities**.

   ![The 'Import discovered entities' tile is displayed.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/import-method.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=423e270a5aa4b7a19e4ab2662d3f81b2)
4. Select the integration to import from. The **Select entities to import** page is displayed.
5. A list of entities from the integration are displayed. Select the checkboxes next to the entities you want to import. Use the search bar to find entities by name, or click the **Filter icon** in the upper-right corner of the results list to filter by entity type. For Azure DevOps integrations, you can also filter by project name. Search and filters run server-side, so they stay responsive even with large catalogs.

   ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/import-services.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=4dad38f81f97976718cee6f8d20a232e)
6. In the bottom-right corner, click **Next step**. The **Edit details** page is displayed.
7. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
   1. From the **Type** drop-down menu, select **Domain.**
   2. In the **Details** section:
      1. Under **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). It's a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Under **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Repository** section:
      1. From the **Provider** drop-down menu, select the repo provider.
      2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
      3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
      4. Under **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
   4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
      * Cortex may recommend owners [based on your catalog data](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations). You can accept or reject the recommendations.
      * When adding an owner, you can also configure one of the following inheritance options:
        * **Append** - Select this option to add your entity as an additional owner to all of its child entities.
        * **Fallback** - Select this option to add your entity as an owner to child entities if the child entity has no other valid owners.
        * **None** - Select this option if you do not want to configure inheritance. The owner owns the domain you are creating, but will not be configured as an appended or a fallback owner.
   5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
8. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.

   ![The 'Next entity' link in the bottom-right corner of the page.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/services-next-entity.png?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=474ea9b95201cd9e12daa01d28f154d2)
9. Click **Confirm import**. The entity is imported into Cortex.

### Manually adding domains

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Create entities manually**. The **Edit details** page is displayed.
4. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
   1. From the **Type** drop-down menu, select **Domain.**
   2. In the **Details** section:
      1. Below **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Below **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Repository** section:
      1. From the **Provider** drop-down menu, select the repo provider.
      2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
      3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
      4. Below **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
   4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
      * Cortex may recommend owners [based on your catalog data](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations). You can accept or reject the recommendations.
      * When adding an owner, you can also configure one of the following inheritance options:
        * **Append** - Select this option to add your entity as an additional owner to all of its child entities.
        * **Fallback** - Select this option to add your entity as an owner to child entities if the child entity has no other valid owners.
        * **None** - Select this option if you do not want to configure inheritance. The owner owns the domain you are creating, but will not be configured as an appended or a fallback owner.
   5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
5. Optionally, if you'd like to add another entity, click **Add entity** in the upper-right corner of the page.
6. Click **Confirm import**. The entity is imported into Cortex. If there are any errors, a banner appears at the bottom of the page with the errors that need to be fixed.

### Adding a domain in YAML via GitOps

Before creating a domain entity via GitOps, be sure UI-based editing is disabled in Cortex. See [Managing entities via GitOps](/ingesting-data-into-cortex/entities-overview/entities#managing-entities-via-gitops).

The hierarchy of entities in Cortex is based on that hierarchy being defined in the entity's YAML file; Cortex does not set hierarchies based on a YAML file's location in your repository.

**Domain entity descriptor**

If your entity is a domain, you must specify `x-cortex-type` as `domain`:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Payments
  description: Domain encompassing all payment processing, billing, and financial transaction services. Owned by the Platform Engineering team.
  x-cortex-tag: payments-domain
  x-cortex-type: domain
```

**Domain hierarchies**

Hierarchies can be defined in two directions:

* **Top-down** (from the parent) - Use the `x-cortex-children` tag in the parent entity YAML to list its children.
* **Bottom-up** (from the child) - Use the `x-cortex-parents` tag in the child entity YAML to list its parents.

Both approaches produce the same hierarchy; choose whichever fits your workflow. For example, if you frequently update a group of child domains together, defining them on the parent YAML is often more efficient.

**Domain parents**

Define another entity as the parent for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace using the `x-cortex-parents` tag:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Payments
  description: Domain encompassing all payment processing, billing, and financial transaction services. Owned by the Platform Engineering team.
  x-cortex-tag: payments-domain
  x-cortex-parents:
    - tag: engineering-domain
    - tag: fintech-domain
```

> [!NOTE]
>
> Parent entities must be of type `domain`.

**Domain children**

Define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace using the `x-cortex-children` tag:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Payments
  description: Domain encompassing all payment processing, billing, and financial transaction services. Owned by the Platform Engineering team.
  x-cortex-tag: payments-domain
  x-cortex-type: domain
  x-cortex-children:
    - tag: payments-api
    - tag: billing-service
    - tag: payments-database
```

**Ownership inheritance**

A common use case for domains is defining ownership for the subtree of entities. Instead of defining ownership individually for every entity in your catalog, you can define ownership at the domain level and have that pass down to all of its children:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Payments
  description: Domain encompassing all payment processing, billing, and financial transaction services. Owned by the Platform Engineering team.
  x-cortex-tag: payments-domain
  x-cortex-type: domain
  x-cortex-owners:
    - type: group
      name: cortexapps/payments-platform
      provider: GITHUB
      inheritance: APPEND
```

The `inheritance` type for each owner can be one of `APPEND`, `FALLBACK`, or `NONE`. If not set, inheritance is defaulted to `NONE`.

* `APPEND` - This owner is appended to the list of owners for all child entities.
* `FALLBACK` - In the case where a child has no valid owners, including fallbacks, this fallback will be assigned as the owner. Note that this only applies to a child entity down the hierarchy; it is not the fallback for the parent domain itself.
* `NONE` - This owner owns the domain, but not necessarily any of its children (no inheritance).

**Example cortex.yaml file**

> [!NOTE]
>
> The YAML definition for a domain entity can take file names other than `cortex.yaml` or `cortex.yml`; see the [GitOps example repository structure](/configure/gitops#how-gitops-works-in-cortex).

```yaml theme={null}
openapi: 3.0.1
info:
  title: Chat
  description: This is the description of the chat domain.
  x-cortex-tag: chat-domain
  x-cortex-type: domain
  x-cortex-children: # children can be of type service, resource, or domain
    - tag: chat-service
    - tag: chat-database
  x-cortex-parents: # parents can be of type domain only
    - tag: payments-domain
    - tag: web-domain
  x-cortex-owners:
    - type: group
      name: Support
      provider: OKTA
      description: Support Team
  x-cortex-slack:
    channels:
    - name: support-team
      notificationsEnabled: true
      description: This is the description for the support-team Slack channel # optional
  x-cortex-oncall:
    pagerduty:
      id: ASDF2345
      type: SCHEDULE
  x-cortex-apm:
    datadog:
      monitors:
        - 23456
```

### Adding a domain via the Cortex API

You can create, update, and delete domains using the Cortex API. See [Catalog entities](/api/rest/catalog-entities) for more information.

## Viewing domains

The **Domains catalog** page lists every domain entity that's been imported into Cortex. To open it, expand **Catalogs** in the main sidebar and select **Domains**. Each row shows the entity's name and tag.

![Overview of the Domains page in the Cortex UI.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/view-all-domains.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=573e402ee67689ef83f97651d92900b8)

> [!NOTE]
>
> Select the **All** tab to view all entities in your workspace. Select the **Mine** tab to view only entities you own, either as an individual owner or as a member of a team that owns them. In the Teams catalog, **Mine** shows the teams you're a member of. Cortex saves your selection and restores it the next time you open this page.
>
> ![The 'All' and 'Mine' tabs located on the main entities page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-mine-entities.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=90324dcacca6f6293cf40416e793a89f)

### Searching across and filtering domains

![The search and filter options in the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/domains-search-filter.png?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=87ee51980725996e176ee04d6349ff09)

There are several ways to search and filter your domains list.

1. From the main sidebar, expand **Catalogs**, then select **Domains.**
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's domains.
   * Select the **Mine** tab to search and filter only the domains you or your teams own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Do any or all of the following:
   * To find specific domains, use the search bar in the upper-right corner of the page and type to search. The search bar shows which fields you can search on and which field your query is matching. For more information, see [Using search in Cortex](/configure/settings/search#using-the-catalog-search-bar).
   * Click **Name** to select whether you want to sort by name or identifier, and whether to sort by ascending or descending order.
   * Click **Display** to choose whether to show archived domains, display [domains by hierarchy](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains#viewing-the-domain-hierarchy), and/or display empty domains.
   * Click **Filter** to narrow down your list by domain, entity type, group, owner, or team.

### Viewing the domain hierarchy

Follow the steps below to display domains in hierarchy.

1. From the main sidebar, expand **Catalogs**, then select **Domains.**
2. Click **Display** at the top of the domains list.
3. Toggle on **Display hierarchy**.

   ![The 'Display hierarchy' toggle enabled.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/display-hierarchy%20\(1\).jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=c7aaf1849984160bebe956b220b9e132)
4. Click **Done**.

> [!NOTE]
>
> You can also view the hierarchy for a given domain on its [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details).

### Viewing the Relationships page

If the domain has parents or children, those appear on the Relationships page.

![Relationships page for the Authentication domain, showing its parent (Identity) above it and two children (OAuth2 identity service and SSO integration) below it in a vertical hierarchy diagram.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/relationships-page.png?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=f8591c6c9f5e2f4cb3a272a8b651e255)

To access the Relationships page of an entity:

1. From the main sidebar, expand **Catalogs**, then select **Domains.**
2. Click **Display** at the top of the domains list.
3. Select the entity whose relationship graph you want to view.
4. In the entity sidebar, select **Relationships**.

   ![Relationships page for the Authentication domain, showing its parent (Identity) above it and two children (OAuth2 identity service and SSO integration) below it in a vertical hierarchy diagram.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/relationships-page-sidebar%20\(1\).png?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=dd052daeb60e80d6992a2f537ecb93b3)
5. Do any of the following:
   1. Click the **Archive icon** to show or hide archived relationships.
   2. Click the **Filter icon** to narrow the scope of the graph.
   3. By default, the domain hierarchy is displayed as a graph. Click the **Table mode** icon to switch to a tabular view.
   4. Click **Configure** in the upper-right corner to configure the relationship type and its associated entities.

See [Relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph) for more information.

## Editing a domain entity

Users with the `Edit Catalog` and `Edit Domains` permissions can edit domain entities.

Domain entities can be modified at any time. Follow the steps below to edit a domain entity.

1. Navigate to the entity's page.
2. In the upper-right corner, click **Configure entity**.

   The entity details page opens.
3. In the upper-right corner, select either **UI editor** or **YAML editor**.
4. Make your changes. Note that the Cortex tag is uneditable.
5. Click **Save changes**.

   The domain entity is updated.

> [!NOTE]
>
> It's possible to change the entity type via the Cortex YAML. See [Changing an entity's type](/ingesting-data-into-cortex/entities-overview/entities#changing-an-entitys-type) for more information.


# Adding custom entity types
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types



Cortex ships with built-in entity types—services, domains, and teams—to cover common engineering assets, but an organization's catalog rarely stops there. Custom entity types let you model anything your teams track, such as employees, vendors, data pipelines, and compliance controls, with structured metadata you define and enforce.

## Prerequisites

Creating a custom entity type is a two-step process:

1. First, define the ***entity type*** itself (its name, icon, and JSON schema)
   * Users or API keys must have the `Edit Entity Types` permission
2. Next, [create individual entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/creating-custom-entities) of that type via the UI, GitOps, or API.
   * Users or API keys must have the `Edit Entities` permission

## Creating a custom entity type

Users or API keys with the `Edit Entity Types` permission can create, edit, and delete entity types.

Custom entity types can be created manually in the Cortex UI or via the API. The type you define— its schema, required fields, and metadata—shape how entities of that type are imported and validated going forward. Once the type exists, you can create entities of that type through the UI, API, or GitOps.

When configuring an entity, you can't add archived teams as owners or archived entities as dependencies, parents, or children.

### Creating a custom entity type manually in the Cortex UI

1. From the main sidebar, expand **All Catalogs**, then select **All entities**.
2. Select the **Entity types** tab.
3. In the upper-right corner, click **Create**, then select **Create new entity type**.

   The **Create entity type** page opens.
4. In the **Details** section, do the following:
   1. Under **Entity type name**, enter a human-readable name that will appear in the catalog for this entity type (required).
   2. Under **Identifier**, enter a unique identifier consisting of letters, digits, and hyphens that corresponds to the entity type (required). This is used to specify the type defined in the YAML definitions for imported entities.
   3. Under **Description**, enter a description for the entity type.
   4. Under **Display icon**, click **Edit** to select an icon to appear alongside the entity type throughout Cortex.
5. In the **Schema** section, do the following:
   1. Define a [JSON schema](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#json-schema-for-custom-entity-types) to 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.
      * In the example screenshot below, the custom entity type `Employee` represents individuals in an organization. The schema requires each entity to include a `location` , so every entity of type "Employee" must define the employee's location.

        ![A custom entity called 'Employee' contains example JSON, demonstrating how to configure a required 'location' field.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-entity-schema.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=55b28891d06cfad01fc90ab62ad5883c)
6. Click **Create**.

   The new entity type now appears in the **Entity types** tab. You can now import entities of the same type into Cortex.

To automatically assign entities of this type to a specific catalog, configure the catalog's entity types when [creating a new catalog](/ingesting-data-into-cortex/catalogs#create-custom-catalogs). Alternatively, [edit an existing catalog](/ingesting-data-into-cortex/catalogs#edit-catalogs) to add the type.

### Creating a custom entity type via the API

You can create, update, and delete entity types using the [Cortex API](/api/rest/catalog-entities). Learn more about the [JSON schema](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#json-schema-for-custom-entity-types).

## JSON schema for custom entity types

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

Custom entity type definitions are powered by the open-source [JSON Schema](https://json-schema.org/) project.

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.

```json theme={null}
{
  "type": "object",
  "required": [
    "location"
  ],
  "properties": {
    "location": {
      "type": "string"
    },
    "department": {
      "type": "string"
    }
  }
}
```

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Definition</th>
      <th>Required?</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`type`</td>
      <td>Type of entity and/or required component: `array`, `boolean`, `integer`, `null`, `number`, `object`, or `string`</td>

      <td />
    </tr>

    <tr>
      <td>`required`</td>
      <td>Required specs for the entity type</td>

      <td />
    </tr>

    <tr>
      <td>`properties`</td>
      <td>Properties of the required specs (including `type`). Required when `required` is non-empty.</td>
      <td>Conditional</td>
    </tr>
  </tbody>
</table>

### 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.

> **Adding attributes via JSON schema**
>
> When creating a custom entity in the Cortex UI, enter the entity's attribute values as JSON in the **Schema** field.
>
> Using the [example above](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#json-schema-for-custom-entity-types), the schema format looks like:
>
> ```json theme={null}
> {
>     "location": "San Diego",
>     "department": "Engineering"
> }
> ```

> **Adding attributes via YAML**
>
> For GitOps workflows or direct YAML editing in the Cortex UI, define the custom entity's metadata in the YAML.
>
> Using the [example above](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#json-schema-for-custom-entity-types), the entity YAML looks like:
>
> ```text theme={null}
> x-cortex-type: org-employees
> x-cortex-definition:
>    location: San Diego
>    department: Engineering
> ```
>
> The `x-cortex-type` (the custom entity type) and the `x-cortex-definition` are required when creating a custom entity. Learn more under [Create custom entities in the entity descriptor](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#entity-descriptor).

## Metadata in the entity details page

Defining a JSON schema enables visibility on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). The schema and the defined properties appear under the **Overview** section on the entity's overview, making it easy for you to identify key specs.

In the example below, the entity "Alabama" displays metadata for the property `location` :

![The entity, 'Alabama', displays metadata for the property 'location'.](https://mintcdn.com/cortex-290c0c42/uWo5OVZ0DdR5tZ8Q/images/entity-metadata.png?fit=max\&auto=format\&n=uWo5OVZ0DdR5tZ8Q\&q=85\&s=f2153c28a861f39c633fd7730c5066c0)

To access an entity's details page, expand **All Catalogs** from the main sidebar, then select **All entities**. Select an entity to view its details.


# Creating custom entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/creating-custom-entities



This article explains how to create a custom entity. For information on creating a custom entity *type*, see [Adding custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/creating-custom-entities).

## Prerequisites

1. Users or API keys with the `Edit Entities` permission can create custom entities.
2. A [custom entity type](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#creating-a-custom-entity-type). Once the custom entity type is created, you can begin creating entities of that type.

## Creating a custom entity

After creating the custom entity type, you can create entities of that custom type in the Cortex UI, in the entity descriptor YAML via GitOps, or via the Cortex API.

### Creating a custom entity manually in the Cortex UI

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Create entities manually**. The **Edit details** page opens.
4. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
   1. In the **Type** section:
      1. From the drop-down menu, select your custom entity type (required).
      2. Below **Entity 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:

         ![The entity schema includes 'location' and 'department' metadata.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/entity-schema.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=b453a147096bd5cba52ce3af528d9c00)

         * Optionally, click **Show example** above the schema to view an example of how the entity's schema should be formatted. The **Entity Schema Example** window opens. To use the example as a starting point, click **Copy example**, then paste it into the **Entity schema** text editor. See [JSON schema for custom entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types#json-schema-for-custom-entity-types) for more information.
   2. In the **Details** section:
      1. Under **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). It's a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Under **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Repository** section:
      1. From the **Provider** drop-down menu, select the repo provider.
      2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
      3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
      4. Below **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
   4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
      * Cortex may recommend owners [based on your catalog data](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations). You can accept or reject the recommendations.
   5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Dependencies** section, click **Add entity** to select an entity or entities that this entity depends on. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
5. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.
6. Click **Confirm import**. The entity is imported into Cortex.

### Adding a custom entity in YAML via GitOps

Before creating a custom entity via GitOps, be sure UI-based editing is disabled in Cortex. See [Managing entities via GitOps](/ingesting-data-into-cortex/entities-overview/entities#managing-entities-via-gitops).

Custom entity types require both `x-cortex-type` and `x-cortex-definition`.

The `x-cortex-definition` field is validated against the entity type definition created via the UI or API. Even if your custom entity type has no specific requirements, you must still provide a non-null definition, e.g. `x-cortex-definition: {}`.

**Example cortex.yaml**

```yaml theme={null}
openapi: 3.0.1
info:
  title: Henry Tallman
  description: Product Manager
  x-cortex-tag: employee-henry
  x-cortex-type: org-employees
  x-cortex-definition:
    location: Cleveland
    department: Product
```

### Creating a custom entity via the API

You can create, read, update, and delete entities via the [Cortex API](/api/rest/catalog-entities).

> [!NOTE]
>
> Users or API keys must have the `Delete Entities` permission to delete entities.


# Managing custom entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/managing-custom-entities



This article explains how to manage custom entities. For information on managing custom entity *types*, [refer to the documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/managing-custom-entity-types).

## Adding custom entities to catalogs

When you import or create an entity, Cortex automatically assigns it to a catalog based on that catalog's entity type criteria. When you create a [custom catalog](/ingesting-data-into-cortex/catalogs), you define this criteria.

By default, any custom entity types you create belong to the Infrastructure catalog. To assign a custom entity type to a different catalog, add it to that catalog's definition.

## Editing a custom entity

Users or API keys with the `Edit Entities` permission can edit a custom entity.

Follow the steps below to edit a custom entity.

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. Make any necessary changes. Note that the **Type** and **Cortex tag** fields are uneditable.
   * The left sidebar provides additional editing options.
4. Click **Save changes**.


# Managing custom entity types
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/managing-custom-entity-types



This article explains how to manage custom entity *types*. For information on managing custom entities, [refer to the documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/managing-custom-entities).

## Viewing custom entity types

After [creating a custom entity type](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/managing-custom-entity-types), you can view or edit its schema, view a list of entities of the same type, and validate the schema of entities of that type.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Entity types** tab.
3. Select an entity type.

   A list of associated entities is displayed.
4. Do any or all of the following:
   * Select an entity to view more information about it. Learn more about the health and incident columns in Step 3 of [Searching across and filtering entities](/ingesting-data-into-cortex/entities-overview/entities#searching-across-and-filtering-entities).
   * Select the **Schema** tab to copy the schema to your clipboard.
   * Select the **Schema linter** tab to validate the schema for a custom entity type. See [Validating an entity schema for a custom entity type](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/managing-custom-entity-types#validating-an-entity-schema-for-a-custom-entity-type) for more information.
   * Click **Edit** in the upper-right corner to edit the entity type's information and schema. Note that the **Identifier** field is uneditable.
   * Click the **Overflow menu** to delete the entity type.

> [!NOTE]
>
> Built-in entity types are marked with a Cortex logo. Hover over the logo to see a "Powered by Cortex" banner. Any other types in the list are custom entity types created for your workspace.
>
> ![The 'Powered by Cortex' icon appears next to a built-in entity in the Entities list.](https://mintcdn.com/cortex-290c0c42/z5k1sDZlDmCOZ-iP/images/powered-by-cortex.png?fit=max\&auto=format\&n=z5k1sDZlDmCOZ-iP\&q=85\&s=a7556e0ea8bdafa44b635023a7ff4a06)

## Validating an entity schema for a custom entity type

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Entity types** tab.
3. Select an entity type.
4. Select the **Schema linter** tab.
5. In the text editor, paste in your entity's JSON schema to verify that it's properly formatted for this entity type.
   * On the right side of the page, click **Show example** to see an example of how the schema should be formatted.
   * If you want to use the example as a starting point, click **Copy example**, then paste it into the text editor.
6. Click **Validate Schema**.

## 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.

> [!NOTE]
>
> A custom entity type's metadata appears on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details), but custom data appears in the **Custom Data** sidebar.

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

```json theme={null}
{
  "type": "object",
    "required": []
    "properties": {}
}
```

This entity type appears in catalogs, but its entities are not validated against certain specs. Use custom data to define those properties instead.

Schemas enforce static properties consistently across all entities, while custom data lets users augment and update attributes as needed.


# Adding teams
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams



In Cortex, teams are a default entity type that bridge your organizational structure with your software catalog. Unlike a simple label or tag, a team in Cortex is a rich entity with its own details page, Scorecard performance tracking, on-call information, Slack channels, and dependency graph, making it the central hub for understanding who owns what and how those owners are performing.

Teams also reflect real-world org structure through parent-child hierarchies, so you can model everything from individual squads up to entire departments. Whether you bring teams in from an identity provider like Okta or Workday, define them in YAML via GitOps, or create them manually in the UI, Cortex keeps team membership and ownership in sync so when your org changes, your catalog stays accurate without extra effort.

Teams are also the foundation of ownership in Cortex. Rather than assign an entity to individual team members, you can assign ownership to an entire team. This makes it easy to assign multiple team members to an entity, and it ensures that when a team’s composition changes, ownership is updated accordingly. See [Defining ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership).

## Adding team entities to Cortex

Users with the `Edit Catalog` and `Edit Teams` permissions can add team entities to Cortex.

When configuring an entity, you can't add archived teams as owners or archived entities as dependencies, parents, or children.

Teams can be added manually, imported, defined in YAML via GitOps, or created via the API.

### Importing teams from an integration

If you already have a source of truth for teams and members, integrate your identity provider to import them. Cortex syncs team pages daily, eliminating duplicate updates when membership changes.

> [!WARNING]
>
> You can only import entities from integrations that have already been configured.

Teams can be imported from the following integrations:

* [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
* [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr)
* [Entra ID](/ingesting-data-into-cortex/integrations/entraid)
* [GitHub](/ingesting-data-into-cortex/integrations/github)
* [GitLab](/ingesting-data-into-cortex/integrations/gitlab)
* [Google](/ingesting-data-into-cortex/integrations/google)
* [Okta](/ingesting-data-into-cortex/integrations/okta)
* [OpsGenie](/ingesting-data-into-cortex/integrations/opsgenie)
* [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow)
  * [Configure table mappings](/ingesting-data-into-cortex/integrations/servicenow#step-2-configure-table-mappings) before importing
* [Workday](/ingesting-data-into-cortex/integrations/workday)
  * Optionally, enable [automatic import of discovered teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles#adjusting-team-settings)

**To import teams from an integration**:

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Import discovered entities**.

   ![The 'Import discovered entities' tile is displayed.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/import-method.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=423e270a5aa4b7a19e4ab2662d3f81b2)
4. Select the integration to import from. The **Select entities to import** page is displayed.
5. A list of entities from the integration is displayed. Select the checkboxes next to the entities you want to import. Use the search bar to find entities by name, or click the **Filter icon** in the upper-right corner of the results list to filter by entity type. Search and filters run server-side, so they stay responsive even with large catalogs.

   ![](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/import-services.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=4dad38f81f97976718cee6f8d20a232e)
6. In the bottom-right corner, click **Next step**. The **Edit details** page is displayed.
7. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
   1. From the **Type** drop-down menu, select **Team.**
   2. In the **Details** section:
      1. Under **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). It's a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Under **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Members** section, click **Add member**. In the side panel, do the following:
      1. Select a user from the drop-down menu OR enter their information manually. If entering the information manually:
         1. Under **Name**, enter the user's first and last name.
         2. Under **Email**, enter the user's email address.
         3. Under **Description**, enter any relevant information about the user, e.g. their timezone.
         4. From the **Team role** drop-down menu, select the user's team role.
         5. Optionally, toggle on **Notifications** to turn on notifications for the user. See [Notifications](/configure/settings/notifications) for more information.
         6. Click **Add**.
   4. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   5. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   6. In the **Parents** section, select a parent team or teams from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   7. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Jira** section, click **Add** to connect the entity to Jira. In the side panel, do the following:
      1. From the **Jira Service Type** drop-down menu, select the service type:
         1. **Component** - The sub-sections of a project used to group issues.
         2. **Label** - Text-based tags used to categorize and track issues.
         3. **Space** - The area where teams organize, track, and manage their operational work.
      2. From the **Alias** drop-down menu, select the service type's alias.
      3. Depending on the service type you selected, configure the appropriate field:
         1. Select a Jira component from the drop-down menu.
         2. Enter the name of the label.
         3. Select a Jira space from the drop-down menu.
      4. Click **Add**.
   9. In the **Jira JQL Query** section, select an alias from the drop-down menu. Enter a custom JQL query for the entity.
8. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.

   ![The 'Next entity' link in the bottom-right corner of the page.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/services-next-entity.png?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=474ea9b95201cd9e12daa01d28f154d2)
9. Click **Confirm import**. The entity is imported into Cortex.

### Manually adding teams

If you don't have an identity provider with updated team information, you can create teams manually in Cortex. Teams are essential for effective ownership, so it's recommended to set them up even without a single source of truth.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Create entities manually**.
4. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
   1. From the **Type** drop-down menu, select **Team.**
   2. In the **Details** section:
      1. Under **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Under **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Members** section, click **Add member**. In the side panel, do the following:
      1. Select a user from the drop-down menu OR enter their information manually. If entering the information manually:
         1. Under **Name**, enter the user's first and last name.
         2. Under **Email**, enter the user's email address.
         3. Under **Description**, enter any relevant information about the user, e.g. their timezone.
         4. From the **Team role** drop-down menu, select the user's team role.
         5. Optionally, toggle on **Notifications** to turn on notifications for the user. See [Notifications](/configure/settings/notifications) for more information.
         6. Click **Add**.
   4. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   5. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   6. In the **Parents** section, select a parent team or teams from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   7. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Jira** section, click **Add** to connect the entity to Jira. In the side panel, do the following:
      1. From the **Jira Service Type** drop-down menu, select the service type:
         1. **Component** - The sub-sections of a project used to group issues.
         2. **Label** - Text-based tags used to categorize and track issues.
         3. **Space** - The area where teams organize, track, and manage their operational work.
      2. From the **Alias** drop-down menu, select the service type's alias.
      3. Depending on the service type you selected, configure the appropriate field:
         1. Select a Jira component from the drop-down menu.
         2. Enter the name of the label.
         3. Select a Jira space from the drop-down menu.
      4. Click **Add**.
   9. In the **Jira JQL Query** section, select an alias from the drop-down menu. Enter a custom JQL query for the entity.
5. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.
6. Click **Confirm import**. The entity is imported into Cortex.

### Adding a team in YAML via GitOps

Before creating a team entity via GitOps, be sure UI-based editing is disabled in Cortex. See [Managing entities via GitOps](/ingesting-data-into-cortex/entities-overview/entities#managing-entities-via-gitops).

Teams can be created manually in Cortex or defined directly in the entity descriptor, where they can also be assigned as owners. See [Defining ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) for more information.

If your entity is a team, you must specify `x-cortex-type` as `team` :

```yaml theme={null}
openapi: 3.0.1
info:
  title: On-Call Illuminati
  description: They know things. Dark things. Usually around 3am on a Friday.
  x-cortex-tag: on-call-illuminati
  x-cortex-type: team
```

> [!NOTE]
>
> The `x-cortex-team` tag has two main sections: `groups` and `members`.

#### **Adding groups to the team entity descriptor**

Use `groups` to connect a team entity to a matching team on another platform you've integrated with Cortex (such as Okta, GitHub, or Azure AD). Only one group can be linked per team entity.

For example, you can specify:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Firewall Whisperers
  description: They don't block traffic, they have stern conversations with it.
  x-cortex-type: team
  x-cortex-tag: firewall-whisperers
  x-cortex-team:
      groups:
      - name: okta-firewall-whisperers
        provider: OKTA
```

Specifying `okta-firewall-whisperers` under `groups` populates your team with every member of that Okta group.

Once linked, any entity that lists `okta-firewall-whisperers` in `x-cortex-owners` automatically recognizes `firewall-whisperers` as an owning team, no extra configuration required.

For example, a service owned by the team would look like:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Perimeter Defense API
  description: Handles ingress rules, packet inspection, and the occasional stern talking-to.
  x-cortex-type: service
  x-cortex-tag: perimeter-defense-api
  x-cortex-owners:
    - type: group
      name: okta-firewall-whisperers
      provider: OKTA
```

#### **Adding team members to the team entity descriptor**

Use `members` when you need to define team membership directly in Cortex, rather than syncing from an external platform. This is useful when a team doesn't map cleanly to a single group in one of your integrations, or when you need finer-grained control over who belongs and in what role.

For example, you can specify:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Velocity Merchants
  description: They move fast and only sometimes break things. Mostly on Fridays.
  x-cortex-type: team
  x-cortex-tag: velocity-merchants
  x-cortex-team:
      members:
      - name: Sprint Shepherd
        email: sprint.shepherd@cortexlabs.io
        notificationsEnabled: true
        roles: 
          - tag: product-manager
      - name: Merge Maestro
        email: merge.maestro@cortexlabs.io
        notificationsEnabled: true
        roles: 
          - tag: engineering-manager
          - tag: manager 
```

Members support roles, and a single member can hold more than one. When a member's email matches an active Cortex account, that user will see the team appear under their Mine tab in any catalog that includes teams.

The `role` field is optional per member. Roles themselves [must be defined](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles) in the entity's settings page, under the **Teams** tab.

> [!NOTE]
>
> A team doesn't need a linked group. You can define membership with `members` instead, link one group, or use both.

#### **Team children**

Use `x-cortex-children` to define sub-teams, letting you model your org structure as a hierarchy in Cortex. The full hierarchy is visible in the Teams catalog.

> [!NOTE]
>
> Cortex derives hierarchy from what's declared in each YAML file, not from where those files live in your repository.

For example, you can specify:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Platform Overlords
  description: They don't write features. They write the things that let others write features.
  x-cortex-tag: platform-overlords
  x-cortex-type: team
  x-cortex-children:
  - tag: infra-gremlins
  - tag: dev-experience-dreamers
```

#### **Team parents**

`x-cortex-children` defines relationships top-down, but if it's more natural to declare a team's place in the hierarchy from its own YAML, use `x-cortex-parents` instead. Both approaches produce the same result; use whichever fits how your team's YAML is maintained.

For example, you can specify:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Microservices Anonymous
  description: I'm a checkout-service, and I depend on 47 other services.
  x-cortex-tag: microservices-anonymous
  x-cortex-type: team
  x-cortex-parents:
  - tag: platform-overlords
  - tag: engineering-org
```

#### **Example cortex.yaml**

The example below shows a fully defined team entity combining groups, members, children, Slack, and PagerDuty. Note that the file doesn't need to be named `cortex.yaml` or `cortex.yml` . See [GitOps example repository structure](/configure/gitops#how-gitops-works-in-cortex) for more information.

```yaml theme={null}
openapi: 3.0.1
info:
  title: Latency Avengers
  description: Milliseconds are their nemesis. They have the dashboards to prove it.
  x-cortex-tag: latency-avengers
  x-cortex-type: team
  x-cortex-team:
      groups:
      - name: okta-latency-avengers
        provider: OKTA
      members:
      - name: P99 Wrangler
        email: p99.wrangler@cortexlabs.io
        notificationsEnabled: true
      - name: Cache Evangelist
        email: cache.evangelist@cortexlabs.io
        notificationsEnabled: true
  x-cortex-children: # children can be of type team
    - tag: frontend-speed-demons
    - tag: cdn-whisperers
  x-cortex-slack:
    channels:
    - name: latency-avengers
      notificationsEnabled: true
      description: For when dashboards go red and everyone's pinging everyone. # optional
  x-cortex-oncall:
    pagerduty:
      id: P99XQRS
      type: SCHEDULE
```

### Adding a team via the Cortex API

You can create, update, and delete teams using the Cortex API. See [Teams](/api/rest/teams) for more information.

## Editing a team entity

Users with the `Edit Catalog` and `Edit Teams` permissions can edit team entities.

Team entities can be modified at any time. Follow the steps below to edit a team entity.

1. Navigate to the entity's page.
2. In the upper-right corner, click **Configure entity**.

   The entity details page opens.
3. In the upper-right corner, select either **UI editor** or **YAML editor**.
4. Make your changes. Note that the Cortex tag is uneditable.
5. Click **Save changes**.

   The team entity is updated.

> [!NOTE]
>
> It's possible to change the entity type via the Cortex YAML. See [Changing an entity's type](/ingesting-data-into-cortex/entities-overview/entities#changing-an-entitys-type) for more information.


# Team ownership entity editing
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing



Organizations can restrict entity editing to the teams and members who own each entity, avoiding the need to grant edit permissions across the entire workspace. Ownership must be defined on an entity for this to apply.

You can also grant all team members edit access by default.

This article walks you through how to enable the team ownership entity editing feature. For information on adding a team to Cortex, see [Adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing). See [Viewing teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/viewing-teams) for information about viewing teams. Refer to [Team roles](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles) for information on how to add roles and assign them to team members.

## Step 1: Enabling team ownership entity editing

Users with the `Configure Settings` permission can enable the team ownership entity editing setting.

Team ownership entity editing must be enabled before you can assign entity editing access.

> [!WARNING]
>
> The `Configure catalog` permission supersedes **Team ownership entity editing**.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Teams**.
5. In the **Team settings** section, toggle on **Team ownership entity editing**. Enabling this feature ensures that the [default user role](/configure/settings/managing-users/permissioning#default-roles) is automatically updated and will not include generic permissions for editing entities.
   * Note that the `Configure catalog` [permission](/configure/settings/managing-users/permissioning) supersedes the **Team ownership entity editing** feature, so any users assigned a custom role with that permission can continue editing all entities, regardless of ownership. Remove the `Configure catalog` permission from the custom role(s) to restrict the ability to edit entities.
6. Optionally, toggle on **Give edit access to all team members** to give editing access to all members of the team who own an entity.

## Step 2: Specifying team editors

Follow the steps below to define editing access to specific users within a team. Note that you cannot specify specific users if the **Give edit access to all team members** option is enabled. See [Adjusting team settings](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles#adjusting-team-settings) for more information.

1. From the main sidebar, expand **Catalogs**, then select **Teams**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Select a team.
4. In the upper-right corner, click **Configure entity**.
5. From the configuration sidebar, select **Members**.
6. Locate the user you want to make an editor, then click the **pencil icon** next to their name.
7. In the side panel, toggle on the **Editor** setting. Note that if the team member does not have an associated Cortex account, they **cannot** be made an editor.
8. Click **Update**.

On the team page in Cortex, the **Team members** tab displays an `Editor` label next to any members you've marked as editors. Members without a configured [identity mapping](/configure/settings/managing-users/identity-mapping) won't appear as editors.

![The 'Editor' label next to a team member's name on the team page.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/editor-badge.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=2817d4d47b90f4c70e641da74c99ea9e)

## Troubleshooting and FAQ

See frequently asked questions below.

> **Can team editors import entities?**
>
> No, team editors can not import entities. To import entities, a user must have the `Configure catalog` permission, which also gives users the permission to edit ALL entities, not just the ones they own.

> **Can team editors delete entities they own?**
>
> No, team editors can not delete any entities, even if they own them.

> **Can users with the Viewer role edit entities if this feature is enabled?**
>
> Yes, if they are a member of the owning team and either **Give edit access to all team members** is enabled or they have been individually marked as an editor. The team ownership editing feature overrides workspace-level role restrictions for editing team-owned entities.

> **Why does a team member not have the `Editor` label after I enabled edit access to all team members?**
>
> This can happen if the team member's [identity mapping](/configure/settings/managing-users/identity-mapping) has not been configured.


# Team roles
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles



Assigning roles to your team members in Cortex helps you control what each individual can see and do within your organization. This article walks you through how to add roles and assign them to team members. For information on adding a team to Cortex, see [Adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles). See [Viewing teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/viewing-teams) for information about viewing teams. Refer to [Team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing) for information on entity editing.

## Adding a user to a team

Refer to Step 4c in [Manually adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#manually-adding-teams).

A few things to keep in mind:

* Users can only be added to manually created teams, and roles can only be assigned to manually created members.
* Members imported from an identity integration keep their imported role. To change it, update the role in the integration. The change then syncs to Cortex.

## Adding team member roles

Cortex allows you to define roles that can be assigned to team members. Follow the steps below to create a new team member role.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Teams**.
5. In the **Roles** section, click **Add role**.
6. In the right pane, configure the role:
   * Under **Role name**, enter the name of the role.
   * Under **Tag**, the tag auto-populates based on the role name.
   * Under **Description**, enter a description of the role.
   * By default, **Enable notifications by default** is toggle on. If enabled, members with this role receive relevant updates on Scorecards, Initiatives, and more.\


     ![The 'Add role' pane.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/team-member-role.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=e04fec812d4991f5e91b12000467a476)
7. Click **Add role**.

   The role is added to your workspace.

### Applying a role to a team member OR editing a team member's role

Roles can only be applied to manually created team members. Members imported from an identity integration retain the role assigned during import.

1. From the main sidebar, expand **Catalogs**, then select **Teams**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Select a team.
4. In the upper-right corner, click **Configure entity**.
5. From the configuration sidebar, select **Members**.

   ![The 'Members' tab in the configuration sidebar.](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/members-tab.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=2ce1cbbae8f998cf1f4406e31ad586e5)
6. Locate the team member, then click the **edit icon** next to their name.
7. In the side panel, select a role from the **Team role** drop-down menu.
8. Click **Update**.

## Removing a team member

You can remove a team member from a manually added team at any time.

Members imported from an identity integration keep their imported role. To remove them from a team, you'll need to remove them in the integration. The change then syncs to Cortex.

1. From the main sidebar, expand **Catalogs**, then select **Teams**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Select a team.
4. In the upper-right corner, click **Configure entity**.
5. From the configuration sidebar, select **Members**.

   ![The 'Members' tab in the configuration sidebar.](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/members-tab.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=2ce1cbbae8f998cf1f4406e31ad586e5)
6. Locate the team member, then click the **trash icon** next to their name.

   The **Remove team member** window opens.
7. Click **Delete**.

   The team member is removed from the team.

## Adjusting team settings

Users with the `Configure Settings` permission can adjust system-wide settings for entities.

**To access team entity settings**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Teams**.
5. From the **Team settings** tab do any of the following:
   1. In the **Team settings** section, toggle on or off the following:
      1. **Auto import Workday teams** - If enabled, Cortex automatically imports any discovered teams and team relationships from Workday. See [the Workday documentation](/ingesting-data-into-cortex/integrations/workday/using-the-integration-for-workday#importing-teams-automatically) for more information.
      2. **Team ownership entity editing** - If enabled, only specific members of the team can edit the entity. See [Team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing) for more information.
      3. **Give edit access to all team members** - If enabled, all team members are granted edit access to the entities owned by the team. Note that turning off editing access for specific members is not supported.
      4. **Sync team roles from identity providers** - If enabled, Cortex automatically assigns roles to team members based on your enabled identity providers. Select the **Identity providers** tab to view your enabled identity providers. Enable this setting if you plan to restrict [data verification](/configure/settings/entity-settings/viewing-and-verifying-data-verifications#how-to-verify-an-entity) to specific team member roles, since members imported without a role can't verify entities.
   2. In the **Roles** section, add, edit, or remove team member roles.
6. From the **Identity providers** tab, enable Cortex to use identity providers to sync teams and team memberships. Toggle on an identity provider to enable automatic sync.
   * When you import teams, Cortex shows the enabled IdPs listed on this page as import options.


# Viewing teams
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/viewing-teams



This article covers viewing teams in Cortex. For information on adding a team to Cortex, see [Adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/viewing-teams). For information on adding users to teams and assigning roles, see [Team roles](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-roles). Refer to [Team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing) for information on entity editing.

## Viewing the Teams catalog page

The **Teams** **catalog** page lists every team entity that's been added to Cortex. To open it, expand **Catalogs** in the main sidebar and select **Teams**. Each row shows the entity's name and number of team members.

![Overview of the Teams page in the Cortex UI.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/teams-page.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=68de9bf16db4c25a351203b0b4fe2467)

> [!NOTE]
>
> Select the **All** tab to view all entities in your workspace. Select the **Mine** tab to view only entities you own, either as an individual owner or as a member of a team that owns them. In the Teams catalog, **Mine** shows the teams you're a member of. Cortex saves your selection and restores it the next time you open this page.
>
> ![The 'All' and 'Mine' tabs located on the main entities page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-mine-entities.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=90324dcacca6f6293cf40416e793a89f)

### Searching across and filtering teams

![The search and filter options in the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/teams-search.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=1f9c848909e59efbbd2ffd8c7eb1c444)

There are several ways to search and filter your teams list.

1. From the main sidebar, expand **Catalogs**, then select **Teams.**
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's teams.
   * Select the **Mine** tab to search and filter only the teams you're a member of.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Do any or all of the following:
   * To find specific teams, use the search bar in the upper-right corner of the page and type to search. The search bar shows which fields you can search on and which field your query is matching. For more information, see [Using search in Cortex](/configure/settings/search#using-the-catalog-search-bar).
   * Click **Name** to select whether you want to sort by name or identifier, and whether to sort by ascending or descending order.
   * Click **Display** to choose whether to show archived teams and/or display teams by hierarchy.
   * Click **Filter** to narrow down your list by team, member, or group.

### Viewing team hierarchy

Follow the steps below to display teams in hierarchy.

1. From the main sidebar, expand **Catalogs**, then select **Teams.**
2. Click **Display** at the top of the teams list.
3. Toggle on **Display hierarchy**.

   ![The 'Display hierarchy' toggle enabled.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/display-hierarchy%20\(1\).jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=c7aaf1849984160bebe956b220b9e132)
4. Click **Done**.

> [!NOTE]
>
> You can also view the hierarchy for a given team on its [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details).

#### Understanding hierarchies

Cortex lets you structure teams to reflect your organization's real hierarchy, whether you're creating teams manually or importing them. Any team can be both a parent to other teams and a child of another, so multi-level structures are fully supported.

The Teams catalog page displays individual and parent teams by default. An arrow next to a team's name indicates it has children; click to expand and view child teams.

In the image below, `My Company` is a parent team with 7 child teams nested under it.

![An arrow icon is displayed next to a parent team. Click the arrow to expand the hierarchy.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/view-teams-hierarchy.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=b8f8746e1dc57bd0269c6aa3427e3a38)

### Viewing the Scorecard leaderboard

![The Scorecard leaderboard is displayed on the Teams page.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/teams-leaderboard.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=e119cd19945b4be512c66a23eefd7d3a)

On the right side of the Teams catalog page is the Scorecard leaderboard, which highlights the 10 best-performing teams within your organization.

The leaderboard is calculated from the average of [Scorecard](/standardize/scorecards) scores for all entities owned by a team. Change in rank is based on the team's score 7 days ago. You can use the drop-down to select a different Scorecard, allowing you to view the leaderboard based on specific Scorecards.

> [!TIP]
>
> The leaderboard gamifies entity quality and encourages team members to achieve goals. This creates a culture of accountability, where everyone has visibility into how they're performing.

## Viewing an individual team's page

Every team has a dedicated details page displaying its key information. Follow the steps below to access a team's details page.

1. From the main sidebar, expand **Catalogs**, then select **Teams.**
2. Select a team to view its individual page.

On the team's details page, you’ll find the following:

* The [entity details sidebar](/ingesting-data-into-cortex/entities-overview/entities/details#configuring-the-entity-details-sidebar)

  ![The entity details sidebar.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/team-details-page.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=21634b592648e8d5ed90d68091c6e9f1)
* The [team name and tag](/ingesting-data-into-cortex/entities-overview/entities/details#locating-an-entitys-unique-identifiers)
* The main **Overflow menu** icon and the **Configure entity** button
* The **Overview** tab:
  * The **Team members** section
    * Includes a list of all team members, their roles, and their emails. When available, Cortex pulls in profile photos from your Git provider.
  * The **Scorecards** section
    * An overview of how the team is performing across Scorecards. By default, the snapshot shows the level that the team’s entities have reached in each Scorecard. Optionally, click the arrow next to This entity only to include entity's children.
  * The **Latest events** section
    * A list of recent events associated with this team, such as alerts from [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty).
* The **Entities** tab:
  * Shows a list of linked entities, including number of incidents and health status. Click into an entity to learn more about it. Optionally, click the **Overflow menu** to copy the entity to your clipboard or view the entity in the relationship graph.
* The [metadata sidebar](/ingesting-data-into-cortex/entities-overview/entities/details#configuring-the-entity-metadata-sidebar)


# Archiving entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/archiving-entities



## Overview

Archiving an entity in Cortex hides it from view without losing any of its history or data, so you can always restore it later. Entities can be [archived manually](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/archiving-entities-manually) (one at a time or in bulk) or [automatically](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive) when Cortex no longer detects them in your integrations or their YAML file is deleted. All changes are recorded in your audit log.

Auto-archival applies to entities that are no longer backed by any discovery provider (e.g., Git, Kubernetes, your cloud account). If one reappears, it's unarchived automatically. Entities that failed to sync due to errors are skipped, so a temporary integration issue won't cause anything to disappear. Admins can disable this behavior to manage archiving manually instead.

Archived entities are not included in the following Cortex features:

* Scorecards and Initiatives
* Reports
* Eng Intelligence
* Cortex Query Language (CQL) features, including CQL reports and query builder
* Relationship graphs
* Workflows

> [!NOTE]
>
> Cortex tags detect changes to signify whether an entity or repository has been archived. Learn more in [Viewing discovered entities](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit).

## Displaying archived entities in Cortex

### Displaying archived entities in the Entities list

By default, archived entities do not appear in the **All entities** list, but you can choose to include them in your view.

> [!WARNING]
>
> This setting resets when you leave the page, so you'll need to toggle it on it each time you want to view archived entities.

**To include archived entities**:

1. From the main sidebar, expand **Catalogs**, then select **All entities.**
2. At the top of the list, click **Display**.

   ![The 'Show archived' toggle turned on to include archived entities in the list.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/display-archived-entities.png?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=ec0360a8497ad6ebdb7f349930184ba8)
3. Toggle on **Show archived**.

### Displaying an Archived label next to an entity

The **Overview** section on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details) only shows active dependencies, child entities, and parent entities; anything archived is hidden. If the entity itself is archived, an **Archived** label appears next to its name:

![An archived entity has an 'Archived' label next to its name.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/archived-entity-label.png?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=520caedd4e0ccd772e0740c545a9065a)


# Archiving entities manually
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/archiving-entities-manually



You might want to archive an entity before Cortex does it automatically, e.g. a service you're deprecating. This article covers how to archive and unarchive entities manually, individually or in bulk.

## Archiving an entity via the Cortex UI

Users with the `Archive Entities` permission can archive an entity.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Select the entity you want to archive.
4. From the entity's details page, click the **overflow menu icon**.

   ![The Overflow icon on an entity's details page.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/archive-entity-overflow.png?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=4a0c5586b7a1b0d25638656d4db196e9)
5. Select **Archive entity**.

   The **Confirm entity archival** window opens.
6. Click **Archive**.

   The entity is archived.

> [!WARNING]
>
> When an entity is archived, it no longer appears in the Entities list. Refer to [Displaying archived entities in the Entities list](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/archiving-entities-manually#displaying-archived-entities-in-the-entities-list).

### **Unarchiving an entity via the Cortex UI**

Users with the `Configure Entities` permission can unarchive an entity.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. At the top of the list, click **Display**.

   ![The 'Show archived' toggle turned on to include archived entities in the list.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/display-archived-entities.png?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=ec0360a8497ad6ebdb7f349930184ba8)
4. Toggle on **Show archived**.
5. Select the entity from the Entities list.
6. From the entity's details page, click the **overflow menu icon**.

   ![The Overflow icon on an entity's details page.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/archive-entity-overflow2.png?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=33ced1d552e120db96e239a0d11a09e9)
7. Select **Unarchive entity**.

   The **Confirm entity restoration** window opens.
8. Click **Restore**.

   The entity is unarchived and moved back into the Entities list.

## Archiving an entity via the Cortex API

Refer to the API documentation on [archiving an entity](/api/rest/catalog-entities#put-api-v1-catalog-tagorid-archive) and [unarchiving an entity](/api/rest/catalog-entities#put-api-v1-catalog-tagorid-unarchive).


# Archiving entities automatically
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive



Cortex automatically archives entities when they're no longer detected in your integrations, so your catalog stays in sync as entities come and go. For example, if AWS auto-hydrates your catalog, enabling auto-archive will archive any entities that are later deleted from AWS.

This article covers how auto-archival works and how to configure it.

> [!TIP]
>
> It's highly recommended to enable this feature to keep your data up-to-date.

Cortex checks every day at 7 a.m. UTC for any affected entities, and skips archiving if any errors are detected.

## Enabling auto-archive of entities

Users with the `Edit Settings` permission can enable the auto-archive entities feature.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select the **General** tab.

   ![The 'General' tab within Cortex settings.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/archive-entity-general-setting.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=30f2bbcd8ad481d709a729da732f3cbf)
5. On the **General** page, scroll to the **Auto-archiving entities by type** section.

   ![The 'Auto-archiving entities by type' section.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/auto-archive-entities.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=d4f5250ebdf3793ea4ec80ba1c032d25)
6. Toggle on any or all of the following:
   * **Enable integration-based auto-archiving for new entity types by default**
     * Toggle on this setting if you want to enable the feature for integration-based archiving. Cortex automatically archives and unarchives entities based on their existence in a third-party integration.
     * Cortex checks for a deleted or archived repo in your integration. To prevent an entity from being unarchived, make sure you have deleted the associated repo. The entity is removed the next time the archival sync runs.
     * This option is recommended if you use microservices that all live in different repos.
   * **Enable GitOps based auto-archiving for new entity types by default**
     * Toggle on this setting if you want to enable the feature for GitOps-based archiving. Cortex automatically archives entities if their corresponding YAML file is deleted.
     * If the file is moved rather than deleted, it is not archived from Cortex. Cortex checks for files that have been deleted.
   * **Auto-archive monorepo entities**
     * When enabled, if a monorepo is archived or unarchived, all entites in Cortex relating to that repo are automatically archived or unarchived.

> [!NOTE]
>
> An entity's `x-cortex-tag` cannot be overwritten; attempting to update the `x-cortex-tag` value via GitOps creates a new entity. The entity only automatically archives if its original YAML file no longer exists in your Git environment.
>
> To change an entity's `x-cortex-tag`, you must archive or delete the entity, then create a new entity with the desired tag.

## Enabling auto-archive per entity type

Users with the `Edit Settings` permission can enable auto-archive per entity type.

Below the auto-archive setting, each entity type (default and custom) is listed with its own toggle, so you can enable auto-archival selectively per type.

![Enable auto archive per entity type.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/archive-per-type.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=4e498ba611ae40a1257954ed567d7e2a)

## Triggering an entity sync

Users need the `Edit Catalog` permission, combined with either:

* `Edit Domains`, `Edit Teams`, or `Edit Services` (depending on the entity type being archived), OR
* `Edit All Catalog`, which covers every entity type.

Deleted entities appear in the Entities list until the next time the auto-archival sync runs. You can also manually trigger the sync.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper right corner, click **Import entities**.
3. Select **Import discovered entities**.
4. Select an integration.

   The **Select entities to import** window opens.
5. Click **Sync entities**.

## Troubleshooting and FAQ

See frequently asked questions below.

> **Why is an entity unexpectedly re-appearing after it's been archived?**
>
> If you are using the integration-based auto-archiving, Cortex is checking whether the entity exists in your third-party integration. When Cortex runs the background sync for entity discovery, if the repo connected to that entity still exists, Cortex will un-archive the entity. To prevent un-archival, you can either delete the associated repo, or you can use the GitOps-based auto-archiving instead.

> **Why is an entity still appearing after I deleted the YAML file for it or deleted the associated repo?**
>
> The auto-archival feature runs once a day at 7 a.m. UTC. The entity appears until the next time the auto-archival sync runs or until you [manually trigger the sync](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive#trigger-an-entity-sync).


# Adding custom data
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/custom-data



Custom data extends Cortex's out-of-the-box metadata by letting you attach additional attributes to entities. It can be used in CQL queries and Scorecard rules.

You can also [delete custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data#deleting-custom-data) from an entity in Cortex or via API.

Custom data can be defined manually in [the entity descriptor](/ingesting-data-into-cortex/entities-overview/entities/custom-data#defining-custom-data-in-the-entity-descriptor), added programmatically [via API](/ingesting-data-into-cortex/entities-overview/entities/custom-data#defining-custom-data-via-api), or sent through a [custom webhook integration](/ingesting-data-into-cortex/entities-overview/entities/custom-data#defining-custom-data-via-webhook).

## Custom data vs. custom metrics

Cortex also offers [custom metrics for Eng Intelligence](/improve/eng-intelligence/custom-metrics). Note the following differences between custom data and custom metrics:

* **Custom data** - Used for static or slowly changing metadata (e.g. deployment environments, compliance statuses). Best for enriching entity details, reporting, and Scorecard rules. Note that new values overwrite previous ones for the same key, so it's not suited for time-sensitive tracking. Refer to the [use cases](/ingesting-data-into-cortex/entities-overview/entities/custom-data#use-cases) below.
* **Custom metrics** - Used for time series or trending data (e.g. incident counts, SLOs). Designed for analytics; use them in dashboards, entity pages, and Scorecards. See [Custom metrics](/improve/eng-intelligence/custom-metrics) for more information.

## Defining custom data

There are a few ways to add custom data to an entity:

* **In the entity descriptor** - Best for low-volume, human-maintained data; requires updating the entity's YAML when the data changes.
* **Via REST API** (`POST`) - Best for data from automated processes like CI/CD pipelines.
* **Via webhook** - Useful when you don't have access to the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities/custom-data#cortex-tag) or can't add authentication headers, as it requires neither.

### Defining custom data in the entity descriptor

> [!TIP]
>
> Learn more about [entity YAML descriptors](/ingesting-data-into-cortex/entities-overview/entities/custom-data#defining-entities-via-yaml-file) in the Cortex documentation.

The simplest way to add custom data is to define an object under `x-cortex-custom-metadata`:

```yaml theme={null}
x-cortex-custom-metadata:
  team-owner: platform-engineering
  deployment-env: production
  compliance-status:
    value: SOC2
    description: Certified under SOC2 Type II as of 2024.
  pagerduty-enabled: true
```

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`key`</td>
      <td>Key or title for the custom data. Anything defined **before** the `:` serves as the `key`.</td>
      <td>**✓**</td>
    </tr>

    <tr>
      <td>`value`</td>
      <td>Value for the custom data. Anything defined **after** the `:` is the `value`.</td>
      <td>**✓**</td>
    </tr>
  </tbody>
</table>

Custom data supports any type: scalars (strings, numbers, booleans), objects, and lists. Once added, key-value pairs appear on the entity's custom data page, tagged as YAML.

#### **Adding descriptions**

To include a description alongside a value, use the explicit `value` + `description` syntax. Note that when a description is present, `value` must be explicitly defined (rather than inlined):

```yaml theme={null}
x-cortex-custom-metadata:
  supported-regions:
    value: 3
    description: us-east-1, eu-west-1, ap-southeast-1
  on-call-rotations:
    value: 2
    description: Primary and secondary on-call rotations are active for this service.
```

| Field | Description | Required |
| - | - | - |
| `key` | Key or title for the custom data. Anything defined **before** the `:` serves as the `key`. | **✓** |
| `value` | Value for the key; should be defined explicitly with `value:`. | **✓** |
| `description` | Description of the custom data | **✓** |

> [!NOTE]
>
> Descriptions are always optional, but if you want to add one, the `value` key is required.

### Defining custom data via API

You can pipe custom data directly into Cortex by POSTing to `/api/v1/catalog/{tag}/custom-data`, where `{tag}` is the entity's `x-cortex-tag`. The request body requires JSON. See the [Custom data API docs](/api/rest/custom-data) for authentication details and required fields.

**Key precedence and overwriting**

If a key is already defined in the entity descriptor, the API does not overwrite it. Instead, it returns the existing value with `YAML` as the source. To explicitly overwrite a YAML-defined value, use the `force=true` query parameter. That said, if you find yourself relying on `force=true`, it's worth updating or removing the field from the YAML to keep a clear source of truth.

> [!NOTE]
>
> Custom data added via API displays with an API tag.

**Bulk upload**

To upload multiple keys for one or more entities at once, `PUT` to `/api/v1/catalog/custom-data`:

```json theme={null}
{
  "values": {
    "payments-service": [
      {
        "key": "deployment-env",
        "value": "production",
        "description": "The environment this service is currently deployed to."
      }
    ],
    "user-auth-service": [
      {
        "key": "compliance-status",
        "value": {
          "certified": "SOC2",
          "last-audit": "2025-03-15",
          "reviewed-by": "security-team"
        }
      }
    ]
  }
}
```

Each tag can include multiple key-value objects, following the same shape as the single upload API.

### Defining custom data via webhook

Refer to [Custom webhook integrations](/ingesting-data-into-cortex/integrations/webhook)

## Data source hierarchy

When the same key is defined from multiple sources, Cortex resolves conflicts in the following order:

1. **Entity descriptor (YAML)** - The source of truth. Keys defined here cannot be overridden by the API or webhooks by default. Use `force=true` to override them via API, but note that the forced value will be overwritten the next time the entity descriptor is re-processed.
2. **API and webhooks** - Treated equally; either can override the other.

## Deleting custom data

You can delete custom data that's no longer accurate, for example a value that points to a deployment branch your team stopped using. When you delete a key, Cortex re-evaluates the entity's Scorecards so that rules based on that key reflect the change.

### Deleting custom data in Cortex

To delete custom data, you need permission to edit the entity. This includes users with the `Edit and Create Entities` permission and, if your workspace uses [team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing), the entity's owners.

1. Go to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the left entity sidebar, select **Custom data & metrics**.
3. On the **Custom data & metrics** page, locate the key you want to remove, then click the **trash icon**. The **Delete custom data** window opens.
4. Click **Delete**.

Each deletion is recorded in your workspace's [audit logs](/configure/settings/audit-logs).

> [!NOTE]
>
> Custom data defined in the entity descriptor (tagged **YAML**) can't be deleted from this page. To remove it, delete the key from the entity's YAML. If an automated process sends a key through the API or a webhook, update that process too, so the key isn't added back.

### Deleting custom data via API

To delete custom data programmatically, send a `DELETE` request to `/api/v1/catalog/{tag}/custom-data` with the `key` query parameter. See [Delete custom data for entity](/api/rest/custom-data/delete-custom-data-for-entity) for details.

> [!NOTE]
>
> The Cortex MCP can't delete custom data. To protect your data from accidental removal, Cortex doesn't make any delete endpoints available through the MCP. Learn more in [What the Cortex MCP can't do](/get-started/cortex-ai-assistant/mcp/using-cortex-mcp#what-the-cortex-mcp-cant-do).

## Use cases

Custom data is flexible by design. Below are two of the most common ways teams put it to work.

### Cataloging

Cortex catalogs surface a lot out of the box—ownership, integration data, and more—but you may have internal fields that don't map to any integration. Custom data fills that gap. Common examples include:

* ***Which AWS zones is this deployed in?***
* ***What databases does this entity consume?***
* ***When was the last successful CI run?***

If the answers fit a fixed list, consider using [groups](/ingesting-data-into-cortex/entities-overview/entities/groups) instead. They display on an entity's details page and work well as catalog filters. Custom data is better suited for flexible or freeform values.

Once defined, custom data can be queried with the [Query builder](/standardize/cql#the-query-builder-tool), explored via [CQL reports](/standardize/cql/cql-reports), viewed directly on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details), or added as a column in Data Explorer's [table view](/improve/eng-intelligence/data-explorer#configuring-table-view).

### Scorecards

Custom data integrates directly with Scorecards. When [adding a rule](/standardize/scorecards/create#step-3-create-a-rule), select **Custom data** from the **Integrations** drop-down menu. Cortex automatically surfaces variables based on the custom data you've defined.

![The 'Custom data' option selected in the Integrations drop-down menu.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/custom-data-scorecard.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=35c275b4903abd6af09b8a1f3f13478a)

For more advanced use cases, push JSON payloads via the [custom data API](/api/rest/custom-data) and process them in a Scorecard using `jq`, or pass them as input to a custom OPA policy rule.


# Defining relationship types
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types



Every organization has structure: teams own services, services depend on each other, domains group related capabilities. Relationship types are how Cortex models that structure, letting you define not just *that* two entities are related, but *how* they relate and *what kinds* of entities can participate.

## Understanding relationship types in Cortex

A relationship type captures the semantics of a connection between entities: its directionality, the roles each side plays, and the constraints on what can appear at either end. Rather than treating all relationships as equivalent links, Cortex distinguishes between a few fundamentally different relationship patterns:

* **Entity relationships** - Customizable relationships (hierarchical or cyclical) between any entity types
* **Team hierarchies** - Hierarchical relationships specifically between teams, including [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) over other entities. Learn more in [Understanding hierarchies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/viewing-teams#understanding-hierarchies).
* **Domain hierarchies** - Hierarchical relationships between domains, with optional inheritance so ownership can flow down from parent to child. Learn more in [Viewing the domain hierarchy](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains#viewing-the-domain-hierarchy).
* **Dependencies** - Cyclical relationships between non-team entities. Learn more in [Defining dependencies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies).

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy course on [Catalogs, Entities, and Relationships](https://academy.cortex.io/courses/understanding-understanding-catalogs-entities-and-relationships).

### **Relationship direction: Source vs. destination**

Every relationship has a direction. The **source** is the parent (the upstream entity), and the **destination** is the child (the downstream entity). For example, in a *Repository* relationship, a `Service` (source/parent) contains a `Repository` (destination/child).

This direction determines how the relationship is drawn in an entity's relationships graph, so define it carefully when creating a relationship type. If upstream and downstream appear reversed, the source and destination entities were likely defined in the opposite order.

### Custom relationship type use cases

| Relationship type | Description | Source | Destination |
| - | - | - | - |
| **Repository** | Mapping services to repositories to view the hierarchy of repos and the services they contain. For example, a service is linked to its code repository. | Service | Repository |
| **Cloud account to resource** | Associating cloud accounts (like AWS, Google Cloud Project, or Azure subscription) with their respective resources (such as EC2 instances or other cloud resources). |  • AWS account • GCP • Azure subscription |  • AWS resources (e.g., EC2) • Google Cloud resources • Azure resources |
| **Service to environment** | Linking services to their deployment environments. | Service | Environment |
| **Monorepo** | Mapping multiple services to a single repository. | Repository | Service |
| **Service to endpoint** | Associating services with their endpoints. | Service | Endpoint |
| **Data center modeling** | Representing data centers and their relationships to other infrastructure components. | Data center | Component |

> [!WARNING]
>
> Use team [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) to represent ownership relationships, not custom relationship types.

## Viewing relationship types

### Viewing all configured relationship types

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.

   ![The 'Relationship types' tab on the Entities page.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/relationship-types-tab%20\(1\).png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=5af78499c846a6298f623be909cbf9aa)
3. Select a relationship type from the list to view more information.

### Viewing relationships on entity pages

If an entity belongs to a relationship, you can explore that context directly from its [details page](/ingesting-data-into-cortex/entities-overview/entities/details).

1. Navigate to the entity's details page.
2. From the left entity details sidebar, select **Relationships**. Relationship types associated with the entity appear in the relationships graph.

In the example below, the entity `California` belongs to a relationship called `Geography` . Relationships default to **graph view**, giving you a visual map of parent/child connections, where sources (parents/upstream) connect to their destinations (children/downstream).

![The relationship graph of an entity.](https://mintcdn.com/cortex-290c0c42/xjQHwXJYhhBDyXuQ/images/Screenshot%202026-02-18%20at%202.18.29%E2%80%AFPM.png?fit=max\&auto=format\&n=xjQHwXJYhhBDyXuQ\&q=85\&s=2f325a45c027da90184174b08e1ff2f7)

From the graph, click any entity to view a quick summary of its metadata. Select **Go to entity** to navigate directly to that entity's detail page.

![Screenshot 2026 02 18 At 2 38 00 PM](https://mintcdn.com/cortex-290c0c42/xjQHwXJYhhBDyXuQ/images/Screenshot%202026-02-18%20at%202.38.00%E2%80%AFPM.png?fit=max\&auto=format\&n=xjQHwXJYhhBDyXuQ\&q=85\&s=eed0267c43d40c281fb941e6f7b9c0e7)

Select **Table view** to see the same data in a structured list. This view is useful for quickly scanning or sorting related entities.

![Screenshot 2026 02 18 At 2 21 22 PM](https://mintcdn.com/cortex-290c0c42/xjQHwXJYhhBDyXuQ/images/Screenshot%202026-02-18%20at%202.21.22%E2%80%AFPM.png?fit=max\&auto=format\&n=xjQHwXJYhhBDyXuQ\&q=85\&s=f06de15facf25f5af261ea2f73880bbd)

## Entity relationship CQL

You can create Scorecard rules and write [CQL queries](/standardize/cql) based on entity relationships. See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **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:
>
> ```text theme={null}
> 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:
>
> ```text theme={null}
> entity.sources(relationshipType = "my-relationship").length > 0
> ```


# Managing relationships
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types/managing-relationships



Cortex captures your organization's structure through two complementary concepts: **relationship types** and **relationship connections**.

A **relationship type** defines the rules of a connection: what it means, which entity types can participate, whether it flows in one direction or can form cycles, and whether metadata should inherit across it. Think of it as a template (e.g. "Repository," "Cloud account to resource," or "Service to environment") that describes *how* two kinds of entities relate before any specific entities are linked.

A **relationship connection** is a concrete instance of that template: the actual link between two specific entities. For example, once you've defined a "Repository" relationship type, a connection is what ties your `payments-service` entity to its specific GitHub repository entity.

This separation gives you flexibility and consistency. You define the shape of a relationship once, then apply it across as many entity pairs as needed. Relationships can be hierarchical (acyclical, like an org chart) or graph-like (cyclical, like service dependencies), and they can carry ownership metadata that flows from parent to child.

Together, relationship types and connections give Cortex a way to reflect how your systems actually fit together.

## Creating relationship types

Users with the `Edit Relationships` permission can create a relationship type.

Relationship types must be created via the Cortex UI or the API.

### Creating relationship types via the Cortex UI

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. In the upper-right corner, click **Create**, then click **Create new relationship type**.

   The **Create new relationship** page is displayed.
4. In the **Details** section, do the following:
   1. Under **Name**, enter a name for the relationship type (required).
   2. The **Identifier** auto-populates based on the relationship type name and is made up of letters, digits, and hyphens.
   3. Under **Description**, enter a description of the relationship to help others understand its purpose.
   4. Toggle on **Create relationship type catalog** to create a catalog for this relationship type.
5. In the **Source entity types** section, do the following:
   1. From the drop-down menu, select an entity type. If no entity type is selected, all entity types are available as sources.
   2. Toggle on **Exclude** to hide all entity types from sources, or leave toggled off to include all.
   3. Optionally, customize the singular and plural wording of the entity types and the cardinality.
6. In the **Destination entity types** section, do the following:
   1. From the drop-down menu, select an entity type. If no entity type is selected, all entity types are available as destinations.
   2. Toggle on **Exclude** to hide all entity types from destinations, or leave toggled off to include all.
   3. Optionally, customize the singular and plural wording of the entity types and the cardinality.
7. In the **Relationship constraints** section, do the following:
   1. Select an architecture:
      1. **Acyclical** - Recommended for hierarchical data such as an org chart or product hierarchy.
      2. **Cyclical** - Recommended for graph-like data such as dependencies.
   2. Under **Definition location**, select a location:
      1. **From destination** - If selected, relationships can only be defined from destination entities.
      2. **From source** - If selected, relationships can only be defined from source entities.
      3. **Either source or destination** - If selected, relationships can be defined by either destination or source entities.
   3. Toggle on **Ownership** to configure inheritance for the relationship type, then select how metadata will be inherited. Learn more in [Ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance).
      1. **Fallback**: This option uses the source's data only if the destination does not have anything defined.
      2. **Append**: This option appends the source's data to the destination, even if it already has data defined.
8. Click **Create**.

### Creating relationship types via the API

You can create, update, and delete relationship types using the [Cortex API](/api/rest/entity-relationship-types).

## Creating relationship connections between entities

After creating a relationship type, connections between entities can be made via the Cortex UI, an entity descriptor, the API, or an integration.

### **Creating relationship connections via the UI**

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. From the left entity sidebar, click **Relationships**.
4. In the **Relationship type** section, select a relationship type to configure from the drop-down menu.
5. Select the entities you want to connect. The available fields depend on the relationship type selected.
6. Click **Save changes**.

### Creating relationship connections via an entity descriptor

Once a relationship type exists, you can define the connection in either the source or destination entity's YAML using the `x-cortex-relationships` tag.

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`.

```yaml theme={null}
  x-cortex-relationships:
  - type: app-components
    destinations:
    - tag: production-ui
    - tag: backend-app
```

Optionally, this can be configured in the YAML of the destination by replacing `source` with `destination` in the YAML above.

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.

### Creating relationship connections via the API

You can create, update, and delete relationships between entities using the [Cortex API](/api/rest/entity-relationships).

### Creating relationship connections via an integration

At this time, Cortex only supports integration-based relationship creation via AWS. See [Configuring tag-based auto-linking](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#configuring-tag-based-auto-linking-for-aws) for more information.

## Editing a relationship type

Users with the `Edit Relationships` permission can edit a relationship type.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Locate the relationship type you want to edit, then click the **pencil icon** next to it.
4. Make any necessary changes.
5. Click **Save**.

## Deleting a relationship type

Users with the `Edit Relationships` permission can delete a relationship type.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Select the relationship type you want to delete.
4. Click the **Overflow menu** icon, then click **Delete relationship type**.


# Adding deployment data via API
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/deploys



Getting deployment data into Cortex is critically important for both engineering insights and organizational success. It enables the use of [Eng Intelligence](/improve/eng-intelligence) to assess [DORA metrics](/improve/eng-intelligence/dora-dashboard) and other KPIs to understand how quickly and efficiently your teams are shipping code. Deployment data also gives you the insight needed to create [Scorecards](/standardize/scorecards) and [Initiatives](/improve/initiatives) that promote process improvement across teams.

> [!TIP]
>
> If you deploy with Harness, Cortex can import your deployments directly, without an API call from your pipeline. See [Using the integration for Harness](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness#viewing-harness-pipelines-and-deployments). If you set up the Harness integration, remove any pipeline step that also sends those deploys to the deploys API, so each deployment isn't counted twice.

## Adding deployment data to Cortex

To get deployment data into Cortex, you must use the [Add deployment for entity](/api/rest/deploys) API endpoint.

### Deploy data pipeline examples

In these examples, the repository secret or variable contains a valid [Cortex API key](/configure/settings/api-keys), and the repository name matches the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities/deploys#cortex-tag).

> **GitHub Action**
>
> In this example, a repository secret called `CORTEX_TOKEN` contains a valid Cortex API key.
>
> ```yaml theme={null}
> name: Build and Deploy with Status Updates
>
> on:
>   push:
>     branches: [ main, develop ]
>   pull_request:
>     branches: [ main ]
>
> env:
>   CORTEX_API_URL: "https://api.getcortexapp.com/api/v1/catalog"
>   PROJECT_NAME: "my-application"
>
> jobs:
>   build-and-deploy:
>     runs-on: ubuntu-latest
>
>     steps:
>     - name: Checkout code
>       uses: actions/checkout@v4
>
>     - name: Validate Cortex token
>       run: |
>         if [ -z "${{ secrets.CORTEX_TOKEN }}" ]; then
>           echo "ERROR: CORTEX_TOKEN secret not configured"
>           exit 1
>         fi
>
>     - name: Setup Node.js
>       uses: actions/setup-node@v4
>       with:
>         node-version: '18'
>         cache: 'npm'
>
>     - name: Install dependencies
>       run: npm ci
>
>     - name: Run tests
>       run: npm test
>
>     - name: Build application
>       run: npm run build
>
>     - name: Deploy to staging
>       run: |
>         echo "Deploying to staging environment..."
>         # Your deployment commands here
>         # This might fail intentionally for demonstration
>
>   # Guaranteed notification job that runs regardless of build-and-deploy outcome
>   notify-result:
>     runs-on: ubuntu-latest
>     needs: build-and-deploy
>     if: always() # This ensures the job runs regardless of build-and-deploy outcome
>
>     steps:
>     - name: Send deployment notification to Cortex
>       run: |
>         echo "Previous job result: ${{ needs.build-and-deploy.result }}"
>         REPO_NAME=$(echo "${{ github.event.repository.name }}" | tr '[:upper:]' '[:lower:]')
>         echo "Using repo name: $REPO_NAME"
>
>         # Check the status of the previous job
>         if [ "${{ needs.build-and-deploy.result }}" == "success" ]; then
>           TYPE="DEPLOY"
>           STATUS="success"
>           MESSAGE="All jobs completed successfully"
>         elif [ "${{ needs.build-and-deploy.result }}" == "failure" ]; then
>           TYPE="ROLLBACK"
>           STATUS="failed"
>           MESSAGE="Build and deploy job failed"
>         elif [ "${{ needs.build-and-deploy.result }}" == "cancelled" ]; then
>           TYPE="ROLLBACK"
>           STATUS="cancelled"
>           MESSAGE="Build and deploy job was cancelled"
>         else
>           TYPE="ROLLBACK"
>           STATUS="skipped"
>           MESSAGE="Build and deploy job was skipped"
>         fi
>
>         curl -L \
>           --request POST \
>           --max-time 30 \
>           --retry 2 \
>           --url "${{ env.CORTEX_API_URL }}/$REPO_NAME/deploys" \
>           --header "Authorization: Bearer ${{ secrets.CORTEX_TOKEN }}" \
>           --header "Content-Type: application/json" \
>           --data "{
>             \"customData\": {
>               \"workflow\": \"${{ github.workflow }}\",
>               \"run_id\": \"${{ github.run_id }}\",
>               \"branch\": \"${{ github.ref_name }}\",
>               \"final_status\": \"$STATUS\",
>               \"message\": \"$MESSAGE\",
>               \"actor\": \"${{ github.actor }}\",
>               \"repository\": \"${{ github.repository }}\"
>             },
>             \"deployer\": {
>               \"email\": \"${{ github.actor }}@users.noreply.github.com\",
>               \"name\": \"${{ github.actor }}\"
>             },
>             \"environment\": \"staging\",
>             \"sha\": \"${{ github.sha }}\",
>             \"timestamp\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\",
>             \"title\": \"Final deployment $STATUS - ${{ github.workflow }}\",
>             \"type\": \"$TYPE\",
>             \"url\": \"${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\"
>           }"
> ```

> **GitLab pipeline**
>
> **Prerequisites**
>
> Before running this pipeline, define a CI/CD variable in GitLab that stores the Cortex API key. Confirm the repository contains a `package.json` file.
>
> **Failure behavior**
>
> If any stage fails, the entire pipeline fails and a `ROLLBACK` event sends to Cortex.
>
> ```yaml theme={null}
> stages:
>   - build
>   - test
>   - deploy
>   - notify
>
> variables:
>   CORTEX_API_URL: "https://api.getcortexapp.com/api/v1/catalog"
>
> # Global settings
> image: node:18
>
> build_job:
>   stage: build
>   script:
>     - echo "Building application..."
>     - npm ci
>     - npm run build
>   artifacts:
>     paths:
>       - dist/
>     expire_in: 1 hour
>
> test_job:
>   stage: test
>   script:
>     - echo "Running tests..."
>     - npm test
>   dependencies:
>     - build_job
>
> deploy_job:
>   stage: deploy
>   script:
>     - echo "Deploying to staging..."
>     # Your deployment commands here
>     - sleep 2
>     - echo "Deployment completed"
>   dependencies:
>     - build_job
>   environment:
>     name: staging
>
> # This job always runs and reports pipeline status to Cortex
> notify_cortex:
>   stage: notify
>   image: curlimages/curl:latest
>   before_script:
>     # Check if previous stages succeeded by examining needs
>     - |
>       if [ "$BUILD_JOB_STATUS" = "success" ] && [ "$TEST_JOB_STATUS" = "success" ] && [ "$DEPLOY_JOB_STATUS" = "success" ]; then
>         PIPELINE_STATUS="success"
>         DEPLOY_TYPE="DEPLOY"
>         MESSAGE="Pipeline completed successfully"
>       else
>         PIPELINE_STATUS="failed"
>         DEPLOY_TYPE="ROLLBACK"
>         MESSAGE="Pipeline failed - one or more stages failed"
>       fi
>
>       echo "Pipeline Status: $PIPELINE_STATUS"
>       echo "Deploy Type: $DEPLOY_TYPE"
>       echo "Message: $MESSAGE"
>   script:
>     - |
>       # Convert repo name to lowercase
>       REPO_NAME=$(echo "$CI_PROJECT_NAME" | tr '[:upper:]' '[:lower:]')
>       echo "Repository: $REPO_NAME"
>
>       # Get current timestamp
>       TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
>
>       # Send notification to Cortex
>       curl -L \
>         --request POST \
>         --max-time 30 \
>         --retry 2 \
>         --url "$CORTEX_API_URL/$REPO_NAME/deploys" \
>         --header "Authorization: Bearer $CORTEX_TOKEN" \
>         --header "Content-Type: application/json" \
>         --data "{
>           \"customData\": {
>             \"pipeline_id\": \"$CI_PIPELINE_ID\",
>             \"job_id\": \"$CI_JOB_ID\",
>             \"branch\": \"$CI_COMMIT_REF_NAME\",
>             \"pipeline_status\": \"$PIPELINE_STATUS\",
>             \"message\": \"$MESSAGE\",
>             \"pipeline_url\": \"$CI_PIPELINE_URL\",
>             \"project_path\": \"$CI_PROJECT_PATH\"
>           },
>           \"deployer\": {
>             \"email\": \"$GITLAB_USER_EMAIL\",
>             \"name\": \"$GITLAB_USER_NAME\"
>           },
>           \"environment\": \"staging\",
>           \"sha\": \"$CI_COMMIT_SHA\",
>           \"timestamp\": \"$TIMESTAMP\",
>           \"title\": \"Pipeline $PIPELINE_STATUS - $CI_PROJECT_NAME\",
>           \"type\": \"$DEPLOY_TYPE\",
>           \"url\": \"$CI_PIPELINE_URL\"
>         }"
>
>       if [ $? -eq 0 ]; then
>         echo "Successfully notified Cortex"
>       else
>         echo "Failed to notify Cortex, but continuing..."
>       fi
>   needs:
>     - job: build_job
>       artifacts: false
>     - job: test_job  
>       artifacts: false
>     - job: deploy_job
>       artifacts: false
>   when: always
> ```

> **Azure DevOps**
>
> In this example, a variable called `CORTEX_TOKEN` contains a valid Cortex API key.
>
> ```yaml theme={null}
> trigger:
>   branches:
>     include:
>       - main
>       - develop
>
> pr:
>   branches:
>     include:
>       - main
>
> variables:
>   CORTEX_API_URL: 'https://api.getcortexapp.com/api/v1/catalog'
>
> pool:
>   vmImage: 'ubuntu-latest'
>
> stages:
> - stage: Build
>   displayName: 'Build Stage'
>   jobs:
>   - job: BuildJob
>     displayName: 'Build Application'
>     steps:
>     - task: NodeTool@0
>       inputs:
>         versionSpec: '18.x'
>       displayName: 'Install Node.js'
>
>     - script: |
>         echo "Building application..."
>         npm ci
>         npm run build
>       displayName: 'Build Application'
>
>     - publish: dist
>       artifact: BuildArtifacts
>       displayName: 'Publish Build Artifacts'
>
> - stage: Test
>   displayName: 'Test Stage'
>   dependsOn: Build
>   jobs:
>   - job: TestJob
>     displayName: 'Run Tests'
>     steps:
>     - task: NodeTool@0
>       inputs:
>         versionSpec: '18.x'
>       displayName: 'Install Node.js'
>
>     - script: |
>         echo "Running tests..."
>         npm ci
>         npm test
>       displayName: 'Run Tests'
>
> - stage: Deploy
>   displayName: 'Deploy Stage'
>   dependsOn: Test
>   jobs:
>   - job: DeployJob
>     displayName: 'Deploy to Staging'
>     steps:
>     - script: |
>         echo "Deploying to staging..."
>         sleep 2
>         echo "Deployment completed"
>       displayName: 'Deploy Application'
>
> - stage: Notify
>   displayName: 'Notify Cortex'
>   dependsOn: 
>     - Build
>     - Test
>     - Deploy
>   condition: always()
>   jobs:
>   - job: NotifyJob
>     displayName: 'Send Cortex Notification'
>     steps:
>     - checkout: none
>
>     - bash: |
>         echo "Build Stage Result: $(stageDependencies.Build.BuildJob.result)"
>         echo "Test Stage Result: $(stageDependencies.Test.TestJob.result)"
>         echo "Deploy Stage Result: $(stageDependencies.Deploy.DeployJob.result)"
>
>         # Determine overall pipeline status
>         BUILD_RESULT="$(stageDependencies.Build.BuildJob.result)"
>         TEST_RESULT="$(stageDependencies.Test.TestJob.result)"
>         DEPLOY_RESULT="$(stageDependencies.Deploy.DeployJob.result)"
>
>         if [ "$BUILD_RESULT" = "Succeeded" ] && [ "$TEST_RESULT" = "Succeeded" ] && [ "$DEPLOY_RESULT" = "Succeeded" ]; then
>           PIPELINE_STATUS="success"
>           DEPLOY_TYPE="DEPLOY"
>           MESSAGE="Pipeline completed successfully"
>         else
>           PIPELINE_STATUS="failed"
>           DEPLOY_TYPE="ROLLBACK"
>           MESSAGE="Pipeline failed - one or more stages failed (Build: $BUILD_RESULT, Test: $TEST_RESULT, Deploy: $DEPLOY_RESULT)"
>         fi
>
>         echo "Pipeline Status: $PIPELINE_STATUS"
>         echo "Deploy Type: $DEPLOY_TYPE"
>         echo "Message: $MESSAGE"
>
>         # Convert repo name to lowercase (extract from full repository name)
>         REPO_NAME=$(echo "$(Build.Repository.Name)" | cut -d'/' -f2 | tr '[:upper:]' '[:lower:]')
>         echo "Repository: $REPO_NAME"
>
>         # Get current timestamp
>         TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
>
>         # Get deployer information
>         DEPLOYER_EMAIL="${BUILD_REQUESTEDFOREMAIL:-devops@company.com}"
>         DEPLOYER_NAME="${BUILD_REQUESTEDFOR:-Azure DevOps}"
>
>         # Send notification to Cortex
>         curl -L \
>           --request POST \
>           --max-time 30 \
>           --retry 2 \
>           --url "$(CORTEX_API_URL)/$REPO_NAME/deploys" \
>           --header "Authorization: Bearer $(CORTEX_TOKEN)" \
>           --header "Content-Type: application/json" \
>           --data "{
>             \"customData\": {
>               \"pipeline_id\": \"$(Build.BuildId)\",
>               \"build_number\": \"$(Build.BuildNumber)\",
>               \"branch\": \"$(Build.SourceBranchName)\",
>               \"pipeline_status\": \"$PIPELINE_STATUS\",
>               \"message\": \"$MESSAGE\",
>               \"build_url\": \"$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)\",
>               \"project\": \"$(System.TeamProject)\",
>               \"repository\": \"$(Build.Repository.Name)\"
>             },
>             \"deployer\": {
>               \"email\": \"$DEPLOYER_EMAIL\",
>               \"name\": \"$DEPLOYER_NAME\"
>             },
>             \"environment\": \"staging\",
>             \"sha\": \"$(Build.SourceVersion)\",
>             \"timestamp\": \"$TIMESTAMP\",
>             \"title\": \"Pipeline $PIPELINE_STATUS - $(Build.Repository.Name)\",
>             \"type\": \"$DEPLOY_TYPE\",
>             \"url\": \"$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)\"
>           }"
>
>         if [ $? -eq 0 ]; then
>           echo "Successfully notified Cortex"
>         else
>           echo "Failed to notify Cortex, but continuing..."
>         fi
>       displayName: 'Send Cortex Notification'
>       env:
>         CORTEX_TOKEN: $(CORTEX_TOKEN)
> ```

> **Jenkins**
>
> In this example, the Jenkins job is assumed to be associated with a repository, and the repository name is used to match the Cortex entity tag. The job also assumes a Global Credential named `CORTEX_TOKEN` has been defined, containing a valid Cortex API key.
>
> ```yaml theme={null}
> pipeline {
>     agent any
>
>     environment {
>         CORTEX_API_URL = "https://api.getcortexapp.com/api/v1/catalog"
>     }
>
>     stages {
>         stage('Build') {
>             steps {
>                 script {
>                     echo "Building application..."
>                 }
>                 sh '''
>                     node --version
>                     npm --version
>                     npm ci
>                     npm run build
>                 '''
>             }
>             post {
>                 success {
>                     script {
>                         env.BUILD_STAGE_RESULT = 'SUCCESS'
>                     }
>                 }
>                 failure {
>                     script {
>                         env.BUILD_STAGE_RESULT = 'FAILURE'
>                     }
>                 }
>             }
>         }
>
>         stage('Test') {
>             steps {
>                 script {
>                     echo "Running tests..."
>                 }
>                 sh 'npm test'
>             }
>             post {
>                 success {
>                     script {
>                         env.TEST_STAGE_RESULT = 'SUCCESS'
>                     }
>                 }
>                 failure {
>                     script {
>                         env.TEST_STAGE_RESULT = 'FAILURE'
>                     }
>                 }
>             }
>         }
>
>         stage('Deploy') {
>             steps {
>                 script {
>                     echo "Deploying to staging..."
>                     sh '''
>                         sleep 2
>                         echo "Deployment completed"
>                     '''
>                 }
>             }
>             post {
>                 success {
>                     script {
>                         env.DEPLOY_STAGE_RESULT = 'SUCCESS'
>                     }
>                 }
>                 failure {
>                     script {
>                         env.DEPLOY_STAGE_RESULT = 'FAILURE'
>                     }
>                 }
>             }
>         }
>     }
>
>     post {
>         always {
>             script {
>                 notifyCortex()
>             }
>         }
>     }
> }
>
> def notifyCortex() {
>     try {
>         echo "Build Stage Result: ${env.BUILD_STAGE_RESULT ?: 'SKIPPED'}"
>         echo "Test Stage Result: ${env.TEST_STAGE_RESULT ?: 'SKIPPED'}"
>         echo "Deploy Stage Result: ${env.DEPLOY_STAGE_RESULT ?: 'SKIPPED'}"
>
>         // Determine overall pipeline status
>         def buildResult = env.BUILD_STAGE_RESULT ?: 'SKIPPED'
>         def testResult = env.TEST_STAGE_RESULT ?: 'SKIPPED'
>         def deployResult = env.DEPLOY_STAGE_RESULT ?: 'SKIPPED'
>
>         def pipelineStatus
>         def deployType
>         def message
>
>         if (buildResult == 'SUCCESS' && testResult == 'SUCCESS' && deployResult == 'SUCCESS') {
>             pipelineStatus = 'success'
>             deployType = 'DEPLOY'
>             message = 'Pipeline completed successfully'
>         } else {
>             pipelineStatus = 'failed'
>             deployType = 'ROLLBACK'
>             message = "Pipeline failed - one or more stages failed (Build: ${buildResult}, Test: ${testResult}, Deploy: ${deployResult})"
>         }
>
>         echo "Pipeline Status: ${pipelineStatus}"
>         echo "Deploy Type: ${deployType}"
>         echo "Message: ${message}"
>
>         // Convert repo name to lowercase (extract from job name)
>         def repoName = env.JOB_NAME.tokenize('/')[0].toLowerCase()
>         echo "Repository: ${repoName}"
>
>         // Get Git commit SHA and branch
>         def gitCommit = sh(
>             script: 'git rev-parse HEAD',
>             returnStdout: true
>         ).trim()
>
>         def gitBranch = sh(
>             script: 'git rev-parse --abbrev-ref HEAD',
>             returnStdout: true
>         ).trim()
>
>         // Get current timestamp
>         def timestamp = sh(
>             script: 'date -u +"%Y-%m-%dT%H:%M:%SZ"',
>             returnStdout: true
>         ).trim()
>
>         // Escape JSON special characters in message
>         def escapedMessage = message.replaceAll('"', '\\\\"').replaceAll("'", "\\\\'")
>
>         // Get deployer information
>         def deployerEmail = env.BUILD_USER_EMAIL ?: 'jenkins@company.com'
>         def deployerName = env.BUILD_USER ?: 'Jenkins'
>
>         // Build JSON payload
>         def jsonPayload = """
>         {
>             "customData": {
>                 "pipeline": "${env.JOB_NAME}",
>                 "build_number": "${env.BUILD_NUMBER}",
>                 "branch": "${gitBranch}",
>                 "pipeline_status": "${pipelineStatus}",
>                 "message": "${escapedMessage}",
>                 "build_url": "${env.BUILD_URL}",
>                 "jenkins_url": "${env.JENKINS_URL}"
>             },
>             "deployer": {
>                 "email": "${deployerEmail}",
>                 "name": "${deployerName}"
>             },
>             "environment": "staging",
>             "sha": "${gitCommit}",
>             "timestamp": "${timestamp}",
>             "title": "Pipeline ${pipelineStatus} - ${env.JOB_NAME}",
>             "type": "${deployType}",
>             "url": "${env.BUILD_URL}"
>         }
>         """
>
>         // Send notification to Cortex
>         withCredentials([string(credentialsId: 'CORTEX_TOKEN', variable: 'CORTEX_TOKEN')]) {
>             def curlResult = sh(
>                 script: """
>                     curl -L \\
>                       --request POST \\
>                       --max-time 30 \\
>                       --retry 2 \\
>                       --url "${env.CORTEX_API_URL}/${repoName}/deploys" \\
>                       --header "Authorization: Bearer \${CORTEX_TOKEN}" \\
>                       --header "Content-Type: application/json" \\
>                       --data '${jsonPayload}' \\
>                       --write-out "%{http_code}" \\
>                       --silent \\
>                       --output /dev/null
>                 """,
>                 returnStdout: true
>             ).trim()
>
>             if (curlResult == '200' || curlResult == '201') {
>                 echo "Successfully notified Cortex (HTTP ${curlResult})"
>             } else {
>                 echo "Failed to notify Cortex (HTTP ${curlResult}), but continuing..."
>             }
>         }
>
>     } catch (Exception e) {
>         echo "Failed to send Cortex notification: ${e.getMessage()}"
>         // Don't fail the build if notification fails
>     }
> }
> ```

### Adding custom data to deployments

Adding a `customData` object to the API call gives you the flexibility to attach metadata that matters to your organization, e.g. build numbers, commit messages, approval info, environment tags, or anything else worth tracking alongside a deploy.
If custom data is included with a deployment, it appears on the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details) under **CI/CD > Deploys**.
**To view deployment custom data**:

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Select the entity.
4. From the left entity details sidebar, locate the **Connections** section, expand **CI/CD**, then click **Deploys**.
5. Click **Details** next to the relevant deployment entry to expand it and view the custom data.

   ![The 'Details' button on the Deploys page of an entity.](https://mintcdn.com/cortex-290c0c42/kRMUfNz-JkLS2xPw/images/CleanShot%202025-11-19%20at%2014.40.55.png?fit=max\&auto=format\&n=kRMUfNz-JkLS2xPw\&q=85\&s=26af323c48a52afe1a3f5ed8f886c7f1)

## Viewing deployment data

Deployment data is found in the following areas of Cortex:

* [Entity pages](/ingesting-data-into-cortex/entities-overview/entities/deploys#viewing-deployments-on-entity-pages)
* [Eng Intelligence](/ingesting-data-into-cortex/entities-overview/entities/deploys#viewing-deployments-in-eng-intelligence)
* [CQL and Scorecards](/ingesting-data-into-cortex/entities-overview/entities/deploys#use-deployment-data-in-cql-and-scorecards)

### Viewing deployments on entity pages

While viewing an entity's page, you can see its latest deployment information.

To access an entity's page, expand **Catalogs** from the main sidebar, then click **All entities**. Select the entity you want to view.

Deployment information appears in the following areas:

Near the top of the page:

![Deployment information is listed at the top of an entity's page.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/deploys-example.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=4459beff4c641c48f1bce7692949bb65)

Near the bottom of the page under **Latest events**:

![The 'Latest events' section of an entity' page.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/deploys-latest-events.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=2187ca480eadef69ab234e42f586721a)

On the **Events** tab:

![The 'Events' tab selected, showing a visual chart of deploys and all recent entity events.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/deployes-events-tab.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=144f560c03fe6d16ec6934ecca4eddcb)

The **Events** page includes:

* A visual chart of deploys
  * By default, the chart shows data from the last month. Click **Last month** in the upper-right to change the timeframe.
* All recent events for the entity
  * Click **Filter** In the upper-right corner of the events list to filter events by type (including **deploys**) and date range.
  * Click **Display** in the upper-right corner of the events list to show dependency events.

![The 'Display' and 'Filter' options in the events list.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/deploys-filter.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=96bb10153794308766fb49597617aee5)

### Viewing deployments in Eng Intelligence

When you add deployment data to Cortex, that data feeds into [Eng Intelligence](/improve/eng-intelligence) reporting, giving you visibility into [deploy metrics](/improve/eng-intelligence/eng-intelligence#metrics) such as average deploys per week and change failure rate.

**To view deploy metrics in Eng Intelligence**:

1. From the main sidebar, expand **Eng Intelligence**, then select **All metrics**.
2. In the upper-left corner, click the drop-down to change the entity type, e.g. domain.

   ![The drop-down menu, located in the upper-left corner of the page.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/deploys-dropdown.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=d5ae7d8db5e4f69d7c01701eadd0358e)
3. Locate the entity whose deploy metrics you want to view, then click into the **Avg deploys/week** and **Deploy change failure rate** columns to get more information including trends and related activity.

   ![The 'Avg deploys/week' and 'Deploy change failure rate' columns.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/deploys-columns.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=0ddea20bf587c930e9e948a802748908)

For more information, including how to filter the page view, see [All metrics](/improve/eng-intelligence/eng-intelligence).

### Using deployment data in CQL and Scorecards

You can use deploy data to write rules for [Scorecards](/standardize/scorecards) and to create [CQL reports](/standardize/cql/cql-reports).

#### CQL reference

Deploys are added to an entity through the [public API](/api/rest/deploys).

`deploys()` returns only deploys sent through the deploys API. To query deployments imported from Harness, use [`cicd.deployments()`](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness#harness-data-in-cql-and-scorecards).

**Definition** -  `deploys(lookback: Duration, types: List): List`

**Example**

In a Scorecard, you can write a rule to check whether an entity had fewer than 5 bug fixes in the last month:

```
deploys(lookback = duration("P1M"), types = ["DEPLOY"]).filter((deploy) => deploy.customData != null AND deploy.customData.get("bugFix") == true).length = 2
```

Write a rule to verify that there was, on average, less than 1 rollback for every 4 deploys in the past month:

```
deploys(lookback=duration("P1M"),types=["ROLLBACK"]).length / deploys(lookback=duration("P1M"),types=["DEPLOY", "ROLLBACK", "RESTART"]).length < 0.25
```


# Entity details page
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/details



Each entity has a dedicated details page that centralizes all related data, helping developers stay focused by reducing context switching. To open an entity's details page, click its name either while browsing a catalog or from the **Catalogs > All entities** page. From here you can quickly access key information:

* **Active incidents** - Any ongoing incidents are surfaced at the top of the page for immediate visibility.
* **Sidebar** - [Customize which metadata](/ingesting-data-into-cortex/entities-overview/entities/details#configuring-the-entity-metadata-sidebar) appears here by pinning the information most relevant to you. Supported data includes on-call schedules, owners, Slack or Microsoft Teams channels, groups, repositories, entity relationships, doc links, project management, custom data, and code quality.

> [!TIP]
>
> During an incident, the entity details page surfaces everything you need in one place: the active incident, owners and on-call contacts, the relevant Slack channel, affected dependencies, and recent deploys.

> [!NOTE]
>
> Fields only appear in the overview if data is available. For example, the **Slack channels** field won't display unless you have the Slack integration configured.

## Locating an entity's unique identifiers

The [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) and the [Cortex ID](/ingesting-data-into-cortex/entities-overview/entities#cortex-id) are displayed below the entity's name.

![The entity's unique identifiers appear below its name.](https://mintcdn.com/cortex-290c0c42/z5k1sDZlDmCOZ-iP/images/cortex-tag-cortex-id.png?fit=max\&auto=format\&n=z5k1sDZlDmCOZ-iP\&q=85\&s=7e73f339b8c76df955c562112b29a95b)

## Configuring the entity's sidebars

Each entity details page includes two sidebars—the entity details sidebar on the left and the entity metadata sidebar on the right—each serving a distinct purpose.

### Configuring the entity details sidebar

The entity details sidebar appear on the left side of every entity page. It provides a deeper view into the entity's recent deploys, events, security vulnerabilities, monitoring metrics, and more, giving you the context needed to resolve incidents quickly.

The entity details sidebar contains the following information about the entity:

#### Overview categories

* **Relationships** - See how an entity connects to the rest of your catalog including domain hierarchy, team hierarchy, dependencies, and any custom relationship types you've defined. See [Defining relationship types](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types) and [Viewing relationships on an entity page](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types#viewing-relationships-on-entity-pages).
* **API explorer** - Pulls from [API documentation](/ingesting-data-into-cortex/entities-overview/entities/external-docs) added to your entity.
* **Events** - A list of recent events sourced from [deploys](/ingesting-data-into-cortex/entities-overview/entities/deploys), [AWS ECS](/ingesting-data-into-cortex/integrations/aws), [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes), [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie), [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty), [Sentry](/ingesting-data-into-cortex/integrations/sentry), and [Snyk](/ingesting-data-into-cortex/integrations/snyk).
* **Links & docs** - [Documentation links](/ingesting-data-into-cortex/entities-overview/entities/external-docs) you have added to the entity, along with documentation pulled from the related repository.
* **Owners** - See the teams and individuals who own the entity, the related Slack or Microsoft Teams channels, and a list of team members. Channels are contacts for the owners, not owners themselves. Learn more about [defining entity owners](/ingesting-data-into-cortex/entities-overview/entities/ownership).
* **Entity YAML** - View the [entity YAML](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-with-yaml) that defines the selected entity.
  * If you have [GitOps editing](/configure/gitops/using-gitops-for-cortex#step-1-disable-ui-editing) enabled for this entity, and you have the `View GitOps logs` permission, this page displays the source of the YAML file and a preview of the latest GitOps log.

#### Cortex features

* **Scorecards** - A list of any [Scorecards](/standardize/scorecards) that are in progress where this entity is being scored. Additionally, see the average score, median score, and a graph showing the entity's scores over time.
  * Above the *Scorecard* section, you can choose which scores to include in calculations if the entity is in a hierarchy:
    * **Domains** - Click **This entity only** to view only the scores that apply to the domain you are viewing. Select **Include entity's children** to include both the parent domain and its child entities in the score calculations.
    * **Entities with a custom relationship type** - Click **This entity only** to view only the scores that apply to the entity you are viewing. Click **\[Relationship type] only** to include both the parent and its child entities in the score calculations.
    * **Teams** - Click **This entity only** to view the scores that apply only to the team you are viewing. Click **Include entity's children** to include scores for the team, the team's children, entities owned by the team, and entities owned by the team's children.
* **Initiatives** - A list of all active [Initiatives](/improve/initiatives) for this entity, including the Scorecard's current level and the due date of the Initiative.
* **Workflows** - A list of [Workflows](/streamline/workflows) that include this entity.
  * If you are a designated approver for any pending Workflows, they will appear at the top of this page. You can also view recently run Workflows and trigger any related Workflows from here.

#### Connections

The *Connections* section displays integration data grouped by context. Once you configure integrations, data appears in the following sections on the entity page:

* **CI/CD** - Pulls from [deploys API](/ingesting-data-into-cortex/entities-overview/entities/deploys), [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [Buildkite](/ingesting-data-into-cortex/integrations/buildkite), [CircleCI](/ingesting-data-into-cortex/integrations/circleci), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), and [Harness](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness#viewing-harness-pipelines-and-deployments).
* **Cloud** - Pulls from [AWS](/ingesting-data-into-cortex/integrations/aws) and [Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes). The **AWS** section appears only on entities that have an `AWS::ECS::Service` resource linked in their `x-cortex-infra` block. See [Viewing AWS data on an entity](/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws).
* **Code quality** - Pulls from [Codecov](/ingesting-data-into-cortex/integrations/codecov) and [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube).
* **Custom data & metrics** - Pulls from [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data) and [Eng Intelligence custom metrics](/improve/eng-intelligence/custom-metrics).
* **Dashboard** - Pulls from [charts](/ingesting-data-into-cortex/entities-overview/entities/external-docs#adding-embedded-dashboards-to-an-entity) configured in the entity's YAML file for [Datadog](/ingesting-data-into-cortex/integrations/datadog), [Grafana](/ingesting-data-into-cortex/integrations/grafana), and [New Relic](/ingesting-data-into-cortex/integrations/newrelic).
* **Error tracking** - Pulls from [BugSnag](/ingesting-data-into-cortex/integrations/bugsnag), [Rollbar](/ingesting-data-into-cortex/integrations/rollbar), and [Sentry](/ingesting-data-into-cortex/integrations/sentry).
* **Feature flags** - Pulls from [LaunchDarkly](/ingesting-data-into-cortex/integrations/launchdarkly).
* **Observability** - Pulls from [Coralogix](/ingesting-data-into-cortex/integrations/coralogix), [Datadog](/ingesting-data-into-cortex/integrations/datadog), [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace), [Google Observability Cloud](/ingesting-data-into-cortex/integrations/google), [Lightstep](/ingesting-data-into-cortex/integrations/lightstep), [New Relic](/ingesting-data-into-cortex/integrations/newrelic), [Prometheus](/ingesting-data-into-cortex/integrations/prometheus), [Splunk Observability Cloud](/ingesting-data-into-cortex/integrations/splunk-observability) (formerly SignalFX), and [Sumo Logic](/ingesting-data-into-cortex/integrations/sumologic).
* **On-call & incidents** - On-call information from [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie), [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty), [Rootly](/ingesting-data-into-cortex/integrations/rootly), [Splunk On-Call](/ingesting-data-into-cortex/integrations/splunk-oncall) (formerly VictorOps), and [xMatters](/ingesting-data-into-cortex/integrations/xmatters), and incidents pulled from [incident.io](/ingesting-data-into-cortex/integrations/incidentio), [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty), [FireHydrant](/ingesting-data-into-cortex/integrations/firehydrant), and [Rootly](/ingesting-data-into-cortex/integrations/rootly).
* **Packages** - Pulls from the [packages API](/api/rest/packages) and any packages automatically discovered from your configured git repositories.
* **Project management** - Pulls from [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [ClickUp](/ingesting-data-into-cortex/integrations/clickup), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), and [Jira](/ingesting-data-into-cortex/integrations/jira).
* **Security** - Pulls from [Apiiro](/ingesting-data-into-cortex/integrations/apiiro), [Checkmarx](/ingesting-data-into-cortex/integrations/checkmarx), [Codecov](/ingesting-data-into-cortex/integrations/codecov), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Mend](/ingesting-data-into-cortex/integrations/mend), [Semgrep](/ingesting-data-into-cortex/integrations/semgrep), [Snyk](/ingesting-data-into-cortex/integrations/snyk), [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube), [Veracode](/ingesting-data-into-cortex/integrations/veracode), and [Wiz](/ingesting-data-into-cortex/integrations/wiz).
* **Version control** - Pulls from [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), and [GitLab](/ingesting-data-into-cortex/integrations/gitlab).

#### Plugins

The *Plugins* section displays [plugins](/streamline/plugins) that are relevant to this entity.

### Configuring the entity metadata sidebar

The entity metadata sidebar appears on the right side of every entity page. You can control which metadata categories are displayed, reorder them, and apply the same layout across multiple entity types at once.

#### Expanding or collapsing the metadata sidebar

Click the **arrow icon** in the bottom-right corner to expand or collapse the metadata sidebar.

![The arrow icon in the bottom-right corner of the page.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/expand-metadata-sidebar%20\(1\).png?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=c414bf74a450e476b3e96fa7b84da804)

#### Customizing the metadata sidebar

Users who are admins or who have the `Edit Entity Types` permission can customize the metadata sidebar.

> [!TIP]
>
> As of July 2026, **Domains** now appear in the **Relationships** tab. When viewing an entity, select **Relationships** from the left entity details sidebar.

1. In the bottom-right corner of the metadata sidebar, click the **Configure entity sidebar** icon.

   ![The 'Configure entity' icon in the bottom-right corner of the page.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/rectangles-icon.png?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=78690ac47cbbb6be3f30e04f6569ba2c)
2. To reorder a category, hover over the **grip icon** and drag it to the desired position. To hide a category, click the **eye icon** next to it. Repeat as necessary.

   ![The Grip icon next to an entity.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/sidebar-category.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=70d3fd67a41b6569f609dc2fe756469d)
3. From the **Apply layout to entity types** drop-down menu, select which entity types to apply this configuration to.

   ![The Apply layout to entity types drop-down  menu in the bottom-right corner of the page.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/sidebar-apply-layout.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=4609adc7a92c5398dbb100ac02b8257d)
4. Click **Apply to workspace**.

## Customizing entity page plugin tabs

Users with the `Edit Entities` permission can pin, reorder, and hide plugins on an entity's details page. Plugins pinned this way appear as tabs at the top of the page, either on a single entity or across all entities of the same type.

Before a plugin can be pinned, it must be configured to include the relevant entity type in its context. For example, to pin a plugin on a Teams entity page, include the `team` entity type when registering the plugin in Cortex.

> [!NOTE]
>
> System-level tabs are always visible by default but can be reordered. Most entity types only have the **Overview** tab, though some have more. For example, Teams entity pages include both the **Overview** and **Entities** tabs. Applicable plugins are also visible by default and are appended to any existing tab configuration.

Tab configurations saved at the individual entity level take precedence over configurations saved at the entity-type level. For example, if you customize tabs on the *Engineering* Teams page and later save a different tab configuration for all `team` entities, the *Engineering* page keeps its original configuration.

**To pin and reorder plugins**:

1. Navigate to the entity.
2. On the entity details page, click the **gear icon**. \
   The **Edit tabs** side panel opens.

   ![The Gear icon near the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/gear-icon-plugins.png?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=490fd57f04da00623242f1cf642d94f3)
   > [!NOTE]
   >
   > When there are too many pinned tabs to fit across the page, the **gear icon** moves into the **overflow menu**. Click the **overflow menu icon** to access it.
3. To reorder a plugin, hover over the **grip icon** and drag it to the desired position. To hide a plugin, click the **eye icon** next to it. Repeat as necessary. There is no limit to the number of plugins you can pin to an entity page. If you have more pinned plugins than can fit across the page, the remaining tabs are accessible via the **Overflow** menu.

   ![The Grip icon next to a plugin.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/grip-icon-plugins.png?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=84c33a54c97ba0eb7ecca6e1cc21c246)
4. To apply the layout to all entities of the same type, select the **Apply to entities of type service** checkbox.
5. Click **Save**. \
   The plugin is pinned to the top of the entity details page.

   ![The pinned plugin tabs.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/entity-page-plugin-tabs.png?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=0b7813742cbae6ced81fb2146f8276de)


# Discovered entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/discovery-audit

Formerly 'Discovery audit

You may have over a hundred repositories in GitHub, dozens of cloud resources across AWS, and services running in Kubernetes; eventually, you'll likely want all of them accounted for in Cortex. With that much information, it can be hard to know at a glance that everything is tracked and that new projects are being brought into your catalogs.

The discovered entities list (formerly known as the discovery audit) gives you confidence in your catalogs by surfacing every change Cortex detects across your environment. Cortex continuously compares what already exists in your catalog against what it finds in your connected integrations—your git provider, APM tools, Kubernetes clusters, cloud accounts, and other key integrations—so you always have insight into what's new or has changed.

## Viewing discovered entities

Users with the `View Entities` permission can view discovered entities.

**To access discovered entities**:

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Discovered entities** tab.

   ![The 'Discovered entities' tab.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/discovered-entities-tab.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=6d04ff8d5959a0d58681a5abd739a907)

The tab opens to the **Discovered** view, which lists recent changes in your environment that aren't yet reflected in Cortex, such as newly created repositories and cloud resources discovered from your integrations. Events you've chosen to ignore live under the **Ignored** view instead.

Each row in the list shows:

* **Entity** - The name of the discovered entity, prefixed with an icon for the integration it came from (e.g. GitHub or AWS).
* **Event type** - The kind of change Cortex detected, such as **New repository** or **New AWS resource**.
* **Event date** - When the change was detected. Some sources don't report a timestamp, in which case this column shows N/A.
* **Actions** - The actions available for that event. The available actions depend on the event type: new resources can be imported or ignored, while resources that are no longer detected can be deleted or ignored. See [Acting on discovered entities](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit#acting-on-discovered-entities)

### Searching and filtering the discovered entities list

The first time you view the discovered entities list, there may be a lot to review. To narrow the scope and start with the changes that are highest priority for you, search or filter the list.

* To search, type into the search bar in the upper-right corner of the list.
* To filter, click **Filter** in the upper-right corner of the list, then choose one or more of the following fields. Select your criteria, then click **Apply**. To clear everything and start over, click **Reset filters**.
  * **Integrations** - Limit the list to events from specific integrations
  * **Types** - Limit the list to specific event types

![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/discovered-entities-filter.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=b2b2c45bbdb8cd5208196643ea56b9ca)

### Refreshing and exporting the discovered entities list

Two actions at the top of the list help you keep it current and share it:

* **Sync** - Prompts Cortex to re-check your connected integrations for changes, refreshing the list with the latest discovered events.
* **Export CSV** - Downloads the current list as a CSV file, which is useful for reviewing discovered entities offline or sharing them with your team.

![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/discovered-entities-sync.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=bed5e2ce5515319759b437a833e9e496)

## Acting on discovered entities

`Admins` can act on discovered entities, i.e. import, ignore, and delete.

Each event offers a set of actions in the **Actions** column, depending on its type. You can import a newly discovered entity into Cortex, delete an entity that Cortex no longer detects, or ignore any event so it no longer appears in the list.

#### Importing an entity

If Cortex detects a new resource that you want to track, you can import it directly from this page:

1. Click the **import icon** in the **Actions** column of the row containing the entity. The **Import entities** page opens.

   ![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/discovered-entities-import.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=2f3f6fa303de23f8d67cb3239c61c1f6)
2. Cortex opens the entity creation flow, prefilled with details from the discovered source. Configure the remaining entity details. For detailed instructions on creating each type of entity, see the relevant docs page: [Services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services), [Domains](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains), [Teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams), or [Custom entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types).
3. Click **Confirm import**.

When you import a discovered entity, Cortex generates a Cortex [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities/yaml) (the cortex.yaml file) seeded with the discovered source. For example, importing a discovered AWS Lambda function as a resource might produce a descriptor like this:

```yaml theme={null}
openapi: 3.0.1
info:
  title: Taylor Lambda
  description: Payment retry handler discovered from AWS
  x-cortex-tag: taylor-lambda
  x-cortex-type: resource
  x-cortex-definition:
    resourceType: lambda-function
  x-cortex-groups:
    - payments

```

> [!NOTE]
>
> The import action isn't available for every event type. Rows where direct import doesn't apply show a disabled import icon.

### Ignoring an event

If an event appears in the list but isn't relevant, for example, a test repository that doesn't need to be imported into Cortex, you can ignore it by clicking the **eye icon** in the **Actions** column of the row containing the event. The event moves to the Ignored view. Ignoring is persistent, so the event won't reappear in the **Discovered** view.

To move an event back, open the **Ignored** view and click the **eye icon** in that row. The event returns to the **Discovered** view.

### Deleting an entity that is no longer detected

When Cortex stops detecting an entity that already exists in your catalog, e.g. its cloud resource was torn down or its APM service stopped reporting, the event appears with a **not detected** type, such as `AWS resource not detected`.
**To delete the entity from the list**:

> [!WARNING]
>
> Deleting an entity is permanent. If you'd rather remove an entity from active use but keep it for historical reference, [archive it](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities) instead of deleting it.

1. Click the **trash icon** in the **Actions** column of the row containing the entity. The **Confirm entity deletion** window opens.

   ![](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/detected-entities-delete.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=bfdd4339fbf67458f2b34f06651a89f0)
2. Review the entity that will be removed (shown with its name and Cortex tag) so you don't unintentionally remove something that's still in use.
3. Click **Delete**.

For hands-off maintenance, you can also configure [auto-archival](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive) to automatically archive entities when they're no longer detected in your integrations, so they never need to be cleaned up from this list manually.

## Troubleshooting and FAQ

See frequently asked questions below.

> **Why don't I see all of my services from my APM provider in the discovered entities list?**
>
> Cortex supports discovery for a subset of integrations. If a service comes from an integration that isn't in the list below, it won't appear as a discovered entity:
>
> * AWS
> * Datadog
> * ECS
> * Google Cloud
> * Instana
> * Kubernetes
> * Lightstep
> * New Relic
> * Version control (Azure DevOps, Bitbucket, GitHub, GitLab)

> **Why is the import icon disabled for some rows?**
>
> The import action is only available for event types that can be created directly from this page. When an event can't be imported this way, its import icon appears disabled. You can still bring the entity into Cortex through the standard [import flow](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit#importing-an-entity) or via [GitOps](/configure/gitops).

> **What's the difference between ignoring and deleting an event?**
>
> Ignoring an event simply hides it from the **Discovered** view and moves it to the **Ignored** view; it doesn't change anything in your catalog, and you can restore it at any time.
>
> Deleting is only available for entities Cortex no longer detects, and it permanently removes the entity from your catalog. If you want to keep an entity for historical reference, [archive it](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities) instead of deleting it.


# Adding external documentation
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/external-docs



Documentation lives in too many places—wikis, git repos, API spec tools, dashboards. Cortex pulls it together on the entity that owns it, so the people working with a service don't have to go looking.

You can attach four kinds of documentation to an entity:

* **Links** - Any URL—e.g. runbooks, tech specs, dashboards, health checks—or custom types you define
* **Git-driven markdown** - Markdown files from your repo, embedded automatically
* **API specs** - OpenAPI/Swagger or AsyncAPI specs, rendered in a built-in API explorer
* **Dashboard charts** - Embedded charts from Datadog, Grafana, New Relic, or other sources

Attached documentation appears in the **Links & docs** section of an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details):

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/links-docs-link.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=d2cabff80ca022843b61dca3967873e8)

## Adding links to an entity

### Adding links via the Cortex UI

#### Prerequisites

Before editing an entity via the UI, make sure that UI editing is enabled.

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. In the entity's left sidebar, click **Links**.

   ![The Links page in the Cortex UI.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/docs-links.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=7a2f54f10976d648c85c756ee6030133)
4. Click **+Add**.
5. In the **Link** side panel, do the following:
   * From the **Type** drop-down menu, select the type of link.
     * To create a new type of link, enter the name into the **Search items** field, then click **Add new \[link type name]**. The link type is created and applied to the entity.
   * Under **Name**, enter a name for the link.
   * Under **URL**, enter the URL.
   * Under **Description**, enter a description of the link.
6. Click **Add**.

### Adding links via an entity descriptor

In the entity descriptor, add a list of `link` objects:

```yaml theme={null}
x-cortex-link:
  - name: Checkout Service Runbook
    type: runbook
    url: https://wiki.example.com/runbooks/checkout-service
    description: Steps for diagnosing and resolving incidents in the checkout service

```

`name`, `type`, and `url` are required. The `type` value is freeform. Common examples include `dashboard`, `documentation`, `healthcheck`, `logs`, `metrics`, and `runbook`.

## Adding git-driven Markdown docs to an entity

Cortex automatically detects and embeds markdown files from the `docs` folder of your linked repository, or from the root directory. When relevant files are found, they appear under **Links & docs** in the entity's left sidebar. Markdown is rendered using the [React markdown library](https://github.com/remarkjs/react-markdown).

No configuration is required as this happens automatically when a repository is associated with the entity.

## Adding API specs to an entity

Cortex renders OpenAPI/Swagger and AsyncAPI specs in a built-in API explorer on the [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details). From the API explorer, you can also authorize your API and run queries directly.

**To access the API explorer**:

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the left entity sidebar, click **API explorer**.

   ![The API Explorer in Cortex.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/api-explorer.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=d35467a09e6ff7638632dc3c6680e321)

### Adding OpenAPI docs

#### From an external URL

Add the spec URL to the entity descriptor with type `OPENAPI` :

```yaml theme={null}
x-cortex-link:
  - name: Payment Service API Spec
    type: OPENAPI
    url: https://api.example.com/specs/payment-service.yaml
```

#### **From your git repo (relative path)**

```yaml theme={null}
x-cortex-link:
  - name: Payment Service API Spec
    type: OPENAPI
    url: ./docs/payment-service-spec.yaml
```

#### **From another git repo**

You can reference specs in repos not associated with the entity, using the format `provider:org/repo:path/to/file`. To target a specific branch, use `provider:org/repo:branch:path/to/file`. If branch is omitted, the repo's default branch is used.

```yaml theme={null}
# GitHub
x-cortex-link:
  - name: Payment Service API Spec
    type: OPENAPI
    url: github:acme-corp/api-specs:services/payment-service/openapi.yaml

# GitLab
  - name: Payment Service API Spec
    type: OPENAPI
    url: gitlab:acme-corp/api-specs:services/payment-service/openapi.yaml

# Azure DevOps
  - name: Payment Service API Spec
    type: OPENAPI
    url: azuredevops:acme-corp/api-specs:services/payment-service/openapi.yaml

# Bitbucket
  - name: Payment Service API Spec
    type: OPENAPI
    url: bitbucket:acme-corp/api-specs:services/payment-service/openapi.yaml

```

#### Via the Cortex API

Send your OpenAPI JSON or YAML to the endpoint `POST /api/v1/catalog/documentation/openapi`, using your entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities/external-docs#cortex-tag). One API doc per entity can be uploaded. It will appear automatically as an API doc entry in the API explorer dropdown.

The request body is JSON with a single field:

| Field | Type | Description |
| - | - | - |
| `spec` | string | The OpenAPI JSON or YAML as a string |

To convert a YAML or JSON file to a string, you can use `jq`:

```shellscript theme={null}
$(cat my_file.yaml | jq -Rsa)
```

See the [API docs](/api/rest/docs) for authentication details.

### Adding AsyncAPI docs

Add AsyncAPI specs from an external URL or a path within your git repository, using type `ASYNC_API`:

```yaml theme={null}
x-cortex-link:
  - name: Order Events API Spec
    type: ASYNC_API
    url: ./docs/order-events-spec.yml
```

## Adding embedded dashboards to an entity

Cortex supports embedding individual charts from Datadog, Grafana, New Relic, or any other source that provides an iframe embed URL. Embedded charts appear on the Dashboard page in the entity's left sidebar.

```yaml theme={null}
x-cortex-dashboards:
  embeds:
    - type: datadog
      url: https://app.datadoghq.com/graph/embed?token=abc123&height=300&width=600
```

* `type` is optional. Accepted values are `datadog`, `grafana`, and `newrelic`.
  * Content from sources other than Datadog, Grafana, or New Relic is supported. Omit the `type` field, and ensure the URL is publicly accessible or supports cross-platform authentication. For example, content accessible via VPN displays in Cortex when you're on the VPN.
* `url` is the `src` value from the iframe embed generated by your dashboard tool, not the dashboard's browser URL.
* The URL must be publicly accessible, or accessible via the same VPN your browser is on.

> [!NOTE]
>
> You can embed individual charts only, not full dashboards. If you're using Grafana and seeing embed errors, verify that [embedding is enabled](https://grafana.com/docs/grafana/latest/administration/configuration/#allow_embedding) in your Grafana instance.

## Accessing docs via Slack

If you have the Slack integration configured, you can look up an entity's documentation links without leaving Slack. Mention `@Cortex` in a channel or direct message and ask a question like "Where are the docs for payments-api?".

For setup and usage details, refer to [Using the AI assistant](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#using-the-ai-assistant).


# Grouping entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/groups



Groups are how you slice your catalog. They are free-form tags with no hierarchy or ownership semantics. Apply them to any set of [entities](/ingesting-data-into-cortex/entities-overview/entities/groups) that belong together, and use those labels to filter, report, and scope work across Cortex.

Think of groups as the vocabulary you invent to describe your system. You might use them to express priority (`tier-0`, `tier-1`), stack (`python`, `java`, `kotlin`), architectural role (`backend`, `frontend`, `library`, `api`), or any other dimension that matters to your organization.

Once entities are tagged, groups become a cross-cutting lens: filter a Scorecard to only Python services, build a catalog view of all tier-0 systems, or aggregate production readiness scores by tier.

## What you can do with groups

**Segment entities** - Tag entities with whatever labels make sense for your org. Groups are additive; an entity can belong to any number of groups.

**Filter throughout Cortex** - Use groups as inclusion or exclusion criteria in [Scorecards](/standardize/scorecards), [catalogs](/ingesting-data-into-cortex/catalogs), and [CQL reports](/standardize/cql/cql-reports). For example, apply a security Scorecard only to backend services, or surface a catalog view that shows only tier-0 entities.

**Aggregate and report** - Break down Scorecard results by group. For example, view a Production Readiness Scorecard segmented by tier to see which tier is furthest from your standards.

## Viewing groups on an entity

When you open an [entity's detail page](/ingesting-data-into-cortex/entities-overview/entities/details), its groups are listed in the upper-right corner. Clicking any group name takes you to a list of all other entities that share that tag.

![](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/groups-example.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=00bc1996b99c04a9bab42a08c862c53d)

## Defining and applying groups

Groups can be created and applied via the Cortex UI, an entity descriptor YAML file, or the API. Each method has distinct behavior.

### Behavior by method

There are important differences in how groups created via different methods interact with each other:

| | UI | Entity descriptor | API |
| - | - | - | - |
| Visible in entity YAML | | | |
| Removable via UI | | | |
| Overwritten by API | | | — |

Specifically:

* Groups set in the entity descriptor YAML cannot be overwritten by an API call.
* Groups created via the API do not appear in the entity descriptor YAML.
* Groups created via the API cannot be removed from the Cortex UI.

### Defining and applying groups via the Cortex UI

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. Locate the **Details** section.
4. From the **Groups** drop-down menu, select a group or groups to apply to the entity.
   * To create a new group, type the group name into the **Search items** field, then click **Add new \[group name]**. The group is created and applied to the entity.
5. Click **Save changes**.

### Defining and applying groups via an entity descriptor

Define groups as a list under `x-cortex-groups`:

```yaml theme={null}
x-cortex-groups:
    - tier-0
    - language:kotlin
```

Note that group name may not contain whitespace.

### Defining and applying groups via the API

Use the [Groups API](/api/rest/groups) to add groups to an entity programmatically.

## Troubleshooting and FAQ

See frequently asked questions below.

> **When should I use groups instead of custom data?**
>
> Groups work best for categorical, enumerable labels, e.g. `backend` vs. `frontend` or `tier-0` vs. `tier-1`. If you need freeform or structured metadata (e.g. `availability-zones`: \[`east`, `west`]), use [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data) instead.

> **What is the difference between `x-cortex-service-groups` and `x-cortex-groups`?**
>
> There is no functional difference. `x-cortex-service-groups` is deprecated in favor of `x-cortex-groups`, but the change is backward-compatible; existing configurations using the old key will continue to work.


# Using On-call Assistant for incident notifications
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant



Cortex’s On-call Assistant leverages the [PagerDuty integration](/ingesting-data-into-cortex/integrations/pagerduty) to automatically surface the most vital information about entity health and metadata when an incident is triggered. On-call Assistant notifies the user(s) responsible for an incident via Slack, including information about the affected entity, recent deployments, ownership, and links to get more details, including dependencies, runbooks, and logs.

On-call Assistant helps users respond to incidents in real time, simplifying the incident response process and helping to reduce MTTR. It can also drive adoption and engagement through links to the catalogs and Scorecards.

> [!NOTE]
>
> On-call Assistant only works for **service-level** PagerDuty registrations, since these notifications are related to affected services. Refer to [this article](/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty#considerations-for-registering-pagerduty-entities) for more information.

## How On-call Assistant notifications are sent in Slack

When a PagerDuty incident is triggered, Cortex identifies the responsible on-call user and notifies them in Slack. The alert includes information about the affected entity, deploy details, and ownership information. A direct link is included to view the alert in PagerDuty, so the incident can be quickly assessed from its source.

**Individual users** - On-call Assistant sends a direct message (DM) to the on-call user. Users don't need to install the Cortex Slack app or select a channel. Cortex looks up the user's Slack account using the email address on their Cortex account, then sends the DM directly. The only requirement is that the user's email in Cortex matches their Slack workspace email.

**Teams** - Notifications are sent to the Slack channel or channels [configured on the entity](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#connecting-an-entity-to-a-slack-channel).

![On-call assistant notifies users via Slack.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/oncall-assist-1.jpeg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=781814b53406cdb75978228f94aadf57)

### Viewing runbooks and other links

![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/oncall-assist-2.jpeg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=79488c2df5da173cb68510da82520818)

### Viewing dependencies

![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/oncall-assist-3.jpeg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=ca020962d3c1438da938ce6f00008e63)

## Enabling On-call Assistant

### Prerequisites

1. An [API key](https://support.pagerduty.com/main/docs/api-access-keys#rest-api-keys) in PagerDuty with the `Write` permission.
   * If you choose to bypass this prerequisite and create an API key with `Read-only` permissions, you also need to [configure a webhook](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant#configuring-a-webhook-for-read-only-api-keys) to get the On-call Assistant working.
2. The [PagerDuty integration](/ingesting-data-into-cortex/integrations/pagerduty) must be configured.
   * If using an API key with `Read-only` permission, be sure to toggle on **Read-only API key** in the PagerDuty side panel.

     ![The 'Read-only API key' option toggled on.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-side-panel%20\(1\).png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=76a1b11307c2324842ec13f00c2b04fb)
3. If sending notifications to teams, Slack channels must be [configured on the entity](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#connecting-an-entity-to-a-slack-channel).

### **Enabling On-call Assistant in Cortex**

1. From the main sidebar, select **Integrations**.
2. Locate PagerDuty, then click **Settings**.
3. Toggle on **Enable On-call Assistant**.

   ![The 'Enable On-call Assistant' option toggled on.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/on-call-asst-toggle.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=456640235f1b45e1564b795f43cd1f7f)

#### Configuring a webhook for read-only API keys

If your PagerDuty API key has `Read-only` permissions, you must also configure a webhook subscription.

**Step 1: Enabling On-call Assistant in Cortex**

1. From the main sidebar, select **Integrations**.
2. Locate PagerDuty, then click **Settings**.
3. Toggle on **Enable On-call Assistant**. The **Configure webhook** side panel opens.

**Step 2: Adding a webhook in PagerDuty**

1. In PagerDuty, add a new [webhook](https://support.pagerduty.com/main/docs/webhooks):
   1. Under Webhook URL, paste the Cortex webhook URL. The Cortex webhook URL can be found in the **Configure webhook** side panel.

      ![The webhook URL.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-webhook.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=1b3d7c877d8736fb0ee1e3ec3d2a713f)
   2. From the **Scope type** dropdown, select **Account**.
   3. Under **Event Subscription**, clear all checkboxes EXCEPT:
      * `incident.escalated`
      * `incident.reopened`
      * `incident.triggered`
      * `incident.unacknowledged`
   4. Click **Add webhook**. The **Webhook subscription created** window opens.
   5. Copy the webhook secret. Don't skip this step! You'll need the webhook secret to complete the setup.
   6. Click **OK**.

**Step 3: Completing setup in Cortex**

1. Go back to the browser window where your Cortex instance is open.
2. In the Configure webhook side panel, paste the webhook secret in the **Secret** field.

   ![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/pagerduty-webhook-sidepanel.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=74c843e7d70e57786bd7698788aa86e5)
3. Click **Save**.


# How ownership works
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership

Understand who can own an entity, where owners come from, how ownership flows through hierarchies, and what ownership unlocks in Cortex

Every entity in Cortex should answer one question: *who is responsible for this?* Ownership is how Cortex answers it, and almost every other feature depends on that answer. Owners get Scorecard and Initiative notifications, verify entity data, appear on the Engineering homepage, and can be the only people allowed to edit or run Workflows against an entity.

Ownership in Cortex works in three layers:

1. **Assignment** - Which teams and people are listed as owners of an entity, and where that list comes from.
2. **Propagation** - How owners flow from a parent entity, such as a domain, to its children.
3. **Effect** - What being an owner lets someone see, receive, and do.

```mermaid theme={null}
flowchart LR
  A["<b>1. Assignment</b><br/>Ownership tool recommendations<br/>Cortex UI<br/>Entity YAML or API<br/>Integration sync"]
  B["<b>2. Propagation</b><br/>Direct owners<br/>+ inherited owners<br/>(APPEND or FALLBACK)<br/>= the entity's owners"]
  C["<b>3. Effect</b><br/>Mine tab and homepage<br/>Notifications<br/>Data verification<br/>Edit and Workflow limits<br/>Reports and Eng Intelligence"]
  A --> B --> C
```

## Who can own an entity

An owner is either a team (recommended) or an individual.

| Owner type | What it is | In YAML | Stays current when people change roles? |
| - | - | - | - |
| **Team owner** | A team entity in Cortex, or a group from an identity provider, Git provider, or HR system | `type: group` with a `name` and `provider` | Yes, if the team is synced from an integration |
| **Individual owner** | One person, identified by email. They don't need a Cortex account. | `type: email` with an `email` | No. Deleted users stay listed as owners until you remove them. |

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: payments-team          # the team's x-cortex-tag
    provider: CORTEX
  - type: group
    name: cortexapps/payments    # a GitHub team, as org/team-slug
    provider: GITHUB
  - type: email
    email: maya.chen@example.com
    description: Escalation contact
```

For the full list of `provider` values and the name format each one expects, see [Assigning owners to entities](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities).

> [!NOTE]
>
> Teams play two roles in Cortex. A team is an entity in its own catalog, and it's also the most common owner of other entities. When you open a team's page, the **Entities** tab lists what it owns.

### Owners, on-call, and contact channels

The **Owners** block in an entity's metadata sidebar page shows the following ownership information. If you don't see the information listed below, the entity doesn't have it defined yet.

| What you see | What it means | Where it's defined |
| - | - | - |
| Teams and people | The entity's owners | `x-cortex-owners`, the UI, or an integration |
| Slack or Microsoft Teams channels | Where to reach the owners. Channels don't count as owners. | `x-cortex-slack`, `x-cortex-microsoft-teams` |
| On-call | Who's paged right now, from PagerDuty, Opsgenie, or another on-call tool | `x-cortex-oncall` |

![The 'Owners' block in an entity's metadata sidebar.](https://mintcdn.com/cortex-290c0c42/AgCb8YuLVqIlobqS/images/ownership-metadata-info.png?fit=max\&auto=format\&n=AgCb8YuLVqIlobqS\&q=85\&s=5be8cfa68d55466ed6cc2f53afca0224)

## Where owners come from

You can combine sources, but each entity should have one source of truth. See [Ownership best practices](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-best-practices). For provider values, name formats, and sync times for each integration, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

| Source | How it works | Best for |
| - | - | - |
| [Ownership tool recommendations](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations) | A machine learning model suggests team owners for services and service-like entities, using signals across your catalog, such as code contributions, related services, domain structure, and connected tools. You accept or reject each suggestion. | Filling gaps quickly after import |
| Cortex UI | Add teams or users in the **Owners** section of **Configure entity** | Small catalogs, one-off fixes |
| Entity YAML | List owners under `x-cortex-owners` and manage them through GitOps | Teams that already manage config as code |
| Cortex API | Create or patch the entity with its `x-cortex-owners` block | Bulk changes and automation |
| Identity provider or Git provider sync | Reference a group from Okta, Entra ID, Google, GitHub, GitLab, Bitbucket, or Azure DevOps. Cortex syncs its members daily. | Keeping team membership current |
| HR or ITSM sync | Import teams and reporting lines from Workday, BambooHR, or ServiceNow | Building the team hierarchy |
| Cloud tags | Tag AWS or Azure resources with `owner: <team x-cortex-tag>` and enable ownership sync | Cloud resources discovered by Cortex |
| Inheritance | A domain or other parent passes its owners to children | Entities that should follow their domain |

If an entity's YAML references a Cortex team that doesn't exist yet, Cortex creates the team and labels it **Automatically created by Cortex**.

## How ownership flows through hierarchies

Cortex has two hierarchies, and they do different things:

* **Entity hierarchy** (domains, and custom relationship types with **Ownership** enabled) *changes who owns* the children.
* **Team hierarchy** (parent and child teams) *changes what you see*. It rolls up views and reports, but it never adds owners to an entity.

### Entity hierarchy: inheritance

Each owner on a parent entity has an inheritance mode. If you don't set one, it's `NONE`.

| Mode | What children get |
| - | - |
| `APPEND` | This owner is added to every child, even children that already have owners. |
| `FALLBACK` | This owner is added to a child only if the child has no other valid owners. |
| `NONE` | This owner owns the parent only. It's the default. |

In this example, the Payments domain has three owners, each with a different mode:

```mermaid theme={null}
flowchart TD
  D["<b>Payments domain</b><br/>payments-leads · NONE<br/>platform-eng · APPEND<br/>payments-team · FALLBACK"]
  S1["<b>checkout-service</b><br/>Direct owner: checkout-team"]
  S2["<b>ledger-service</b><br/>No direct owners"]
  R1["Owners: checkout-team, platform-eng"]
  R2["Owners: platform-eng, payments-team"]
  D --> S1
  D --> S2
  S1 -.-> R1
  S2 -.-> R2
```

* `payments-leads` owns the domain only, so neither service lists it.
* `platform-eng` is appended to both services.
* `payments-team` is a fallback, so it appears only on `ledger-service`, which has no other owners.

Inheritance continues down every level of the hierarchy, so a domain's `APPEND` owner also reaches services inside its child domains.

If an entity receives the same owner from more than one ancestor, Cortex lists that owner once. The closest ancestor is shown as the source, and the stronger mode wins: `APPEND` beats `FALLBACK`, and both beat `NONE`.

To see where an inherited owner came from, open the entity, find **Owners** in the sidebar, and click the inheritance chain icon next to the owner. Cortex shows the source entity, the relationship type, and the mode. Direct owners don't have the icon.

You can set inheritance in YAML, when you [add a domain](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains) in the UI, or on a [relationship type](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types/managing-relationships) by turning on **Ownership**. For details, see [Ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance).

### Team hierarchy: roll-up

Teams can have parent and child teams. A parent team doesn't own what its child teams own, but you can include child teams when you view or report on ownership.

```mermaid theme={null}
flowchart TD
  P["<b>Engineering</b> (parent team)<br/>Owns: eng-portal"]
  C1["<b>Payments</b> (child team)<br/>Owns: checkout-service"]
  C2["<b>Platform</b> (child team)<br/>Owns: build-service"]
  P --> C1
  P --> C2
  V["Engineering's <b>Entities</b> tab with<br/><b>Inherited Children</b> on:<br/>eng-portal, checkout-service, build-service"]
  P -.-> V
```

Enabling **Include child teams** (on the **Mine** tab and Engineering homepage) or **Inherited Children** (on a team's **Entities** tab) adds child teams' entities to the list. It doesn't make Engineering an owner of `checkout-service`, so Engineering members can't verify it and don't receive its owner notifications.

## Who counts as an owner in each feature

Features check ownership in slightly different ways. Use this table when someone asks why they can see an entity but can't act on it.

| Feature | You count as an owner if |
| - | - |
| **Mine** tab and [Engineering homepage](/streamline/homepage) | You're listed as an individual owner, or you're a member of a team that owns the entity. Child teams are optional. |
| [Notifications](/configure/settings/notifications) | You're an individual owner, or a member of an owning team with notifications enabled. Owners without a Cortex account can be notified if **Enable notifications for non-Cortex users** is on. |
| [Data verification](/configure/settings/entity-settings/viewing-and-verifying-data-verifications) | You're a direct member of a team that owns the entity. Inherited owners and parent teams don't count. If the verification period lists team member roles, you also need one of those roles. |
| [Team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing) | You're a member of the owning team and flagged as **Editor**, or **Give edit access to all team members** is on. Inherited team owners count. Entities owned only by individuals have no owning team, so nobody gets edit access through this feature. |
| [Workflow run restrictions](/streamline/workflows/configuring-workflow-settings) | You own the target entity and also have edit access to it. |
| [Data Explorer](/improve/eng-intelligence/data-explorer) and [OpEx Review](/improve/opex-review/configuring-opex) | **Entity owner (Team)** groups metrics by the team that owns the entity, including its sub-teams while **Include child teams** is on (the default). The **Team owner** filter covers the selected team only. **Team (Author)** groups metrics by the team of the person who did the work. |

## What you need before ownership works

[Identity mappings](/configure/settings/managing-users/identity-mapping) connect each Cortex user to their accounts in other tools. Without them, Cortex can't tell that a GitHub team member is you. Set them up before you rely on:

* The **Mine** tab and Engineering homepage.
* The **Editor** label for team ownership entity editing.
* Team metrics in Eng Intelligence.

Ownership tool recommendations work without identity mappings, but they get more accurate as more people are mapped.


# Assigning owners to entities
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities



Cortex supports several ways to assign owners to an entity: accepting an automated recommendation, defining owners in the entity descriptor YAML, adding them directly in the UI, or syncing them from an integration. For most teams, a combination is common: automated recommendations to tackle unowned entities at scale, YAML for entities managed through GitOps, and the UI for quick edits.

## Types of owners

Owners can be defined as:

* **A team** (recommended)
  * If you link a `group` from an external platform (such as Okta), Cortex automatically updates team membership when someone leaves your organization and is removed from your identity provider.
* **An individual user**

An entity can also inherit owners from a parent entity, such as a domain. See [Ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance).

## Methods for assigning ownership

Owners can be assigned:

* By accepting Cortex's automated recommendations for owners, based on signals from across your catalog
* By pulling information from third-party integrations in the [entity's YAML](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-with-yaml)
  * Ownership can also be inherited via [fallback or append configuration](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance)
* Directly in the Cortex UI
* Automatically if Cortex detects that an entity is owned by a team that does not yet exist in Cortex
  * If an entity's YAML references a team, but that team doesn't have a corresponding entry within Cortex, Cortex automatically creates the team. A label next to the team name denotes that team was **Automatically created by Cortex**.

### Assigning ownership via Cortex recommendations

Cortex's ownership recommendations uses a machine learning model to suggest team owners for entities in your catalog. It draws on the context of all the data in your catalog, including code contribution activity, the owners of related services, entity names and descriptions, domain structures, metadata, and connections to other tools, such as on-call and issue tracking tools.

The model works even with very little data to start. The richer and better connected your catalog is, the more the model can extend that signal to the rest of your catalog, and the more accurate its recommendations are.

> [!NOTE]
>
> **Ownership tool preview**
>
> Not seeing the results you expect? This is an early version of the Ownership tool. Please submit feedback [via this form](https://docs.google.com/forms/d/e/1FAIpQLSdURosGQhMnmMCF7FA66v9DOdnk5rOSoK1SaUVGjpOy4ywt5g/viewform). Note the following considerations:
>
> * To get recommendations, you must have teams configured in Cortex, and your team members must have Git [identity mappings](/configure/settings/managing-users/identity-mapping). The more teams and people you map, the better your recommendations.
> * To accept or reject the recommended owner, the user must have the `Edit Entities` permission (**Edit and create entities** in [Roles and permissions](/configure/settings/managing-users/permissioning)).
> * If you are using GitOps, you can view recommendations, but you cannot accept them from the UI.

When Cortex has an ownership recommendation for an entity, it surfaces in the following places: the Ownership tool (**Tools > Ownership**), the **Owners** section of the entity's details page overview, the **Owners** block in the entity's metadata sidebar, and the import flow when adding entities.

#### Reviewing recommendations per entity

You can review and accept recommendations from an entity's details page in one of two ways: via the **Owners** block in the metadata sidebar and via the entity's settings.

**Prerequisites**

1. UI editing must be enabled for the entity type
2. The user must have entity-level access via RBAC or fine-grained access control
3. The user must have the `Edit Services` and `Edit Catalog` roles.

**To review and accept ownership recommendations via the metadata sidebar**:

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. Make sure the metadata sidebar is expanded.

   ![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/expand-metadata-sidebar%20\(1\).png?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=c414bf74a450e476b3e96fa7b84da804)
3. In the **Owners** block, click the **Recommendations** button.

   ![](https://mintcdn.com/cortex-290c0c42/AgCb8YuLVqIlobqS/images/ownership-recommendations-button.png?fit=max\&auto=format\&n=AgCb8YuLVqIlobqS\&q=85\&s=bab3d0dcb211411ebe74efdff9995b2c)
4. Review the suggested owners. Do one of the following:
   * To accept a recommendation, click the checkmark next to that entity.
   * To accept more than one recommendation, select the checkboxes next to those entities, then click **Apply**.
   * To remove a recommendation, click the **X** next to the entity.
   * To remove more than one recommendation, select the checkboxes next to those entities, then click **Reject**.
   * To remove all recommendations, click **Dismiss all**.

**To review and accept ownership recommendations via the entity's settings**:

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. From the left entity details sidebar, click **Owners**.
4. Review the suggested owners. Do one of the following:
   * To accept a recommendation, click the checkmark next to that entity.
   * To accept more than one recommendation, select the checkboxes next to those entities, then click **Apply**.
   * To remove a recommendation, click the **X** next to the entity.
   * To remove more than one recommendation, select the checkboxes next to those entities, then click **Reject**.
   * To remove all recommendations, click **Dismiss all**.

#### Reviewing recommendations on the Ownership page

The Ownership page shows the teams Cortex recommends as owners for your entities, so you can review and accept them in one place. To open it, go to **Tools > Ownership** in the main sidebar.

![The Ownership page in Cortex.](https://mintcdn.com/cortex-290c0c42/AgCb8YuLVqIlobqS/images/ownership-tools-ownership.png?fit=max\&auto=format\&n=AgCb8YuLVqIlobqS\&q=85\&s=6e2ef54bf8bcb1321d82fe01702b7044)

The page has two panes:

* **Left pane** - Lists the entities or teams you can review, grouped by status.
* **Right pane** - Shows the recommendations and current owners for whatever you select in the left pane.

**Entities and Teams tabs**

The tabs at the top of the left pane let you review ownership from either side.

* **Entities** - Lists entities, grouped into **Missing Team Owner** and **Has Team Owner**. Select an entity to see the teams recommended to own it, how confident each recommendation is, and its current owners. Click **Open Entity** to go to the entity's details page, or click the repository link to open it in your git provider.
* **Teams** - Lists teams, grouped into **Has recommendations** and **No recommendations**. Select a team to see the entities recommended for it and the entities it already owns. Click **Open Team** to go to the team's details page.

Each group shows a count next to its name. Click the arrow next to a group to expand or collapse it.

**All and Mine tabs**

Below the **Entities** and **Teams** tabs, you can choose how much of the list to show:

* **All** - Shows every entity or team in your workspace.
* **Mine** - Shows only the entities or teams associated with you.

**Sort, filter, and search the list**

Use the icons to the right of the **All** and **Mine** tabs to narrow the list.

**To sort the list**:

1. Click the **sort icon**.
2. Select **Name**, or select **Recommendations** to sort by confidence (high to low). Click the arrows next to the selected option to reverse the order.

**To filter the list**:

1. Click the **filter icon**.
2. In the left side of the filter panel, click **+** next to a field you want to filter by:
   * **Domains** - Available on the **Entities** and **Teams** tabs.
   * **Entity types** - Available on the **Entities** tab only.
3. Choose one or more values from the **Select** dropdown.
4. Click **Apply**.

To remove a filter, click the **trash icon** next to it. To clear all of them, click **Reset filters**.

To search the list, click the **search icon** and enter a name.

**Accepting or rejecting recommendations**

The **Recommendations to review** table lists each recommended team (on the **Entities** tab) or entity (on the **Teams** tab) with a confidence level of High or Low.

To accept or reject a single recommendation:

1. In the left pane, select an entity or team.
2. In the **Recommendations to review** table, find the recommendation:
   * To accept it, click the checkmark.
   * To reject it, click the X.

To accept or reject several recommendations at once:

1. Select the checkbox next to each recommendation you want to act on. To select all of them, select the checkbox in the table header.
2. In the action bar at the bottom of the table, click **Apply** to accept the selected recommendations, or click **Reject** to reject them.

To clear your selection, click the **X** on the right side of the action bar.

To dismiss all recommendations for the selected entity or team, click **Dismiss all** at the bottom of the table.

To add an owner manually, click **Add** in the Owners panel (**Entities** tab) or the Owned entities panel (**Teams** tab). On the **Teams** tab, click the **trash icon** next to an owned entity to remove it.

### Assigning ownership via an entity's YAML

Use the `x-cortex-owners` field to define owners directly in your entity's YAML. Each owner is either a `group` (a team from Cortex or a connected integration) or an individual identified by `email`.
Each owner entry requires the `type` field, set to either `group` or `email`. For `group` owners, the `name` and `provider` fields are also required. For `email` owners, the `email` field is required.

Cortex recognizes groups from the following integrations: [Azure Active Directory](/ingesting-data-into-cortex/integrations/entraid), [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Google](/ingesting-data-into-cortex/integrations/google), [Okta](/ingesting-data-into-cortex/integrations/okta), [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie), [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow), and [Workday](/ingesting-data-into-cortex/integrations/workday).

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: platform-engineering        # x-cortex-tag of the Cortex team
    provider: CORTEX
  - type: group
    name: cortexapps/payments-team    # GitHub org/team slug
    provider: GITHUB
  - type: group
    name: payments-oncall             # Opsgenie team name
    provider: OPSGENIE
  - type: email
    email: maya.chen@acme.com      # individual owner
    description: Primary escalation contact
```

The `provider` field tells Cortex which system the group comes from. Supported values are: `ACTIVE_DIRECTORY`, `AZURE_DEVOPS`, `BAMBOO_HR`, `BITBUCKET`, `CORTEX` (use for teams defined natively in Cortex, including teams Cortex creates automatically from Workday), `GITHUB`, `GITLAB`, `GOOGLE`, `OKTA`, `OPSGENIE`, `SERVICE_NOW`, and `WORKDAY`.

The `name` field is case-sensitive. What it refers to depends on the provider:

| Provider | When |
| - | - |
| `CORTEX` | The `x-cortex-tag` of the team in Cortex |
| All other providers | The upstream identifier for the group in that integration (e.g. an Okta group name, a GitHub `org/team-slug`) |

> [!NOTE]
>
> The `description` field is optional on any owner entry and is purely for human reference.

### Assigning ownership via the Cortex UI

Users with the `Edit Entities` or `Edit Catalog` role can assign ownership via the Cortex UI.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Select the entity whose ownership you want to edit.
4. In the upper-right corner, click **Configure entity**.
5. From the left entity details sidebar, click **Owners**.
6. Do one or both of the following:
   1. To assign a team ownership:
      1. Locate the **Teams** section, then click **Add**.

         ![The Add button next to Teams.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/ownership-team.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=77aca859868aeeeac87b003cc72a0bbd)
      2. In the **Add Teams** side panel, select the team from the drop-down menu.
      3. Optionally, enter a description for the team.
      4. Click **Add**.
   2. To assign an individual user ownership:
      1. Locate the **Users** section, then click **Add**.

         ![The Add button next to Users.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/ownership-user.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=f21bb7f4b2ef15619c6d11d37e42b9d9)
      2. In the **User** side panel, do one of the following:
         1. Select a Cortex user from the drop-down menu. To find a user not shown in the list, use the **Search** field.
         2. To add a user who is not listed in Cortex, enter their email address into the **Email address** field. The drop-down populates with the user's email address.
      3. Optionally, enter a description for the user.
      4. Click **Add**.


# Ownership best practices
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-best-practices

Set up entity ownership in Cortex that stays accurate as people and teams change

Ownership is only useful if it's right. A stale owner means notifications go to someone who left, verifications stall, and Scorecard failures land on nobody's homepage. These practices help you set up ownership once and keep it current with little manual work.

If you're new to ownership in Cortex, start with [How ownership works](/ingesting-data-into-cortex/entities-overview/entities/ownership).

## Quick checklist

* [ ] Every entity is owned by at least one team.
* [ ] Teams are synced from an identity provider, Git provider, or HR system.
* [ ] Identity mappings are configured for your Git, on-call, and chat tools.
* [ ] Each entity type has one source of truth for owners: the UI or GitOps.
* [ ] Domains use inheritance on purpose, not by default.
* [ ] A Scorecard flags entities without owners.
* [ ] A recurring data verification period asks owners to confirm their entities.

## Assign teams, not people

Make a team the owner of every entity. Add an individual only as an extra contact.

* **Teams survive turnover.** When someone leaves a synced team, Cortex removes them from the team at the next sync. The entity keeps its owner.
* **Individual owners don't update.** Deleting a user from Cortex doesn't remove their email from owner fields. You have to find and replace them.
* **Most features act on teams.** Team notifications, ownership-based editing, data verification roles, and team metrics in Eng Intelligence all work through team membership.

> [!TIP]
>
> Use individual owners for people outside your team structure, such as a security reviewer or a vendor contact. Add a `description` so others know why they're listed.

## Sync teams from the system that already knows your org

Don't maintain team membership by hand in Cortex if another system already does it.

| If your org structure lives in | Use it for | Set up |
| - | - | - |
| An HR system (Workday, BambooHR) | Teams, members, and reporting lines | [Workday](/ingesting-data-into-cortex/integrations/workday), [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr) |
| An identity provider (Okta, Entra ID, Google) | Team membership from groups | [Okta](/ingesting-data-into-cortex/integrations/okta), [Entra ID](/ingesting-data-into-cortex/integrations/entraid), [Google](/ingesting-data-into-cortex/integrations/google/connecting-entities-to-google-cloud-platform) |
| A Git provider (GitHub, GitLab, Bitbucket, Azure DevOps) | Team membership from Git teams, plus ownership recommendations | [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) |
| ServiceNow | Teams and relationships from table mappings | [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow) |

Pick one system as the source of team membership. Mixing sources for the same team makes it hard to tell why someone was added or removed.

If you sync team roles, turn on **Sync team roles from identity providers** in **Settings** > **Entities** > **Teams**. Members imported without a role can't verify entities when a verification period requires a role.

## Set up identity mappings first

Cortex matches people across tools with [identity mappings](/configure/settings/managing-users/identity-mapping). Configure them before you roll out ownership, because several features silently do nothing without them:

* The **Mine** tab and Engineering homepage can't show what you own.
* The **Editor** label doesn't appear for team ownership entity editing.
* Team metrics in Eng Intelligence come back empty.

Ownership tool recommendations work without identity mappings, but they get more accurate as more people are mapped.

## Choose one source of truth per entity type

Owners can come from the UI, YAML, the API, or an integration. Decide per entity type where owners are managed, and stick to it.

> **Cortex UI**
>
> Manage owners in **Configure entity** > **Owners**. This is the fastest way to accept ownership recommendations in bulk.
>
> Keep UI editing enabled for these entity types, and avoid also defining owners in YAML.

> **GitOps**
>
> Manage owners in `x-cortex-owners` alongside the code. Changes go through review, and history lives in Git.
>
> Disable UI editing for these entity types in **Settings > GitOps**. If UI editing is enabled, commits to those entities aren't reflected in Cortex. See [GitOps settings](/configure/settings/gitops-settings) for more information.
>
> With GitOps, you can view ownership recommendations but can't accept them from the UI. Copy the recommended team into YAML instead.

To remove an owner, use the same method you used to add it. See [Viewing and managing ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership/viewing-and-managing-ownership#removing-ownership).

## Use inheritance on purpose

Inheritance keeps children owned when nobody remembers to set an owner, but it can also add owners nobody expects. Choose a mode for each domain owner:

| Use | When | Example |
| - | - | - |
| `FALLBACK` | You want a safety net for children with no owner | The domain's team catches any new, unowned service |
| `APPEND` | A group must be on every child, regardless of its owners | A platform or security team that needs every notification |
| `NONE` | The owner is responsible for the domain itself, not its contents | Domain leads who own the domain's roadmap |

* Prefer `FALLBACK` over `APPEND`. Appended owners receive every child's notifications, which adds up fast in a large domain.
* Inherited owners can't verify data. If a domain team should verify a child, make it a direct owner.
* To remove an inherited owner, change its mode on the parent. See [Removing inherited ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership/viewing-and-managing-ownership#removing-inherited-ownership).

> [!NOTE]
>
> Domain inheritance and team hierarchy are distinct concepts. Parent teams never become owners of their child teams' entities. Use **Include child teams** to see everything below a team instead.

## Fill gaps with recommendations, then verify

After you import entities, use the [Ownership tool](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations) to assign owners quickly.

**1. Review recommendations in bulk**

Go to **Tools** > **Ownership**, select entities, adjust the recommended teams, and click **Accept recommendations**. Recommendations come from a model that uses signals across your catalog, such as code contributions, related services, domain structure, and connected tools.

**2. Assign the rest manually**

Some entities won't have enough signal for a recommendation. Use the **Unowned entities** filter in your catalogs to find what's left.

The more your catalog contains (descriptions, domains, team membership, and integrations), the more entities get a recommendation and the more accurate they are. Filling these in before you run the Ownership tool pays off.

**3. Ask owners to confirm**

Create a [data verification period](/configure/settings/entity-settings/verification) for the entities you just assigned, so each team confirms it really owns them. See [Verify services after AI-based auto-mapping](/guides/ai-excellence/verify-auto-mappings).

## Keep owners and on-call separate

Ownership and on-call answer different questions. Owners are accountable for an entity over time; on-call is who responds right now.

* Define owners in `x-cortex-owners` and on-call schedules in `x-cortex-oncall`.
* Don't use an on-call schedule or a Slack channel as a stand-in for an owner. Channels in the **Owners** block are contacts, not owners.
* Opsgenie can provide both. Its integration page (**Integrations >  Configurations > Opsgenie**) shows each block.

## Enforce ownership with Scorecards

Make missing ownership visible so it gets fixed:

* Start from the **Ownership Verification** Scorecard template in [Create a Scorecard](/standardize/scorecards/create#option-1-use-a-template). Failing entities appear as tasks on owners' homepages.
* Or add a rule to an existing Scorecard:

```text theme={null}
ownership.allOwners().length > 0
```

To require a team owner specifically, use `ownership.teams().length > 0`.

* Track the unowned count over time in the [Executive report](/improve/reports/executive-report).

## Restrict editing to owners when you're ready

Once ownership is accurate, you can limit who edits each entity to its owning team with [Team ownership entity editing](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/team-entity-editing). Turn it on after the steps above, not before. Only team ownership grants edit access, so check these first:

* **Entities owned only by individuals** have no owning team. Only users with broad edit permissions, or `Configure catalog`, can edit them. Add a team owner.
* **Inherited team owners count.** Members of a team that owns an entity through a domain can edit it.
* **Unmapped members** don't get the **Editor** label. Configure identity mappings first.

## Plan for reorgs

* **Archive, don't delete, old teams.** You can't add an archived team as an owner, which prevents new assignments to a team that no longer exists.
* **Watch for new team IDs.** In Workday, changing a team's supervisory org ID or name creates a new team. Reassign entities from the old team.
* **Clean up individual owners.** Search with `owner:` for departed users' emails and replace them with teams.
* **Re-run verification.** After a reorg, start a verification period so new teams confirm what they inherited.


# Ownership inheritance
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance



Rather than assigning owners to every entity individually, you can define ownership at the domain level and have it propagate to child entities. This is useful for large catalogs where many entities share a common accountable team.

Inheritance is configured per owner using the `inheritance` field in the `x-cortex-owners` block. If omitted, it defaults to `NONE`.

```yaml theme={null}
openapi: 3.0.1
info:
  title: Payments Platform
  description: Domain covering all payments-related services and resources.
  x-cortex-tag: payments-platform
  x-cortex-type: domain
  x-cortex-owners:
    - type: group
      name: payments-leads             # owns this domain directly; no inheritance
      provider: CORTEX
      inheritance: NONE
    - type: group
      name: platform-engineering       # appended as owner on all child entities
      provider: CORTEX
      inheritance: APPEND
    - type: group
      name: cortexapps/payments-team   # fallback if a child has no other owners
      provider: GITHUB
      inheritance: FALLBACK
```

## Inheritance modes

Each owner on a parent entity has one of three `inheritance` values.

### `APPEND`

This owner is added to the owner list of every child entity, regardless of whether the child already has owners. Use it for a team that must be included on everything in the domain, such as a platform or security team.

### `FALLBACK`

This owner is assigned to a child entity only if that child has no other valid owners (including other fallbacks). `FALLBACK` applies to children only, not to the domain itself. Use it as a safety net so new or unowned entities in the domain always have an owner.

### `NONE`

This owner belongs to the domain but does not propagate to children. This is the default.

## How inheritance works across levels

* **Inheritance is transitive.** Owners continue down every level of the hierarchy. For example, a domain's `APPEND` owner is also added to the services inside its child domains.
* **Duplicate owners are listed once.** If an entity receives the same owner from more than one ancestor, Cortex lists that owner once and shows the closest ancestor as its source.
* **The stronger mode wins.** If the same owner arrives with different modes, `APPEND` takes precedence over `FALLBACK`, and both take precedence over `NONE`. A mode is never downgraded.

## Configuring inheritance in the Cortex UI

You can configure inheritance in the Cortex UI in two places:

* **On a domain's owners** - When you [create or edit a domain](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains), select **Append**, **Fallback**, or **None** for each owner.
* **On a relationship type** - When you [create a relationship type](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types/managing-relationships), toggle on **Ownership** and choose **Fallback** or **Append**. Owners then flow from the source entity to the destination entity of each relationship of that type.

## Viewing the source of an inherited owner

When ownership is layered across a hierarchy, it can be hard to tell why a particular team appears as an owner on a given entity. To trace it:

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the entity's metadata sidebar, locate the **Owners** block.
3. Next to an owner, click the **Inheritance chain** icon.

   ![The 'Inheritance chain icon'; is found within the Owners section in the metadata sidebar.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/inherited-entity-ownership%20\(1\).png?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=cc2edb091210c012cd943553d949aeaa)

   \
   Cortex shows the source entity, the relationship type, and the rule (`APPEND` or `FALLBACK`) that caused the owner to propagate. The icon only appears for inherited owners; direct owners defined on the entity itself have no chain to display.

## Related pages

* Ownership can also be set from tags on cloud resources. See [Syncing ownership from AWS](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#syncing-ownership-from-aws) and [Syncing ownership from Azure Resources](/ingesting-data-into-cortex/integrations/azureresources#syncing-ownership-from-azure-resources).
* Inheritance applies to entity hierarchies, not team hierarchies. Parent teams don't inherit ownership of their child teams' entities. See [How ownership works](/ingesting-data-into-cortex/entities-overview/entities/ownership#how-ownership-flows-through-hierarchies).


# Ownership sources reference
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources

Compare the integrations that can supply owners in Cortex: provider values, name formats, sync times, and identity mapping needs

Cortex can pull owners from your Git provider, identity provider, HR system, ITSM tool, on-call tool, or cloud tags. This page compares every ownership source in one place so you can choose a source of truth and write `x-cortex-owners` blocks correctly.

If you're new to ownership in Cortex, start with [How ownership works](/ingesting-data-into-cortex/entities-overview/entities/ownership). For help choosing a source, see [Ownership best practices](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-best-practices).

## Sources that use `x-cortex-owners`

For these sources, reference the provider's team or group in the entity descriptor with `type: group`:

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: <name in the format below>
    provider: <provider value below>
```

| Source | `provider` value | `name` format | Sync time (UTC) | Identity mapping |
| - | - | - | - | - |
| [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops#syncing-ownership-from-azure-devops) | `AZURE_DEVOPS` | Azure DevOps team name (case-sensitive) | Daily at 10 a.m. | Required to connect team members to Cortex users |
| [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr#syncing-ownership-from-bamboohr) | `BAMBOO_HR` | Team value from BambooHR's **Employee ownership field** | Daily at 6 a.m. | Not needed. Cortex uses each member's email address from BambooHR. |
| [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket#syncing-ownership-from-bitbucket) | `BITBUCKET` | Bitbucket team name | Daily at 10 a.m. | Required to connect team members to Cortex users |
| [Entra ID](/ingesting-data-into-cortex/integrations/entraid#syncing-ownership-from-entra-id) | `ACTIVE_DIRECTORY` | Entra ID group name (case-sensitive) | Daily at 6 a.m. | Optional. Cortex uses identity mappings when they exist, and falls back to the member's email address from Entra ID. |
| [GitHub](/ingesting-data-into-cortex/integrations/github#syncing-ownership-from-github) | `GITHUB` | `<organization>/<team-name>` | Daily at 9 a.m. | Required to connect team members to Cortex users |
| [GitLab](/ingesting-data-into-cortex/integrations/gitlab#syncing-ownership-from-gitlab) | `GITLAB` | GitLab group name | Daily at 10 a.m. | Required to connect group members to Cortex users |
| [Google](/ingesting-data-into-cortex/integrations/google/connecting-entities-to-google-cloud-platform#syncing-ownership-from-google-groups) | `GOOGLE` | Full Google Group email address | Daily at 9 a.m. | Optional. Cortex uses identity mappings when they exist, and falls back to the member's email address from Google. |
| [Okta](/ingesting-data-into-cortex/integrations/okta#syncing-ownership-from-okta) | `OKTA` | Okta group name (case-sensitive) | Daily at 3 p.m. | Optional. Cortex uses identity mappings when they exist, and falls back to the member's email address from Okta. |
| [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie#syncing-ownership-from-opsgenie) | `OPSGENIE` | Opsgenie team name (case-sensitive) | Teams daily at 9 a.m., identities daily at 10 a.m. | Required to connect team members to Cortex users |
| [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow#syncing-ownership-from-servicenow) | `SERVICE_NOW` | ServiceNow team name (case-sensitive) | Daily at 9 a.m. | Not needed |
| [Workday](/ingesting-data-into-cortex/integrations/workday/using-the-integration-for-workday#syncing-ownership-from-workday) | `CORTEX` | Cortex tag of the team imported from Workday | Daily at 9 a.m. | Not needed. Cortex uses each member's email address from Workday. |

> [!NOTE]
>
> Workday teams are imported as Cortex teams, so you reference them by their Cortex tag with `provider: CORTEX`.

## Sources that use cloud tags

AWS and Azure Resources don't use `x-cortex-owners`. Instead, Cortex reads an ownership tag on each cloud resource and matches its value to a Cortex team's `x-cortex-tag`. By default, the tag key is `owner`, and you can customize it in each integration's settings. Because the tag points to a Cortex team, you don't need identity mappings for this step.

| Source | Tag value | Sync time (UTC) | How to enable |
| - | - | - | - |
| [AWS](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#syncing-ownership-from-aws) | The owning team's `x-cortex-tag` | Daily at 6 a.m. | Turn on ownership sync in the AWS integration settings |
| [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources#syncing-ownership-from-azure-resources) | The owning team's `x-cortex-tag` | Daily at 6 a.m. | Turn on ownership sync in the Azure Resources settings |


# Viewing and managing ownership
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/ownership/viewing-and-managing-ownership



Once your catalog has owners assigned, Cortex gives you several ways to slice that data: by individual, by team, or across a team hierarchy. This page covers how to find the entities you own, filter by team, and remove ownership that's no longer accurate.

## Viewing an entity's owners

When viewing an entity, the owners appear in the metadata bar on the right side of the page:

![The Owners section in an entity's metadata sidebar.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/owners-entity-details.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=9f75a78836e48f641239ccb2ce3a96fb)

If the entity is owned by a team, click the team name to open the team's entity page, which lists its members and owned entities. If owned by an individual, Cortex displays the user's email. If an owner was inherited from a parent entity, click the inheritance chain icon next to it to see where it came from. For information on assigning owners, refer to [Assigning owners to entities](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities).

## Finding entities without owners

There are a few ways to find entities in your catalog that don't have owners yet:

* Use the [Ownership tool](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations) to see unowned entities and Cortex's automated recommendations for owners.
* In your catalogs, click **Filter** and select **Unowned entities**.
* View the [Executive report](/improve/reports/executive-report), which lists unowned entities.
* Run an [Ownership Verification Scorecard](/standardize/scorecards/create#option-1-use-a-template), which adds tasks to your homepage for any entities still missing owners.

## Viewing entities you own

1. From the main sidebar, expand **Catalog**, then select **All entities**.
2. Select the **Mine** tab. A list of entities you own is displayed.

   ![The Entities page showing all entities owned by the user.](https://mintcdn.com/cortex-290c0c42/uWo5OVZ0DdR5tZ8Q/images/entities-owner.png?fit=max\&auto=format\&n=uWo5OVZ0DdR5tZ8Q\&q=85\&s=c1b9b555b995f985186173162af3ee8e)

### Viewing child team ownership

1. From the main sidebar, expand **Catalog**, then select **All entities**.
2. Select the **Mine** tab.
3. At the top of the list, click **Display**.
4. Toggle on **Include child teams**.

   ![The 'Include child teams' option, toggle on.](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/include-child-teams.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=f661a9692dd7c63446ef2177b844547d)
5. Click **Done**.

## Viewing a team's owned entities

1. From the main sidebar, expand **Catalog**, then select **All entities**.
2. Select the **All** tab.
3. At the top of the list, click **Filter**.
4. In the **Filter** window, click **Teams**.

   ![The 'Teams' option in the Filter window.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/view-team-entities.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=1187aa577877ef10b402cbca3b839230)
5. Select a team or teams from the drop-down menu.
6. Click **Apply**.

### Viewing entities owned by all teams within a hierarchy

Teams can exist [within hierarchies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams/viewing-teams#understanding-hierarchies). To view a list of entities owned by the parent team and all children teams in the hierarchy:

1. Navigate to the parent team's page.
2. Select the **Entities** tab.

   ![The 'Entities' tab on a team's page.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/team-page-entities-tab.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=7e417152a31739617ba7a313e58c6051)
3. At the top of the list, click **Display**.
4. Toggle on **Inherited Children**.

   ![The 'Inherited children' option toggled on.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/teams-inherited-children.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=c38136412c7507c8f26c6b631bbd6a3a)
5. Click **Done**.

The list displays all entities owned by the parent and its children teams. Note that this setting does not persist when you navigate away from the page.

## Removing ownership

To remove an owner, use the same method you used to add them.

### Removing ownership via the Cortex UI

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper right corner, click **Configure entity**.
3. In the left sidebar, select **Owners**.
4. Locate the team or user you want to remove, then click the **trash icon**. The **Confirm team owner deletion** modal opens.
5. Click **Delete**.

### Removing ownership via YAML

* Update the `x-cortex-owners` block in your YAML to reference only the correct teams or individuals. Ensure that all referenced teams actually exist in Cortex.
* If using [GitOps](/configure/gitops), make sure the YAML is updated and merged to your main branch, then allow Cortex to re-sync. This updates the ownership in the UI to match the YAML.

### Removing ownership via API

Use the [Create or update entity API](/api/rest/catalog-entities#post-api-v1-open-api) to completely replace the entity YAML, or the [Create or patch entity API](/api/rest/catalog-entities#patch-api-v1-open-api) to remove one or more owner and not change the rest of the entity YAML.

### Removing inherited ownership

* Check if the entity is a child of a domain, or of an entity linked by a relationship type, with [ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance) enabled. If so, the parent’s owners may be appended to the entity.
* To remove inherited owners, edit the domain or parent’s owner inheritance setting (for example, change it from `APPEND` to `NONE`).


# Relationship graph
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/relationship-graph



The relationship graph gives you a visual map of your Cortex catalog. Instead of reading dependencies, ownership, and architecture out of individual entity pages, you can see how everything connects in one interactive diagram. Use it to understand three different views of your organization:

* **Dependencies** - Visualize how entities depend on one another. You can also [sync dependencies](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph#sharing-or-syncing-from-the-graph) directly from the graph.
* **Domains** - See a hierarchical diagram of your software architecture.
* **Teams** - View your company's team structure and how teams nest within one another.

## Viewing the relationship graph

To access the relationship graph, expand **Tools** in the main sidebar, then click **Relationship graphs**. By default, the page loads [the view you've set as your default](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph#setting-the-default-view) (Dependencies, Domains, or Teams) and shows all entities in that view along with their connections.

Use the toolbar controls to move around the large graph:

* Use the zoom controls in the bottom-left corner to zoom in and out, fit the graph to the screen, or lock the view in place. If your mouse has a scroll wheel, you can also scroll to zoom in and out.
* Use the mini-map in the bottom-right corner to orient yourself and jump to another part of the graph.

### Choosing a relationship type

At the top-left of the page, use the view drop-down menu to switch between the three relationship types: Dependencies, Domains, and Teams. The available filters and display options change depending on which type you're viewing.

**Dependencies**

Visualize how entities relate to one another:

![The relationship graph showing dependencies.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-dependencies.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=03c7ca7c4f1347dbdada5098bf6c6d95)

**Domains**

See a hierarchical diagram of your software architecture:

![The relationship graph showing domains.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-domains.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=a2fdddf551902754f3b9ef841c15d81a)

**Teams**

View your org's team structure:

![The relationship graph showing teams.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-teams.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=b4f01ea7cff6f56814d7baed0cbd03ef)

### Searching and filtering the graph

**Searching**

Use the search bar at the top of the page to find and focus a single entity. Start typing an entity's name, then select it to center the graph on that entity and its connections.

![The search bar on the relationship graph](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-search.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=c9f3db331aed69346b5902fe3795cf09)

**Filtering**

> [!WARNING]
>
> If your graph has more than 500 nodes, you must apply a filter before the graph displays.

Filters are available in the Dependencies and Domains views. Click **Filters** in the upper-right corner of the page, then narrow the graph with any combination of:

* **Sources** - Limit the graph to entities from specific data sources.
* **Groups** - Limit the graph to entities in specific groups.
* **Entity types** - Limit the graph to specific entity types.
* **Degrees from selected node** - This is unlocked when you select an entity node. Once you've selected an entity node, set how many connection hops out from that entity to display.

The graph applies your selections and reloads automatically. Click **Reset display** to clear all filters.

![The filters option on the relationship graph.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-filters.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=138687030a57490d5a903c00cb2e8f8b)

### Choosing display options

Click **Display options** in the upper-right corner of the page to control how the graph is drawn. The options depend on which relationship type you're viewing.

![The display options on the relationship graph.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-display.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=e33affeb57dfae1467139cd93b02f7ea)

**In the Dependencies view**:

* **Show entity type icons** - Show or hide the icon on each node.
* **Show nodes without dependencies** - Show or hide entities that have no dependencies.
* **Scorecard** - Select a Scorecard to color and evaluate the graph against.

**In the Domains view**:

* **Show domain nodes without children** - Show or hide domains that contain no entities.
* **Show archived entities** - Include or exclude archived entities.
* **Scorecard** - Select a Scorecard to color and evaluate the graph against.

**In the Teams view**:

* **Show team nodes without children** - Show or hide teams that have no members or child teams.
* **Show archived entities** - Include or exclude archived entities.
* **Scorecard** - Select a Scorecard to color and evaluate the graph against.

Click **Reset display** to return to the default display options.

### Inspecting an entity

Click any node in the graph to open a quick-actions popup for that entity, where you can:

* **Filter by this node** - Refocus the graph on the selected entity. This also enables the **Degrees from selected node** filter so you can expand or contract how much of its network is shown.
* **Go to entity** - Open the entity's details page.

If the entity has dependencies or child entities, the popup also lists them. Click any item in the list to open that entity.

![A selected node with the quick-actions popup displayed.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-selected.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=ca2d5768ebce7d4a304bb6b8f900c57a)

### Sharing or syncing from the graph

Click the **overflow menu icon** in the upper-right corner of the page to:

* **Share** - Share the current graph view.
* **Sync dependencies** - Users with the `Enable Entity Dependency Discovery` permission can manually sync dependencies. Cortex automatically syncs AWS dependencies every day at 8:00 a.m. UTC. All other dependencies sync at 12:00 a.m. UTC.

![The overflow menu icon.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-overflow.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=0109c08c6f7f1f22e59b185459c63f28)

## Setting the default view

Users with the `Configure Settings` permission can set the default view of the relationship graph.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then click **Relationship graph**.

   ![The 'Relationship graph' tab in the Settings.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/rg-settings.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=4a32c444509184ed4fec70e4fea92afc)
4. Under **Select view**, choose which view (Dependencies, Domains, or Teams) opens by default when you navigate to the relationship graph.


# Managing Terraform infra in Cortex
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/terraform



Cortex Workflows can trigger Terraform execution to manage your cloud infrastructure, such as provisioning new services, databases, buckets, or networking primitives.

[Terraform](https://developer.hashicorp.com/terraform/intro) is an infrastructure-as-code tool that lets you provision, manage, and update infrastructure. Terraform can help you manage databases, s3 buckets, clusters, and every other component that comprises your infra. Terraform’s ability to manage resources comes from **providers**, which are plugins that enable interaction with cloud providers, SaaS providers, and other APIs. Providers allow you to define as code what a resource looks like.

The instructions on this page apply to [Terraform Cloud](https://developer.hashicorp.com/terraform/tutorials/cloud-get-started/cloud-sign-up), the web-based interface for Terraform.

> [!NOTE]
>
> Cortex integrates with Terraform in two different ways, depending on whether you want to manage Cortex resources using Terraform or use Cortex to drive Terraform runs for your infrastructure.
>
> To learn about managing Cortex resources using Terraform, see [Manage entities using Cortex Terraform Provider](/ingesting-data-into-cortex/entities-overview/entities/terraform/terraform-provider).

## How to manage Terraform infrastructure in Cortex

> [!TIP]
>
> See end-to-end examples for [using a Workflow to provision an EC2 instance with Terraform](/guides/production-readiness/terraform/provision), [using a Workflow to update the EC2 instance](/guides/production-readiness/terraform/update), and [using a Workflow to destroy a resource](/guides/production-readiness/terraform/destroy).

### Prerequisite

Expand the tile below for instructions on provisioning a new instance.

> **Provision a new instance and update the instance name**
>
> * Provision a new instance
>   * Terraform will automatically provide you with a starter workspace when you begin — our example workspace is named **"tfc-guide-example"**.
>
> ![Our example workspace is named 'tfc-guide-example'](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-1.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=0b89b0026e01f2b9d60e6f885e39ff38)
>
> * Update the instance name in the Terraform `variables.tf` file.
>   * All Terraform modules come with a file called `variables.tf`. As part of the Terraform script, we can enter variables for a given set, like region or instance type. In the example screen shot below, the variable name is "My Other Great Instance".
>
> ![The variable instance name is 'My other great instance.'](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-2.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=3972f60958caada58126bfc7df9c9de0)
>
> * Note: Terraform modules also come with a `main.tf` file, which contains instructions and information about the action. In our example, the `main.tf` file describes the instance that we’re going to create through Terraform.
>
>   ![Example of the main.tf file](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-3.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=511ffc2604da5204720ad71db60d27bb)
>
> > [!NOTE]
> >
> > Terraform stores a “state” about your infrastructure and configuration when it’s deployed. State maps resources to this configuration, and will update any time variables or properties are changed.

### Step 1: Confirm your instance name update in Terraform

In Terraform Cloud, navigate to the **Run** page. Verify that the changes you made to the instance name in `variables.tf` have applied.

![In Terraform, verify that your changes have applied.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-4.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=79066c43dacb3fd7852d13c6c74b701d)

In Terraform, there are two primary commands: `plan` and `apply`.

* The `plan` command creates a plan and preview of the changes that will be made to your infrastructure. During the plan stage, Terraform assesses the `main.tf` file with variables and compares it against the state. If there are differences, Terraform prompts you to approve and apply the change.
* When you navigate to the run that was triggered by updating `variables.tf`, you can see that the plan was automatically conducted. In this case, the plan was to create an instance with the name provided earlier. Verify that the run displays a "Plan finished" message.

![Terraform displays a 'Plan finished' message.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-5.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=8108b6c0802d0e583bcc5033429d8c1a)

In AWS, you can confirm that the instance exists and that the Terraform action was successful:

![AWS shows that the instance exists.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-6.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=6ca45b77c9eba307daa709dad5a34752)

> [!NOTE]
>
> In this example, we made direct modifications to the main branch, but typically, you will edit a separate branch and create a pull request. This approach will run a plan in Terraform, but will not automatically apply changes.

### Step 2: Add the Terraform template in Cortex

Cortex not only integrates with Terraform, but can enhance your use of it. Once the integration is set up, you’ll use a [Scaffolder step in a Workflow](/streamline/workflows#scaffolder) to interact with Terraform.

You must have the `Configure Scaffolder templates` permission.

> [!NOTE]
>
> When using the Scaffolder, it's best to edit a secondary branch and create a pull request — the Scaffolder will actually create the pull request for you, which someone else can approve to apply the changes.

1. Create a [Cookiecutter](https://www.cookiecutter.io/) JSON file that is equivalent to your Terraform module.
   * In this file, we defined the region and instance name. You’ll then update the fields in the `variables.tf` file so it knows to pull information from the Cookiecutter JSON.

     ![](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-7.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=0afa26994eb95ddd09dea9452abd5db5)
2. [Register your template](/streamline/workflows/scaffolder#step-2-add-the-template-to-cortex) in Cortex.
3. After you have added the template to Cortex, you can [create a Workflow](/streamline/workflows) that includes a [Scaffolder](/streamline/workflows#scaffolder) block using the template.
4. Run the Workflow. When you run it, Cortex will automatically open a pull request against the selected repository.

#### Verify that the process worked

> **Verify the process**
>
> To verify that the process worked, open Terraform Cloud and navigate to **Runs**.
>
> Any runs that originate from Cortex will have `[Cortex Scaffolder]` at the start of their name. Click into one of these runs to see its status and how many changes were proposed.
>
> ![A Cortex Scaffolder run shows as planned and finished in Terraform.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-9.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=55cabfb6d420610ed653c8ceae35c2dc)

## Execute a run via a Workflow

Terraform Cloud also has an API that can be used to make updates without following the pull request workflow. You can use a [Workflow](/streamline/workflows) in Cortex to execute a run through the API. If a run is set to automatically apply, then Cortex will handle the rest of the process.

1. [Create a Workflow](/streamline/workflows) in Cortex.
2. Add a [user input](/streamline/workflows#user-input) block.
   1. Define inputs for `Instance name`, `Region`, and `Instance type`.
3. Add an [HTTP request](/streamline/workflows#http-request) block. Configure the following fields:
   1. **HTTP method**: Select `POST`.
   2. **URL**: Enter the URL for the Terraform API you want to call.
   3. **Headers**: Add `Authorization: Bearer {{token}}` and `Content-type: application/(name)`.
   4. **Payload**: Build the payload by referencing the outputs of the "User input" block, e.g., `{{actions.input.outputs.instance-name}}`
4. Save the Workflow. After saving, click **Run** at the top of the Workflow to run it.

When the Workflow is run in Cortex, it will override data in the `variables.tf` file with information that was entered in the fields.

#### Verify the run

> **Verify that the action was successful**
>
> In Terraform Cloud, you can verify that the action was successful and the run was queued. Runs triggered by actions are named "Triggered via API."
>
> ![The run in Terraform is labeled 'Triggered via API.'](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-14.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=1d6c6c06dacf2145958f070c8acd8758)
>
> Once the run has been applied, you can also verify it in AWS. In the example screen shot below, the instance name has been changed:
>
> ![The instance is listed in AWS.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/terraform-15.jpeg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=6c21a1674a3ab7c64bfda5f24e868de9)

## Terraform Workflow examples

See guides on creating the following Workflows: [Provision EC2 instance with Terraform](/guides/production-readiness/terraform/provision), [Update EC2 instance](/guides/production-readiness/terraform/update), and [Terraform destroy](/guides/production-readiness/terraform/destroy).


# Manage entities using Cortex Terraform Provider
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/terraform/terraform-provider



The [Cortex Terraform Provider](https://github.com/cortexapps/terraform-provider-cortex) acts as a bridge between Terraform and the Cortex platform, allowing you to manage and provision Cortex resources (such as [Scorecards](/standardize/scorecards), [integrations](/ingesting-data-into-cortex/integrations), and [entities](/ingesting-data-into-cortex/entities-overview/entities)) using Terraform’s infrastructure-as-code approach. The provider is a wrapper around the public Cortex API and is maintained by the Cortex team, with shared ownership and ongoing support for customers who use it.

> [!NOTE]
>
> Cortex integrates with Terraform in two different ways, depending on whether you want to manage Cortex resources using Terraform, or use Cortex to drive Terraform runs for your infrastructure.
>
> To learn about using Cortex to drive Terraform runs, see [Managing Terraform infra in Cortex](/ingesting-data-into-cortex/entities-overview/entities/terraform/terraform-provider).

### Managing the catalog as code

Many Cortex customers manage their entire service catalog and engineering standards as code using the Cortex Terraform Provider.

Expand the tiles below for examples on how to handle different use cases with this approach.

> **Service catalog as code**
>
> **Goal:** Any time a new microservice or app is created (via a Terraform module, template repo, or platform workflow), it’s automatically added to the Cortex catalog with the right metadata and ownership.
>
> **How to do it:**
>
> * Use the `cortex_catalog_entity` resource to create and update services, libraries, or other catalog entities from Terraform.
> * Attach extra metadata with `cortex_catalog_entity_custom_data` – e.g. `tier`, `business_unit`, `cost_center`, “is\_internally\_facing”, etc.
> * Optionally define departments (e.g. “Payments”, “Growth”) with `cortex_department`, and link services/teams to those for reporting and ownership.

> **Scorecards and standards as code**
>
> **Goal**: Treat operational standards (SRE, security, compliance, production-readiness gates) as code that lives next to infrastructure, reviewed via PRs and rolled out safely.
>
> How to do it:
>
> * Define scorecards via the `cortex_scorecard` resource. It supports:
>   * a ladder (levels with names, colors, rank)
>   * rules (expressions, titles, weights, optional failure messages)
>   * an evaluation window (how often to evaluate, min every 4 hours)
>   * a filter to target specific entity types or groups
> * Use `cortex_resource_definition` to standardize external signals that Scorecards rely on (e.g. “has SLO in Datadog”, “has PagerDuty service”, “has runbook link”).
> * Manage changes to standards through Git review: PRs update the Terraform code, then Terraform updates the Cortex Scorecards and resources.

> **API contracts and org model as code**
>
> **Goal**: Ensure that API documentation and org metadata are always in sync, accurate, and consistent across environments.
>
> How to do it:
>
> * Use `cortex_catalog_entity_openapi` to attach OpenAPI specs (YAML/JSON) to catalog entities in Cortex, keyed by the entity’s tag/ID.
> * Keep department and ownership structure in Terraform via `cortex_department` and catalog entity custom data (e.g., `department`, `team`, `criticality`).
> * When infrastructure changes (e.g., new API version, team moves between org units), updating Terraform automatically pushes the new OpenAPI spec + org metadata into Cortex.

## Install the Terraform Provider for Cortex

For installation instructions, see the [repository's README in GitHub](https://github.com/cortexapps/terraform-provider-cortex).

### Examples

See [the repository for examples](https://github.com/cortexapps/terraform-provider-cortex/tree/main/examples).


# Defining entities with YAML
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/yaml



Every entity in your Cortex catalog is defined by a YAML file called the **Cortex entity descriptor**—often referred to as an entity's *Cortex YAML*, after the `cortex.yaml` filename used in the GitOps approach. This applies whether you manage entities through the UI or GitOps; the descriptor is the underlying source of truth either way.

Each descriptor is a fully compliant OpenAPI 3 spec file, extended with Cortex-specific fields that unlock additional functionality in your catalog.

> [!NOTE]
>
> You don't need to use OpenAPI or Swagger to use Cortex. The OpenAPI spec serves as the foundation for entity metadata because it's an open standard with official support for extensions, allowing Cortex to extend it into a full entity descriptor spec, while keeping the actual OpenAPI fields optional.

## Metadata in entity descriptor YAML files

You can extend an entity by adding metadata to the `info` section of its descriptor. Throughout the docs, you'll see snippets prefixed with `x-cortex-*`; these are descriptor blocks that belong inside `info` and unlock additional Cortex functionality.

> [!WARNING]
>
> Add every `x-cortex-*` block inside `info`, not at the root level of the file. Cortex doesn't read blocks outside `info`, and the linter doesn't flag them, so a misplaced block has no effect and no error explains why.
>
> **Correct example**, with the block nested under `info`:
>
> ```yaml theme={null}
> openapi: 3.0.1
> info:
>   title: Payments API
>   x-cortex-tag: payments-api
>   x-cortex-type: service
>   x-cortex-oncall:
>     datadog:
>       - type: SCHEDULE
>         id: ee409e39-5449-4eb8-900f-8bea9d2162d7
> ```
>
> **Incorrect example**, with the block at the root level below `info`:
>
> ```yaml theme={null}
> openapi: 3.0.1
> info:
>   title: Payments API
>   x-cortex-tag: payments-api
>   x-cortex-type: service
> x-cortex-oncall:
>   datadog:
>     - type: SCHEDULE
>       id: ee409e39-5449-4eb8-900f-8bea9d2162d7
> ```

> [!NOTE]
>
> YAML comments aren't supported in entity descriptors. Cortex stores descriptors as JSON in the database, and JSON doesn't support comments. Most YAML parsers also strip comments during round-tripping, so any comments added to a descriptor will be lost.

### Required blocks

Every entity YAML requires the following:

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Block</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`title`</td>
      <td>The name of the entity</td>
    </tr>

    <tr>
      <td>`x-cortex-tag`</td>
      <td>The [unique identifier for the entity](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag)</td>
    </tr>

    <tr>
      <td>`x-cortex-type`</td>
      <td>The [entity type](/ingesting-data-into-cortex/entities-overview#entity-types)\
      \
      • If the entity is a [custom type](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types/creating-custom-entities#adding-a-custom-entity-in-yaml-via-gitops), you must also include `x-cortex-definition`</td>
    </tr>
  </tbody>
</table>

### **Recommended blocks**

Although they aren't required, it's strongly recommended to add a description, groups, and owners:

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Block</th>
      <th>Definition</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`description`</td>
      <td>A description of the entity</td>
    </tr>

    <tr>
      <td>`x-cortex-groups`</td>
      <td>The entity's [groups](/ingesting-data-into-cortex/entities-overview/entities/groups) - a tagging system used to segment entities\
      \
      • Required field - `tag`</td>
    </tr>

    <tr>
      <td>`x-cortex-owners`</td>
      <td>The entity's [owners](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-an-entitys-yaml)\
      \
      • Required field(s) - `type`, which can be `group` or `email`\
      • For `group` owners, `name` and `provider` are also required. The `provider` value is the integration the group comes from; use `CORTEX` for a team defined in Cortex.\
      • For `email` owners, `email` is also required\
      • `inheritance` - When creating a domain entity and adding owners to it, or while creating an entity relationship, you can set [ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance) under this block to pass down to the entity's children. The inheritance type can be `APPEND`, `FALLBACK`, or `NONE`.</td>
    </tr>
  </tbody>
</table>

### **Additional basic metadata blocks**

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Block</th>
      <th>Definition</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`x-cortex-custom-metadata`</td>
      <td>The entity's [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data)\
      \
      • Required fields - a key, `value`, and `description`. The key is the title for the custom data.</td>
    </tr>

    <tr>
      <td>`x-cortex-dependency`</td>
      <td>The entity's [dependencies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies)\
      \
      • Required fields - `tag`. If `method` is included, then `path` is also required.</td>
    </tr>

    <tr>
      <td>`x-cortex-link`</td>
      <td>[Documentation links](/ingesting-data-into-cortex/entities-overview/entities/external-docs) associated with the entity: `name`, `type`, and `url`</td>
    </tr>

    <tr>
      <td>`x-cortex-parents` and\
      `x-cortex-children`</td>
      <td>The entity's parent entities and children entities\
      \
      • Required field - `tag`\
      • These fields are supported for entities that are members of a [hierarchical entity relationship](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types#understanding-relationship-types-in-cortex), such as domains or teams</td>
    </tr>

    <tr>
      <td>`x-cortex-relationships`</td>
      <td>A block that includes the entity's [relationship type and destination entities](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types/managing-relationships#creating-relationship-connections-via-an-entity-descriptor)\
      \
      • Required fields - `type` and `destinations`</td>
    </tr>

    <tr>
      <td>`x-cortex-team`</td>
      <td>This appears in a [team entity's YAML](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#adding-a-team-in-yaml-via-gitops). `members` can be defined under this block.\
      \
      • A `member` is defined by `name` and `email`, and can also include `notificationsEnabled` and `roles`.</td>
    </tr>
  </tbody>
</table>

### **Integration metadata blocks**

See the related linked documentation pages for instructions on adding metadata within each type of block.

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Block</th>

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`x-cortex-alerts`</td>
      <td>[Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie)</td>
    </tr>

    <tr>
      <td>`x-cortex-apiiro`</td>
      <td>[Apiiro](/ingesting-data-into-cortex/integrations/apiiro)</td>
    </tr>

    <tr>
      <td>`x-cortex-apm`</td>
      <td>[Datadog](/ingesting-data-into-cortex/integrations/datadog), [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace), [New Relic](/ingesting-data-into-cortex/integrations/newrelic)</td>
    </tr>

    <tr>
      <td>`x-cortex-azure`</td>
      <td>[Azure Resources](/ingesting-data-into-cortex/integrations/azureresources)</td>
    </tr>

    <tr>
      <td>`x-cortex-azure-devops`</td>
      <td>[Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)</td>
    </tr>

    <tr>
      <td>`x-cortex-bugsnag`</td>
      <td>[BugSnag](/ingesting-data-into-cortex/integrations/bugsnag)</td>
    </tr>

    <tr>
      <td>`x-cortex-ci-cd`</td>
      <td>[Buildkite](/ingesting-data-into-cortex/integrations/buildkite), [Harness](/ingesting-data-into-cortex/integrations/harness/importing-data-from-harness)</td>
    </tr>

    <tr>
      <td>`x-cortex-checkmarx`</td>
      <td>[Checkmarx](/ingesting-data-into-cortex/integrations/checkmarx)</td>
    </tr>

    <tr>
      <td>`x-cortex-circle-ci`</td>
      <td>[CircleCI](/ingesting-data-into-cortex/integrations/circleci)</td>
    </tr>

    <tr>
      <td>`x-cortex-coralogix`</td>
      <td>[Coralogix](/ingesting-data-into-cortex/integrations/coralogix)</td>
    </tr>

    <tr>
      <td>`x-cortex-dashboards`</td>
      <td>Charts embedded from [Datadog](/ingesting-data-into-cortex/integrations/datadog), [Grafana](/ingesting-data-into-cortex/integrations/grafana), or [New Relic](/ingesting-data-into-cortex/integrations/newrelic)</td>
    </tr>

    <tr>
      <td>`x-cortex-firehydrant`</td>
      <td>[FireHydrant](/ingesting-data-into-cortex/integrations/firehydrant)</td>
    </tr>

    <tr>
      <td>`x-cortex-git`</td>
      <td>[Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab)</td>
    </tr>

    <tr>
      <td>`x-cortex-incident-io`</td>
      <td>[incident.io](/ingesting-data-into-cortex/integrations/incidentio)</td>
    </tr>

    <tr>
      <td>`x-cortex-infra`</td>
      <td>[AWS](/ingesting-data-into-cortex/integrations/aws), [Google](/ingesting-data-into-cortex/integrations/google)</td>
    </tr>

    <tr>
      <td>`x-cortex-issues`</td>
      <td>[ClickUp](/ingesting-data-into-cortex/integrations/clickup), [GitHub](/ingesting-data-into-cortex/integrations/github), [Jira](/ingesting-data-into-cortex/integrations/jira)</td>
    </tr>

    <tr>
      <td>`x-cortex-k8s`</td>
      <td>[Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes)</td>
    </tr>

    <tr>
      <td>`x-cortex-launch-darkly`</td>
      <td>[LaunchDarkly](/ingesting-data-into-cortex/integrations/launchdarkly)</td>
    </tr>

    <tr>
      <td>`x-cortex-microsoft-teams`</td>
      <td>[Microsoft Teams channels](/ingesting-data-into-cortex/integrations/microsoftteams)</td>
    </tr>

    <tr>
      <td>`x-cortex-oncall`</td>
      <td>[PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty), [Rootly](/ingesting-data-into-cortex/integrations/rootly), [Splunk On-Call (VictorOps)](/ingesting-data-into-cortex/integrations/splunk-oncall), [xMatters](/ingesting-data-into-cortex/integrations/xmatters)</td>
    </tr>

    <tr>
      <td>`x-cortex-owners`</td>
      <td>When you specify `group` as the `type`, you can use the following integrations as the group `provider`: [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [Entra ID (Azure AD)](/ingesting-data-into-cortex/integrations/entraid), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Google](/ingesting-data-into-cortex/integrations/google), [Okta](/ingesting-data-into-cortex/integrations/okta), [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow), [Workday](/ingesting-data-into-cortex/integrations/workday)</td>
    </tr>

    <tr>
      <td>`x-cortex-rollbar`</td>
      <td>[Rollbar](/ingesting-data-into-cortex/integrations/rollbar)</td>
    </tr>

    <tr>
      <td>`x-cortex-rootly`</td>
      <td>[Rootly](/ingesting-data-into-cortex/integrations/rootly)</td>
    </tr>

    <tr>
      <td>`x-cortex-sentry`</td>
      <td>[Sentry](/ingesting-data-into-cortex/integrations/sentry)</td>
    </tr>

    <tr>
      <td>`x-cortex-semgrep`</td>
      <td>[Semgrep](/ingesting-data-into-cortex/integrations/semgrep)</td>
    </tr>

    <tr>
      <td>`x-cortex-servicenow`</td>
      <td>[ServiceNow](/ingesting-data-into-cortex/integrations/servicenow)</td>
    </tr>

    <tr>
      <td>`x-cortex-slack`</td>
      <td>[Slack channels](/ingesting-data-into-cortex/integrations/slack)</td>
    </tr>

    <tr>
      <td>`x-cortex-slos`</td>
      <td>[Datadog](/ingesting-data-into-cortex/integrations/datadog), [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace), [Google](/ingesting-data-into-cortex/integrations/google), [Lightstep](/ingesting-data-into-cortex/integrations/lightstep), [Prometheus](/ingesting-data-into-cortex/integrations/prometheus), [Splunk Observability Cloud (SignalFX)](/ingesting-data-into-cortex/integrations/splunk-observability), [Sumo Logic](/ingesting-data-into-cortex/integrations/sumologic)</td>
    </tr>

    <tr>
      <td>`x-cortex-snyk`</td>
      <td>[Snyk](/ingesting-data-into-cortex/integrations/snyk)</td>
    </tr>

    <tr>
      <td>`x-cortex-static-analysis`</td>
      <td>[Codecov](/ingesting-data-into-cortex/integrations/codecov), [Mend](/ingesting-data-into-cortex/integrations/mend), [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube), [Veracode](/ingesting-data-into-cortex/integrations/veracode)</td>
    </tr>

    <tr>
      <td>`x-cortex-wiz`</td>
      <td>[Wiz](/ingesting-data-into-cortex/integrations/wiz)</td>
    </tr>
  </tbody>
</table>

## Example entity YAML

The example below demonstrates how you can use each of the blocks in an entity's YAML.

```yaml theme={null}
## API Spec and Version
openapi: 3.0.0

# Service Descriptors
# Required fields: info, title, x-cortex-tag
info:
  title: Payments API
  x-cortex-tag: payments-api
  description: Handles payment processing, refunds, and transaction history for the Cortex platform.

  # Groups
  # !Groups must contain only alphanumeric characters, and may not contain whitespaces!
  x-cortex-groups:
    - backend
    - payments
    - us-west

  # Owners
  x-cortex-owners:
    - type: group
      name: platform-engineering
      provider: CORTEX # Use when referring to a team defined in Cortex; these teams do not map to identities from integrations
      description: Core platform team responsible for payments infrastructure
    - type: email
      email: backend-oncall@cortex.io
      description: On-call rotation for backend services
    - type: group
      name: cortexapps/backend-platform
      provider: ACTIVE_DIRECTORY | AZURE_DEVOPS | BAMBOO_HR | GITHUB | GITLAB | GOOGLE | OKTA | OPSGENIE | SERVICE_NOW | WORKDAY
  # Also see the team entity example below

  # Links
  x-cortex-link:
    - name: API Reference
      type: OPENAPI
      url: https://api.cortex.io/payments/openapi.yaml
      description: OpenAPI spec for the Payments API
    - name: Runbook
      type: DOCUMENTATION
      url: https://cortex.atlassian.net/wiki/spaces/ENG/pages/payments-api-runbook
      description: Operational runbook for incidents and deployments
  ## Note that type of OPENAPI/ASYNC_API will be displayed in the API Explorer tab in the Cortex UI
  ## Links support relative URLs

  # Dashboards
  x-cortex-dashboards:
    embeds:
      - type: datadog
        url: https://app.datadoghq.com/dashboard/abc-123-xyz/payments-api-overview

  # Custom Data
  x-cortex-custom-metadata:
    tier: tier-1
    language:
      value: go
      description: Primary implementation language
    pci-compliant:
      value: true
      description: Service is in scope for PCI DSS compliance
    on-call-schedule:
      - platform-engineering
      - backend-sre

  # Custom entities
  # You cannot create a custom entity type via GitOps, but after creating the type in the UI or API, you can create custom entities via GitOps.
  title: Alex Rivera
  description: Senior Platform Engineer
  x-cortex-tag: employee-alex-rivera
  x-cortex-type: org-employees
  x-cortex-definition:
    location: San Francisco
    department: Platform Engineering

  # Parent and child relationships
  x-cortex-type: team
  x-cortex-children:
    - tag: payments-frontend-team
    - tag: payments-backend-team

  x-cortex-type: domain
  x-cortex-parents:
    - tag: engineering-domain
    - tag: fintech-domain

  # Entity relationships
  x-cortex-relationships:
    - type: depends-on
      destinations:
        - tag: fraud-detection-service
        - tag: ledger-service

  # Dependencies
  # Required fields: x-cortex-tag, method (required if path present), path (required if method present)
  x-cortex-dependency:
    - tag: fraud-detection-service
      method: POST
      path: /v1/evaluate
      description: Evaluates transactions for fraud signals before processing
      metadata:
        tags:
          - payments
          - fraud
        prod: true

# Team configurations
title: Platform Engineering
x-cortex-tag: platform-engineering
x-cortex-type: team
x-cortex-team:
  groups:
    - name: platform-engineering
      provider: OKTA
  members:
    - name: Jordan Lee
      email: jordan.lee@cortex.io
      notificationsEnabled: true
    - name: Samantha Dawson
      email: samantha.dawson@cortex.io
      notificationsEnabled: false
x-cortex-children:
  - tag: infra-team
  - tag: sre-team

# Domain configurations
x-cortex-type: domain
x-cortex-owners:
  - type: group
    name: cortexapps/engineering
    provider: GITHUB
    inheritance: APPEND | FALLBACK | NONE
x-cortex-children:
  - tag: payments-api
  - tag: payments-database

# Integrations

# Apiiro
x-cortex-apiiro:
  repositories:
    - alias: payments-api
      repositoryId: cortexapps-payments-api
    - alias: payments-worker
      repositoryId: cortexapps-payments-worker
  applications:
    - alias: payments-api-app
      applicationId: app-payments-api-prod
    - alias: payments-worker-app
      applicationId: app-payments-worker-prod

# AWS Cloud Control types
x-cortex-infra:
  aws:
    cloudControl:
      - type: AWS::RDS::DBInstance
        region: us-west-2
        accountId: "123456789012"
        identifier: payments-db-prod

# AWS ECS
x-cortex-infra:
  aws:
    ecs:
      - clusterArn: arn:aws:ecs:us-west-2:123456789012:cluster/prod-cluster
        serviceArn: arn:aws:ecs:us-west-2:123456789012:service/prod-cluster/payments-api
      - clusterArn: arn:aws:ecs:us-east-1:123456789012:cluster/prod-cluster-east
        serviceArn: arn:aws:ecs:us-east-1:123456789012:service/prod-cluster-east/payments-api

# Azure DevOps
x-cortex-git:
  azure:
    project: cortex-platform
    repository: payments-api

# Azure Resources
x-cortex-azure:
  ids:
    - id: /subscriptions/1fbb2da1-2ce7-45e4-b85f-676ab8e12345/resourceGroups/payments-prod/providers/Microsoft.Compute/disks/payments-db-disk
      alias: payments-prod-disk # alias is optional and only relevant if you have opted into multi account support
    - id: /subscriptions/1fbb2da1-2ce8-45e4-b85f-676ab8e12345/resourceGroups/payments-staging/providers/Microsoft.Compute/disks/payments-db-disk-staging
      alias: payments-staging-disk # alias is optional and only relevant if you have opted into multi account support

# BambooHR
x-cortex-owners:
  - type: group
    name: Platform Engineering
    provider: BAMBOO_HR
    description: # optional

# Bitbucket
x-cortex-git:
  bitbucket:
    repository: cortexapps/payments-api
x-cortex-owners:
  - type: group
    name: platform-engineering
    provider: BITBUCKET
    description: # optional

# Bugsnag
x-cortex-bugsnag:
  project: payments-api-prod

# Buildkite and Harness
x-cortex-ci-cd:
  buildkite:
    pipelines:
      - slug: payments-api-build
      - slug: payments-api-deploy
    tags:
      - tag: payments
      - tag: backend
  harness:
    services:
      - orgIdentifier: default
        projectIdentifier: payments
        identifier: paymentsapi

# Checkmarx
x-cortex-checkmarx:
  projects:
    - projectName: payments-api
    - projectId: 8821

# CircleCI
x-cortex-circle-ci:
  projects:
    - projectSlug: gh/cortexapps/payments-api
      alias: payments-api-circleci # alias is optional and only relevant if you have opted into multi account support

# ClickUp
x-cortex-issues:
  clickup:
    spaces:
      - identifier: 987654321
        identifierType: ID
    folders:
      - identifier: Platform Engineering
        identifierType: NAME
    tags:
      - name: payments
      - name: backend

# Codecov
x-cortex-static-analysis:
  codecov:
    owner: cortexapps
    repo: payments-api
    provider: AZURE_DEVOPS | BITBUCKET | BITBUCKET_SERVER | GITHUB | GITHUB_ENTERPRISE | GITLAB | GITLAB_ENTERPRISE
    flag: unit

# Coralogix
x-cortex-coralogix:
  applications:
    - applicationName: payments-api
      alias: payments-prod # alias is optional and only relevant if you have opted into multi account support
    - applicationName: payments-worker
      alias: payments-worker-prod # alias is optional and only relevant if you have opted into multi account support

# Datadog
x-cortex-apm:
  datadog:
    serviceTags: # List of tags & values
      - tag: service
        value: payments-api
      - tag: env
        value: prod
    serviceName: payments-api
    monitors:
      - 12345678
      - 12345679
x-cortex-slos:
  datadog: # List of SLO ids
    - id: abc123def456ghi7
    - id: xyz789uvw012rst3

# Dynatrace
x-cortex-apm:
  dynatrace:
    entityIds:
      - SERVICE-A1B2C3D4E5F60001
      - SERVICE-A1B2C3D4E5F60002
    entityNameMatchers:
      - "payments.*"
x-cortex-slos:
  dynatrace:
    - id: slo-payments-availability
    - id: slo-payments-latency

# Entra ID (Azure Active Directory)
x-cortex-owners:
  - type: group
    name: platform-engineering
    provider: ACTIVE_DIRECTORY
    description: # optional

# FireHydrant
x-cortex-firehydrant:
  services:
    - identifier: PYMT1234
      identifierType: ID
    - identifier: payments-api
      identifierType: SLUG

# GitHub
x-cortex-git:
  github:
    repository: cortexapps/payments-api
    basepath: payments-api # optional
x-cortex-owners:
  - type: group
    name: cortexapps/backend-platform # Must be of form <org>/<team>
    provider: GITHUB
    description: Backend platform team

# GitLab
x-cortex-git:
  gitlab:
    repository: cortexapps/platform/payments-api
    basepath: payments-api # optional
x-cortex-owners:
  - type: group
    name: Platform Engineering
    provider: GITLAB
    description: Core platform team for payments infrastructure

# Google
x-cortex-owners:
  - type: group
    name: platform-engineering@cortex.io
    provider: GOOGLE
x-cortex-dependency:
  gcp:
    labels:
      - key: service
        value: payments-api
      - key: env
        value: prod
x-cortex-infra:
  Google Cloud:
    resources:
      - resourceName: us-central1/payments-processor-fn
        projectId: cortex-platform-prod
        resourceType: function
      - resourceName: payments-assets-prod
        projectId: cortex-platform-prod
        resourceType: storage
x-cortex-slos:
  gcp:
    - projectId: cortex-platform-prod
      serviceId: iLE2e4HvR_PaymentsAPI01
    - projectId: cortex-platform-prod
      serviceId: iLE2e4HvR_PaymentsWorker01

# Grafana
x-cortex-dashboards:
  embeds:
    - type: grafana
      url: https://grafana.cortex.io/d/abcd1234/payments-api-overview

# incident.io
x-cortex-incident-io:
  customFields:
    - name: Service
      value: Payments API
      alias: payments-prod
    - id: payments-worker-id
      value: payments-worker
      alias: payments-worker-prod

# Jira
x-cortex-issues:
  jira:
    labels:
      - payments
      - backend
    components:
      - api-gateway
    projects:
      - PLAT
      - PAY
    # Optional: Override Cortex default Jira query
    defaultJql: 'project = PAY AND status = "In Progress" AND labels = "payments"'

# Kubernetes
x-cortex-k8s:
  deployment:
    - identifier: payments/payments-api
      cluster: prod-us-west-2 # optional
    - identifier: payments/payments-api
      cluster: staging
    - identifier: default/payments-api
      cluster: prod-us-east-1
  argorollout:
    - identifier: payments/payments-api-canary
      cluster: prod-us-west-2
  statefulset:
    - identifier: payments/payments-db-replica
      cluster: prod-us-west-2
  cronjob:
    - identifier: payments/payments-reconciler
      cluster: prod-us-west-2

# LaunchDarkly
x-cortex-launch-darkly:
  projects:
    - key: payments-platform
      environments: # Optional
        - environmentName: prod
        - environmentName: staging
      alias: payments-ld-prod # alias is optional and only relevant if you have opted into multi account support
    - tag: backend-services
      environments: # Optional
        - environmentName: prod
      alias: backend-ld-prod # alias is optional and only relevant if you have opted into multi account support
  feature-flags:
    - tag: payments-rollout
      environments: # Optional
        - environmentName: staging
      alias: payments-flags-staging # alias is optional and only relevant if you have opted into multi account support

# Lightstep
x-cortex-slos:
  lightstep:
    - streamId: AbCdEfGhIjKlMnOp
      targets:
        latency:
          - percentile: 0.99
            target: 200
            slo: 0.999

# Mend
x-cortex-static-analysis:
  mend:
    applicationIds:
      - payments-api-mend
      - payments-worker-mend
    projectIds:
      - cortexapps_payments-api
      - cortexapps_payments-worker

# Microsoft Teams
x-cortex-microsoft-teams:
  channels:
    - name: payments-engineering
      teamName: Platform Engineering
      description: Channel for payments engineering discussions and alerts.
      notificationsEnabled: true

# New Relic
x-cortex-apm:
  newrelic:
    applications:
      - applicationId: 987654321
        alias: payments-api-prod
    tags:
      - tag: service
        value: payments-api
        alias: payments-api-prod
x-cortex-dashboards:
  embeds:
    - type: newrelic
      url: https://one.newrelic.com/dashboards/abc123def456-payments-api

# While the `applications` wrapper format is the recommended format, Cortex also supports a flat array format:
# x-cortex-apm:
#   newrelic:
#     - applicationId: 987654321

# Okta
x-cortex-owners:
  - type: group
    name: platform-engineering # group name in Okta
    provider: OKTA
    description: # optional

# OpsGenie
x-cortex-oncall:
  opsgenie:
    type: SCHEDULE
    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 # Optionally, can use the Rotation UUID instead
x-cortex-owners:
  - type: group
    name: platform-engineering
    provider: OPSGENIE
    description: # optional
x-cortex-alerts:
  - type: opsgenie
    tag: service
    value: payments-api

# PagerDuty
x-cortex-oncall:
  pagerduty:
    id: P1A2B3C # Service ID
    type: SERVICE
x-cortex-oncall:
  pagerduty:
    id: S4D5E6F # Schedule ID
    type: SCHEDULE
x-cortex-oncall:
  pagerduty:
    id: E7G8H9I # Escalation Policy ID
    type: ESCALATION_POLICY

# Prometheus
x-cortex-slos:
  prometheus:
    - errorQuery: sum(rate(http_requests_total{service="payments-api",status=~"5.."}[5m]))
      totalQuery: sum(rate(http_requests_total{service="payments-api"}[5m]))
      slo: 0.999
      alias: payments-prometheus
      name: payments-api-availability

# Rollbar
x-cortex-rollbar:
  project: payments-api

# Rootly
x-cortex-rootly:
  services:
    - id: PYMT5678
    - slug: payments-api
x-cortex-oncall:
  rootly:
    - type: TEAM
      id: 3f2c9a7e-1b4d-4e8a-9c6f-2d5b8e1a7c40

# Sentry
x-cortex-sentry:
  projects:
    - name: payments-api
    - name: payments-worker

# Semgrep
x-cortex-semgrep:
  projects:
    - alias: cortexapps
      projectId: 1122334
    - alias: cortexapps-oss
      projectId: 4433221

# ServiceNow
x-cortex-servicenow:
  services:
    - tableName: cortex-platform-services
      id: 42
x-cortex-owners:
  - type: group
    name: Platform Engineering
    provider: SERVICE_NOW
    description: Primary team responsible for payments infrastructure # optional

# Slack
x-cortex-slack:
  channels:
    - id: C04ABCDE123
      notificationsEnabled: true
      description: Payments team channel for engineering discussions
    - name: payments-alerts
      notificationsEnabled: true
      description: Automated alerts channel for the Payments API

# Snyk
x-cortex-snyk:
  projects:
    - organizationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      projectId: f0e9d8c7-b6a5-4321-fedc-ba9876543210
      source: CODE

# SonarQube
x-cortex-static-analysis:
  sonarqube:
    project: cortexapps_payments-api
    alias: payments-sonar

# Splunk Observability Cloud (SignalFX)
x-cortex-slos:
  signalfx:
    - query: 'sf_metric:"request.latency" AND service:"payments-api"'
      rollup: AVERAGE
      target: 200
      lookback: 3600000
      operation: BELOW

# Splunk On-Call (VictorOps)
x-cortex-oncall:
  victorops:
    type: SCHEDULE
    id: platform-engineering-24x7

# Sumo Logic
x-cortex-slos:
  sumologic:
    - id: 000000000001001
    - id: 000000000001002

# Veracode
x-cortex-static-analysis:
  veracode:
    applicationNames:
      - Payments API
      - Payments Worker
    sandboxes:
      - applicationName: Payments API
        sandboxName: payments-api-staging
      - applicationName: Payments Worker
        sandboxName: payments-worker-staging

# Wiz
x-cortex-wiz:
  projects:
    - projectId: 9a8b7c6d-e5f4-3210-abcd-ef1234567890

# Workday
x-cortex-owners:
  - type: group
    name: platform-engineering
    provider: CORTEX
    description: Platform Engineering team in Workday org structure

# xMatters
x-cortex-oncall:
  xmatters:
    id: platform-engineering-oncall
    type: SERVICE
```


# YAML linter tool
Source: https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/yaml/linter



The Cortex YAML linter validates your `cortex.yaml` files against both general YAML syntax and Cortex-specific schema requirements, catching invalid or incomplete entity definitions before they reach the platform.

This page covers the built-in tool available in the Cortex UI under **Tools > YAML Linter**. A separate linter is also built into the Cortex GitHub app, which runs checks on pull requests when you use GitHub in a [GitOps workflow](/configure/gitops).

## Using the YAML linter

### Validating a YAML file in the Cortex UI

1. From the main sidebar, expand **Tools**, then select **YAML linter**.

   ![The YAML linter tool displayed in the Cortex UI.](https://mintcdn.com/cortex-290c0c42/Rc9VK2OZxA5RHuut/images/yaml-linter-tool.png?fit=max\&auto=format\&n=Rc9VK2OZxA5RHuut\&q=85\&s=3610b4b6978f5566a65c32cbf0d49c4f)
2. Paste your YAML into the text editor, then click **Validate YAML**.
3. A status banner appears at the bottom of the page:
   * If the format is valid, a success message is displayed:

     ![YAML success message and icon.](https://mintcdn.com/cortex-290c0c42/qRY2zZcIyXqFVeCq/images/Screenshot%202025-10-08%20at%201.33.04%E2%80%AFPM.png?fit=max\&auto=format\&n=qRY2zZcIyXqFVeCq\&q=85\&s=f5de80ea8d74568975c118361cb9d511)
   * If the format is incorrect:
     * For issues with the format of a Cortex-specific block, a warning banner appears:

       ![The linter warning banner indicates that x-cortex-apm has an empty value in the YAML file.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/linter-warning-banner.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=7baed1419e45c716ac416ce36a588081)
     * For errors that cause the YAML to fail the linter check (such as missing a `title` or `x-cortex-tag`), a failure banner that includes the error message and which line is affected appears:

       ![YAML fail message and icon.](https://mintcdn.com/cortex-290c0c42/Rc9VK2OZxA5RHuut/images/yaml-invalid-error.jpg?fit=max\&auto=format\&n=Rc9VK2OZxA5RHuut\&q=85\&s=15b70f87bfcfc51b48e9fe4dbac43392)

### Validation scope

The linter checks for valid YAML structure and ensures required Cortex fields (like `openapi` version, `x-cortex-tag`, etc.) are present. If a required field is not present, this results in an error and the YAML does not pass the linter check.

The linter also validates the format of Cortex-specific blocks (e.g., `x-cortex-groups`, `x-cortex-firehydrant`) but does not verify the correctness of referenced data (such as whether a group or monitor ID actually exists). If there is an issue for a Cortex block, such as a block that doesn't contain a value, you will see a warning; however, the YAML will still pass the linter check.

If you submit a file with templating syntax (e.g., Jinja or cookiecutter variables like `{{ variable }}`), the linter will fail because these are not valid YAML until rendered. Only fully rendered YAML files will pass validation.

If the YAML is invalid or missing required fields, the linter will return errors indicating the line and nature of the problem.

### GitOps settings for the linter tool

If you are using GitHub in a GitOps workflow, you can adjust settings related to the linter. See [GitOps Settings](/configure/settings/gitops-settings) for more information.


# Integrations
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations



**Seamlessly connect your entire stack**

Cortex supports a broad set of [third-party](/ingesting-data-into-cortex/integrations#third-party-integrations), [internally hosted](/ingesting-data-into-cortex/integrations#internally-hosted-integrations), and [custom webhook](/ingesting-data-into-cortex/integrations#custom-webhook-integrations) integrations designed to meet your engineering organization where it already works. Whether you're connecting source control, CI/CD pipelines, incident management tools, or cloud infrastructure providers, Cortex fits into your existing workflows without significant setup overhead or custom development.

**Key Benefits**

* **Centralized data synchronization**. Aggregate data from across your toolchain into a single, unified view. Eliminate the need for manual data collection and reduce the risk of fragmented or inconsistent reporting.
* **Flexibility at scale**. Cortex supports organizations of all sizes, offering both out-of-the-box integrations and extensible configurations for teams with more specialized tooling requirements.
* **Minimal operational overhead**. Once configured, integrations run continuously in the background, keeping your platform data fresh and reliable without ongoing maintenance from your team.
* **Secure and compliant by design**. All integration connections are established using industry-standard authentication protocols, ensuring your data is transmitted and stored in accordance with your organization's security requirements.

![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/new-integration-page.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=1347c6fab5132d3514ea51526ceb8057)

Users can view the Integrations page to check which integrations are configured and monitor their health status. To install, uninstall, or modify integrations, users must have the `Configure Integrations` permission.

> [!NOTE]
>
> Integration sync times vary and are subject to scheduling overrides and timing variance.

## Third-party integrations

Cortex connects to each tool via its official API, pulling live data directly from your systems. When viewing an entity, the information displayed reflects the current state of your tools—no manual syncing or stale data to manage.

Cortex integrates with tools across the core domains of engineering operations, including:

### Essentials

> **Version control**
>
> * [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
> * [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket)
> * [GitHub](/ingesting-data-into-cortex/integrations/github)
> * [GitLab](/ingesting-data-into-cortex/integrations/gitlab)

> **Team/Ownership**
>
> * [AWS](/ingesting-data-into-cortex/integrations/aws)
> * [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
> * [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources)
> * [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr)
> * [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket)
> * [Entra ID (formerly Azure Active Directory)](/ingesting-data-into-cortex/integrations/entraid)
> * [GitHub](/ingesting-data-into-cortex/integrations/github)
> * [GitLab](/ingesting-data-into-cortex/integrations/gitlab)
> * [Google](/ingesting-data-into-cortex/integrations/google)
> * [Okta](/ingesting-data-into-cortex/integrations/okta)
> * [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie)
> * [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow)
> * [Workday](/ingesting-data-into-cortex/integrations/workday)
>
> To compare what each source syncs and when, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

> **On-call**
>
> * [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty)
> * [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie)
> * [Splunk On-Call (formerly VictorOps)](/ingesting-data-into-cortex/integrations/splunk-oncall)
> * [xMatters](/ingesting-data-into-cortex/integrations/xmatters)

> **Project management**
>
> * [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
> * [ClickUp](/ingesting-data-into-cortex/integrations/clickup)
> * [GitHub](/ingesting-data-into-cortex/integrations/github)
> * [GitLab](/ingesting-data-into-cortex/integrations/gitlab)
> * [Jira](/ingesting-data-into-cortex/integrations/jira)

> **Communication**
>
> * [Slack](/ingesting-data-into-cortex/integrations/slack)
> * [Microsoft Teams](/ingesting-data-into-cortex/integrations/microsoftteams)

> **Code quality**
>
> * [Codecov](/ingesting-data-into-cortex/integrations/codecov)
> * [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube)

### Extended

> **CI/CD**
>
> * [ArgoCD](/ingesting-data-into-cortex/integrations/argocd)
> * [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
> * [Buildkite](/ingesting-data-into-cortex/integrations/buildkite)
> * [CircleCI](/ingesting-data-into-cortex/integrations/circleci)
> * [GitHub](/ingesting-data-into-cortex/integrations/github)
> * [Jenkins](/ingesting-data-into-cortex/integrations/jenkins)
>
> You can also use Cortex's [deploys API](/api/rest/deploys) to send deployment data from other services to Cortex.

> **Cloud**
>
> * [AWS](/ingesting-data-into-cortex/integrations/aws)
> * [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources)
> * [Google](/ingesting-data-into-cortex/integrations/google)
> * [Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes)
> * [Syntasso Kratix Enterprise (SKE)](/ingesting-data-into-cortex/integrations/syntasso)

> **Error tracking**
>
> * [BugSnag](/ingesting-data-into-cortex/integrations/bugsnag)
> * [Rollbar](/ingesting-data-into-cortex/integrations/rollbar)
> * [Sentry](/ingesting-data-into-cortex/integrations/sentry)

> **Feature flags**
>
> * [LaunchDarkly](/ingesting-data-into-cortex/integrations/launchdarkly)

> **Incidents**
>
> * [FireHydrant](/ingesting-data-into-cortex/integrations/firehydrant)
> * [Incident.io](/ingesting-data-into-cortex/integrations/incidentio)
> * [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty)
> * [Rootly](/ingesting-data-into-cortex/integrations/rootly)

> **Observability**
>
> * [Coralogix](/ingesting-data-into-cortex/integrations/coralogix)
> * [Datadog](/ingesting-data-into-cortex/integrations/datadog)
> * [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace)
> * [Google Observability Cloud](/ingesting-data-into-cortex/integrations/google)
> * [Instana](/ingesting-data-into-cortex/integrations/instana)
> * [New Relic](/ingesting-data-into-cortex/integrations/newrelic)
> * [Prometheus](/ingesting-data-into-cortex/integrations/prometheus)
> * [ServiceNow Cloud Observability (formerly Lightstep)](/ingesting-data-into-cortex/integrations/lightstep)
> * [Splunk Observability Cloud (formerly SignalFX)](/ingesting-data-into-cortex/integrations/splunk-observability)
> * [Sumo Logic](/ingesting-data-into-cortex/integrations/sumologic)

> **Security**
>
> * [Apiiro](/ingesting-data-into-cortex/integrations/apiiro)
> * [Checkmarx](/ingesting-data-into-cortex/integrations/checkmarx)
> * [GitHub](/ingesting-data-into-cortex/integrations/github)
> * [GitLab](/ingesting-data-into-cortex/integrations/gitlab)
> * [Mend](/ingesting-data-into-cortex/integrations/mend)
> * [Semgrep](/ingesting-data-into-cortex/integrations/semgrep)
> * [Snyk](/ingesting-data-into-cortex/integrations/snyk)
> * [Veracode](/ingesting-data-into-cortex/integrations/veracode)
> * [Wiz](/ingesting-data-into-cortex/integrations/wiz)

> **ITSM**
>
> * [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow)

## Configuring third-party integrations

Cortex integrates with a wide range of third-party tools to surface relevant data across your workspace.

### **Adding an integration**

Users with the `Configure Integrations` permission can install integrations.

1. From the main sidebar, select **Integrations**.
2. Locate the integration you want to set up, then click **Install**.

Specific configuration steps and required credentials vary by integration.

### Integration categories

Some integrations can bring in more than one type of data, such as monitors, incidents, and on-call schedules. When you configure one of these integrations, use the **Category** dropdown to choose which types of data Cortex imports from that configuration. You must select at least one category.

Cortex only imports data for the categories you select. If an integration is connected but its incident or on-call data doesn't appear on entity pages, check that the matching category is selected on the configuration.

#### Changing categories on an existing configuration

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate the integration, then click **Settings**.
3. Find the configuration you want to edit, then click the **pencil icon**.
4. From the **Configuration details** side panel, select or remove a category from the **Category** dropdown.
5. Click **Save**.

### **Modifying an integration configuration**

You can edit an existing configuration directly, including credentials, without deleting and re-adding it. This applies to both single and multi-configuration integrations.

Users with the `Configure Integrations` permission can modify integrations.

> [!NOTE]
>
> **The following third-party configurations cannot be modified**
>
> OAuth-based configurations cannot be directly modified. To make changes, you'll need to delete and re-install the integration, since setup requires a third-party redirect. This applies to: Bitbucket Atlassian App, GitHub App, Kubernetes (which uses its own unique flow), Microsoft Teams, and Slack.
>
> Additionally, configuration management isn't available for ArgoCD, Grafana, Humanitec, and Syntasso.

1. From the main sidebar, select **Integrations**.
2. Locate the integration you want to edit, then click **Settings**.
3. Find the configuration you want to edit, then click the **pencil icon**.
4. Make your changes, then click **Save**.

**A note about deleting and re-installing integrations**

If your third-party integration can't be modified in Cortex, you'll need to delete and re-install it.

Helpful tips include:

* Use the same alias name. Delete the old integration configuration in Cortex and re-install using the same alias, e.g. `cortex-github`.
* If you had multiple configurations for this integration, and the integration with the expired key was set as the default, set the new configuration as the default. This helps avoid disruptions to dependent workflows or entities, as entities will fall back to the default configuration if their YAML file references an alias that doesn't exist.
* Monitor the new integration configuration.

### **Removing an integration configuration**

Users with the `Configure Integrations` permission can remove an integration configuration.

1. From the main sidebar, select **Integrations**.
2. Locate the integration you want to remove, then click **Settings**.
3. Find the configuration you want to edit, then click the **trash icon**.

   The **Confirm configuration removal** window opens.
4. Click **Delete**.

### **Managing integrations via the API**

You can also manage integration configurations programmatically using the Cortex API which is useful for codifying integration setup, syncing configurations across environments, or automating credential rotation.

The API supports listing, creating, updating, and deleting configurations for the following integrations:

* AWS, Azure DevOps, Azure Resources, Bitbucket, Buildkite, CircleCI, Coralogix, Datadog, Entra ID, GitHub, GitLab, incident.io, Jira, LaunchDarkly, Mend, New Relic, PagerDuty, Prometheus, Semgrep, SonarQube, and Wiz.

For all other integrations—including OAuth-based ones like the GitHub App, Bitbucket Atlassian App, Microsoft Teams, and Slack—use the UI to install and configure.

See the [Cortex API reference](/api/rest/integrations) for endpoint details and authentication.

## Internally hosted integrations

If your tooling is hosted within your own infrastructure rather than the cloud, Cortex can still connect to it. Internally hosted integrations allow you to source data from systems running behind your firewall or private network and reflect that data in Cortex, giving you the same visibility and platform functionality without requiring your tools to be publicly accessible.

**Example use case**

If your team runs tools like GitLab, Jenkins, or Jira on private infrastructure rather than in the cloud, or relies on proprietary internal tooling for tracking services, deployments, or ownership, internally hosted integrations allow Cortex to pull in that data without requiring those systems to be publicly accessible.

See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for more information.

## Custom webhook integrations

Custom webhook integrations allow you to send data to Cortex from virtually any source, including internal tooling or systems that don't have a native Cortex integration. Each webhook generates a unique URL that accepts arbitrary JSON payloads via `POST`—no authentication headers or Cortex entity tags required. This makes custom webhooks a flexible option for teams that need to pipe in data from homegrown tools, scripts, or automated workflows that fall outside Cortex's standard integration offerings.

**Example use case**

If your team uses an internal deployment tool that isn't supported as a native integration, you can configure it to `POST` deployment events directly to your custom webhook URL, making that data available within Cortex without any additional middleware.

See [Custom webhook integrations](/ingesting-data-into-cortex/integrations/webhook) for more information.

## SSO integrations for Cortex workspace access

Single sign-on (SSO) allows users to authenticate with Cortex using the same credentials they already use across your organization's other tools and systems. Rather than managing a separate set of login credentials, users sign in once through your identity provider—such as Okta, Google, or Microsoft Entra ID—and gain access automatically. For organizations with strict security or compliance requirements, SSO also provides centralized control over user access, making it easier to provision and deprovision accounts as team members join or leave.

Cortex supports the following SSO integrations:

* [Microsoft Entra ID](/configure/settings/managing-users/configuring-sso/entraid)
* [Google](/configure/settings/managing-users/configuring-sso/google)
* [Okta](/configure/settings/managing-users/configuring-sso/okta)
* [Other OIDC providers](/configure/settings/managing-users/configuring-sso/oidc)

## SCIM integrations for provisioning users

System for Cross-domain Identity Management (SCIM) is an open standard protocol that automates the exchange of user identity information between an identity provider (IdP)—such as Microsoft Entra ID or Okta—and a target application like Cortex. It defines a standard schema and REST API for creating, updating, and deprovisioning user accounts, eliminating the need for manual account management.

Cortex supports the following SCIM integrations:

* [Microsoft Entra ID](/configure/settings/managing-users/scim/entraid-scim)
* [Okta](/configure/settings/managing-users/scim/okta-scim)

See [Provisioning users with SCIM](/configure/settings/managing-users/scim/provisioning-users-with-scim) for more information.

## Integration rate limiting

Cortex has built a distributed self-throttling system to ensure that certain functionality, such as CQL evaluations or background syncs to pull data from integrations, are not going over the rate limit thresholds for specific vendors. It handles different rate limit thresholds for different APIs within the same integration, which is common for git APIs such as Bitbucket.

The system is designed to proactively throttle before hitting a 429 from the vendor, and it works regardless of how many evaluators are trying to access that integration. Note that this system does not track other requests with the same token or undocumented limits set by vendors.

## Troubleshooting with integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, click the **Error Logs** tab to view error logs from the last 7 days. You can filter the logs list by configuration, by entity to see only the errors affecting a specific entity, and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![Click the Error Logs tab on an integration to view integration logs and errors.](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/int-logs-filter.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=b6b080c83e75b00a094c5ae9bf37ff1f)

Click into a log to get more information, including time stamp, status code, full error, and request path.


# Apiiro
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/apiiro



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to configure the integration for Apiiro. For instructions on connecting Apiiro to entities, see [Connecting entities to Apiiro](/ingesting-data-into-cortex/integrations/apiiro/connecting-entities-to-apiiro). For information on how to use the integration, see [Using the integration for Apiiro](/ingesting-data-into-cortex/integrations/apiiro/using-the-integration-for-apiiro).

## Why use the integration for Apiiro

Apiiro is an application security posture management (ASPM) platform that surfaces risks across your applications and repositories. On its own, Apiiro tells you what is at risk. Connecting it to Cortex tells you *who* owns it and whether it meets your standards.

* **Connect risks to owners**. Cortex maps Apiiro repositories and applications to your entities, so every risk is tied to a service and the team that owns it.
* **Put security context where engineers work**. Risks appear on entity pages, grouped by severity, next to the rest of a service's operational data. Developers don't need to switch tools to see what needs attention.
* **Turn security goals into measurable standards**. Use Scorecards to define rules, such as no open critical risks or every service registered in Apiiro, and track compliance across your catalog.
* **Prioritize by severity**. Grouping risks as critical, high, medium, and low helps teams focus on the issues that matter most first.

## Configuring Apiiro

### Prerequisites

1. Users with the `Configure Integrations` permission can configure Apiiro.
2. In Apiiro, create an [API key](https://docs.apiiro.com/admin-apiiro/access-tokens). Include the following permissions:
   * `Risks > Read`
   * `Inventory management > Applications > Read`
   * `Inventory management > Repositories > Read`

### Configuring the integration in Cortex

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Apiiro, then click **Install**. The Apiiro side panel opens.
   > [!TIP]
   >
   > To add another configuration (for example, for a second Apiiro instance), click **Settings**, then click **Add configuration**.
3. In the Apiiro side panel, do the following:
   * From the **Category** dropdown, select the types of data to import from Apiiro (required). The category field is set to **Security** by default.
   * Under **Alias**, enter the alias you'll use in the `alias` field of an entity's `x-cortex-apiiro` block (required).
   * Under **API key**, enter the API key you generated in Apiiro (required).
   * Optionally, under **Host**, enter the base URL of your Apiiro instance. If left blank, the default host is used.
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

> [!NOTE]
>
> To modify the integration configuration, see [Modifying an existing integration configuration](/ingesting-data-into-cortex/integrations#modifying-an-existing-integration-configuration).


# Connecting entities to Apiiro
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/apiiro/connecting-entities-to-apiiro



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to connect Cortex entities to Apiiro. For configuration instructions, see [Configuring the integration for Apiiro](/ingesting-data-into-cortex/integrations/apiiro). For what you can do once entities are connected, see [Using the integration for Apiiro](/ingesting-data-into-cortex/integrations/apiiro/using-the-integration-for-apiiro).

## Connecting an entity to Apiiro

Before Cortex can show Apiiro risks on an entity, the entity needs to be connected to an application or repository in Apiiro. Cortex connects entities to Apiiro repositories automatically when their repository paths match. To connect an entity to an application, or to a repository whose path doesn't match, map it in the entity's YAML.

This page explains both methods and how to confirm that an entity is connected.

## Importing entities from Apiiro

The Apiiro integration doesn't import entities into Cortex. It adds security risk data to entities that already exist in your catalog. To add entities to Cortex, see [Adding entities](/ingesting-data-into-cortex/entities-overview/entities/adding-entities).

## Connecting entities automatically

If an entity has a git repository and no `x-cortex-apiiro` block, Cortex connects it to any Apiiro repository with the same path.

Cortex compares the repository path from the entity's `x-cortex-git` block (for example, `my-org/my-service`) to the repository paths in Apiiro. Keep these rules in mind:

* **Matches are exact.** Matching is case-sensitive, and Cortex doesn't normalize spaces or punctuation. `My-Org/My-Service` doesn't match `my-org/my-service`.
* **Only paths are compared.** Cortex doesn't match on repository URLs, repository IDs, entity names, or Cortex tags.
* **Every match is kept.** If more than one Apiiro repository has the same path, Cortex connects the entity to all of them.
* **Applications aren't matched automatically.** To connect an entity to an Apiiro application, [map it manually](#connecting-entities-manually).

**Cortex refreshes its list of Apiiro repositories every night at 10 p.m. UTC**. A repository you add to Apiiro won't match any entities until after the next refresh. Cortex matches entities to repositories when it loads their Apiiro data, so you don't need to take any action after you configure the integration.

> [!NOTE]
>
> Automatic matching requires a git repository on the entity. Entities without an `x-cortex-git` block only connect to Apiiro through manual mapping.

## Connecting entities manually

Add an `x-cortex-apiiro` block to an entity's YAML to connect it to specific Apiiro repositories or applications. Use manual mapping when:

* You want to connect an entity to an Apiiro application.
* The entity's repository path doesn't exactly match the path in Apiiro.
* The entity doesn't have a git repository in Cortex.

> [!WARNING]
>
> A manual mapping replaces automatic matching for that entity. If you add an `x-cortex-apiiro` block that lists only applications, Cortex stops matching the entity's git repository. To keep the repository connected, list it under `repositories` as well.

### Mapping an entity in its YAML

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

1. In Cortex, navigate to the entity's YAML:
   1. From the main sidebar, expand **Catalogs**, then select **All entities**.
   2. Do one of the following:
      * Select the **All** tab to search and filter across all of your organization’s entities.
      * Select the **Mine** tab to search and filter only the entities you own.
      * Note that Cortex saves your selection and restores it the next time you open this page.
   3. Select your entity.
   4. From the [entity's left sidebar](/ingesting-data-into-cortex/entities-overview/entities/details#configuring-the-entity-details-sidebar), select **Entity YAML**.
   5. In the upper-right corner, click **Configure entity**.
2. Add an `x-cortex-apiiro` block. You can list repositories, applications, or both. Set each entry's `alias` to the alias of your Apiiro configuration in Cortex.
   ```yaml theme={null}
   x-cortex-apiiro:
     repositories:
       - alias: alias-one
         repositoryId: repository-one
     applications:
       - alias: alias-one
         applicationId: application-one
   ```
3. Click **Save changes**.

### Field reference

| Field | Description | Required |
| - | - | - |
| `repositories` | A list of Apiiro repositories to connect to the entity. | No |
| `repositories[].alias` | The alias of the Apiiro configuration in Cortex. You set this when you add a configuration on the Apiiro settings page. | Yes |
| `repositories[].repositoryId` | The ID of the repository in Apiiro. | Yes |
| `applications` | A list of Apiiro applications to connect to the entity. | No |
| `applications[].alias` | The alias of the Apiiro configuration in Cortex. | Yes |
| `applications[].applicationId` | The ID of the application in Apiiro. | Yes |

You can include `repositories`, `applications`, or both. If an entity has neither, Cortex uses [automatic matching](#connecting-entities-automatically).

> [!WARNING]
>
> Every entry needs an `alias`, every repository entry needs a `repositoryId`, and every application entry needs an `applicationId`. If any entry is missing a required field, Cortex ignores the entire `x-cortex-apiiro` block without showing an error.

### How repository and application mappings differ

Both types of mapping show risks in the same places: the **Code & security** block on the entity's overview page, and `apiiro.risks()` in CQL. The difference is which risks Cortex pulls in:

* **Repository mapping** - Cortex shows only the risks in that repository.
* **Application mapping** - Cortex shows every risk Apiiro associates with that application, which can span multiple repositories.

If an entity has both, Cortex combines the results and removes duplicates, so each risk appears once.

> [!NOTE]
>
> The **Code & security** block only appears if the entity has at least one risk. If the entity is connected but has no risks, the block doesn't appear.

### Using multiple configurations

If you have more than one Apiiro configuration in Cortex (for example, one for each Apiiro instance), one entity can connect to repositories and applications under different aliases. Cortex pulls risks from each configuration, then combines the results and removes duplicates.

```yaml theme={null}
x-cortex-apiiro:
  repositories:
    - alias: alias-one
      repositoryId: repository-one
  applications:
    - alias: alias-two
      applicationId: application-two
```

## Verifying the connection

After an entity is connected, check that its Apiiro data appears in Cortex:

* **On the entity's details page** - Risks appear in the **Code & security** block on the overview, grouped by severity. For the full list, go to **Security > Apiiro** in the entity's sidebar.
  > [!NOTE]
  >
  > The **Code & security** block only appears if the entity has at least one risk. If the entity is connected but has no risks, the block doesn't appear.
* **With CQL** - Run `apiiro != null` in the [Query builder - US](https://app.getcortexapp.com/admin/queries) / [Query builder - EU](https://app.eu.cortex.io/admin/queries) to find entities that are connected to Apiiro. Entities that don't appear in the results aren't connected.


# Using the integration for Apiiro
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/apiiro/using-the-integration-for-apiiro



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for Apiiro. For configuration instructions, see [Configuring the integration for Apiiro](/ingesting-data-into-cortex/integrations/apiiro). For instructions on connecting Apiiro to entities, see [Connecting entities to Apiiro](/ingesting-data-into-cortex/integrations/apiiro/connecting-entities-to-apiiro).

## Viewing Apiiro risks on an entity

You can view Apiiro risks on an entity's details page and in the entity's sidebar. You can also use CQL to query for Apiiro risks.

> [!NOTE]
>
> Cortex shows up to 5,000 Apiiro risks per configuration for each entity.

### Entity's details page

On an [entity's overview](/ingesting-data-into-cortex/entities-overview/entities/details), risks are listed under the **Code & security** block. Within this block, issues and vulnerabilities are grouped by severity: `Critical`, `High`, `Medium`, and `Low`. Click into any of these to open a list of all applicable issues and vulnerabilities.

> [!NOTE]
>
> The **Code & security** block only appears if the entity has at least one risk. If the entity is connected but has no risks, the block doesn't appear.

### Entity's left sidebar

In an entity's left sidebar, expand **Security**, then select Apiiro to view risks.

### Scorecards and CQL

With the Apiiro integration, you can create Scorecard rules and write CQL queries based on Apiiro risks.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **List risks**
>
> List all risks for an entity's connected Apiiro repositories and applications.
>
> **Definition**: `apiiro.risks()`
>
> **Example**
>
> A Scorecard's top level might include a rule to ensure that entities have a low number of Apiiro risks:
>
> ```
> apiiro.risks().length < 3
> ```

> **Check if the entity is connected to Apiirot**
>
> Check if the entity is connected to Apiiro.
>
> **Definition:** `apiiro != null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to make sure entities are connected to Apiiro. Without a connection, Cortex can't pull in the entity's risks.
>
> ```
> apiiro != null
> ```

## Viewing Apiiro integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

See frequently asked questions below.

> **An entity doesn't show any Apiiro data**
>
> * Check that the repository path in the entity's `x-cortex-git` block exactly matches the path in Apiiro, including capitalization.
> * If the repository was added to Apiiro recently, wait for the nightly refresh at 10 p.m. UTC.
> * If the entity has an `x-cortex-apiiro` block, check that the IDs match the values in Apiiro, and that the block lists every repository you want connected. A manual mapping turns off automatic matching.
> * Check that every entry in the block has an `alias` that matches an Apiiro configuration in Cortex. If any entry is invalid, Cortex ignores the whole block.
> * Check the integration's error logs. See [Viewing Apiiro integration logs](#viewing-apiiro-integration-logs) for instructions.

> **The entity is connected, but no risks appear**
>
> The entity's Apiiro repositories or applications might not have any open risks. In that case, the **Code & security** block doesn't appear on the entity's overview, and **Security > Apiiro** shows an empty state. If you expect risks, check the following:
>
> * The API key has the `Risks > Read` permission. Look for 401 or 403 errors in the integration logs, or click **Test connection** on the configuration.
> * The repository and application IDs in the entity's YAML still exist in Apiiro. Cortex returns no risks for IDs that no longer exist, without showing an error.


# ArgoCD
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/argocd



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[ArgoCD](https://argoproj.github.io/cd/) is a declarative, GitOps continuous delivery tool for Kubernetes.

Integrating Cortex with ArgoCD allows you to:

* Send information about ArgoCD syncs into Cortex
  * This data appears on [entity detail pages](/ingesting-data-into-cortex/integrations/argocd#view-argocd-data-on-entity-pages).
* Use [Cortex Workflows to automate ArgoCD syncs](/ingesting-data-into-cortex/integrations/argocd#automate-argocd-events-in-workflows)
* See [deploy data for ArgoCD in Eng Intelligence](/ingesting-data-into-cortex/integrations/argocd#see-argocd-data-in-eng-intelligence)

## How to configure ArgoCD with Cortex

### Step 1: Use ArgoCD notification webhooks

To send Cortex information about syncs in ArgoCD, use ArgoCD notification [Webhooks](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/webhook/) to call the Cortex [deploy REST endpoint](/api/rest/deploys).

#### Example config map

Here is an example of what a `argocd-notifications-cm` config map may look like:

```yaml theme={null}
apiVersion: v1
kind: ConfigMap
data:
  context: |
    argocdUrl: https://argo.company.com
  service.webhook.cortex-webhook: |
    url: https://api.getcortexapp.com
    headers:
    - name: Content-Type
      value: application/json
    - name: Accept
      value: application/json
    - name: Authorization
      value: Bearer $token 
    subscriptions: |
      - recipients:
        - cortex-webhook
        triggers:
        - on-sync-succeeded
  template.app-sync-succeeded: |
    webhook:
      cortex-webhook:
        method: POST
        path: /api/v1/catalog/{{.app.metadata.name}}/deploys 
        body: |
          { "customData": { "Sync Status": "{{.app.status.sync.status}}","Sync Details": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" },
            "environment": "{{.app.spec.destination.name}}",
            "sha": "{{.app.status.operationState.operation.sync.revision}}",
            "timestamp": "{{.app.status.operationState.finishedAt}}",
            "title": "Sync by ArgoCD",
            "type": "DEPLOY"
          }
  trigger.on-sync-succeeded: |
    - send:
      - app-sync-succeeded
      when: app.status.operationState.phase in ['Succeeded']
        
```

This example assumes your ArgoCD application's name matches the `x-cortex-tag`. In this case, each application in ArgoCD can subscribe to the same trigger.

If your application name doesn't match the `x-cortex-tag`, add a value/pair to the info section of the Application manifest. Then, instead of using `.app.metadata.name` in the url path, use `{{(index .app.spec.info 0).value}}`.

### Step 2: Subscribe application to webhooks

Next, subscribe your application to the webhook. You do this by adding a label annotation in the Application spec in the following format:

```yaml theme={null}
    notifications.argoproj.io/subscribe.<trigger-name>.<webhook-name>: ""
```

For example, if we want to subscribe an application to the example webhook above, the Application YAML may look like the following example:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  annotations:
    notifications.argoproj.io/subscribe.on-sync-succeeded.cortex-webhook: ""
...  

```

## Using the ArgoCD integration

### View ArgoCD data on entity pages

After you configure the integration, you will see data about ArgoCD syncs in an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details):

* On the entity overview, ArgoCD syncs will appear under the **Latest events** section.

  ![ArgoCD syncs appear in the latest events on an entity.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/argocd-entity.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=5e9ccce6a6a8b68094e14fab25e2568d)
* In the entity's sidebar, click **Events** to see a full list of events for the entity, including sync events from ArgoCD.
* In the entity's sidebar, click **CI/CD > Deploys** to see data from the [Cortex deploys API](/api/rest/deploys), including ArgoCD syncs.

  ![ArgoCD data shows up on an entity page's sidebar under CI/CD > Deploys.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/argocd-sidebar.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=13b3d739d82bf0f5231d7c850164d864)

### Automate ArgoCD events in Workflows

You can use a Workflow to automate ArgoCD syncs. See the [ArgoCD Workflow guide](/guides/operational-readiness/argocd-workflow) for more information.

### See ArgoCD data in Eng Intelligence

Since the ArgoCD integration uses Cortex's [deploys API endpoint](/api/rest/deploys), ArgoCD data is included in Eng Intelligence deploy metrics. Learn more about [Eng Intelligence in the docs](/improve/eng-intelligence).

## Troubleshooting and FAQ

#### What permissions does my API Key need?

The API key needs to be able to call the[ "Add deployment for entity"](/api/rest/deploys#post-api-v1-catalog-tagorid-deploys) API endpoint, so ensure the `Edit entities` permission is enabled.

#### Ensure the Cortex API Key is encoded correctly

Make sure the encoded Cortex API Key does not contain an extra line. Use a tool like [https://www.base64encode.org/](https://www.base64encode.org/) to ensure your encoded key does not contain an extra line.

#### Check the ArgoCD logs

The notification webhook is managed by the `argocd-notifications-controller` which will have a pod running in your ArgoCD namespace.

Assuming the ArgoCD is running in the `argocd` namepsace, run the following command to get the list of pods:

`kubectl get pods -n argocd`

This will return a list of pods similar to the ones listed below:

```
NAME                                                READY   STATUS    RESTARTS   AGE
argocd-application-controller-0                     1/1     Running   0          108d
argocd-applicationset-controller-69f96ccf5b-5jnpv   1/1     Running   0          108d
argocd-dex-server-5dff9c5998-j29zd                  1/1     Running   0          80d
argocd-notifications-controller-6cd988b564-sql55    1/1     Running   0          107d
argocd-redis-54c687db9d-kdxwj                       1/1     Running   0          80d
argocd-repo-server-6c6f8859c7-mrwll                 1/1     Running   0          108d
argocd-server-b77b48886-s2mtg                       1/1     Running   0          80d
```

In this example, the pod managing the webhook notifications is `argocd-notifications-controller-6cd988b564-sql55`. To get the logs, run the following command:

`kubectl logs argocd-notifications-controller-6cd988b564-sql55 -n argocd`

If your trigger was successful, you should seem something similar to this:

```
time="2023-07-19T02:41:13Z" level=info msg="Start processing" app=argocd/app-direct
time="2023-07-19T02:41:13Z" level=info msg="Trigger on-sync-succeeded result: []" app=argocd/app-direct
time="2023-07-19T02:41:13Z" level=info msg="Notification about condition 'on-sync-succeeded.[0].zxM90Et6k4Elb1-fHdjtDJq0xR0' already sent to ''" app=argocd/app-direct
time="2023-07-19T02:41:13Z" level=info msg="Processing completed" app=argocd/app-direct
```

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# AWS
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/aws

Configuring the integration for AWS

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Why use the integration for AWS

Amazon Web Services (AWS) provides on-demand cloud computing platforms and APIs.

As your AWS footprint grows across accounts, regions, and resource types, it gets harder to answer simple questions: what resources exist, who owns them, and how they connect to the services your teams run day to day. Integrating Cortex with AWS gives you a live, accurate picture of your AWS environment, so that information doesn't live only in the AWS console, or in a spreadsheet someone updates once a quarter.

When you connect AWS to Cortex, you get:

* A single catalog of your AWS resources that stays in sync automatically, instead of one you maintain by hand.
* Clear [ownership](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#syncing-ownership-from-aws), discovered from the tags you already use, so you can find who's responsible for a resource without asking around.
* Dependency mapping between your services and the AWS resources they rely on, so you can see the blast radius of a change before you make it.
* [Scorecards and CQL queries](/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws#creating-scorecard-rules-and-writing-cql-queries-with-the-aws-integration) that measure your AWS resources against standards like tagging hygiene, deprecated runtimes, or required configurations.
* A [discovery audit](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#discovery-audit) that flags new or missing AWS resources, so your catalog doesn't quietly drift out of date.

If you are on a self-hosted Cortex instance, see the [self-managed AWS](/self-managed/features/integrations/aws) setup instructions.

## Configuring AWS

### Prerequisites

1. Users with the `Configure Integrations` permission can configure AWS.

### Step 1: Configuring the integration in Cortex

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate AWS, then click **Install**. The AWS side panel opens.
3. In the modal, the JSON configuration, Cortex AWS account ID, and External ID are displayed. In the configuration side bar instructions, you will also see the option to copy a starting "Read Only Access" JSON policy. Keep this browser window open, as you will need these in the next steps.

### Step 2: Configuring an IAM policy in AWS

You must configure an IAM policy for each account you want to connect to Cortex.

> [!NOTE]
>
> When using Cloud Control, the role Cortex assumes to get access into your account needs to have read access to all the selected types. This access is included by default in the Read Only Access policy in Cortex, or it can be configured manually for each type.

1. Log in to the AWS Management Console, then open the [IAM console](https://console.aws.amazon.com/iam/).
2. Click **Policies**, then choose **Create policy**.
3. Switch to the JSON editor. In Cortex while configuring AWS, copy the JSON "Read Only Access" starting policy that appears in the in-app instructions. Paste it into the JSON editor.
   * This policy allows Cortex to list all resources, resource types, and resource tags.
   * If you choose to configure this manually, rather than using the starting policy provided, insert a valid IAM policy depending on the resource types you'd like to import. For example, if you want to import resources of type `AWS::IAM::role`, we'll need to have permission to `iam:ListRoles`, `iam:ListAttachedRolePolicies`, `iam:GetRole`, `iam:ListAccountAliases` and `iam:ListRolePolicies`.
     * For manual configurations, make sure to add the `cloudformation:ListTypes`, `cloudformation:ListResources`, and `cloudformation:GetResource` permissions so that we can pull the list of types available from AWS.
4. Click **Review Policy**, enter a name, then click **Create Policy**.

See the AWS documentation for more information: [Create IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html).

### Step 3: Create a role in AWS

This section is specific to cloud-based Cortex accounts. If you are on a self-hosted Cortex instance, please see the AWS account setup guide for self-hosted Cortex.

1. In AWS, navigate to **Roles > Create Role**.
2. For the trusted entity type, select **Another AWS account**.
3. In the **Account ID** field, enter the Cortex AWS account ID that was displayed in Cortex in the earlier steps.
4. Click **Require External ID**, then enter the Cortex external ID that was displayed in Cortex in the earlier steps.
5. Click **Next**.
6. Select your newly created policy, and click **Next**.
7. Enter a name for your role. Optionally, configure tags. When you are finished, click **Create Role**.
8. Search for your new role in the list and copy its name. You will need this in the next steps.
9. In the upper right corner of AWS, click your name. In the dropdown that appears, copy your AWS account ID. You will need these in the next steps.

Note that if you use multiple AWS accounts, they will share a common rotatable `externalId`.

### Step 4: Finish the configuration in Cortex

1. Navigate back to the browser window containing your [Cortex AWS settings page](https://app.getcortexapp.com/admin/settings/aws).
2. Configure the AWS integration form:
   * **Account ID**: Enter the AWS account ID you obtained in the previous steps.
   * **IAM role**: Enter the role name you obtained in the previous steps.
3. Click **Save**.


# Importing entities from AWS
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws

Automatically import AWS resources as entities, discover dependencies between them, and keep ownership in sync

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to import entities from AWS. For configuration instructions, see [Configuring the integration for AWS](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws). For instructions on using the integration, see [Using the integration for AWS](/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws).

### Keep in mind

When importing from AWS, Cortex replaces non-alphanumeric characters in entity names with a space. For example, `resource_1` becomes `resource 1`.

For the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag), Cortex replaces non-alphanumeric characters with `-` and lowercases the letters. If multiple special characters appear together in a tag, Cortex replaces the group of characters with only one `-`. For example, `mY_e%ntity#$_tag` becomes `my-e-ntity-tag`.

## Importing an entity from AWS

Cortex gives you two ways to import entities from AWS: automatically or manually.

Turn on auto import and Cortex creates an entity for every resource it discovers in the Cloud Control types you've selected, then keeps them in sync as your AWS environment changes.
Import manually instead if you'd rather pick exactly which discovered resources land in your catalog and set details like ownership and repository as you go.
If an entity already exists in Cortex, you can connect it to specific AWS resources by adding an `x-cortex-infra` block to its YAML.

### Prerequisites

1. Ensure that Cortex only pulls the cloud control types you want it to:
   1. From the main sidebar, select **Integrations**.
   2. Locate AWS, then click **Settings**.
   3. Select the **Integration settings** tab.
   4. From the **Cloud control types** dropdown, select the types you want Cortex to discover.
      * When you turn on auto-import for AWS, Cortex imports these types automatically.
      * To remove an auto-imported cloud control type, click the **X** next to its name, then click **Save cloud control types**.
   5. Click **Save cloud control types**.

> [!WARNING]
>
> If a type does not appear in the list, ensure that `cloudformation:ListTypes`, `cloudformation:ListResources`, and `cloudformation:GetResource` are added to your IAM policy.

> **Expand to see which cloud control types are NOT supported**
>
> ```
> AWS::ApiGateway::DocumentationVersion
> AWS::ApiGateway::Step
> AWS::CloudFormation::ResourceVersion
> AWS::CustomerProfiles::Integration
> AWS::CustomerProfiles::ObjectType
> AWS::EC2::TransitGatewayMulticastGroupMember
> AWS::EC2::TransitGatewayMulticastGroupSource
> AWS::ECS::TaskSet
> AWS::Glue::Attach::SchemaVersion
> AWS::Glue::Attach::SchemaVersionMetadata
> AWS::IoTSiteWise::AccessPolicy
> AWS::IoTSiteWise::Dashboard
> AWS::IoTSiteWise::Project
> AWS::Kendra::DataSource
> AWS::Kendra::Faq
> AWS::MediaConnect::FlowEntitlement
> AWS::MediaConnect::FlowOutput
> AWS::MediaConnect::FlowSource
> AWS::MediaConnect::FlowVpcInterface
> AWS::MediaPackage::Asset
> AWS::MediaPackage::PackagingConfiguration
> AWS::NetworkFirewall::LoggingConfiguration
> AWS::QuickSight::Analysis
> AWS::QuickSight::Dashboard
> AWS::QuickSight::DataSet
> AWS::QuickSight::DataSource
> AWS::QuickSight::Template
> AWS::QuickSight::Theme
> AWS::RDS::DBProxyTargetGroup
> AWS::S3Outposts::AccessPoint
> AWS::S3Outposts::Bucket
> AWS::SSO::Assignment
> AWS::SSO::InstanceAccessControlAttributeConfiguration
> AWS::SSO::PermissionSet
> ```
>
> If the type you want to import is in the list above, contact [support@cortex.io](mailto:support@cortex.io) to submit a feature request.

### Automatically importing AWS entities

Users with the `Manage Integrations` permission can enable auto import of AWS resources.

Follow the steps below to configure automatic import from AWS. If you don't want Cortex to auto import AWS resources, you can [manually import them](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#manually-importing-aws-entities).

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select **General**.
5. Under **Entity settings**, toggle on **Auto import from AWS, Azure, and/or Google Cloud**.

   ![The auto import option toggled on in the Settings.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/auto-import-aws.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=7dc9a1a1fc5926d46c59b5ff7e450635)

After you toggle on auto-import, Cortex imports all entities of the selected types into your catalog, and keeps importing new ones as it discovers them.

#### Limiting discovery to specific regions

By default, Cortex searches for resources across all AWS regions, but you can limit that to specific regions.

1. From the main sidebar, select **Integrations**.
2. Locate AWS, then click **Settings**.
3. Select the **Integration settings** tab.
4. Scroll to **Regions**, then select one or more regions from the dropdown.

   ![The 'Regions' dropdown.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/aws-regions%20\(1\).png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=c72ac7b6ae5106ac9820765dec6db767)
5. Click **Save regions**. Cortex will now only search across the regions you specified.

### Manually importing AWS entities

Follow the steps below to manually import from AWS. If you don't want to import manually, you can [automatically import them](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#automatically-importing-aws-entities).

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Import discovered entities**.
4. Select AWS. The **Select entities to import** page is displayed.
5. A list of entities is displayed. Select the checkboxes next to the entities you want to import. Use the search bar to find entities by name, or click the **Filter icon** in the upper-right corner of the results list to filter by entity type.
6. In the bottom-right corner, click **Next step**. The **Edit details** page is displayed.
7. Configure the following:
   1. From the **Type** drop-down menu, select **Service.**
   2. In the **Details** section:
      1. Under **Entity name**, enter a name for the entity (required).
      2. The **Cortex tag** field is auto-populated based on the name of the entity (required). It's a unique identifier for the entity. This is also known as the `x-cortex-tag`.
      3. Under **Description**, enter a description of the entity to help others understand its purpose.
      4. From the **Groups** drop-down, select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups).
   3. In the **Repository** section:
      1. From the **Provider** drop-down menu, select the repo provider.
      2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
      3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
      4. Under **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
   4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
      * Cortex may recommend owners [based on your catalog data](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations). You can accept or reject the recommendations.
   5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
   6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
   7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
   8. In the **Dependencies** section, click **Add entity** to select an entity or entities that this entity depends on. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph).
8. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.
9. Click **Confirm import**. The entity is imported into Cortex.

### Editing an entity via its descriptor

To connect a Cortex entity to one or more AWS resources, add the `x-cortex-infra` block to the entity's YAML. For certain AWS resource types, Cortex displays those AWS entities' metadata on the Cortex entity page.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

| Field | Description | Required? |
| - | - | - |
| `type` | The AWS Cloud Control resource type, e.g. `AWS::RDS::DBInstance` | |
| `region` | The AWS region the resource belongs to | |
| `accountId` | The AWS account ID the resource belongs to | |
| `identifier` | The primary identifier of the resource | |

**Example**

```yaml theme={null}
x-cortex-infra:
  aws:
    cloudControl:
    - type: AWS::RDS::DBInstance
      region: us-west-2
      accountId: "623456123456"
      identifier: checkout-db-prod
```

#### Connecting multiple ECS services to a single entity

To connect a Cortex entity to multiple ECS services, use one of the formats below, depending on whether you're using Cloud Control resource types.

| Field | Description | Required? |
| - | - | - |
| `type` | Must be `AWS::ECS::Service` | |
| `region` | The AWS region the service belongs to | |
| `accountId` | The AWS account ID the service belongs to | |
| `identifier` | The primary identifier of the service | |

**Example**

```yaml theme={null}
x-cortex-infra:
  aws:
    cloudControl:
    - type: AWS::ECS::Service
      region: us-west-2
      accountId: "623456123456"
      identifier: checkout-service
    - type: AWS::ECS::Service
      region: us-east-1
      accountId: "345673456731"
      identifier: checkout-service-dr
```

#### Using the legacy ECS format

If you're not using Cloud Control types, or you imported your entity before Cortex supported Cloud Control types, use the format below.

| Field | Description | Required? |
| - | - | - |
| `clusterArn` | The ECS cluster's ARN. See [ECS](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) for details. | |
| `serviceArn` | The ECS service's ARN. See [ECS](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) for details. | |

**Example**

```yaml theme={null}
x-cortex-infra:
  aws:
    ecs:
      - clusterArn: arn:aws:ecs:us-west-2:123456789012:cluster/checkout-cluster
        serviceArn: arn:aws:ecs:us-west-2:123456789012:service/checkout-cluster/checkout-service
      - clusterArn: arn:aws:ecs:us-east-1:123456789012:cluster/checkout-cluster-dr
        serviceArn: arn:aws:ecs:us-east-1:123456789012:service/checkout-cluster-dr/checkout-service-dr
```

### Discovery audit

Cortex pulls recent changes from your AWS environment into the [discovered entities list](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit), where you can find:

* New entities in AWS that haven't been imported into your Cortex catalog. These are tagged **New AWS Resource**.
* Entities in the catalog that no longer exist in AWS. These are tagged **AWS Resource Not Detected**.

![The 'Discovered entities' list.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/disc-entities.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=06cb779a579c7d0c14dab54e14039701)

## Relationships, ownership, and dependencies for AWS entities

### **Configuring tag-based auto-linking for AWS**

You can configure any relationship type to automatically create relationships between AWS resources and other Cortex entities based on matching AWS tag values. This is the recommended way to connect AWS resources to domains, services, or custom entities for Scorecard reporting.

> [!NOTE]
>
> The **Auto-create relationships from integration tags** section only appears when at least one AWS-backed entity type is selected as the source and/or destination.

**To configure tag-based auto-linking**:

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Locate the relationship type you want to configure, then click the **pencil icon**. You can also create a new relationship type.
4. Scroll to the **Auto-create relationships from integration tags** section.
5. From the **Provider** drop-down menu, select **AWS**.
6. Configure the **Source tag key** by doing one of the following:
   * Enter the AWS tag key on the source entity (e.g. `cortex-entity-tag`), OR
   * Toggle on **Cortex provided tag** to use Cortex's standardized managed tag key.
7. Configure the **Destination tag key** by doing one of the following:
   * Enter the tag key on the destination entity (e.g. `AWS-tag-parent`), OR
   * Toggle on **Cortex provided tag** to use Cortex's standardized managed tag key.
8. Click **Save** (or **Create** if it's a new relationship type).

> [!NOTE]
>
> Once a relationship type is saved with integration-backed auto-creation configured, this setting cannot be changed. To modify it, delete the relationship type and create a new one.

Cortex scans entities matching the relationship type's source and destination definitions and creates a relationship wherever tag values match. Newly configured relationships are created asynchronously and may take up to one sync cycle to appear.

**Example: Linking AWS resources to domains**

To roll AWS resources up to a domain for Scorecard reporting:

1. Tag your AWS resources with the domain they belong to (e.g. a `domain` tag with the domain's Cortex tag as the value).
2. Create or open a relationship type with AWS resources as the source and domains as the destination.
3. In the **Auto-create relationships from integration tags** section, set the source tag key to `domain` and the destination tag key to the corresponding identifier on your domain entities.
4. Click **Save**. Cortex creates the relationships automatically.

### Discovering dependencies automatically

Cortex automatically discovers dependencies between your services and resources by scanning for AWS resources tagged with specific keys. By default, a service depends on any Cortex resource whose corresponding AWS resource has a tag where the key is `service` and the value matches the service's Cortex tag.

> [!NOTE]
>
> Cortex syncs AWS tags (dependencies) daily at 8 a.m. UTC.
> **To manually refresh tags**:
>
> 1. From the main sidebar, expand Tools, then select **Relationship graphs**.
> 2. In the upper-right corner, click the **overflow menu icon**, then select **Sync dependencies**.\\
>
>    ![The 'Sync dependencies' option.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/sync-dependencies.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=a016c4cc4c2e040f229ef442bdf34d8f)

Specifying a tag name is optional. If you don't specify one, Cortex uses `service` as the key name.

**To specify a tag name in Cortex**:

1. From the main sidebar, select **Integrations**.
2. Locate AWS, then click **Settings**.
3. Select the **Integration settings** tab.
4. Scroll to **Dependencies sync from AWS**, then select one or more tags from the dropdown. Note that an `AND` operator is used when you select multiple tags; the resource needs to have all specified tags in order to be recognized by Cortex.

   ![The 'Dependencies sync from AWS' section.](https://mintcdn.com/cortex-290c0c42/jF7ejFzeAkCGjvGG/images/depend-sync-aws.png?fit=max\&auto=format\&n=jF7ejFzeAkCGjvGG\&q=85\&s=49025bf12c763753e7e22074a7ea22b1)
5. Click **Save dependency tag keys**.

#### **Using key/value pairs in the entity descriptor for dependency discovery**

You can also define explicit tag key/value pairs in the `x-cortex-dependency` block for AWS dependency discovery. Instead of matching on service tags, Cortex matches a service to any AWS resource whose tags match the key/value pairs you define in the service's `x-cortex-dependency` block.
For example, the service below depends on any AWS resource tagged with key `service` and value `checkout-service`, key `team` and value `checkout-team`, or a resource created by the CloudFormation stack `checkout-service-prod`.

```yaml theme={null}
x-cortex-dependency:
  aws:
    tags:
      - key: service
        value: checkout-service
      - key: team
        value: checkout-team
      - key: "aws:cloudformation:stack-name"
        value: "checkout-service-prod"
      - key: "aws:cloudformation:stack-id"
        value: "arn:aws:cloudformation:us-west-2:123456789012:stack/checkout-service-prod/1a2b3c4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d"
```

For more information, see the [Dependencies documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies).

### **Auto-creating AWS account entities**

Users with the `Manage Integrations` permission can configure the auto-creation of AWS account entities.

When enabled, Cortex automatically creates an entity for each AWS account connected to your integration and links it to its AWS resources through a built-in, Cortex-managed relationship.

> [!NOTE]
>
> The **Auto import from AWS, Azure, and/or Google Cloud** setting must be [toggled on](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#automatically-importing-aws-entities) prior to auto-creating AWS account entities.

**To enable AWS account auto-creation:**

1. From the main sidebar, select **Integrations**.
2. Locate AWS, then click **Settings**.
3. Select the **Integration settings** tab.
4. Scroll to **Accounts as entities**, then toggle on **Import AWS accounts as entities**.

   ![The 'Import AWS accounts as entities' option in the AWS settings.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/auto-create-aws.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=e0f6b2290959f8789a16c99ef162c3e0)

Once enabled:

* Cortex creates an **AWS Account** entity for each account configured in Cortex.
* Each AWS resource is automatically linked to its parent account through a Cortex-managed relationship.

As new accounts are configured and resources are discovered, entities and relationships stay in sync automatically.

**To view your AWS account entities:**

1. From the main sidebar, expand **Catalogs**.
2. Select **All entities**, then select the **Entity types** tab.
3. Search for **AWS account**.

   ![The search box on the 'Entity types' page.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/search-aws.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=d9648d775bb5a831564865ffc3cba447)
4. Select an entity type, then select an entity.
5. From the **Catalog** menu, select the **Relationships** tab.

   ![The 'Relationships' tab.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/relationships-tab-from-entity.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=733f20abbe410a271337317f37c38f8e)

### Syncing ownership from AWS

Cortex can automatically discover ownership for your AWS resources from their tags. Tag each resource with the `x-cortex-tag` of the Cortex team that owns it. By default, Cortex looks for the `owner` tag, but you can customize the tag key name.

> [!NOTE]
>
> Cortex syncs ownership from AWS every day at 6 a.m. UTC.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

To enable ownership sync:

1. From the main sidebar, select **Integrations**.
2. Locate AWS, then click **Settings**.
3. Select the **Integration settings** tab.
4. Scroll to **Ownership sync from AWS**, then toggle on **Enable ownership sync**.

   ![The 'Ownership sync from AWS' section.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/owner-sync-aws.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=f5ebf99a01bcc268381889ca6b1f67d5)
5. Optionally, customize the tag key name:
   1. From the **Select tags** dropdown, select one or more tags.
   2. Click **Save ownership tag keys**.


# Using the integration for AWS
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws

How to use the integration for AWS in Cortex

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for AWS. For configuration instructions, see [Configuring the integration for AWS](/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws). For instructions on connecting GCP to entities, see [Connecting entities to AWS](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws).

> [!NOTE]
>
> Cortex conducts a sync of integration details daily at 10 a.m. UTC.

## Viewing AWS data on an entity

The **Cloud > AWS** section of an entity's details sidebar shows Amazon Elastic Container Service (ECS) data for the ECS services linked to that entity.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Only ECS services populate this section. Cortex reads the entity's `x-cortex-infra` block, keeps any entries of type `AWS::ECS::Service`, and builds the view from those:

```yaml theme={null}
x-cortex-infra:
  aws:
    cloudControl:
    - type: AWS::ECS::Service
      region: us-west-2
      accountId: "123456123456"
      identifier: arn:aws:ecs:us-west-2:123456123456:service/payments-cluster/payments-api
```

| Field | Description | Required |
| - | - | - |
| `type` | The AWS Cloud Control resource type. Only `AWS::ECS::Service` populates the **Cloud > AWS** section. | |
| `region` | The AWS region the ECS service runs in, for example `us-west-2`. | |
| `accountId` | The ID of the AWS account that owns the service. Wrap the value in quotation marks so leading zeros aren't dropped. | |
| `identifier` | The fully-qualified ARN of the ECS service. Note that the `identifier` must be the fully-qualified ARN of the ECS service, not the service name. | |

A few things to keep in mind:

* `AWS::ECS::Service` is the only type that populates this section. Other AWS types, including `AWS::ECS::Cluster`, don't populate it, even when they're linked to the entity correctly.
* Links defined with `x-cortex-relationships` don't populate this section. To see data here, link the ECS service in the entity's `x-cortex-infra` block.
* If an entity has no linked ECS service, the **Cloud > AWS** section doesn't appear in its details sidebar.

To work with other AWS resource types in Cortex, [import them as entities](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#importing-an-entity-from-aws), then connect them to related entities using [relationships](/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types). You can also query their metadata with the `aws.details()` function in [CQL](/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws#creating-scorecard-rules-and-writing-cql-queries-with-the-aws-integration).

## Searching AWS entities in Cortex

The following keys are supported when searching for your AWS entities in Cortex.

* `aws-account-id` - Account ID number
* `aws-account-name` - Account alias
* `aws-region` - AWS region of the resource
* `aws-type` - AWS type of the resource
* `aws-name` - AWS name of the resource
* `aws-identifier` - The primary identifier of a resource
* `aws-secondary-identifier` - The secondary identifier of a resource
* `aws-arn` - Searches for an Amazon Resource Name (ARN). This is not supported for Cloud Control types.

**To search for entities**:

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. In the upper-right corner, enter your search parameters in the Search bar.

### Example search queries

* `aws-type:"AWS::EC2" AND aws-region:"us-west"` - Searches for entities of category EC2 in the any of us-west regions
* `aws-account-id: "234512324"` - Searches for all entities from the account 234512324
* `aws-name:"aws-identifier-of-resource" AND aws-account-name:"test-account"` - Searches for entities with the identifier `aws-identifier-of-resource` in the account with alias `test-account`

## Creating Scorecard rules and writing CQL queries with the AWS integration

With the AWS integration, you can create Scorecard rules and write CQL queries based on AWS resources.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **AWS details**
>
> Get the AWS details for an entity
>
> **Definition** - `aws.details(): Object`
>
> **Example**
>
> In a Scorecard, you can create a rule to verify that an entity of type `lamda` has a correct function name:
>
> ```
> aws.details().resources.filter((resource) => resource.typeName == "AWS::Lambda::Function").length > 0
> ```
>
> You could also create a rule to verify that an entity is not using deprecated runtimes:
>
> ```
> aws.details().resources.filter((resource) => resource.typeName == "AWS::Lambda::Function" and resource?.metadata?.get("Runtime")?.matchesIn("(python3\\.6|python2\\.7|dotnetcore2\\.1|ruby2\\.5|nodejs12\\.|nodejs10\\.|nodejs8\\.10|nodejs4\\.3|nodejs6\\.10|dotnetcore1\\.0|dotnetcore2\\.0|nodejs4\\.3-edge|nodejs$)")).length == 0    
> ```

## Viewing AWS integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

See frequently asked questions below.

> **If I have auto-import enabled, how can I remove cloud control types that I no longer want to be imported?**
>
> If you want to remove any of the cloud control types after importing them: Disable the [automatic import](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#automatically-importing-aws-entities) setting, remove the cloud control types from your [AWS integration settings](/ingesting-data-into-cortex/integrations/aws#step-4-finish-the-configuration-in-cortex), then enable [auto-archival](/ingesting-data-into-cortex/entities-overview/entities/archiving-entities/auto-archive). This will cause the removed cloud control types to be archived during the next sync.

> **Why am I seeing the AWS account ID instead of the AWS account alias?**
>
> We've recently added support for pulling in the AWS account alias. The required permission is `iam:ListAccountAliases` (see the AWS documentation [here](https://000001.awsstudygroup.com/1-create-new-aws-account/1.3-aws-account-alias/#create-or-edit-an-account-alias)). Once this permission is added, the we will persist the account alias everywhere instead of the ID.

> **Why don't I see the Cloud > AWS section on an entity?**
>
> That section only appears on entities that have an `AWS::ECS::Service` resource linked in their `x-cortex-infra` block. If the entity has no linked ECS service, or is linked to a different AWS type such as `AWS::ECS::Cluster`, Cortex hides the section instead of showing an empty page. See [Viewing AWS data on an entity](/ingesting-data-into-cortex/integrations/aws/using-the-integration-for-aws#viewing-aws-data-on-an-entity).

> **When does Cortex sync AWS resources?**
>
> Cortex conducts the following daily syncs for AWS:
>
> * Integration details daily at 10 a.m. UTC
> * Ownership sync daily at 6 a.m. UTC
> * AWS tag sync (dependencies) daily at 8 a.m. UTC
>   * This sync can also be [triggered manually](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws#discovering-dependencies-automatically)


# Internally hosted integrations
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/axon-relay

Setting up internally hosted integrations with Axon Relay

Cortex Axon is a framework for building jobs that run in your environment and securely send data to Cortex. You can use Axon for two things:

* **Custom handlers** - Write code against the Cortex API that sends data to Cortex on a set interval, on a cron schedule, or after processing a webhook. For more information, see the [Cortex Axon README](https://github.com/cortexapps/axon).

* **Internally-hosted integrations** - Axon Relay creates a virtual connection between your network and Cortex, so Cortex can reach integrations you host internally. Axon Relay supports [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Google Cloud Platform](/ingesting-data-into-cortex/integrations/google#configuring-gcp), [Harness](/ingesting-data-into-cortex/integrations/harness), [Jira](/ingesting-data-into-cortex/integrations/jira), [Prometheus](/ingesting-data-into-cortex/integrations/prometheus), and [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube). You can also use it to [call internal service endpoints from a Workflow](/guides/operational-readiness/internal-endpoints).

## How Axon Relay works

![Network diagram showing how Cortex Axon works.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/axon-diagram.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=90058b319cf32c042d2582d1eb15b52b)

Cortex Axon is built on [Snyk Broker](https://docs.snyk.io/implementation-and-setup/enterprise-setup/snyk-broker), an open-source project published by Snyk. Snyk Broker uses WebSockets to create a secure tunnel between your internal network and cloud-hosted Cortex. HTTP requests from Cortex travel through this tunnel to the Axon agent. Because the tunnel is opened from inside your network, you don't need to open any inbound firewall ports.

When you deploy Axon, you store your API tokens or credentials as secrets on infrastructure you own, inside your network. Axon uses these credentials to proxy requests to third-party integrations. Your sensitive information stays inside your virtual private cloud (VPC) and is never exposed to Cortex cloud services.

The process works like this:

1. In Cortex, you register the integration with an alias you choose.
2. You start the Cortex Axon Docker container with your Cortex API key, the integration type, and the alias.
3. The Axon agent connects to Cortex, authenticates, and registers itself with the integration type and alias.
4. The agent starts a Snyk Broker client process. The client uses the configuration details returned by that registration (the `/register` call) to connect to the Snyk Broker server that runs on the Cortex backend.
5. Once the connection is established, Cortex relays API calls to your internal network, and the responses come back to Cortex through the same tunnel.

## Using Axon Relay

Cortex Axon is composed of an agent which runs in a Docker container (`cortex-axon-agent`) and integrates with Kubernetes, creating a secure tunnel between the broker and Cortex.

### Prerequisites

1. Create an [API key](/configure/settings/api-keys#managing-api-keys-via-the-cortex-api) in Cortex.
2. Create authentication credentials for the integration you're configuring. Refer to the third-party's documentation for more information.

### Step 1: Setting up the Cortex Axon agent

#### Step 1.1: Configuring the Axon Relay in Cortex

> [!NOTE]
>
> Axon Relay supports [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), [GitLab](/ingesting-data-into-cortex/integrations/gitlab), [Google Cloud Platform](/ingesting-data-into-cortex/integrations/google#configuring-gcp), [Harness](/ingesting-data-into-cortex/integrations/harness), [Jira](/ingesting-data-into-cortex/integrations/jira), [Prometheus](/ingesting-data-into-cortex/integrations/prometheus), and [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube). You can also use Axon Relay to [call internal service endpoints via a Workflow](/guides/operational-readiness/internal-endpoints) .

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Search for the integration you want to set up, then click **+Install**.

   ![The Install button, located to the right of the integration's name.](https://mintcdn.com/cortex-290c0c42/D56PZu6_5KOjw5dK/images/axon-install-integration.png?fit=max\&auto=format\&n=D56PZu6_5KOjw5dK\&q=85\&s=c6b53c56ce34d52f536eefaa575e9b66)
3. In the side panel, select **Relay** as the configuration type.
4. From **Configuration details**, do the following:
   1. Optionally, select a new category from the **Category** dropdown. Cortex provides a default category, you can change it if you need to. Needs at least one category.
   2. **Configuration alias** - Enter the alias that ties the service registration to this configuration (required).
   3. Depending on the integration, there may be additional options to configure.

#### Step 1.2: Creating a .env file and a docker-compose.yml file

1. Locally on your machine, create a file called `.env`. Inside the file, add contents for the integration you are configuring:\


   > **Docker Compose**
   >
   > See the [variables for your integration in the README](https://github.com/cortexapps/axon/blob/main/README.relay.md#environment-variables-summary).
   > For example, for GitLab you would add:
   >
   > ```text theme={null}
   > CORTEX_API_TOKEN=your_cortex_token
   > GITLAB_TOKEN=your_gitlab_token
   > ```

   > **Kubernetes**
   >
   > To run the agent in Kubernetes, you'll need to create a Deployment that runs the agent with similar configuration [as described above](/ingesting-data-into-cortex/integrations/axon-relay#how-it-works).
   > There is a [Helm chart](https://github.com/cortexapps/axon/tree/main/examples/relay/helm-chart) available that can be used as a starting point. Its critical variables are:
   >
   > ```yaml theme={null}
   > # Example for github
   > relay:
   >   integration: github # can be blank
   >   subtype:   # optional, can be blank, see table above for options
   >   alias: alias for configuration from Cortex
   >   env:
   >     GITHUB: "https://github.com"
   >     GITHUB_API: "https://api.github.com"
   >     GITHUB_GRAPHQL_API: "https://api.github.com/graphql"
   >   verbose: false # set to true to enable verbose logging
   > ```
   >
   > If you have a proxy setup you can add values such as:
   >
   > ```yaml theme={null}
   > proxy:
   >   server:  http://proxy.example.com:8080
   >   noProxy: proxy.example.com # note localhost is added automatically
   >   certSecretName: my-proxy-ca-pem # name of the secret containing a .pem file with the CA certificate
   > ```

> [!NOTE]
>
> For Google Cloud Platform (GCP), your `.env` file only needs `CORTEX_API_TOKEN`. The agent gets its Google credential from Application Default Credentials (ADC), so you don't need to add a Google token or password to `.env`. If you use a service account key, mount in `docker-compose.yml` instead. You enter your Google Workspace customer ID in Cortex when you configure the relay.

2. Locally on your machine, create a file called `docker-compose.yml`. Inside the file, add contents for the integration you are configuring:\


   > **Bitbucket**
   >
   > **Bitbucket Cloud**:
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - BITBUCKET_API=https://api.bitbucket.org
   >       - BITBUCKET_TOKEN=<token>
   >     command: [
   >       "relay",
   >       "-i", "bitbucket",
   >       "-a", "bitbucket-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```
   >
   > **Bitbucket Hosted**:
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - BITBUCKET_API=https://bitbucket.mycompany.com
   >       - BITBUCKET_USERNAME=<user>
   >       - BITBUCKET_PASSWORD=<password>
   >     command: [
   >       "relay",
   >       "-i", "bitbucket",
   >       "-a", "bitbucket-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```

   > **GitHub**
   >
   > **GitHub**:
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - GITHUB_API=api.github.com
   >       - GITHUB_GRAPHQL=api.github.com/graphql
   >     command: [
   >       "relay",
   >       "-i", "github",
   >       "-a", "github-relay", # this is the alias you set up in the Cortex UI
   >
   >       # if you are using a Github App token, add the following line
   >       # "-s", "app",
   >     ]
   > ```
   >
   > Additional environment variables include: `GITHUB_API=https://api.github.com`, `GITHUB_TOKEN`
   > **GitHub Hosted**:
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - GITHUB_API=https://github.mycompany.com/api/v3
   >       - GITHUB_GRAPHQL=https://github.mycompany.com/api/graphql
   >     command: [
   >       "relay",
   >       "-i", "github",
   >       "-a", "github-relay", # this is the alias you set up in the Cortex UI
   >
   >       # if you are using a Github App token, add the following line
   >       # "-s", "app",
   >     ]
   > ```
   >
   > Additional environment variables include: `GITHUB=https://github.mycompany.com`, `GITHUB_TOKEN`
   > **GitHub App**:
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - GITHUB_API=https://api.github.com
   >       - GITHUB_GRAPHQL=https://api.github.com/graphql
   >     command: [
   >       "relay",
   >       "-i", "github",
   >       "-a", "github-relay", # this is the alias you set up in the Cortex UI
   >
   >       # if you are using a Github App token, add the following line
   >       # "-s", "app",
   >     ]
   > ```
   >
   > Additional environment variables include: Arg `-s app`, `GITHUB=https://github.com`, `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_PEM` (either path to PEM or PEM contents), `GITHUB_INSTALLATION_ID`

   > **GitLab**
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - GITLAB_API=https://gitlab.com
   >       - GITLAB_TOKEN=<token>
   >     command: [
   >       "relay",
   >       "-i", "gitlab",
   >       "-a", "gitlab-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```

   > **Google Cloud Platform (GCP)**
   >
   > The Google Cloud agent doesn't use a token or password in `.env`. It gets short-lived credentials from Application Default Credentials (ADC) in your environment. The alias must be `gcp`.
   > **Service account key**:
   > Mount the key file into the container and point `GOOGLE_APPLICATION_CREDENTIALS` to it.
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     volumes:
   >       - ./gcp-service-account.json:/etc/gcp/credentials.json:ro
   >     environment:
   >       - GOOGLE_APPLICATION_CREDENTIALS=/etc/gcp/credentials.json
   >     command: [
   >       "relay",
   >       "-i", "google",
   >       "-a", "gcp", # must be gcp
   >     ]
   > ```
   >
   > **GKE Workload Identity**:
   > You don't need to mount anything. The container reaches the GKE metadata server over pod networking.
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     command: [
   >       "relay",
   >       "-i", "google",
   >       "-a", "gcp", # must be gcp
   >     ]
   > ```

   > **Harness**
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - HARNESS_API=https://app.harness.io # for self-managed, set to your internal host
   >       - HARNESS_TOKEN=<your_harness_api_key>
   >     command: [
   >       "relay",
   >       "-i", "harness",
   >       "-a", "harness-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```

   > **Jira**
   >
   > **Jira**:
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - JIRA_API=https://jira.mycompany.com
   >       - JIRA_USERNAME:<user>
   >       - JIRA_TOKEN=<token>
   >     command: [
   >       "relay",
   >       "-i", "jira",
   >       "-a", "jira-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```
   >
   > **Jira Bearer/Cloud**:
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - JIRA_API=https://mycompany.atlassian.com
   >       - JIRA_TOKEN=<token>
   >     command: [
   >       "relay",
   >       "-i", "jira",
   >       "-a", "jira-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```
   >
   > Additional variables include: Arg `-s bearer`

   > **Prometheus**
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - PROMETHEUS_API=http://mycompany.prometheus.internal
   >       - PROMETHEUS_USERNAME=<user>
   >       - PROMETHEUS_PASSWORD=<password>
   >     command: [
   >       "relay",
   >       "-i", "prometheus",
   >       "-a", "prometheus-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```

   > **SonarQube**
   >
   > ```yaml theme={null}
   > services:
   >   axon:
   >     image: ghcr.io/cortexapps/cortex-axon-agent:latest
   >     env_file: .env
   >     environment:
   >       - SONARQUBE_API=https://sonarqube.mycompany.com
   >       - SONARQUBE_TOKEN=<token>
   >     command: [
   >       "relay",
   >       "-i", "sonarqube",
   >       "-a", "sonarqube-relay", # this is the alias you set up in the Cortex UI
   >     ]
   > ```

### Step 2: Running the agent

You can run Axon Relay in one of two ways:

* **In a production environment**
  * Use the Helm chart provided by Cortex.
* **In a sandbox environment**
  1. In your CLI, run the command `docker compose up`. \
     The agent starts and connects to Cortex.
  2. Verify that your agent is working:
     1. From the main sidebar in Cortex, expand **Integrations**, then select **Configurations**.
     2. Locate the integration, then click **Settings**.
     3. On the integration's **Settings** page, click **Test all** at the top right.

        * If watching the logging output in your CLI, you'll see the agent receive the request and forward it to your internal service.
        * Check the message in the bottom-right corner of the screen to see whether the test succeeded.

### Examples

See examples of using Axon Relay with unsupported tools in the [Cortex Axon repository](https://github.com/cortexapps/axon/tree/main/examples).


# Azure DevOps
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/azuredevops



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Azure DevOps](https://azure.microsoft.com/en-us/products/devops) is a Microsoft-owned version control system used for managing the software development lifecycle.

Integrating Cortex with Azure DevOps allows you to:

* Automatically discover and track ownership of Azure DevOps entities
* Follow a GitOps workflow with Azure DevOps
* View information about your Azure DevOps repositories on an entity's details page, including: The repo associated with the entity, recent commits and releases in the event timeline, the most-used language in the files for that entity, the top code contributors, and their number of contributions
  * If you pull in [Azure DevOps pipeline data](/ingesting-data-into-cortex/integrations/azuredevops#define-pipelines), you can also see pipeline runs and builds in the CI/CD section of an entity's details page.
  * If you enable the [option to pull in Azure DevOps work items](/ingesting-data-into-cortex/integrations/azuredevops#enable-or-disable-azure-devops-work-items), you will also see a list of open work items on entity pages.
* View information about pull requests and work items in the engineering homepage
* [Create a work item from an Initiative issue](/ingesting-data-into-cortex/integrations/azuredevops#create-a-work-item-from-an-initiative-issue) in Cortex
* Use Azure DevOps metrics in Eng Intelligence to understand key metrics and gain insight into services, incident response, and more
* Create [Scorecards](/ingesting-data-into-cortex/integrations/azuredevops#scorecards-and-cql) that track progress and drive alignment on projects involving your repositories, Azure DevOps work items, and Azure DevOps pipeline data

## How to configure Azure DevOps with Cortex

### Configure the integration in Cortex

You can configure Azure DevOps with a Personal Access Token (PAT) or with a Service Principal with Entra ID.

> **Personal access token**
>
> **Prerequisites**
>
> 1. Add a [Azure DevOps personal access token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) with at least the following scopes enabled:
>
> * Analytics - `read`
> * Build - `read`
> * Code - `read`
>   * If using the [Scaffolder](/streamline/workflows/scaffolder) with Azure DevOps, you must also enable:
>     * Code - `write`
>     * Code - `manage`
> * Graph & Identity - `read`
> * Work Items - `read` and `write`
>
> **Configure the Azure DevOps integration with a PAT**
>
> 1. In Cortex, navigate to the [Azure DevOps settings page](https://app.getcortexapp.com/admin/integrations/azuredevops).
>
> * Click **Integrations** from the main nav. Search for and select **Azure DevOps**.
>
> 2. Click **Add configuration** and select **Personal Access Token**.
>
> 3. Configure the Azure DevOps integration form:
>
> * **Organization** - Enter the slug for your Azure DevOps organization.
>
> * **Username** - Enter the username for your personal access token.
>
> * **Personal access token** - Enter your Azure DevOps personal access token.
>
> * **Host** - Optionally, if you are using a self-managed setup, enter your hostname.
>
> 4. Click **Save**.

> **Service principal**
>
> **Prerequisites**
>
> 1. In your Azure portal under **Entra ID > App registrations**, [set up an app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-credentials).
>
> * You will need the Client ID and Azure Tenant ID associated with this app registration.
>
> * When you create an app registration, a Service Principal user is also generated.
>
> 2. In your Azure portal, create a Client Secret for your app registration.
>
> * While viewing the overview of your app registration, click the link next to "Client credentials." You will be directed to the **Certificates & secrets** page, where you can click **+New client secret** to create a secret.
>
> **Step 1: Add your Service Principal to your Azure DevOps organization**
>
> You must add the Service Principal user to the organization you're integrating with Cortex.
>
> 1. In Azure DevOps, from the list of organizations, select the one you will be integrating with Cortex.
>
> 2. Navigate to **Organization Settings > General > Microsoft Entra**. Connect your Entra ID directory (the one containing the app registration) with the Azure DevOps organization.
>
> 3. Navigate to **Organization Settings > General > Users,** then click **Add users**.
>
> 4. In the side panel, configure the new user:
>
> * **Users or Service Principals**: Enter the Service Principal associated with your app registration.
> * **Access level**: Select `Basic`.
> * **Add to projects**: Add the user to the project(s) that your Cortex integration will need access to.
> * **Azure DevOps Groups**: Select security groups. `Project Contributors` should be sufficient, or you can choose a custom security group that has Code write permissions.
>   * Learn more about [permissions for Service Principals in Azure's documentation](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity?view=azure-devops#step-3-configure-permissions).
>
> 5. At the bottom of the side panel, click **Add**.
>
> **Step 2: Configure the Azure DevOps integration in Cortex**
>
> 1. In Cortex, navigate to the [Azure DevOps settings page](https://app.getcortexapp.com/admin/integrations/azuredevops).
>
> * Click **Integrations** from the main nav. Search for and select **Azure DevOps**.
>
> 2. Click **Add configuration** and select **Service Principal**.
>
> 3. Configure the Azure DevOps integration form:
>
> * **Category**: Select which integration categories this configuration will apply to.
>
> * **Configuration alias**: Enter an alias for this configuration.
>
> * **Organization**: Enter the slug for your Azure DevOps organization.
>
> * **Client ID**: Enter the Application Client ID for your app registration.
>
> * **Client Secret**: Enter the Client Secret for your app registration.
>
> * **Azure Tenant ID**: Enter the Directory (Tenant) ID for your app registration.
>
> * **Host**: Optionally, if you are using a self-managed setup, enter your hostname.
>
> 4. Click **Save**.

Cortex supports mapping multiple identities for a single user if you have multiple configurations of Azure DevOps. See the [Identity mapping documentation](/configure/settings/managing-users/identity-mapping) for more information.

#### **Enable or disable Azure DevOps work items**

On the [Azure DevOps settings page in Cortex](https://app.getcortexapp.com/admin/settings/azuredevops), you can choose whether Azure DevOps work items should be pulled in from Azure DevOps. Cortex recommends disabling this option if your organization does not use work items or if you are worried about running into rate limit issues.

## How to connect Cortex entities to Azure DevOps

### Import entities from Azure DevOps

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#importing-services-from-an-integration) for instructions on importing entities.

### Editing the entity descriptor

In an entity's YAML, you can define a [repository](/ingesting-data-into-cortex/integrations/azuredevops#define-a-repository), [work items](/ingesting-data-into-cortex/integrations/azuredevops#define-work-items), [ownership](/ingesting-data-into-cortex/integrations/azuredevops#syncing-ownership-from-azure-devops), and [pipelines](/ingesting-data-into-cortex/integrations/azuredevops#define-pipelines).

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

#### **Define a repository**

To define an Azure DevOps repository for a given entity, add the `x-cortex-git` block to the entity's descriptor.

```yaml theme={null}
x-cortex-git:
  azure:
    project: cortex
    repository: docs
    basepath: myService
    alias: accountAlias
```

| Field | Description | Required |
| - | - | - |
| `project` | The name of the project as listed under the "Projects" tab when you are logged into Azure DevOps (on the [https://dev.azure.com//](https://dev.azure.com//) screen) | **✓** |
| `repository` | The repo name you see when you navigate to the "Repos" section of Azure DevOps | **✓** |
| `basepath` | If the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdir | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

Only one repository can be defined for in a given entity's YAML in the `x-cortex-git` block.

#### **Define work items**

Before adding work items to your entity YAML, make sure you have [enabled the option to pull in Azure DevOps work items](/ingesting-data-into-cortex/integrations/azuredevops#enable-or-disable-azure-devops-work-items) in your integration settings.

To define Azure DevOps work items for a given entity, add the `x-cortex-azure-devops` block to the entity's descriptor. If there is no work item registrations, but the entity matches a repository, we will pull in all work items from the repository's project with a tag that matches the Cortex entity name, [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag), or the repository name.

> **Example WIQL**
>
> The example YAML below is based on the following example WIQL:
>
> ```
> SELECT
>     [System.Id],
>     [System.AssignedTo],
>     [System.State],
>     [System.Title],
>     [System.Tags]
> FROM workitems
> WHERE
>     '[System.TeamProject] = Design Agile'
>     AND '[System.WorkItemType] = User Story'
>     AND '[System.State] = Active'
> ORDER BY [System.ChangedDate] DESC
> ASOF '02-11-2020'
> ```
>
> Learn more about WIQL in [Microsoft's WIQL syntax reference](https://learn.microsoft.com/en-us/azure/devops/boards/queries/wiql-syntax?view=azure-devops).

```yaml theme={null}
x-cortex-azure-devops:
    workItems:
        projects:
            - name: projectName1
              wiqls:
                - "[System.TeamProject] = 'Design Agile'"
                - "[System.WorkItemType] = 'User Story'"
                - "[System.State] = 'Active'"
                - ORDER BY [System.ChangedDate] DESC ASOF '02-11-2020'
            - name: projectName2
              alias: alias1
            - name: projectName3
              alias: alias2
```

| Field | Description | Required |
| - | - | - |
| `projects` | List of the projects | **✓** |
| `name` | The project name as listed under the "Projects" tab when you are logged into Azure DevOps (on the [https://dev.azure.com//](https://dev.azure.com//) screen) | **✓** |
| `wiqls` | List of WIQL conditions to filter work items fetched | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

#### Syncing ownership from Azure DevOps

Ownership of each entity through Azure DevOps is defined through an owner of type `group`.

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: My Azure DevOps Team
    provider: AZURE_DEVOPS
    description: This is a description for this owner # optional
```

`name` is a case-sensitive field that corresponds to the upstream identifier of your owner from Azure DevOps.

Cortex syncs Azure DevOps identities every day at 10 a.m. UTC. Cortex connects team members to their Cortex users through [identity mappings](#identity-mappings-for-azure-devops).

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

#### Define pipelines

You can add Azure DevOps pipelines under the `x-cortex-azure-devops` block:

```yaml theme={null}
  x-cortex-azure-devops:
    pipelines:
      projects:
      - name: projectName1
        alias: config-1
        pipelines:
        - id: 1
      - name: projectName2
        alias: config-2
        pipelines:
        - id: 2
```

| Field | Description | Required |
| - | - | - |
| `piepelines` | List of the pipelines | **✓** |
| `projects` | List of the projects | **✓** |
| `name` | The project name as listed under the "Projects" tab when you are logged into Azure DevOps (on the [https://dev.azure.com//](https://dev.azure.com//) screen) | **✓** |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |
| `pipelines:id` | The Azure DevOps `system.definitionID` for the pipeline. | **✓** |

Learn more about Azure DevOps pipelines in [Microsoft's documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/get-started/what-is-azure-pipelines?view=azure-devops).

### Identity mappings for Azure DevOps

Cortex maps users' email addresses to discovered Azure DevOps accounts.

You can confirm users' Azure DevOps accounts are connected from [Azure DevOps identity mappings in settings](https://app.getcortexapp.com/admin/settings/azuredevops-mappings).

### Create a work item from an Initiative issue

Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.

From the Issues tab of an Initiative, you can automatically create a Azure DevOps work item from a failing rule:

1. Click **Create issue**.
2. In the modal that appears, fill out the form:
   * **Integration**: If you have multiple task tracking tools, select Azure DevOps from the Integration dropdown.
   * **Name**: Enter a name for the configuration.
   * **Project**: Select from the dropdown.
     * Options available in the dropdown are pulled in from the specific Azure DevOps instances configured in Settings.
3. Select the [**Work item type**](https://learn.microsoft.com/en-us/azure/devops/boards/work-items/about-work-items?view=azure-devops\&tabs=agile-process/) and the **Sub-item Type** from the respective dropdowns. Then, select how the sub-items's fields should be populated on issue creation and status change.
4. Choose to include or exclude groups of entities, or define a more advanced filter.

The issue configuration will apply to all entities that meet the filter criteria. Once an entity is passing the rule, Cortex will automatically close the associated ticket.

## Using the Azure DevOps integration

### View Azure DevOps data on entity pages in Cortex

The Azure DevOps integration will populate the **Repo** detail block on an entity's details page.

In the **Recent activity preview**, you'll find the recent commits and releases. These will also appear in the event timeline.

These data will appear for entities imported from a Git source or those that have a Git repo defined in their YAMLs.

#### **Events**

On an entity's **Events** page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in Azure DevOps and includes a timestamp.

#### **CI/CD**

From the **CI/CD > Deploys** page in the entity's sidebar, see a history of pipeline runs.

#### **Repository**

You can access more detailed information pulled from Azure DevOps under **Repository** in the sidebar. At the top of the repository page, you'll find the repo associated with that entity and the most-used language in files for that entity. In the **Top contributors** block, you'll find the three users who have contributed the most code and the number of their contributions.

In the **Commits** section, you'll find the 10 most recent commits and metadata about each. Below **Commits** is the **Recent releases** section, which includes the 5 most recent releases.

#### **Issue tracking**

In the **Issue tracking** section, you can find a list of open [Azure DevOps work items](https://learn.microsoft.com/en-us/azure/devops/boards/work-items/about-work-items?view=azure-devops\&tabs=agile-process). Each work item will show the title, summary, assignees, priority, and date created.

#### **Packages**

Packages are automatically scraped from your Git repos or they can be submitted via the [packages API](/api/rest/packages). The package file must be in the root of your repository — or, if you're using `basepath`, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) using `packages()`.

To view packages, click **Packages** in the entity's sidebar.

The following package types are automatically scraped from repositories:

* JavaScript / Node.js: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Python: `requirements.txt`, `pipfile.lock`
* .NET (C#): `packages.lock.json`
* Java: `pom.xml`
* Go: `go.sum`

All other files of these types can be added via the [packages API](/api/rest/packages).

### Engineering homepage

The Azure DevOps integration enables Cortex to pull information about pull requests and work items into the [homepage](/streamline/homepage). You can find your open pull requests, any pull requests assigned to you for review, and any work items assigned to you.

Pull requests and work items from Azure DevOps are refreshed every 5 minutes.

### Eng Intelligence

The [Eng Intelligence tool](https://app.getcortexapp.com/admin/eng-intelligence) also uses pull request data from Azure DevOps to generate metrics:

* Average PR open to close time
* Avg time to first review
* Avg time to approval
* PRs opened
* Weekly PRs merged
* Avg PRs reviewed/week
* Avg commits per PR

Read more about how Eng Intelligence tracks metrics for teams and users in the [Eng Intelligence documentation](/improve/eng-intelligence).

### Scorecards and CQL

With the Azure DevOps integration, you can create Scorecard rules and write CQL queries based on Azure DevOps work items.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Approvals required to merge**
>
> Total number of approval required to merge a pull request into a repository. Defaults to 0 if no approvals are defined.
>
> **Definition:** `git.numOfRequiredApprovals()`
>
> **Examples**
>
> For a security or development maturity Scorecard, you can write a rule to make sure at least one approval is required for a pull request:
>
> ```
> git.numOfRequiredApprovals() >= 1
> ```
>
> By having a rigorous PR process in place for a repo, you can make sure changes aren't made that create vulnerabilities. This kind of rule could also be used in a best practices or project standards Scorecard.
>
> You can also use a similar expression in the Query Builder to find entities lacking approval:
>
> ```
> git.numOfRequiredApprovals() < 1
> ```

> **Branches**
>
> List all live branches with some basic metadata:
>
> * Head
> * Is protected
> * Name
>
> **Definition:** `git.branches(): List<GitBranch>`
>
> **Example**
>
> For a development best practices Scorecard, you can make sure that branches associated with an entity match a standard naming convention:
>
> ```
> git.branches().all((branch) => branch.name.matches("(main|master|feat-.*|bug-.*|task-.*
> ```

> **Branch protection details**
>
> Find details for a specified branch or default branch if none is specified.
>
> **Definition:** `git.branchProtection(branchName: Text?): GitBranchProtection`
>
> **Examples**
>
> For a security Scorecard, you can write a rule to make sure the default branch is protected:
>
> ```
> git.branchProtection() != null
> ```
>
> Or to make sure the main branch is protected:
>
> ```
> git.branchProtection("main") != null
> ```
>
> Because vulnerabilities in the default branch are critical, this rule should be in one of the first couple levels. A higher-level rule might make sure that branch protection checks are set:
>
> ```
> git.branchProtection("main").requiredStatusChecks.length > 0
> ```
>
> You can also use the Query Builder to find entities with unprotected default branches:
>
> ```
> git.branchProtection() = null
> ```

> **Commits**
>
> Get the latest commits (to a maximum of 100) for a defined lookback period (defaulting to 7 days).
>
> These results can be filtered based on branch name, using the default branch if no other branch is provided.
>
> **Definition:** `git.commits()`
>
> **Examples**
>
> You can use the `git.commits()` expression in a security Scorecard to make sure entities have fewer than three commits to a "security-fixes" branch in the last week:
>
> ```
> git.commits(branch="security-fixes").length < 3
> ```
>
> Entities passing this rule will include those that haven't needed three or more security fixes. This can indicate that there aren't vulnerabilities in a given entity's code, but could also suggest that fixes aren't being implemented.
>
> Using this rule in conjunction with one focused on vulnerabilities could provide the extra context needed to gain a better understanding of what's happening.

> **Default branch**
>
> Default branch for the entity's repository or `main` when null.
>
> **Definition:** `git.defaultBranch()`
>
> **Examples**
>
> If default branches should always be named "main," you can write a rule in a best practices Scorecard to make sure entities are compliant:
>
> ```
> git.defaultBranch().matches("main")
> ```

> **File contents**
>
> Load the contents of a file from the entity's associated repository.
>
> The contents can be validated by using string comparison operations or parsed by the built-in `jq` function. The `jq` function will automatically coerce file contents of JSON or YAML formats.
>
> **Definition:** `git.fileContents(<filename: Text>)`
>
> **Examples**
>
> For a Scorecard focused on development maturity, you could use the `git.fileContents()` rule to enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline:
>
> ```
> git.fileContents(“circleci/config.yml”).matches(“.*npm test.*”) - Enforce that a CI pipeline exists, and there is a testing step defined in the pipeline
> ```
>
> A best practices Scorecard, meanwhile, could use this expression for a number of rules:
>
> * To make sure node engine version in specified in the `package.json` file:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.node") != null
>   ```
> * To make sure TypeScript projects have a `tsconfig.json` file checked in:
>
>   ```
>   jq(git.fileContents("package.json"), ".devDependencies | with_entries(select(.key == \"typescript\")) | length") == 0 or git.fileExists("tsconfig.json")
>   ```
> * To make sure projects using yarn do not allow NPM:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.yarn") == null or jq(git.fileContents("package.json"), ".engine.npm") = "please-use-yarn"
>   ```
> * And to ensure the yarn version being used is not deprecated:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.yarn") == null or !(semver("1.2.0") ~= semverRange(jq(git.fileContents("package.json"), ".engines.yarn")))
>   ```

> **File exists**
>
> Check if file exists from within the entity's associated repository.
>
> **Definition:** `git.fileExists(<filename: Text>)`
>
> **Examples**
>
> For a development best practices Scorecard, this expression can be used for a rule that makes sure developers are checking in lockfiles to ensure repeatable builds:
>
> ```
> git.fileExists(“package-lock.json”)
> ```
>
> In the Query builder, you can use this expression with a wildcard to find entities with unit tests enabled:
>
> ```
> git.fileExists(*Test.java”)
> ```
>
> Or to find entities with an outdated Terraform version:
>
> ```
> git.fileExists("terraform/versions.tf") and !git.fileContents("terraform/versions.tf").matchesIn("required_version =! \"[~>= ]{0,3}0\\.(12|13)")
> ```

> **Has Cortex YAML (GitOps)**
>
> When enabling GitOps to manage entity descriptors, Cortex checks for a checked in file `./cortex.yaml` at the root directory. This rule can help track migrations from UI editing to GitOps for entity descriptor management.
>
> **Definition:** `git.hasCortexYaml()`
>
> **Examples**
>
> If you're using a Scorecard to track a migration from Cortex UI to GitOps, you can use this rule to make sure entities are set up for GitOps management of entity descriptors:
>
> ```
> git.hasCortexYaml() == true
> ```

> **Git repository set**
>
> Check if entity has a registered Git repository.
>
> **Definition:** `git (==/!=) null`
>
> **Examples**
>
> A Scorecard focused on best practices or standards will likely include a rule in its first level making sure a Git repository is set up:
>
> ```
> git != null
> ```
>
> If an entity is failing this rule, it can indicate broader issues with the integration or explain why an entity isn't functioning as expected.

> **Last commit details**
>
> Provides last commit details.
>
> **Definition:** `git.lastCommit()`
>
> **Examples**
>
> Depending on best practices at your organization, you may want to confirm the last commit for a given entity is no older than 3 days:
>
> ```
> datetime(git.lastCommit().date).fromNow() > duration("P-3D")
> ```
>
> Confirming whether a service was updated recently can help team members catch outdated code sooner. Plus, if there is a security issue, you can quickly determine which services have or have not been updated to patch the vulnerability.
>
> For a best practices Scorecard, you can also use this expression to make sure the entity's last commit message follows conventional commit guidelines:
>
> ```
> git.lastCommit().message.matches("^(feat|fix|docs|style|refactor|test|chore)(\\(.+\\))?:*")
> ```

> **List pipelines**
>
> List pipelines with metadata, including name, id, url, and project name.
>
> **Definition**: `azureDevops.pipelines()`
>
> **Examples**
>
> You could write a Scorecard rule to ensure that the entity has at least 1 pipeline that scans vulnerabilities:
>
> ```
> azureDevops.pipelines().any(pipeline => pipeline.name.matchesIn("Vuln scan"))
> ```
>
> You could write a Scorecard rule to ensure that the entity has an Azure DevOps pipeline set:
>
> ```
> azureDevops.pipelines() != null
> ```

> **Pipeline build success rate**
>
> Percentage of build pipelines that complete successfully.
>
> This is calculated against builds on the default branch for commits in the last 30 days: `# successful builds / (# successful + # failed)`.
>
> **Definition:** `git.percentBuildSuccess()`
>
> **Examples**
>
> This expression can be used in a development maturity Scorecard to write a rule making sure at least 95% of build runs are successful:
>
> ```
> git.percentBuildSuccess() >= 0.95
> ```

> **Pipeline metrics**
>
> List pipelines with metrics. Metrics contains the successRate & averageDuration of a pipeline.
>
> **Definition**: `azureDevops.pipelineMetrics()`
>
> **Examples**
>
> You could write a Scorecard rule to ensure pipelines have a successRate higher than 95%:
>
> ```
> azureDevops.pipelineMetrics().all((pipeline) => pipeline.metrics.successRate > 0.95)
> ```

> **Pipeline runs**
>
> Get pipelines runs meeting the given filter criteria, which includes results, states. Results include "succeeded", "failed", "canceled", "unknown", states include "completed", "inProgress", "canceling", "unknown".
>
> **Definition**: `azureDevops.pipelineRuns()`
>
> **Examples**
>
> List pipeline runs that are opened and reviewed within 1 day:
>
> ```
> azureDevops.pipelineRuns().filter(run => run.run.completedDate != null).map((run) => run.run.createdDate.until(run.run.completedDate)).averageDuration() < duration("P1D")
> ```

> **Pull requests**
>
> Lists pull requests opened during a defined lookback period.
>
> * Approval date
> * Author
> * Date closed
> * Date opened
> * First review date
> * Is draft
> * Last updated
> * Number of commits
> * Number of lines added
> * Number of lines deleted
> * Organization
> * Repository
> * Source
> * Status
> * URL
>
> **Definition:** `git.pullRequests()`
>
> **Example**
>
> You can use the `git.pullRequests()` query to find entities that have a small number of pull requests opened in the last two weeks:
>
> ```
> git.pullRequests(lookback=duration("P14D")).length < 3
> ```
>
> This can highlight entities that haven't been updated recently, which may be especially useful when entities have to be updated to address a vulnerability.
>
> **Example**
>
> You can count only non-draft pull requests:
>
> ```
> git.pullRequests(lookback=duration("P14D")).filter(pr => !pr.isDraft).length < 3
> ```

> **Recency of last commit**
>
> Calculates the duration of time between Scorecard evaluation and the date of the last commit from the entity's Git repository.
>
> **Definition:** `git.lastCommit().freshness`
>
> **Examples**
>
> One of the first rules you might write for a Scorecard focused on development maturity or security is one validating that the last commit was within the last month:
>
> ```
> git.lastCommit().freshness < duration("P1M")
> ```
>
> As counterintuitive as it may seem, services that are committed too infrequently are actually at more risk. People who are familiar with the service may leave a team, institutional knowledge accumulates, and from a technical standpoint, the service may be running outdated versions of your platform tooling.

> **Reviews**
>
> List reviews left during a defined lookback period.
>
> * Organization
> * Repository
> * Review date
> * Reviewer
>
> **Definition:** `git.reviews()`
>
> **Examples**
>
> A development maturity Scorecard might use the `git.reviews()` expression to make sure that there is a rigorous review process in place before changes are implemented:
>
> ```
> git.reviews(lookback=duration("P7D")).length > 25
> ```
>
> This rule makes sure that there are more than 25 reviews left in the last week.

> **Search repository files**
>
> Find all instances of code search query from within a repository.
>
> Can filter by path, file name (extension required in file name), or extension. Filters can use \* for glob matching. Supplying a query is required.
>
> **Definition:** `git.codeSearch((query = <query: Text>) (, path = <path: Text>) (, fileName = <fileName: Text>) (, fileExtension = <fileExtension: Text>)): List<GitSearchResult>`
>
> **Examples**
>
> You can use the `git.codeSearch()` expression to query for entities that have certain components, like icons:
>
> ```
> git.codeSearch(query = "icon", fileExtension = "css").length > 0
> ```

> **Top repository language**
>
> Find top used language for a repository, if available.
>
> **Definition:** `git.topLanguage()`
>
> **Examples**
>
> Let's say the primary language developers should be using is Kotlin. You can write a rule to make sure that the top language associated with entities is Kotlin:
>
> ```
> git.topLanguage() == "kotlin"
> ```
>
> You can also use this expression to query for entities that don't have Kotlin as the top language to identify those that need to be updated:
>
> ```
> git.topLanguage() != "kotlin"
> ```

> **Work items**
>
> Number of **unresolved** work items associated with the entity, where unresolved is defined as the WIQL \[System.State] NOT IN ('Closed', 'Done', 'Completed', 'Inactive', 'Removed').
>
> **Definition:** `azureDevops.workItems()`
>
> **Examples**
>
> For a Scorecard measuring entity maturity, you can use this expression to make sure entities have fewer than 10 Azure DevOps work items:
>
> ```
> azureDevops.workItems().length <= 10
> ```

> **Work items from WIQL query**
>
> Number of work items associated with the entity based on arbitrary WIQL query.
>
> **Definition:** `azureDevops.workItems(query: Text | Null)`
>
> **Examples**
>
> For a more specific rule in an entity maturity Scorecard, you can use this expression with a WIQL query to make sure entities have no more than 3 tickets with "Doing" status and highest priority.
>
> ```
> jira.workItems("System.State = \"Doing\" AND Microsoft.VSTS.Common.Priority = 1").length <= 3
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts a background sync of Azure DevOps identities every day at 10 a.m. UTC. Pull requests and work items are refreshed every 5 minutes.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Azure Resources
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/azureresources



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Azure Resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/overview) provides on-demand cloud computing platforms and APIs. Cortex uses the Azure Resource API to pull in resource details and import entities such as SQL servers, virtual machines, virtual networks, load balancers, and others.

Integrating Azure Resources with Cortex allows you to:

* [Automatically import entities](/ingesting-data-into-cortex/integrations/azureresources#enable-automatic-discovery-of-azure-resource-entities) and track ownership of entities
* Create [Scorecards](/ingesting-data-into-cortex/integrations/azureresources#scorecards-and-cql) to drive alignment and track progress on projects involving resources from Azure

> [!NOTE]
>
> Cortex conducts a background sync of Azure Resources every day at 00:00 a.m. UTC and an ownership sync every day at 6 a.m. UTC.

## How to configure Azure Resources with Cortex

### Prerequisites

Before getting started, you will need the following information. These can be found in the **Enterprise applications** section of Azure:

* Azure tenant ID
* Azure client ID and [client secret](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-credentials)
* Azure subscription ID
  * Ensure that the service principal for the subscription ID has a [Reader role](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#assign-a-role-to-the-application).

### Configure the integration in Cortex

1. In Cortex, navigate to the [Azure Resources settings page](https://app.getcortexapp.com/admin/integrations/azureresources).
   * Click **Integrations** from the main nav. Search for and select **Azure Resources**.
2. Click **Add configuration**.
3. Configure the Azure Resources integration form:
   * **Account alias**: Enter your Azure account alias. Account aliases are used to tie service registrations to different configuration accounts.
   * **Azure tenant ID**: Enter your Azure tenant ID.
   * **Client ID** and **Client secret**: Enter your Azure client ID and secret.
   * **Subscription ID**: Enter your Azure subscription ID.
4. Click **Save**.
   * You will be redirected to the Azure Resources Settings page in Cortex, where you can optionally choose to include only specified Azure resource types for this integration. You can also enable [automatic import](/ingesting-data-into-cortex/integrations/azureresources#enable-automatic-discovery-of-azure-resource-entities) for any discovered entities of known types.

After saving your configuration, you are redirected to the integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Azure Resources was configured properly.

## How to connect entities to Azure Resources

> [!NOTE]
>
> For Azure Resources, Cortex replaces non-alphanumeric characters in entity names with a space. For example, `resource_1` would become `resource 1`.
>
> For the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag), Cortex replaces non-alphanumeric characters with `-` and lowercases the letters. If multiple special characters appear together in a tag, Cortex replaces the group of characters with only one `-`. For example, `mY_e%ntity#$_tag` would become `my-e-ntity-tag`.

### Enable automatic discovery of Azure Resource entities

You can configure automatic import from Azure:

1. In Cortex, navigate to the [Entities Settings page](https://app.getcortexapp.com/admin/settings/entities).
2. Next to **Auto import from AWS, Azure, and/or Google Cloud**, click the toggle to enable the import.

   ![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/auto-import-entities%20%281%29.jpeg)

### Syncing ownership from Azure Resources

Cortex can automatically discover ownership for your Azure resources from their tags. Tag each resource with the `x-cortex-tag` of the Cortex team that owns it. By default, Cortex looks for the `owner` tag, but you can customize the tag key name.

> [!NOTE]
>
> Cortex syncs ownership from Azure Resources every day at 6 a.m. UTC.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

To enable ownership sync:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Azure Resources, then click **Settings**. The **Azure Resources** settings page opens.
3. Select the **Integration settings** tab.
4. In the **Sync ownership from Azure** section, toggle on **Enable ownership sync from Azure Resources**.
5. Optionally, select a custom tag key name for ownership sync. By default, Cortex looks for the `owner` tag on each resource.

### Define a dependency

Cortex automatically discovers dependencies between your services and resources by scanning for resources with specific Azure Resources tags. By default, a service will have dependencies on any Cortex resource that has a corresponding Azure Resources resource with Azure Resources tag key = "service" and tag value = the service's Cortex tag.

On the [Azure Resources settings page](https://app.getcortexapp.com/admin/settings/azureresources), you can customize the tag key names for dependencies.

For more information on defining dependencies, please see the [Dependencies documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies).

### Import entities from Azure Resources

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#importing-services-from-an-integration) for instructions on importing entities.

### Editing the entity descriptor

You can associate a Cortex entity with one or more Azure Resources entities. Cortex will display those Azure Resources entities' metadata on the Cortex entity page.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

When the entity is connected to Azure, the entity YAML will look like the following:

```yaml theme={null}
x-cortex-azure:
  ids:
  - id: /subscriptions/1fbb2da1-2ce7-45e4-b85f-676ab8e685b9/resourceGroups/GROUP1/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e9
    alias: my-default-alias # alias is optional and only relevant if you have opted into multi account support
  - id: /subscriptions/1fbb2da1-2ce8-45e4-b85f-676ab8e685b0/resourceGroups/GROUP2/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e0
    alias: my-other-alias # alias is optional and only relevant if you have opted into multi account support
```

## Using the Azure Resources integrations

### Scorecards and CQL

With the Azure Resources integration, you can create Scorecard rules and write CQL queries based on Azure Resources details.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Get Azure Resource details for entity**
>
> Get Azure Resource details for an entity.
>
> **Definition:** `azureResource.details(): Object`
>
> **Examples**
>
> In a Scorecard, you can write a rule to make sure an entity has Azure Resource details:
>
> ```
> azureResource.details() != null
> ```
>
> Make sure an entity has an environment tag:
>
> ```
> azureResource.details().resources.filter((resource) => jq(resource, ".metadata.\"environment\"") != null).length > 0
> ```
>
> Make sure an entity has a health check:
>
> ```
> jq(azureResource.details(), ".resources[].metadata.siteConfig.healthCheckPath") != null
> ```
>
> Make sure an entity has a tag with a certain key and value:
>
> ```
> azureResource.details().resources.filter((resource) => resource.tags.get("tag-key") == "tag-value").length > 0
> ```

> **Availability zones**
>
> Availability zone data (VM Scale Sets, Redis, Application Gateways) is a first-class `.zones` field, sourced directly from Azure Resource Graph.
> If you have existing "Resource Redundancy" rules for these resource types, update them to reference `.zones` instead of deriving zone data from the ARM export template.
>
> **Example**
>
> ```
> azureResource.details().resources.filter((resource) => resource.zones != null && resource.zones.length > 0).length > 0
> ```

> **App Service health-check path and minimum TLS version**
>
> Cortex reads App Service configuration data, including `healthCheckPath` and minimum TLS version.
> Existing "Health Check" and App Service Scorecard rules will continue to work as-is, no Scorecard rule changes needed.
>
> **Example**
>
> ```
> azureResource.details().resources.filter((resource) => resource.zones != null && resource.zones.length > 0).length > 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

See frequently asked questions below.

> **Why is the Azure resource type `microsoft-resources-subscriptions-resourcegroups` not pulling in Azure Resource details?**
>
> Cortex pulls from the Azure Resource API, but not from the Azure Resource Group API. If you would like to submit a feature request for support of Azure Resource Groups, please contact our customer engineering team.

> **Why is ARM template data sometimes missing or stale?**
>
> Cortex uses the Azure ARM export template endpoint to ingest resource data for some resource types. This endpoint has known reliability limitations [acknowledged in Microsoft's documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/export-template-portal#limitations), which can cause intermittent failures that result in missing or outdated data.
>
> Cortex is actively migrating away from ARM template-based ingestion toward Azure Resource Graph and the resource metadata endpoint. In the interim, if you see empty or stale data for a resource, this is likely caused by an ARM export failure on the Microsoft side.


# BambooHR
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/bamboohr



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

[BambooHR](https://www.bamboohr.com/) is a Human Resources Information System (HRIS) solution that allows you to define organizational membership. Integrate Cortex with BambooHR to automatically sync team memberships, giving you insight into entity ownership.

## How to configure BambooHR with Cortex

### Prerequisite

Before getting started, create a [BambooHR API key](https://documentation.bamboohr.com/docs#section-authentication).

### Configure the integration in Cortex

1. In Cortex, navigate to the [BambooHR settings page](https://app.getcortexapp.com/admin/integrations/bamboohr).
   * Click **Integrations** from the main nav. Search for and select **BambooHR**.
2. Click **Add configuration**.
3. Configure the BambooHR integration form:
   * **Subdomain**: Enter your BambooHR subdomain.
     * This can be found in your app URL, e.g., `subdomain.bamboohr.com`.
   * **API token**: Enter your BambooHR API token.
   * **Report ID**: Optionally, enter a Report ID to filter the list of employees.
     * We recommend entering a Report ID if you have a custom BambooHR Report that has the authoritative list of active employees.
     * This value can be found in the app URL, e.g., `subdomain.bamboohr.comreports/custom/New+Hires/REPORTID`
   * **Employee ownership field**: Optionally, enter the ownership field name.
     * If left blank, Cortex defaults to finding the list of employees using their `division` followed by their `department`.
4. Click **Save**.

## How to connect Cortex entities to BambooHR

### Import entities from BambooHR

See the [Create teams documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#importing-teams-from-an-integration) for instructions on importing entities.

### Syncing ownership from BambooHR

Ownership of each catalog entity through BambooHR is defined through an owner of type `group`.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: My Bamboo HR Team
    provider: BAMBOO_HR
    description: This is a description for this owner # optional
```

The `name` should exactly match the team value Cortex reads from BambooHR. See **Employee ownership field** in [Configure the integration in Cortex](/ingesting-data-into-cortex/integrations/bamboohr#configure-the-integration-in-cortex).

Cortex syncs BambooHR teams every day at 6 a.m. UTC. You don't need identity mappings for BambooHR teams. Cortex uses each member's email address from BambooHR.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

## Using the BambooHR integration

### Scorecards and CQL

With the BambooHR integration, you can create Scorecard rules and write CQL queries based on BambooHR teams.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity
>
> **Definition:** `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts an ownership sync for BambooHR teams every day at 6 a.m. UTC.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Bitbucket
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/bitbucket



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Bitbucket](https://bitbucket.org/product/) is a Git-based version control system from Atlassian. You can use Bitbucket to drive insights into repository details in the Catalog and Scorecard rules.

Integrating Bitbucket with Cortex allows you to:

* Discover and track ownership of Bitbucket entities
* [View Bitbucket data on entity pages](/ingesting-data-into-cortex/integrations/bitbucket#view-bitbucket-information-on-entity-pages-in-cortex) in Cortex
* Follow a [GitOps](/configure/gitops) workflow with Bitbucket
* View information about pull requests in the [engineering homepage](/ingesting-data-into-cortex/integrations/bitbucket#engineering-homepage)
* Use Bitbucket metrics in [Eng Intelligence](/ingesting-data-into-cortex/integrations/bitbucket#eng-intelligence) to understand key metrics and gain insight into services, incident response, and more
* Create [Scorecards](/ingesting-data-into-cortex/integrations/bitbucket#scorecards-and-cql) that track progress and drive alignment on projects involving your Bitbucket repositories

> [!NOTE]
>
> Bitbucket data in [Eng Intelligence](/ingesting-data-into-cortex/integrations/bitbucket#eng-intelligence) and in the [engineering homepage](/ingesting-data-into-cortex/integrations/bitbucket#engineering-homepage) is available in private beta. Please contact your Cortex Customer Success Manager for access.

## How to configure Bitbucket with Cortex

There are multiple options for integrating with Bitbucket:

* Cloud: Using a workspace token (recommended), the Cortex Atlassian app, or an app password.
* On-prem: Using Basic auth or using OAuth
* You can also integrate using Cortex Axon Relay, a relay broker that allows you to securely connect your on-premises Bitbucket data.

Expand the tabs below for instructions on the method you choose.

> **Workspace token**
>
> **Configure Cortex with Bitbucket using a workspace token**
>
> **Step 1: Generate a workspace token in Bitbucket**
>
> 1. In Bitbucket, navigate to **Settings > Workspace settings > Access tokens**.
> 2. Create a workspace-level access token. Include the following scopes:
>    1. `Repositories: Read`
>    2. `Pull requests: Read`
>
> **Step 2: Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
>    * Click **Integrations** from the main nav. Search for and select **Bitbucket**.
> 2. For the configuration type, select **Cloud (workspace token)**.
>
>    ![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/bitbucket-config-type.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=b80ffb1cb9a6085f1a45e0b94a37e408)
> 3. Configure the form:
>    * **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
>    * **Token**: Enter the workspace token you generated in Bitbucket.
> 4. Click **Save**.
>
> **Step 3: Set your Bitbucket workspace**
>
> 1. On the [Bitbucket Settings page](https://app.getcortexapp.com/admin/settings/bitbucket) in Cortex, next to your integration's alias, click **Add workspace**.
>
>    ![Click on Add workspace](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/bitbucket-add-workspace%20%281%29.jpg)
> 2. In the "Workspace configuration" modal, enter your Workspace name.
>    * You can find this in Bitbucket under **Settings > Workspace settings**.
> 3. Click **Save**.

> **Atlassian App**
>
> **Configure Cortex with Bitbucket using the Atlassian app**
>
> **Step 1: Install the Cortex Atlassian app**
>
> Follow the [installation instructions in the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1225295/cortex?tab=installation\&hosting=cloud) for the Cortex app.
>
> **Step 2: Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
>    * Click **Integrations** from the main nav. Search for and select **Bitbucket**.
> 2. Click **Add Bitbucket configuration**.
> 3. For the configuration type, select select **Atlassian app**.
>
> ![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/bitbucket-config-type.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=b80ffb1cb9a6085f1a45e0b94a37e408)
>
> 4. Configure the "Add Bitbucket configuration" form:
>    * **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
> 5. Click **Save**.
>    * You will be redirected to the Bitbucket Settings page in Cortex.
>
> **Step 3: Connect to Atlassian from Cortex**
>
> 1. On the [Bitbucket settings page](https://app.getcortexapp.com/admin/settings/bitbucket) in Cortex, click **Atlassian Application**. ![Click on Atlassian Application](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/bitbucket-atlassian-app%20%281%29.jpg)
> 2. In the popup that appears, click **Grant access** to authorize Cortex access to your Atlassian Workspace.

> **App password**
>
> **Configure Cortex with Bitbucket using an app password**
>
> > [!WARNING]
> >
> > Bitbucket is [deprecating app passwords on June 9, 2026](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation). If you are currently using an app password, we recommend switching to a workspace token or the Atlassian app before that date.
>
> **Step 1: Create an app password**
>
> * Follow Atlassian's documentation to [create an app password for Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/).
> * Make sure to give the app password the following minimum permissions: `Repositories: Admin`, `Repositories: Read`, `Pull requests: Read`
>
> **Step 2: Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
>    * Click **Integrations** from the main nav. Search for and select **Bitbucket**.
> 2. Click **Add configuration**.
> 3. For the configuration type, select **Cloud (basic auth)**.
>
> ![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/bitbucket-config-type.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=b80ffb1cb9a6085f1a45e0b94a37e408)
>
> 4. Configure the "Add Bitbucket configuration" form:
>    * **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
>    * **Username**: Enter your Bitbucket username.
>      * You can find this in Bitbucket under **Personal settings > Account settings > Bitbucket profile settings**.
>    * **Password**: Enter the app password you created in the previous steps.
> 5. Click **Save**.
>    * You will be redirected to the Bitbucket Settings page.
>
> **Step 3: Set your Bitbucket workspace**
>
> 1. On the [Bitbucket Settings page](https://app.getcortexapp.com/admin/settings/bitbucket) in Cortex, next to your integration's alias, click **Add workspace**.
>
>    ![Click on Add workspace](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/bitbucket-add-workspace%20%281%29.jpg)
> 2. In the "Workspace configuration" modal, enter your Workspace name.
>    * You can find this in Bitbucket under **Settings > Workspace settings**.
> 3. Click **Save**.

> **Basic auth**
>
> **Configure Cortex with Bitbucket using a on-premises basic auth**
>
> > [!WARNING]
> >
> > Bitbucket is [deprecating app passwords on June 9, 2026](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation). If you are currently using an app password for basic auth, we recommend switching to an alternative authentication method before that date.
>
> **Step 1: Create an app password**
>
> * Follow Atlassian's documentation to [create an app password for Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/).
> * Make sure to give the app password the following minimum permissions: `Repositories: Admin`, `Repositories: Read`, `Pull requests: Read`
>
> **Step 2: Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
>    * Click **Integrations** from the main nav. Search for and select **Bitbucket**.
> 2. Click **Add configuration**.
> 3. For the configuration type, select **On-prem (basic auth)**.
>
> ![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/bitbucket-config-type.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=b80ffb1cb9a6085f1a45e0b94a37e408)
>
> 4. Configure the "Add Bitbucket configuration" form:
>    * **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
>    * **Host**: Enter your Bitbucket on-prem host, e.g., `https://bitbucket.example.com`.
>    * **Username**: Enter your Bitbucket username.
>      * You can find this in Bitbucket under **Personal settings > Account settings > Bitbucket profile settings**.
>    * **Password**: Enter the app password you created in the previous steps.
> 5. Click **Save**.
>
> Note: When using an on-premises configuration of Bitbucket, the language does not populate on [entity detail pages](/ingesting-data-into-cortex/integrations/bitbucket#view-bitbucket-information-on-entity-pages-in-cortex).

> **OAuth**
>
> **Configure Cortex with Bitbucket on-premises using OAuth**
>
> > [!NOTE]
> >
> > Scaffolder and Workflow automation are supported with this configuration. See [Registering a Scaffolder template](/streamline/workflows/scaffolder) for setup details.
>
> **Prerequisites**
>
> To configure this integration with on-prem OAuth, you must be running a self-hosted Bitbucket instance with Bitbucket Server or Data Center version 7.20 or higher.
>
> **Step 1: Set up an application link in Bitbucket**
>
> 1. In your Bitbucket server, navigate to **Settings > System > Application Links > Create Link**.
> 2. Configure the application link:
>    * For the application type, select "External Application."
>    * For the direction, select "Incoming."
>    * For the redirect URL:
>      * Default configuration: Enter the URL of your Cortex instance and `/oauth/internal/bitbucket`.
>      * Non-default configuration: Enter the URL of your Cortex instance and `/oauth/internal/bitbucket/{alias}`.
>    * For the Permission, select `Projects: Admin` and `Repositories: Admin`.
> 3. Click **Save**.
> 4. Copy the client ID and client secret. You will need these in the next steps.
>
> **Step 2: Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Bitbucket settings page](https://app.getcortexapp.com/admin/integrations/bitbucket).
>    * Click **Integrations** from the main nav. Search for and select **Bitbucket**.
> 2. Click **Add configuration**.
> 3. For the configuration type, select **On-prem (OAuth)**.
>
>    ![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/bitbucket-config-type.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=b80ffb1cb9a6085f1a45e0b94a37e408)
> 4. Configure the "Add Bitbucket configuration" form:
>    * **Account alias**: Enter an alias for the account. Aliases are used to tie service registrations to different configuration accounts.
>    * **Host**: Enter your Bitbucket on-prem host, e.g., `https://bitbucket.example.com`.
>    * **Client ID**: Enter the client ID you obtained in the previous steps.
>    * **Client secret**: Enter the client secret you obtained in the previous steps.
> 5. Click **Save**.
>
> Note: When using an on-premises configuration of Bitbucket, the language does not populate on [entity detail pages](/ingesting-data-into-cortex/integrations/bitbucket#view-bitbucket-information-on-entity-pages-in-cortex).

> **Axon Relay**
>
> **Configure Bitbucket with Cortex Axon Relay**
>
> > [!NOTE]
> >
> > Scaffolder and Workflow automation are supported when connecting Bitbucket via Axon Relay. See [Registering a Scaffolder template](/streamline/workflows/scaffolder) for setup details.
>
> See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for instructions. Make sure to follow the Bitbucket-specific instructions for the docker-compose.yml file.

Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to **Remove Integration** in Settings.

You can also use the **Test all configurations** button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

**Configure the integration for multiple Bitbucket accounts**

The Bitbucket integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Bitbucket page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.

Cortex supports mapping multiple identities for a single user if you have multiple configurations of Bitbucket. See the [Identity mapping](/configure/settings/managing-users/identity-mapping) documentation for more information.

### Limit which Bitbucket projects are used for the integration

If you are a part of multiple projects in Bitbucket but you only want to show repositories for a specific set of projects, you can specify the projects in Cortex:

1. Navigate to the [Bitbucket integration settings page](https://app.getcortexapp.com/admin/settings/bitbucket).
2. Click the pencil icon in the row containing the Bitbucket configuration you want to edit.

   ![Click the pencil icon to edit the Bitbucket configuration.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/edit-bitbucket-config.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=7651828ed6269f75d37c16a3ce4249a2)
3. Under **Project names**, select which projects you want to include.

   ![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/bitbucket-project-names.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=580b449964b52b9184cae95ad2f2c6d1)
4. At the bottom of the side panel, click **Save**.

### Use webhooks for GitOps functionality

To use webhooks for GitOps functionality, you need to set a secret token on the [Bitbucket Settings](https://app.getcortexapp.com/admin/settings/bitbucket) page. This helps Cortex identify that the webhook event is valid. Make sure to enter the same secret when configuring the webhook on Bitbucket Server.

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/bitbucket-webhook%20%281%29.jpg)

## How to connect Cortex entities to Bitbucket

### Import entities from Bitbucket

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#importing-services-from-an-integration) for instructions on importing entities.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

**Set repository details**

By specifying the `x-cortex-git` field in your Cortex entity descriptor, you'll be able to see Git information in the entity page, including the top language, recent commits, and top contributors.

```yaml theme={null}
x-cortex-git:
  bitbucket:
    repository: /
    basepath: myService # optional
    alias: myApp # optional
```

| Field | Description | Required |
| - | - | - |
| `repository` | `org/repo` as defined in Bitbucket | true |
| `basepath` | If the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdirectory | false |
| `alias` | Alias is optional and only relevant if you have opted into multi account support | false |

The value for `repository` should be the *workspace/repo* as defined in Bitbucket.

#### Syncing ownership from Bitbucket

You can define the following block in your Cortex entity descriptor to add your Bitbucket teams as owners.

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: Team Name
    provider: BITBUCKET
    description: This is a description for this Bitbucket team that owns this entity.
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Ownership type; must be defined as `group` for Bitbucket teams | **✓** |
| `name` | Bitbucket team name | **✓** |
| `provider` | Name of integration (in this case, `BITBUCKET`) | **✓** |
| `description` | Description for the Bitbucket team | |

Cortex syncs Bitbucket identities every day at 10 a.m. UTC. Cortex connects team members to their Cortex users through [identity mappings](#identity-mappings).

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

### Identity mappings

Cortex maps users' email addresses to discovered Bitbucket accounts, so you never need to define email ownership in an entity descriptor.

You can confirm users' Bitbucket accounts are connected from [Bitbucket identity mappings in settings](/configure/settings/managing-users/identity-mapping).

## Using the Bitbucket integration

### View Bitbucket information on entity pages in Cortex

The Bitbucket integration populates the **Repository** block on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). For cloud configurations, it also populates the **Language** block. If a Bitbucket team has been defined as the owner for an entity, it will also appear in the Owners block.

![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/bitbucket-repo.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=fa24c591f976305c8cc1d0ed1611fd04)

In the **Recent activity** preview, you'll find the recent commits and releases.

#### **Events**

On an entity's **Events** page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in Bitbucket and includes a timestamp.

#### **CI/CD**

To see pipeline runs for Bitbucket, use the [deploys API](/ingesting-data-into-cortex/entities-overview/entities/deploys) to add deploy information. After doing this, from the **CI/CD > Deploys** page in the entity's sidebar, you will see a history of pipeline runs.

#### **Workflows**

If a Workflow applies to a given entity, any actions you can perform are available under the **Workflows** link in the side panel of an entity.

#### **Repository**

You can access more detailed information pulled from Bitbucket in the **Repository** link in the sidebar. At the top of the repository page, see the repositories associated with that entity. For cloud configurations, you can also see the most-used language in files for that entity. In the **Top contributors** block, you'll find the three users who have contributed the most code and the number of their contributions.

In the **Commits** section, you'll find the 10 most recent commits and metadata about each. Below **Commits** is the **Recent releases** section, which includes the 5 most recent releases.

#### **Packages**

Packages are automatically scraped from your Git repos or they can be submitted via the [packages API](/api/rest/packages). The package file must be in the root of your repository — or, if you're using `basepath`, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) using `packages()`.

To view packages, click **Packages** in the entity's sidebar.

The following package types are automatically scraped from repositories:

* JavaScript / Node.js: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Python: `requirements.txt`, `pipfile.lock`
* .NET (C#): `packages.lock.json`
* Java: `pom.xml`
* Go: `go.sum`

All other files of these types can be added via the [packages API](/api/rest/packages).

### Engineering homepage

> [!NOTE]
>
> Due to rate limits, Bitbucket ingestion on the homepage is limited to repositories mapped to a Cortex entity.

The Bitbucket integration enables Cortex to pull information about pull requests and work items into the [homepage](/streamline/homepage). You can find your open pull requests and any pull requests assigned to you for review.

Pull requests from Bitbucket are refreshed every 5 minutes.

Cortex also checks for pull requests that were deleted in Bitbucket every day at 3:30 a.m. UTC. Deleted pull requests are removed from your homepage after this daily check, so a deleted pull request can still appear for up to 24 hours.

### Eng Intelligence

> [!NOTE]
>
> * Due to rate limits, Bitbucket ingestion in Eng Intelligence is limited to repositories mapped to a Cortex entity.
> * When using Bitbucket in Eng Intelligence, it's highly recommended to use the [workspace token configuration](/ingesting-data-into-cortex/integrations/bitbucket#workspace-token).

[Eng Intelligence](/improve/eng-intelligence) also uses pull request data from Bitbucket to generate metrics:

* Average PR open to close time
* Avg time to first review
* Avg time to approval
* PRs opened
* Weekly PRs merged
* Avg PRs reviewed/week

### Scorecards and CQL

With the Bitbucket integration, you can create Scorecard rules and write CQL queries based on Bitbucket details.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Approvals required to merge**
>
> The total number of approvals required to merge a Pull Request into the repository, defaulting to 0 if no approvals are defined.
>
> **Definition:** `git.numOfRequiredApprovals(): Number`
>
> **Example**
>
> In a Scorecard, you can write a rule to encourage at least one approval for each Pull Request:
>
> ```
> git.numOfRequiredApprovals() >= 1
> ```

> **Git repository set**
>
> Check if an entity has a registered Git repository.
>
> **Definition:** `git (==/!=) null: Boolean`
>
> **Example**
>
> In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:
>
> ```
> git != null
> ```

> **Pipeline build success rate**
>
> The percentage of build pipelines that complete successfully. This is calculated against builds on the default branch, for commits in the last 30 days. The calculation is # successful builds / (# successful + # failed). **Definition:** `git.percentBuildSuccess(): Number`
>
> **Example**
>
> In a Scorecard, you can write a rule that requires at least 90% of build runs to be successful:
>
> ```
> git.percentBuildSuccess() > 0.9
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts a background sync of Bitbucket identities every day at 10 a.m. UTC. Repositories are refreshed every day at 2 p.m. UTC.

Every day at 3:30 a.m. UTC, Cortex also removes pull requests that were deleted in Bitbucket. This runs automatically for all workspaces with the Bitbucket integration configured.

## Troubleshooting and FAQ

**Rules are failing saying that I don't have file `x`, but I verified that the file exists.**

We always use the default branch for file existence checks. Make sure that the file is present in the default branch.

**A pull request I deleted in Bitbucket still appears on my homepage.**

Cortex removes deleted Bitbucket pull requests once a day, at 3:30 a.m. UTC. A deleted pull request stays on the homepage until the next daily cleanup runs. If it still appears after that, contact the Cortex Customer Engineering team.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# BugSnag
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/bugsnag



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[BugSnag](https://www.bugsnag.com/) is an application stability monitoring platform that provides error tracking and analytics.

Integrating BugSnag with Cortex allows you to:

* [View errors on entity pages](/ingesting-data-into-cortex/integrations/bugsnag#viewing-bugsnag-errors-on-an-entity) in Cortex, giving you insight into your entity's operational maturity
* Create [Scorecards](/ingesting-data-into-cortex/integrations/bugsnag#scorecards-and-cql) that include rules related to BugSnag errors

## How to configure BugSnag with Cortex

### Prerequisites

Before getting started:

* Create a [BugSnag auth token](https://bugsnagapiv2.docs.apiary.io/#introduction/authentication) in your [BugSnag account's settings page](https://app.bugsnag.com/settings/my-account) under "My account."
* You must have the `Configure integrations` permission in Cortex.

> [!WARNING]
>
> If you're using a self-hosted instance of BugSnag, you'll need to verify that your Cortex instance is able to reach the BugSnag instance.
>
> We route our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your BugSnag instance.

### Configure the integration in Cortex

1. In Cortex, navigate to the [BugSnag settings page](https://app.getcortexapp.com/admin/integrations/bugsnag).
   * Click **Integrations** from the main nav. Search for and select **BugSnag**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **Auth token**: Enter the auth token you generated in BugSnag.
   * **Organization slug**: Enter your BugSnag organization slug.
     * You can find this in your BugSnag URL, e.g., `https://app.bugsnag.com/organizations/{SLUG}/stability-center`.
   * **Host**: If using a custom BugSnag instance, enter the URL here *without* the API path (e.g., `bugsnag.getcortexapp.com`).
4. Click **Save**.

After saving your configuration, you are redirected to the BugSnag integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure BugSnag was configured properly.

## How to connect Cortex entities to BugSnag projects

### Discovery

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" for BugSnag projects. For example, if your Cortex tag is `my-entity`, then the corresponding project in BugSnag should also be `my-entity`.

If your BugSnag projects don’t cleanly match the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag), you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can define projects under the `x-cortex-bugsnag` block:

```yaml theme={null}
x-cortex-bugsnag:
  project: my-project
```

| Field | Description | Required |
| - | - | :-: |
| `project` | Project key defined in BugSnag | **✓** |

## Using the BugSnag integration

### Viewing BugSnag errors on an entity

Error data will appear on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). You can find the total number of detected errors and a full list on the **Error tracking** page in the entity's side panel. Error data is fetched live.

Each error in the list will display with an `Error`, `Info`, or `Warning` tag based on the [severity](https://docs.bugsnag.com/product/severity-indicator/#severity) applied to a given error in BugSnag.

### Scorecards and CQL

With the BugSnag integration, you can create Scorecard rules and write CQL queries based on BugSnag projects and issues.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if BugSnag is set**
>
> Check if an entity has a registered BugSnag project.
>
> **Definition:** `bugsnag (==/!=) null`
>
> **Example**
>
> This expression can be used to write a Scorecard rule to make sure each entity has a registered BugSnag project:
>
> ```
> bugsnag != null
> ```
>
> This is also a good way to double-check that the integration is synced and reporting frequently.

> **Number of issues**
>
> Count all unresolved issues in BugSnag or counts number of issues for a given query. By default, will count all unresolved issues.
>
> **Definition:** `bugsnag.numOfIssues(query: Text | Null)`
>
> **Example**
>
> For a Scorecard focused on operational maturity, you can pull in error data from BugSnag to make sure your entities have no or few errors.
>
> ```
> bugsnag.numOfIssues() < 2
> ```
>
> To set a more specific standard, you can also create a rule based on a [filter](https://docs.bugsnag.com/product/custom-filters/).
>
> ```
> bugsnag.numOfIssues("filters[error.status][][type]=example")
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Buildkite
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/buildkite



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Buildkite](https://buildkite.com/) is a continuous integration and delivery platform that enablers users to run fast, secure, and scalable pipelines on their own infrastructure.

Integrating Buildkite with Cortex allows you to:

* Pull in metrics about your builds and pipelines
* Create [Scorecards](/ingesting-data-into-cortex/integrations/buildkite#scorecards-and-cql) that track progress and drive alignment on projects involving your Buildkite pipelines

## How to configure Buildkite with Cortex

### Prerequisites

Before getting started:

* Create a [Buildkite API access token](https://buildkite.com/docs/apis/managing-api-tokens) with read-only permissions for pipelines and builds.
  * You must be a member of a Buildkite organization to generate and use an access token for it.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Buildkite settings page](https://app.getcortexapp.com/admin/integrations/buildkite).
   * Click **Integrations** from the main nav. Search for and select **Buildkite**.
2. Configure the Buildkite integration form:
   * **API token**: Enter your Buildkite API token.
   * **Organizational slug**: Enter the slug for your Buildkite organization.
     * This can be found in your organization's Buildkite settings, or at the end of your Buildkite URL after navigating to **Pipelines**.
3. Click **Save**.

## How to connect Cortex entities to Buildkite

### Discovery

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) for your Buildkite pipeline. For example, if your Cortex tag is `my-pipeline`, then the corresponding pipeline tag in Buildkite should also be `my-pipeline`.

Cortex will also use the the GitHub, GitLab, Bitbucket, or Azure DevOps repository to connect entities to Buildkite pipelines. For example, if the GitHub repo associated with your Buildkite pipeline is `my-org/repo`, then entities in Cortex that also live in `my-org/repo` will populate with details from that pipeline.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can add Buildkite pipelines to an entity by defining the pipeline slug or tags with one of the following blocks in the entity descriptor:

```yaml theme={null}
x-cortex-ci-cd:
  buildkite:
    pipelines:
    - slug: my-buildkite-pipeline-slug-1
    - slug: my-buildkite-pipeline-slug-2
```

| Field | Description | Required |
| - | - | :-: |
| `slug` | Slug for the Buildkite pipeline | **✓** |

```yaml theme={null}
x-cortex-ci-cd:
  buildkite:
    tags:
    - tag: my-buildkite-tag-1
    - tag: my-buildkite-tag-2
```

| Field | Description | Required |
| - | - | :-: |
| `tag` | Tag for the Buildkite pipeline | **✓** |

The slug for your pipeline can be found in the Buildkite URL for a given pipeline (e.g., `https://buildkite.com//`).

## Using the Buildkite integration

#### Entity pages

Once the Buildkite integration is established, Cortex will automatically pull in pipeline data to an entity's page. You can access this data from the **CI/CD** page in the entity's side panel.

You can find a list of pipeline runs for each pipeline linked to a given entity on this page:

* Pipeline slug/tag
* Action (e.g. "scheduled build")
* Timestamp
* Branch
* State

The [state](https://buildkite.com/docs/pipelines/notifications#build-states) for a build will appear as a tag next to the pipeline slug/tag (e.g. `canceled`, `passed`, or `failed`).

### Scorecards and CQL

With the Buildkite integration, you can create Scorecard rules and write CQL queries based on Buildkite pipelines.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Buildkite pipeline(s) are set**
>
> Check if entity has registered Buildkite pipelines in its entity descriptor.
>
> **Definition:** `buildkite (==/!=) null`
>
> **Example**
>
> For a Scorecard focused on production readiness, you can pull in data from Buildkite to make sure that entities belong to a CI/CD pipeline.
>
> ```
> buildkite != null
> ```

> **Get Buildkite build(s)**
>
> Gets pipelines and builds that meet given filter criteria.
>
> * Build criteria:
>   * Branch
>   * Commit
>   * Created at
>   * ID
>   * Message
>   * Number
>   * Pipeline
>   * State
> * Pipeline criteria:
>   * Description
>   * Git repository
>   * ID
>   * Name
>   * Slug
>   * Tags
>
> States include CANCELED, PASSED, and FAILED.
>
> **Definition**: `buildkite.builds()`
>
> **Example**
>
> If you're building a Scorecard with an emphasis on operational maturity, you could set a rule to make sure not only that entities belong to a pipeline, but that the pipeline is functioning as expected.
>
> ```
> buildkite.builds(states["passed"]).length >=1
> ```

> **Get Buildkite pipelines**
>
> Get all Buildkite pipelines associated with the entity: Description, Git repository, ID, Name, Slug, Tags.
>
> **Definition**: `buildkite.pipelines()`
>
> **Example**
>
> A production readiness Scorecard can use this expression in a rule confirming that there are pipelines linked to a specific repository:
>
> ```
> buildkite.pipelines().any((pipeline) => pipeline.gitRepository = )
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Checkmarx
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/checkmarx



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

Checkmarx is an automated application security platform that checks source code for security vulnerabilities and compliance issues. Integrate Cortex with Checkmarx to drive insight into the vulnerabilities detected on your entities.

This integration is supported for [Checkmarx Static Application Security Testing (SAST)](https://checkmarx.com/cxsast-source-code-scanning/).

## How to configure Checkmarx with Cortex

### Prerequisites

Before getting started, create a user with access to the `sast_rest_api` scope.

> [!WARNING]
>
> If you're using a self-hosted instance of Checkmarx, you'll need to verify that your Cortex instance is able to reach the Checkmarx instance.
>
> We route our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Checkmarx instance.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Checkmarx settings page](https://app.getcortexapp.com/admin/integrations/checkmarx).
   * Click **Integrations** from the main nav. Search for and select **Checkmarx**.
2. Click **Add configuration**.
3. Configure the Checkmarx integration form:
   * **Username** and **Password**: Enter the username and password for the user with access to `sast_rest_api`.
   * **Host**: Enter the full URL of your Checkmarx instance.
4. Click **Save**.

## How to connect Cortex entities to Checkmarx

### Discovery

By default, Cortex will use your associated Git repository (e.g. `repo-name`) or the service tag as the "best guess" for the Checkmarx project name.

If your repository and entity names don’t cleanly match the Checkmarx CxSAST project names, or if you have multiple Checkmarx projects for a service, you can add a Checkmarx project ID (recommended) or a Checkmarx project name in the Cortex entity descriptor.

### Editing the entity descriptor

We recommend using the project ID as it is a unique identifier across projects.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Example using project IDs:

```yaml theme={null}
x-cortex-checkmarx:
  projects:
    - projectId: 1234
    - projectId: 2345
```

Example using both project IDs and names:

```yaml theme={null}
x-cortex-checkmarx:
  projects:
    - projectName: My Cool Project
    - projectId: 1234
```

## Using the Checkmarx integration

#### Entity pages

Once the integration is established, vulnerabilities pulled from Checkmarx will be available for each entity in the **Code and Security** block in the **Overview** tab.

While viewing an entity, click **Code & security > Checkmarx**. On this page, view the number of vulnerabilities per severity and a link directly to your Checkmarx instance.

### Scorecards and CQL

With the Checkmarx integration, you can create Scorecard rules and write CQL queries based on Checkmarx details.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Checkmarx project is set**
>
> Check if entity has a registered Checkmarx project in its entity descriptor. If there is a Checkmarx project name, we will try and make sure that the project exists in Checkmarx.
>
> **Definition:** `checkmarx (==/!=) null: Boolean`
>
> **Example**
>
> In a Scorecard, you can write a rule to check whether an entity has a Checkmarx project set:
>
> ```
> checkmarx != null
> ```

> **Checkmarx scan risk**
>
> Get the maximum scan risk among the entity's project's latest scans
>
> **Definition:** `checkmarx.sastScanRisk(): Number`
>
> **Example**
>
> In a Scorecard, you can write a rule to verify that an entity has no Checkmarx projects where the latest scan risk is higher than 35:
>
> ```
> checkmarx.sastScanRisk() < 35
> ```

> **Number of Checkmarx vulnerabilities**
>
> Get the count of all vulnerabilities for an entity's Checkmarx project's last scan
>
> **Definition:** `checkmarx.numOfVulnerabilities(): Number`
>
> **Example**
>
> In a Scorecard, you can write a rule to verify that an entity has no vulnerabilities with a severity of `HIGH`:
>
> ```
> checkmarx.numOfVulnerabilities(severity=["High"]) < 1
> ```
>
> Verify that an entity has less than 5 vulnerabilities total:
>
> ```
> checkmarx.numOfVulnerabilities() < 5
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## FAQs and troubleshooting

**Does Cortex support integrating with Checkmarx One?**

No, Cortex does not currently support Checkmarx one. Only Checkmarx SAST is supported for this integration.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# CircleCI
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/circleci



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[CircleCI](https://circleci.com/) is continuous integration and continuous delivery platform that can be used to implement DevOps best practices.

Integrating CircleCI with Cortex allows you to:

* [View information about CircleCI workflows and pipelines on entity pages](/ingesting-data-into-cortex/integrations/circleci#viewing-circleci-information-on-entity-pages) in Cortex
* Create [Scorecards](/standardize/scorecards) that track progress and drive alignment on projects involving your CircleCI data

## How to configure CircleCI with Cortex

### Prerequisites

Before getting started:

* Create a [CircleCI API token](https://circleci.com/docs/managing-api-tokens/).

**Self-hosted CircleCI instances**

If you’re using a self-hosted instance of CircleCI, you’ll need to verify that your Cortex instance is able to reach the CircleCI instance.

We route our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your CircleCI instance.

### Configure the integration in Cortex

1. In Cortex, navigate to the [CircleCI settings page](https://app.getcortexapp.com/admin/integrations/circleci).
   * Click **Integrations** from the main nav. Search for and select **CircleCI**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **Account alias**: Enter an alias for this integration, used to tie entity registrations to different configurations.
   * **API token**: Enter the value of the API token you created in CircleCI.
   * **Host**: Enter the URL for your CircleCI instance if self-hosted, e.g., `https://cortex.circleci.com`
4. Click **Save**.

**Configure the integration for multiple CircleCI accounts**

The CircleCI integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the CircleCI page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.

## How to connect Cortex entities to CircleCI

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can define CircleCI projects in an [entity's YAML descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file). Add each project's full project slug under the `x-cortex-circle-ci` block:

```yaml theme={null}
x-cortex-circle-ci:
  projects:
    - projectSlug: gh/my-org/auth-service
      alias: circleci-alias
```

| Field | Description | Required |
| - | - | - |
| `projectSlug` | The full CircleCI project slug. See [Finding the project slug](#finding-the-project-slug) for the supported formats. | Yes |
| `alias` | The alias of the CircleCI configuration to use. Only relevant if you've set up multiple CircleCI accounts. | No |

> [!WARNING]
>
> Cortex sends `projectSlug` to CircleCI exactly as written. A slug that contains only the repository name (for example, `auth-service`) doesn't match a CircleCI project, so Cortex can't retrieve data for the entity.

#### Finding the project slug

The slug format depends on how your project is connected to CircleCI.

**Projects connected through the GitHub OAuth app or Bitbucket**

These projects use the format `{vcs}/{org}/{repo}`:

* **VCS type** - `gh` for GitHub or `bb` for Bitbucket.
* **Organization** - The GitHub organization or Bitbucket workspace that owns the repository.
* **Repository** - The repository name.

If the entity already has a Git repository defined in its `x-cortex-git` block, you can build the slug from that value. For example, for an entity with this Git configuration:

```yaml theme={null}
x-cortex-git:
  github:
    repository: my-org/auth-service
```

The CircleCI project slug is `gh/my-org/auth-service`.

**Projects connected through GitLab or the CircleCI GitHub App**

These projects use the format `circleci/{org-id}/{project-id}`, where both values are IDs assigned by CircleCI:

```yaml theme={null}
x-cortex-circle-ci:
  projects:
    - projectSlug: circleci/a1b2c3d4-0000-0000-0000-000000000000/e5f6a7b8-0000-0000-0000-000000000000
```

You can't build this slug from `x-cortex-git`. Copy it from your project settings in CircleCI instead.

## Using the CircleCI integration

### Viewing CircleCI information on entity pages

When an entity has a CircleCI project defined in its YAML file, you will see metric and pipeline details on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). Click **CI/CD > CircleCI** in the entity's sidebar to see this information.

### Scorecards and CQL

With the CircleCI integration, you can create Scorecard rules and write CQL queries based on CircleCI metrics and pipelines.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check for CircleCI flaky tests**
>
> Get all Circle CI flaky tests associated with the entity.
>
> **Definition**: `circleci.flakyTests()`
>
> **Example**
>
> You could create a Scorecard with a rule that verifies no flaky tests:
>
> ```
> circleci.flakyTests().length == 0
> ```

> **Get Circle CI projects**
>
> Get all Circle CI projects associated with the entity.
>
> **Definition**: `circleci.projects()`
>
> **Example**
>
> You could also create a rule that checks for a success rate over 90%:
>
> ```
> circleci.projects().all((project) => project.metrics.successRate > 0.9) == true
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# ClickUp
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/clickup



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[ClickUp](https://clickup.com/) is a project management tool that combines tasks, document collaboration, and issue management in a single platform.

Integrating ClickUp with Cortex allows you to:

* View task information directly on [entity pages](/ingesting-data-into-cortex/integrations/clickup#entity-pages) in Cortex
* Create ClickUp tasks based on Initiatives directly from Cortex
* Map ClickUp identities to users in Cortex
* View open ClickUp tasks in the [dev homepage](/ingesting-data-into-cortex/integrations/clickup#dev-homepage)
* Create [Scorecards](/ingesting-data-into-cortex/integrations/clickup#scorecards-and-cql) that track progress and drive alignment on projects involving your ClickUp tasks

## How to configure ClickUp with Cortex

### Prerequisites

Before getting started:

* Create a [ClickUp personal API token](https://clickup.com/api/developer-portal/authentication/#generate-your-personal-api-token).

### Configure the integration in Cortex

1. In Cortex, navigate to the [ClickUp settings page](https://app.getcortexapp.com/admin/integrations/clickup).
   * Click **Integrations** from the main nav. Search for and select **ClickUp**.
2. Click **Add configuration**.
3. Configure the ClickUp integration form:
   * **API token**: Enter your ClickUp API token.
4. Click **Save**.

If you’ve set everything up correctly, you’ll see the option to **Remove Integration** in settings.

You can also use the **Test configuration** button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

Note that mapping options will not appear in Cortex for users who have not finished user registration in ClickUp. If a user is partially registered, Cortex will filter them out of the mapping page.

## How to connect Cortex entities to ClickUp

### Auto discovery of spaces, folders, and tags

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" for ClickUp space, folder, or tag. For example, if your Cortex tag is `my-entity`, then the corresponding space, folder, or tag in ClickUp should also be `my-entity`.

If your ClickUp space, folder, or tag don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

You can map any number of ClickUp spaces, folders, and tags to a Cortex entity. Spaces and folders can be mapped by using either ID or name.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can find your folder ID or space ID in your ClickUp URL: `https://app.clickup.com/:workspace_id/v/f/:folder_id/:space_id`.

**Mapping spaces by ID or name**

When mapping spaces, you can use the ID or name for the space.

```yaml theme={null}
x-cortex-issues:
  clickup:
    spaces:
      - identifier: 123456789
        identifierType: ID
```

```yaml theme={null}
x-cortex-issues:
  clickup:
    spaces:
      - identifier: My Space
        identifierType: NAME
```

These blocks share the same fields:

| Field | Description | Required |
| - | - | :-: |
| `spaces` | Denotes that mapping should be based on ClickUp spaces | **true** |
| `identifier` | Identifier for the space; either the full ID or name | **true** |
| `identifierType` | Type of identifier; either `ID` or `NAME` | **true** |

**Mapping folders by ID or name**

When mapping folders, you can use the ID or name for the folder.

```yaml theme={null}
x-cortex-issues:
  clickup:
    folders:
      - identifier: 123456789
        identifierType: ID
```

```yaml theme={null}
x-cortex-issues:
  clickup:
    folders:
      - identifier: my-folder
        identifierType: NAME
```

| Field | Description | Required |
| - | - | :-: |
| `folders` | Denotes that mapping should be based on ClickUp folder | **true** |
| `identifier` | Identifier for the folder; either the full ID or name | **true** |
| `identifierType` | Type of identifier; either `ID` or `NAME` | **true** |

**Mapping by tags**

Cortex also supports mapping entities to ClickUp [tags](https://help.clickup.com/hc/en-us/articles/6304382595991-Manage-task-tags).

```yaml theme={null}
x-cortex-issues:
  clickup:
    tags:
      - name: tag a
      - name: tag b
      - name: tag c
```

| Field | Description | Required |
| - | - | :-: |
| `folders` | Denotes that mapping should be based on ClickUp tags | **true** |
| `name` | Name for the tag | **true** |

### Specify a list for Initiative issues

You can also specify a ClickUp list to store all issues created via Cortex Initiatives. If `Use list defined in entity YAML` is **toggled on** in the Initiative issue creation form, Cortex will automatically create tasks in the specified list for a given entity.

If a list is not specified in an entity's YAML and `Use list defined in entity YAML` option is **toggled on** in the initiative issue creation form, Cortex will attempt to create a list in the mapped space or folder above.

Define one of these following blocks in an entity descriptor to specify a list for Initiative issues.

**Specify list by ID**

```yaml theme={null}
x-cortex-issues:
    clickup:
      initiativesList:
        id: 12345
```

| Field | Description | Required |
| - | - | :-: |
| `initiativesList` | Denotes that Cortex | **true** |
| `name` | Name for the tag | **true** |

**Specify list by name**

```yaml theme={null}
x-cortex-issues:
    clickup:
      initiativesList:
        name: Cortex Initiative Issues
```

### Identity mappings

Cortex maps email addresses in your ClickUp instance to email addresses that belong to team members in Cortex. When [identity mapping](/configure/settings/managing-users/identity-mapping) is set up, users will be able to see their personal on-call status from the developer homepage.

Note that mapping options will not appear in Cortex for users who have not finished user registration in ClickUp. If a user is partially registered, Cortex will filter them out of the mapping page.

## Using the ClickUp integration

### Entity pages

**Integrations - ClickUp**

Tasks detected from your ClickUp instance will populate on the **Issue tracking** page in the entity's sidebar. Each row will show the following information (when available in ClickUp):

* Task name (hyperlinked to task in ClickUp)
* Project
* Assignees
* Priority
* Created at
* Due date

### Initiatives

Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.

From the Issues tab of an Initiative, you can automatically [create a ClickUp task from a failing rule](/ingesting-data-into-cortex/integrations/clickup#create-a-task-from-an-initiative-issue).

### Dev homepage

The ClickUp integration enables Cortex to pull information about tasks into the Dev homepage. You can find open tasks assigned to you under the [Issues tab](https://app.getcortexapp.com/admin/home?activeTab=Issues).

Issues are refreshed every 5 minutes, or you can click **Refresh ClickUp tasks** to manually refresh issues.

### Scorecards and CQL

With the ClickUp integration, you can create Scorecard rules and write CQL queries based on ClickUp tasks.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **List of ClickUp tasks**
>
> Get ClickUp tasks meeting the given filter criteria.
>
> * Assignees
> * Created at
> * Creator
> * Due date
> * Folder
> * Priority
>   * "Urgent", "High", "Normal," and "Low"
> * Status
> * Tags
> * Task name
>
> Statuses are dependent on your own ClickUp configured statuses. Closed tasks are filtered out by default.
>
> **Definition:** `clickup.tasks()`
>
> **Examples**
>
> To evaluate the maturity of an entity in a Scorecard, you can use this expression to make sure it has fewer than five unassigned ClickUp tasks:
>
> ```
> clickup.tasks().filter((task) => task.assignees.length < 1).length < 5
> ```
>
> You can also query for entities that don't have any urgent ClickUp tasks with a "security" tag:
>
> ```
> clickup.tasks(priorities=["Urgent"], tags=["security"]).length == 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Create a task from an Initiative issue

Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates. You can create a ClickUp task from a failing rule in an Initiative. Learn more in [Creating issues based on Initiatives](/improve/initiatives/issue-config).

The issue configuration will apply to all entities that meet the filter criteria. Once an entity is passing the rule, Cortex will automatically close the associated ticket.

## Background sync

Cortex conducts a background sync of ClickUp identities every day at 10 a.m. UTC. Pull requests and issues are refreshed every 5 minutes.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Codecov
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/codecov



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Codecov](https://about.codecov.io/) is a code coverage reporting platform that that monitors how much of your code has been tested and validated. Codecov analytics can be used to drive visibility into your microservice architecture and understand coverage trends over time.

Integrating Cortex with Codecov allows you to:

* View code coverage details for entities directly in Cortex
* Create [Scorecards](/ingesting-data-into-cortex/integrations/codecov#scorecards-and-cql) that track progress and drive alignment on projects involving your Codecov code coverage metrics

## How to configure Codecov with Cortex

### Prerequisites

Before getting started:

* Create a [Codecov access token](https://docs.codecov.io/reference#usagen).

### Configure the integration in Cortex

1. In Cortex, navigate to the [Codecov settings page](https://app.getcortexapp.com/admin/integrations/codecov).
   * Click **Integrations** from the main nav. Search for and select **Codecov**.
2. Click **Add configuration**.
3. Configure the Codecov integration form:
   * **API token**: Enter your Codecov access token.
   * **Host**: If you're using a custom Codecov instance, enter your host URL.
     * Make sure to enter the URL **without** the API path (e.g., `https://codecov.getcortexapp.com`).
4. Click **Save**.

## How to connect Cortex entities to Codecov

### Auto discovery of Codecov projects

Cortex will use the GitHub, GitLab, Bitbucket, or Azure DevOps repository as the "best guess" for the corresponding Codecov project, since Codecov projects are connected to repositories. For example, if the GitHub repo associated with your Codecov instance is `my-org/repo`, then the entities in Cortex should also be associated with `my-org/repo`.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can find the repository for a given entity in its YAML, defined in a block like the one below:

```yaml theme={null}
x-cortex-git:
  github:
    repository: cortexapps/sample-repo
```

If the Codecov project you want to associate isn't the same as the repository, you can override this in the Cortex entity descriptor.

> [!WARNING]
>
> While Cortex uses the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) for discovery with many integrations, the **repository** is used for Codecov projects.

### Editing the entity descriptor

```yaml theme={null}
x-cortex-static-analysis:
  codecov:
    owner: org-name
    repo: my-project
    provider: AZURE_DEVOPS | BITBUCKET | BITBUCKET_SERVER | GITHUB | GITHUB_ENTERPRISE | GITLAB | GITLAB_ENTERPRISE
    flag: flag
```

| Field | Description | Required |
| - | - | :-: |
| `owner` | Name of the Git organization | **✓** |
| `repo` | Git repository (without the organization) | **✓** |
| `provider` | One of the Git providers in the sample YAML | **✓** |
| `flag` | Pulls from isolated and categorized coverage reports | |

The value for `repo` should be the **full repository** because Codecov maps projects by repo.

**Flags**

Codecov's [flags](https://docs.codecov.com/docs/flags) are used to categorize coverage reports for various features and tests in a given project. Flags allow you to set different statistics for different areas of your code base. For example, if you have a monorepo with multiple unique projects, you can use Codecov flags to evaluate each project with different test coverage metrics.

To pull flags into Cortex, define the `flag` line in the [entity descriptor block](/ingesting-data-into-cortex/integrations/codecov#editing-the-entity-descriptor).

> [!WARNING]
>
> If you choose to configure with flags, discovery will be disabled; you would need to define the `owner`, `repo`, and `provider` lines.

## Using the Codecov integration

#### Entity pages

With the Codecov integration, you can find code coverage details on an entity's details page as long as that entity is associated with a repo linked to your Codecov instance.

Click **Code & security** in the entity's sidebar to see the code coverage for that entity.

### Scorecards and CQL

With the Codecov integration, you can create Scorecard rules and write CQL queries based on Codecov code coverage metrics.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Code coverage**
>
> Code coverage for an entity's Git repository (out of 100)
>
> **Definition:** `codecov.codeCoverage()`
>
> **Example**
>
> For a Scorecard focused on development maturity, you can set a rule to make sure code coverage for a given entity is at least 95%:
>
> ```
> codecov.codeCoverage() >= 95
> ```
>
> Set a threshold that is both challenging and realistic so there's an incentive for developers to improve.

> [!TIP]
>
> Setting up a rule based on code coverage can serve as a secondary check to confirm an entity is synced with Codecov and reporting frequently.

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Coralogix
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/coralogix



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

[Coralogix](https://coralogix.com/) is an observability and security platform. Integrate Cortex with Coralogix to drive insights into alerts.

After setting up the integration, relevant alerts from Coralogix will appear in your entity pages. While viewing an entity, click **Integrations > Coralogix** in its sidebar to view the list of alerts.

## How to configure Coralogix with Cortex

### Prerequisites

Before getting started, generate a [Coralogix API key](https://coralogix.com/docs/alerts-api/#api-access).

### Step 1: Configure the integration in Cortex

1. In Cortex, navigate to the [Coralogix settings page](https://app.getcortexapp.com/admin/integrations/coralogix)
   * Click **Integrations** from the main nav. Search for and select **Coralogix**.
2. Click **Add configuration**.
3. Configure the Coralogix integration form:
   * **Account alias**: Enter your account alias.
   * **API key**: Enter your Coralogix API key.
   * **Region**: Select your region.
4. Click **Save**.

## How to connect Cortex entities to Coralogix

### Discovery

By default, Cortex will use the entity name or [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-service`) as the "best guess" for the Coralogix alert application name. For example, if your entity name is "My Service" and your Cortex tag is “my-service”, then the corresponding application name in Coralogix should be “My Service” or "my-service".

If your Coralogix application names don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

Coralogix alerts can be listed in the Catalog under the `Coralogix` section. We support application names in the YAML for pulling Coralogix alerts.

```yaml theme={null}
info:
  x-cortex-coralogix:
    applications:
    - applicationName: my-app # application name tied to alert
      alias: my-alias # alias is optional and only relevant if you have opted into multi account support
```

## Using the Coralogix integration

### Scorecards and CQL

With the Coralogix integration, you can create Scorecard rules and write CQL queries based on Coralogix alerts.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Coralogix application is set**
>
> Check if entity has a registered Coralogix application in its entity descriptor. If no registration exists, we'll try to automatically detect which corresponding Coralogix application is associated with the entity.
>
> **Definition:** `coralogix (==/!=) null: Boolean`
>
> **Example**
>
> You could write a rule that checks whether an entity has a Coralogix application set:
>
> ```
> coralogix != null
> ```

> **Alerts**
>
> List of alerts, filterable on status
>
> **Definition:** `coralogix.alerts(): List`
>
> **Example**
>
> You could write a rule that checks whether an entity has at least 3 alerts:
>
> ```
> ccoralogix.alerts().length >= 3
> ```
>
> You could write a rule that checks whether an entity has no alerts and status triggered:
>
> ```
> coralogix.alerts(statuses = ["triggered"]).length -= 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.


# Datadog
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to configure the integration for Datadog. For instructions on connecting Datadog to entities, see [Connecting entities to Datadog](/ingesting-data-into-cortex/integrations/datadog/connecting-entities-to-datadog). For information on how to use the integration, see [Using the integration for Datadog](/ingesting-data-into-cortex/integrations/datadog/using-the-integration-for-datadog).

## Why use the integration for Datadog

Datadog is an observability platform that tracks the health and performance of your services, infrastructure, and applications. The integration brings that operational data into Cortex, so the health of a service sits alongside its ownership, dependencies, and Scorecard results in one place.

The integration for Datadog brings the following into Cortex:

* **Monitors** - The status and query for each Datadog monitor linked to an entity.
* **SLOs** - Targets, current value, and status for each service level objective (SLO) linked to an entity.
* **Dependencies** - Service relationships discovered from Datadog's Service Map, which feed into the Relationships graph.
* **Incidents** - Every incident across your organization, with severity, status, and affected entities.
* **On-call schedules** - Who's on call now and who's on call next for an entity.

Incidents and on-call schedules are only imported when you select their categories while configuring the integration. If you set up Datadog before categories were available, [update the categories on your existing configuration](/ingesting-data-into-cortex/integrations/#changing-categories-on-an-existing-configuration) to start importing this data.

You can also build Scorecard rules and Cortex Query Language (CQL) queries against incident and on-call data, and track incident frequency and mean time to resolution (MTTR) in Eng Intelligence.

## Configuring Datadog

### Prerequisites

1. Users with the `Configure Integrations` permission can configure Datadog.
2. A [Datadog application key](https://docs.datadoghq.com/account_management/api-app-keys/#application-keys) with the following scopes:
   * `monitors_read`
   * `apm_api_catalog_read`
   * `dashboards_read`
   * `metrics_read`
   * `timeseries_query`
   * `apm_service_catalog_read`
   * `slos_read`
   * `apm_read`
   * `teams_read`
   * `user_access_read`
   * `incident_read`
   * `on_call_read`
3. A [Datadog API key](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).

### **Installing Datadog in Cortex**

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Datadog, then click **Install**. The Datadog side panel opens.
3. In the Datadog side panel, do the following:
   1. From the **Category** dropdown, select the types of data to import from Datadog (required). To see incidents and on-call schedules in Cortex, select **Incidents** and **On-call**. For more information, see [Integration categories](/ingesting-data-into-cortex/integrations/#integration-categories).
   2. Under **Configuration alias**, enter the alias you'll use to tie entity registrations to different configuration accounts (required).
   3. From the **Region** dropdown, select the Datadog region where your account is hosted (required). See the [Datadog docs](https://docs.datadoghq.com/getting_started/site/) for more information.
   4. Optionally, under **Custom sub-domain**, enter your organization's custom subdomain, found in your Datadog URL, e.g. `https://subdomain.datadoghq.com`.
   5. Optionally, from the **Environments** dropdown, select environment tags for Datadog entities. If you set an environment tag here, make sure to set the `env` dropdown in Datadog to match. See the [Datadog docs](https://docs.datadoghq.com/service_catalog/navigating/#performance-view) for more information.
   6. Under **API key**, enter the API key you generated in Datadog.
   7. Under **App key**, enter the application key you generated in Datadog. This key appears under the **Key** column in Datadog while viewing your list of Application Keys.
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

> [!NOTE]
>
> To modify an existing configuration, see [Modifying an integration configuration](/ingesting-data-into-cortex/integrations#modifying-an-integration-configuration).

### **Using multiple Datadog configurations**

The Datadog integration supports multiple configurations. To add another:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Datadog, then click **Settings**.
3. In the upper-right corner of the page, click **Add configuration**.
4. Follow the steps in [Installing Datadog in Cortex](/ingesting-data-into-cortex/integrations/datadog#installing-datadog-in-cortex) above.

Each configuration requires an alias, which ties entity registrations to a specific account. If no alias is specified, Cortex uses the default configuration. To set a default:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Datadog, then click **Settings**.
3. Click the **pencil icon** next to a configuration.
4. Toggle on **Set as default**. If you only have one configuration, it's automatically set as the default.


# Connecting entities to Datadog
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog/connecting-entities-to-datadog



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to connect Cortex entities to Datadog. For configuration instructions, see [Configuring the integration for Datadog](/ingesting-data-into-cortex/integrations/datadog). For what you can do once entities are connected, see [Using the integration for Datadog](/ingesting-data-into-cortex/integrations/datadog/using-the-integration-for-datadog).

## Connecting an entity to Datadog monitors, SLOs, and dependencies

### How Cortex matches entities to Datadog

Cortex uses the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) as the "best guess" for the Datadog tag. For example, if your Cortex tag is `payment-service`, then the corresponding tag in Datadog should also be `payment-service`.

If your Datadog tags don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor (YAML).

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

#### Service tags

You can use service tags to connect Datadog services to Cortex entities. These tags are used to discover your monitors and SLOs. Cortex finds monitors and SLOs by querying `tag:value OR tag:value2 ...`

```yaml theme={null}
x-cortex-apm:
  datadog:
    serviceTags:
      - tag: service
        value: payments-api
        alias: datadog-us
      - tag: service
        value: payments-worker
        alias: datadog-eu
```

Service tags have the following field definitions:

| Field | Description | Required? |
| - | - | - |
| `tag` | Tag key to match on in Datadog. | |
| `value` | Value for the tag in Datadog. | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support). | |

To hard code and/or override discovery, you can define a monitor or SLOs block in the YAML, as described in [Monitors and SLOs](/ingesting-data-into-cortex/integrations/datadog/connecting-entities-to-datadog#monitors-and-slos) below.

#### Monitors and SLOs

Adding monitors lets you see information about their current status directly from a catalog and in the **Observability** tab, located on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

* Locate **Connections** in the left details sidebar, expand **Observability**, then select Datadog.

You can find your monitors in Datadog on the **Manage Monitors** page.

The monitor ID is found in the URL when you click on a monitor in your Datadog dashboard, e.g.  `https://app.datadoghq.com/monitors/<id>`.

```yaml theme={null}
x-cortex-apm:
  datadog: 
    monitors:
      - id: 138472901
        alias: datadog-us
      - id: 138473055
        alias: datadog-us
```

Like monitors, Datadog SLOs can be found in the **Observability** tab, located on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

* Locate **Connections** in the left details sidebar, expand **Observability**, then select Datadog.

You can find the SLOs for your instance in Datadog on the **SLO status** page.

The SLO ID is found in the URL when you click on an SLO in the Datadog dashboard, e.g.  `https://app.datadoghq.com/slo?slo_id=<id>&timeframe=7d&tab=status_and_history`.

```yaml theme={null}
x-cortex-slos:
  datadog:
    - id: 0b73859a3e2504bf09ad23a161702654
      alias: datadog-us
    - id: 228499184a9efe34d4e4e9df838c7fa1
      alias: datadog-eu
```

Monitors and SLOs have the same field definitions:

| Field | Description | Required? |
| - | - | - |
| `id` | The Datadog ID for the monitor or SLO. | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support). | |

#### Dependency mapping

Cortex syncs dependencies from Datadog's Service Map automatically, matching entities on the entity identifier (`x-cortex-tag`). Those relationships feed into the [Relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph), so you can visualize the connections between your entities.

For a dependency to sync, both entities must already exist in Cortex, and each identifier must exactly match the corresponding entity name in the Service Map. For example, if `entity-one` and `entity-two` have a dependency edge in Datadog, both need Cortex tags of `entity-one` and `entity-two`.

> [!NOTE]
>
> If a Cortex tag doesn't exactly match the entity identifier in Datadog, that dependency won't sync. Override automatic discovery in the YAML.

You can override discovery two ways:

* Set `serviceTags` with `tag: entity` and the Service Map entity name as the value. See Service tags.
* Connect an APM service directly:

```yaml theme={null}
x-cortex-apm:
  datadog:
    serviceName: payments-api
```

## Connecting an entity to Datadog incidents

Datadog incidents link to entities automatically, with no configuration required. Cortex reads the incident's `services` field and matches each value to an entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag).

Cortex also reads the incident's `teams` field and matches each team handle to the entity with the same Cortex tag. Only that entity is linked, so the services a team owns aren't linked unless the incident also names them in its `services` field.

* **Services** - Cortex matches each value in the incident's `services` field to an entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag).
* **Teams** - Cortex matches each team handle in the incident's `teams` field to the entity with the same Cortex tag. Only the team entity is linked. The services that team owns aren't linked unless the incident also names them in its `services` field.

Matching compares the whole value and ignores case. For example, the team handle `payments-team` matches an entity tagged `Payments-Team`, but not one tagged `payments-team-eu`. Archived entities aren't linked.

Incidents declared from a monitor, or with a service attached, carry a `services` value. Incidents declared by hand often don't, and won't match a service until one is set.

If a Datadog team's handle doesn't match its team entity's Cortex tag, incidents for that team won't link to it. Change the handle in Datadog or the entity's Cortex tag so they match. For more on team entities, see [Adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams).

To confirm what matched, go to **Integrations > Data** in the main sidebar, then select the **Incidents** tab.

## Connecting an entity to Datadog On-Call

> [!NOTE]
>
> Datadog On-Call is not available on Datadog for Government (US1-FED) sites. On gov-site tenants, on-call surfaces in Cortex will be empty. Incidents are unaffected.

Connect on-call schedules from Datadog to see current on-call information for an entity in the catalog. An entity gets linked to a schedule in one of two ways:

* **Automatic mapping** - Cortex creates the link on its own, using the Datadog team handle. No configuration needed.
* **Registration** - You link a specific schedule or team to an entity, either on the entity's details page or in the YAML.

Registration takes precedence. If an entity has an on-call registration, Cortex doesn't automatically map schedules to it. Remove the registration and automatic mapping resumes, normally within an hour.

### Automatic mapping

Cortex connects unlinked Datadog schedules to entities on its own. If a schedule belongs to a Datadog team, and that team's handle matches an entity's Cortex tag, Cortex creates the link with no registration needed.

Mapping runs in both directions and keeps running: new schedules find your existing entities, and new entities find your existing schedules. Allow up to an hour for a new link to appear.

To confirm what matched, go to **Integrations > Data** in the main sidebar, select the **On-call shifts** tab, and check the **Entities** column.

Two cases don't map on their own:

* **A schedule with no team in Datadog**. Schedules migrated from another on-call tool often arrive without one. Attach a team in Datadog whose handle matches the entity's Cortex tag, or add a registration.
* **A team whose handle doesn't match a Cortex tag**. Change the handle to match, or add a registration.

### Registering a schedule or team

Register a schedule or team when the Datadog team handle can't be made to match the entity's Cortex tag, or when you want one specific rotation on an entity. You can register in one of two ways:

* **By schedule** - Select one or more specific Datadog schedules to link directly to the entity.
* **By team** - Select a team from Datadog. Every schedule associated with that team is linked to the entity, so new schedules for that team appear without additional configuration.

Register by team when the team owns the entity and you don't want to revisit the mapping each time its rotations change. Register by schedule when you need a specific rotation on the entity and not everything the team runs.

You can register on-call from an entity's details page, or in the YAML.

### **Connecting from an entity's details page**

1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details) in Cortex.
2. In the upper-right corner, click **Configure entity**.
3. From the left sidebar, locate the **Connections** section, then select the **On-call** tab.
4. From the **Integration** dropdown, select Datadog.
5. Do one of the following:
   1. From the **Schedule name** dropdown, select a schedule to link to the entity.
   2. From the **Team name** dropdown, select a team to link to the entity.
6. Click **Save changes**.

Registrations added through the editor take effect immediately; no re-sync is required.

### Connecting in the YAML

To register on-call in the YAML, add an `x-cortex-oncall` block to the entity's descriptor.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

| Field | Description | Required? |
| - | - | - |
| `type` | Either `SCHEDULE` or `TEAM` | |
| `id` | The Datadog ID for the schedule or team. | |

#### Schedules

To map a single schedule to an entity, use the schedule's ID. You can find it in the schedule URL: `app.datadoghq.com/on-call/schedules/<id>`.

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: SCHEDULE
      id: ee409e39-5449-4eb8-900f-8bea9d2162d7
```

Multiple schedules can be mapped to an entity:

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: SCHEDULE
      id: ee409e39-5449-4eb8-900f-8bea9d2162d7
    - type: SCHEDULE
      id: 7c1d0a84-2f6b-41e0-b3aa-5d92c8f4e011
```

#### Teams

To map every schedule a team owns to an entity, use the team's ID. You can find it in the team page URL: `app.datadoghq.com/teams/<id>`.

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: TEAM
      id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9
```

Multiple teams can be mapped to an entity:

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: TEAM
      id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9
    - type: TEAM
      id: 3f0be512-8d47-4a91-9c26-a1e7f3b60d84
```

> [!NOTE]
>
> Registrations are made by ID, not by name, and do not take an alias. A `TEAM` registration only affects on-call. Incidents link to teams by handle, as described in [Connecting an entity to Datadog incidents](#connecting-an-entity-to-datadog-incidents).

#### Schedules and Teams

You can register both on the same entity. Use this when a team owns the entity but you also want a specific shared rotation on it:

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: TEAM
      id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9
    - type: SCHEDULE
      id: ee409e39-5449-4eb8-900f-8bea9d2162d7
```

### **How Datadog users map to Cortex users**

Datadog on-call users are resolved to Cortex users by email address. If a Datadog user has no matching Cortex account, Cortex displays their email address instead of a linked user.


# Using the integration for Datadog
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog/using-the-integration-for-datadog



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for Datadog. For configuration instructions, see [Configuring the integration for Datadog](/ingesting-data-into-cortex/integrations/datadog). For instructions on connecting Datadog to entities, see [Connecting entities to Datadog](/ingesting-data-into-cortex/integrations/datadog/connecting-entities-to-datadog).

## **Viewing monitors and SLOs on an entity's details page**

High-level information about monitors and service level objectives (SLOs) appears in the **Overview** tab on an entity's details page:

![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/datadog-high-level.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=9356f87860406e0a9509bb8d816b098e)

To drill into the data, locate **Connections** in the left details sidebar, expand **Observability**, then select Datadog.

![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/datadog-observability.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=52a05c18d6d63798bc86c028c7d3bd5c)

The Datadog Monitoring page opens. Select a tab to view the following:

* **All** - Shows both monitors and SLOs.
* **Monitors** - Shows the title for each monitor, its query (if available), and its status.
* **SLOs** - Shows each SLO for the entity: its targets, current value, status, and the time period it's calculated over. For example, "7 days ago" means the SLO covers the range from 7 days ago to now.

Click any monitor or SLO block to open Datadog, where you can dig further into the data.

### Discovery audit

Cortex pulls recent changes from your Datadog environment into the [discovered entities list](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit). Here, you can find new entities in Datadog that have not been imported into your Cortex catalog. These entities have the **New APM Resource** tag. You'll also find entities in the catalog that no longer exist in Datadog. These have the **APM Resource Not Detected** tag.

## Viewing incident data

### Incident list

You can view incident data in the incident list and on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

See every incident across your organization in one place, with metadata including severity, status, and affected entities.

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incident-list.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=13c406f0ee0dd97f918e37745856beb8)

**To access the incident list**:

1. From the main sidebar, expand **Integrations**, then select **Data**.
2. Select the **Incidents** tab.

The list is sorted by most recently opened incidents first.

#### **Searching across and filtering the incident list**

There are several ways to search and filter the list:

* To find specific incidents, use the search bar in the upper-right corner of the page and type to search.
* By default, the list sorts by most recently opened incident. Click **Opened** to reverse the order, or click **Name** to sort alphabetically instead.
* Click **Filter** to narrow down your list by date range, severity level, or status.

### Incidents on an entity's details page

View incidents in the following places on an entity's details page:

* On the **Overview** tab; active incidents are prominently displayed at the top of the page

  ![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incidents-overview.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=47597d54e017259b6923ed5d2cb541c2)
* In the left details sidebar, locate **Connections**, then select **Incidents**

  ![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incidents-side-panel.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=d81efeab515878e496af6c2a8c1ecda7)

## Viewing on-call information

### On-call shift data

View all on-call shifts ingested via the Datadog integration in a single place. This allows you to see exactly what data Cortex has brought in from the integration and what entities it's been linked to within Cortex.

**To access the on-call list**:

1. From the main sidebar, expand **Integrations**, then select **Data**.
2. Select the **On-call shifts** tab.
3. Do one of the following:
   * Select the **All** tab to view all on-call shifts in your workspace.
   * Select the **Mine** tab to view only your on-call shifts.

The list is sorted alphabetically by schedule name. Click a row to open a side panel showing who's on call now, who's on call next, and the teams the schedule is associated with.

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incident-on-call-tab.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=d05a263f674f93fd29034b6c1fe71bf9)

#### Searching across and sorting the on-call list

To search and sort the list:

* Use the search bar in the upper-right corner of the page and type to search.
* By default, the list sorts alphabetically by schedule name. Click **Name** to sort from Z to A.

### On-call on an entity's details pages

View current on-call information in the following places on an entity's details page:

* In the metadata sidebar in the **On-call now** block

  ![](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/oncall-block.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=143d3323e83228e4fd2ca4446c66c567)
* In the left details sidebar, locate **Connections**, then select **On-call**
  * Click a row to open a side panel showing who's on call now, who's on call next, and the teams the schedule is associated with.

    ![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/datadog-oncall.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=069a0c073087d8ea089846d96cf33d2f)

### Engineering homepage

View upcoming on-call rotations in the **My on-calls** block on your engineering homepage. Cortex shows on-call schedules up to six months out.

![](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/homepage-oncalls.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=891e6100fa27f48736a6b006120304fc)

## Creating Scorecard rules with Datadog data

Cortex Query Language (CQL) lets you write Scorecard rules and queries against Datadog data, including:

* Metrics
* Monitors
* SLOs
* Incidents
  * Common Scorecard rules include:
    * Ensure services have had no critical incidents in the past 30 days
    * Verify mean time to resolution meets your SLOs
* On-call
  * Common Scorecard rules include:
    * Verify that all production services have an on-call schedule configured
    * Ensure critical services have on-call coverage before go-live

For more information, including example queries, refer to the [in-app Datadog CQL documentation](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Integrations\&path=Datadog).

## Incident metrics in Eng Intelligence

Incident metrics in [Eng Intelligence](/improve/eng-intelligence) are powered by the same unified data pipeline as the incident list, so the numbers stay consistent across Cortex. Eng Intelligence supports the following incident metrics:

* Incident frequency
* Mean time to resolution (MTTR)

## Syncing data from Datadog

Cortex syncs data from Datadog as follows:

* **Monitors and SLOs** - Cortex syncs Datadog monitor and SLO data on a background schedule, so values in Cortex may lag live Datadog by up to 30 minutes.
* **Dependencies** - The dependency sync runs automatically each day at 12 a.m. UTC, and can be run manually via the [Sync dependencies button](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies#sync-dependencies) in the relationship graph.
* **Incident data** - Cortex syncs incident data from Datadog every 15 minutes.

  Because Datadog does not support sorting incidents by last-modified date, Cortex refreshes the full incident set on each sync rather than fetching only what changed. Edits to older incidents are picked up on the next full refresh.
* **Schedule and shift data** - Cortex syncs schedule and shift data from Datadog every 30 minutes. Because Datadog schedules do not expose a last-modified timestamp, Cortex refreshes the full schedule set on each sync rather than fetching only what changed.

## Viewing Datadog integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

**Monitoring**

> **Can I set a Scorecard rule to monitor Datadog monitors/SLOs based on tags?**
>
> Yes, you can specify key-value pairs that allow Cortex to discover your SLOs and monitors, and use these tags in Scorecard rules.

**Dependency**

> **How does Datadog work with other dependency sources?**
>
> When leveraging multiple dependency sources such as Datadog and a catalog entity's YAML, all the sources would be merged together and Cortex will de-duplicate the dependencies.
>
> For example, if an entity YAML indicates `X → Y` and Datadog indicates `X → Y` and `X → Z`, the entity will display two edges presented as `X → Y` and `X → Z`.

**On-Call**

> **I connected Datadog but no on-call data appears on my entity.**
>
> On-call requires an explicit registration. Confirm the entity has a `SCHEDULE` or `TEAM` registration, either in the on-call editor or in the entity descriptor, and that the ID matches the one in the Datadog URL.

> **I registered a team but see no schedules.**
>
> A `TEAM` registration maps every schedule that carries that team in Datadog. If the team has no schedules attached, nothing will map. Register the schedule directly instead.

> **Why does my schedule show a different person than the rotation says?**
>
> Overrides in Datadog take precedence. Cortex shows the effective on-call person for the current shift.

> **A responder appears twice in the participant list.**
>
> This is expected when a user is a member of more than one layer on the same schedule.


# Dynatrace
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/dynatrace



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

### Overview

[Dynatrace](https://www.dynatrace.com/) is a monitoring and observability platform. Integrate Dynatrace with Cortex to get insights into application performance, service discovery, SLOs, and dependencies.

## How to configure Dynatrace with Cortex

### Prerequisite

Before getting started, generate an [access token in Dynatrace](https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-authentication) with the scopes `Read entities` and `Read SLO`.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Dynatrace settings page](https://app.getcortexapp.com/admin/integrations/dynatrace).
   * Click **Integrations** from the main nav. Search for and select Dynatrace.
2. Click **Add configuration**.
3. Configure the Dynatrace integration form:
   * **Domain**: Enter your [Dynatrace domain](https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/get-entities-list) necessary to access your environment, depending on whether you use managed, SaaS, or the Environment ActiveGate version.
   * \**API token*: Enter the access token you generated in Dynatrace.
4. Click **Save**.

If you’ve set everything up correctly, you’ll see the option to **Remove Integration** in settings.

You can also use the **Test configuration** button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

## How to connect Cortex entities to Dynatrace

### Import entities from Dynatrace

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#creating-services) for instructions on importing entities.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

**Entity ID**

Entities with a type of `"SERVICE"` will be discovered and surfaced. When using the Dynatrace portal, service IDs can be found in the URL of a selected service under the id query param. For example, `https://.live.dynatrace.com/#newservices/serviceOverview;id=`

```yaml theme={null}
x-cortex-apm:
  dynatrace:
    entityIds:
      - mock-service-id-1
      - mock-service-id-2
```

**Entity name**

You can also match entities based on matching [display names](https://www.dynatrace.com/support/help/dynatrace-api/environment-api/entity-v2/get-entities-list#response-body-objects) with a regular expression, like:

```yaml theme={null}
x-cortex-apm:
  dynatrace:
    entityNameMatchers:
      - "foo.*"
```

#### Linking SLOs in Cortex

Dynatrace supports service-level objective (SLO) monitoring. You can link these SLOs to your Dynatrace entity in Cortex:

1. In Dynatrace, navigate to the Service-Level Objectives app.
   * On the left sidebar of Dynatrace, click **Search**, then type in `slo` to find the app.
2. On the SLOs page, see the list of SLOs. On the right side of an SLO, click **^** to expand the Details.

   ![The details button is on the right side of an SLO](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/dynatrace-details.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=82c22349a08b5f7a58125ec2c39c2244)
3. In your browser's URL bar, locate the ID in the URL. Copy the ID and store it in a secure location, as you will need this value in the next steps.
   * The ID is displayed in the URL following `sloexp=`. For example, `https://.apps.dynatrace.com/ui/.../sloexp=&slovis=` ![The SLO ID is in the URL](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/dynatrace-slo-id.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=8199e4fe3b447860d8088b750091b1d8)
   * On the SLOs page, expand the details for each SLO to display the SLO ID in the URL.
4. Open your Cortex home page, then navigate to the service you are configuring.
5. In the upper right corner of the service page, click **Switch to YAML**.
6. Paste in the following text, making sure to replace `slo-id-1` and `slo-id-2` with the SLO IDs you obtained from the Dynatrace URL in the previous steps:

```yaml theme={null}
x-cortex-slos:
  dynatrace:
    - id: slo-id-1
    - id: slo-id-2
```

7. At the bottom of the page, click **Save**.

After saving, navigate back to your service details page to view the SLO status in the service's Overview tab.

For information on working with SLOs in Dynatrace, see [Dynatrace's documentation](https://docs.dynatrace.com/docs/platform-modules/automations/service-level-objectives/configure-and-monitor-slo).

#### Dependencies

Cortex automatically syncs [dependencies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies) from Dynatrace using attributes inherent to each entity.

#### Discovery audit

Cortex will pull recent changes from your Dynatrace instance into the [discovered entities list](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit). Here, you can find new entities in Dynatrace that have not been imported into the catalog - these will have the tag **New APM resource** - as well as entities in the catalog that no longer exist in Dynatrace - these will have the tag **APM resource not detected**.

## Using the Dynatrace integration

#### Entity pages

With the Dynatrace integration, you'll see SLOs on an entity's home page. High-level information about SLOs appears in the **Overview** tab.

Click **Monitoring** in the entity's sidebar to see more detailed data: the SLO name, its target, the current value for that entity, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.

#### Relationship graphs

[Dependencies](/ingesting-data-into-cortex/integrations/dynatrace#dependencies) detected from Dynatrace will appear in [Relationship graphs](https://app.getcortexapp.com/admin/graph).

### Scorecards and CQL

With the Dynatrace integration, you can create Scorecard rules and write CQL queries based on Dynatrace SLOs.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **SLOs**
>
> SLOs associated with a given entity via ID or tags. You can use these data to check whether an entity has SLOs associated with it and if those SLOs are passing.
>
> * History
> * ID
> * Name
> * Operation
> * Remaining budget
> * SLI value
>   * Datum
>   * Timeseries
> * SLO target
> * Source
> * Thresholds
>   * Name
>   * Threshold
>
> **Definition:** `slos()`
>
> **Examples**
>
> For a Scorecard focused on operational maturity, this expression can be used to make sure an entity has associated SLOs in Dynatrace:
>
> ```
> slos().length > 0
> ```
>
> This rule checks that there is at least one SLO is set up. While this rule makes sense in a Scorecard's first level, a rule checking the status of the SLO would make sense in a higher level:
>
> ```
> slos().all((slo) => slo.passing)
> ```
>
> Entities will pass this rule if all SLOs associated with it have "passing" status.

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts a background sync of Dynatrace entities at 7 a.m. UTC and a dependency sync every day at 12 a.m. UTC. You can [manually sync dependencies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies#sync-dependencies) via the Relationship Graph.


# Entra ID
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/entraid



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id), formerly known as Azure Active Directory, is an identity service that provides SSO and authentication.

Integrating Cortex with Entra ID allows you to:

* Automatically discover and track Entra ID teams and team memberships
* Track ownership of entities
* Create [Scorecards](/ingesting-data-into-cortex/integrations/entraid#scorecards-and-cql) that track progress and drive alignment on projects involving your Entra ID teams

> [!NOTE]
>
> For information on configuring Entra ID SSO for logging in to Cortex, see the [Microsoft Entra ID SSO documentation](/configure/settings/managing-users/configuring-sso/entraid).

## How to configure Entra ID with Cortex

### Step 1: Register and configure a new Active Directory application

1. Follow Microsoft's documentation to [register a new single tenant Entra ID application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate#register-an-application).
2. In your Entra ID admin center, navigate to your new application, and then to API Permissions. Add the following permissions:
   * Microsoft APIs > Microsoft Graph > Application permissions > User > `User.Read.All`
   * Microsoft APIs > Microsoft Graph > Application permissions > Group > `Group.Read.All`
3. Click **Grant Admin Consent** to grant permissions for all accounts in the directory.
4. Navigate to **Certificates & secrets** and click **New client secret**.
   * Note that you will need to rotate the secret before the expiration date you set for it.
5. Navigate to the application's Overview page and copy the client ID. You will need the client ID and secret in the next steps.

### Step 2: Configure the integration in Cortex

1. In Cortex, navigate to the [Entra ID settings page](https://app.getcortexapp.com/admin/integrations/microsoft-entra-id).
   * Click **Integrations** from the main nav. Search for and select **Entra ID**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **Tenant ID**: Enter your Entra ID [tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant#find-tenant-id-through-the-azure-portal).
   * **Client ID** and **Client secret**: Enter the client ID and secret you generated in the previous steps.
4. Click **Save**.
   * You will be redirected to the Azure Active Directory settings page in Cortex, where you can optionally set a group filter to limit which groups are pulled in from Entra ID.

## How to connect Cortex entities to Entra ID

### Import entities from Entra ID

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#importing-services-from-an-integration) for instructions on importing entities.

### Syncing ownership from Entra ID

To assign an Entra ID group as an owner, add it to the entity descriptor. The `provider` value is `ACTIVE_DIRECTORY`, from the service's former name, Azure Active Directory.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: Engineering # group name in Entra ID
    provider: ACTIVE_DIRECTORY
```

The group name is case-sensitive and should be exactly the same as in Entra ID.

Cortex syncs Entra ID ownership every day at 6 a.m. UTC. Cortex uses [identity mappings](/configure/settings/managing-users/identity-mapping) to connect group members to Cortex users when they exist, and falls back to each member's email address from Entra ID otherwise.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

## Using the Entra ID integration

### Teams page

Under **Catalogs > Teams**, you will see teams and team members pulled in from Entra ID.

### Entity pages

If you have ownership of entities set up, then Azure AD teams and users will be listed in the **Owners** page for an entity.

### Scorecards and CQL

With the Entra ID integration, you can create Scorecard rules and write CQL queries based on Entra ID teams.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts an ownership sync every day at 6 a.m. UTC.

## FAQ and Troubleshooting

**Why were all my Entra ID users unexpectedly deleted after rotating my client secret?**

Updating your configuration can cause a temporary deletion of users. When you delete the old secret from your Azure AD configuration in Cortex, a sync is triggered to delete the users. The addition of the new secret to your configuration will trigger a sync to add the users. There may be a delay before seeing the users re-added.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# FireHydrant
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/firehydrant



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[FireHydrant](https://firehydrant.com/) is an incident management platform that emphasizes reliability and consistency across the entire incident response lifecycle.

Integrating FireHydrant with Cortex allows you to:

* [View incidents on entity pages](/ingesting-data-into-cortex/integrations/firehydrant#viewing-firehydrant-incidents-on-an-entity) in Cortex, giving you insight into incidents to act on them quickly
* [Trigger new incidents](/ingesting-data-into-cortex/integrations/firehydrant#trigger-an-incident) directly from Cortex
* Create [Scorecards](/ingesting-data-into-cortex/integrations/firehydrant#scorecards-and-cql) to set standards around incident management and production readiness

## How to integrate FireHydrant with Cortex

### Prerequisites

Before getting started:

* Create a [FireHydrant API key](https://app.firehydrant.io/settings/api_keys).

### Configure the integration in Cortex

1. In Cortex, navigate to the [FireHydrant settings page](https://app.getcortexapp.com/admin/integrations/firehydrant):
   * Click **Integrations** from the main nav. Search for and select **FireHydrant**.
2. Click **Add configuration**.
3. Configure the integration:
   * **API key**: Enter the API key you created in FireHydrant.
4. Click **Save**.

## How to connect Cortex entities to FireHydrant projects

### Editing the entity descriptor

You can define FireHydrant services in an [entity's YAML file](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file).

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

For a given entity, define FireHydrant services by ID or slug. Each of these has the same field definitions.

| Field | Description | Required |
| - | - | :-: |
| `identifier` | Service ID or slug | **✓** |
| `identifierType` | Type of identifier (`ID` or `SLUG`) | **✓** |

```yaml theme={null}
x-cortex-firehydrant:
  services:
    - identifier: ASDF1234
      identifierType: ID
```

You can find the service ID value in FireHydrant under **FireHydrant > Catalog > Services**. The URL for the service will also contain the ID (e.g., `https://app.firehydrant.io/catalog/services/{ID}/incidents`).

If you prefer to use the service slug in the registration instead, you can find it on the right-hand side of the service page in FireHydrant.

```yaml theme={null}
x-cortex-firehydrant:
  services:
    - identifier: service-slug
      identifierType: SLUG
```

## Using the FireHydrant integration

### Viewing FireHydrant incidents on an entity

When active incidents are detected in FireHydrant, Cortex will display incident information on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

Click **On-call & incidents** in the entity's sidebar to see all detected incidents.

Each issue will be listed with its title and description (when available). Cortex will also display the status for an issue as a badge next to its name:

* `Acknowledged`
* `Closed`
* `Detected`
* `Identified`
* `Investigating`
* `Mitigated`
* `Postmortem completed`
* `Postmortem started`
* `Resolved`
* `Started`

The issue's severity will also appear in a badge (e.g. `SEV0`, `SEV1`, `SEV2`).

### **Trigger an incident**

While viewing an entity in Cortex, you can trigger an incident in FireHydrant:

1. In Cortex, navigate to an entity. On the left side of an entity details page, click **On-call & incidents.**
2. In the upper right side of the entity's "On-call" page, click **Trigger incident**.
3. Configure the incident modal:
   * **Summary**: Enter a title for the incident.
   * **Description**: Enter a description of the incident.
   * **Severity**: Select a severity level.
   * **Condition:** Nature of the incident - `Unavailable`, `Partially Unavailable`, `Degraded`, `Bug`, or `Operational`.
4. At the bottom of the modal, click **Trigger incident**.
   * A confirmation screen will appear. In the confirmation, click the link to view the incident in FireHydrant.

### Scorecards and CQL

With the FireHydrant integration, you can create Scorecard rules and write CQL queries based on FireHydrant incidents.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if FireHydrant service is set**
>
> Check if entity has a registered FireHydrant service in its entity descriptor. If no registration exists, we'll try to automatically detect which corresponding FireHydrant service is associated with the entity.
>
> **Definition:** `firehydrant (==/!=) null`
>
> **Example**
>
> For a Scorecard focused an production readiness, you can use this expression to make sure a FireHydrant service - and thus incident response - is defined for entities:
>
> ```
> firehydrant != null
> ```
>
> This is also a good way to make sure over time that FireHydrant is set up properly and reporting frequently.

> **Incidents**
>
> List of incidents, filterable on severity and status.
>
> * Created at
> * Description
> * Impact condition name
> * Name
> * Severity
> * Status
>
> **Definition:** `firehydrant.incidents()`
>
> **Examples**
>
> For a Scorecard focused on service maturity or quality, you can use this expression to make sure there are no detected or identified FireHydrant incidents with a severity rating of 1 for a given entity:
>
> ```
> firehydrant.incidents(severity = ["SEV1"], statuses = ["Detected", "Identified"]).length == 0
> ```
>
> You can also tier severity-based rules to indicate progress over time. While the above rule might make sense in the first or second level, a higher-severity rule might make sense in a higher level:
>
> ```
> firehydrant.incidents(severity = ["SEV3"], statuses = ["Detected", "Identified"]).length == 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# GitHub
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/github



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Why use the integration for GitHub

GitHub is a Git-based source code management platform that helps teams share code, track changes over time, and collaborate on projects across an organization.

Integrating GitHub with Cortex allows you to:

* Automatically discover GitHub repositories and track ownership of the entities they represent in Cortex
* Manage your Cortex workspace through a GitOps workflow, using GitHub as the source of truth for entity definitions
* View repository context directly on an entity's details page, including the associated repo, recent commits and releases in the event timeline, the most-used language, and top contributors with their contribution counts
  * In an entity's **Code & Security** section, surface vulnerabilities from [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security), including code scanning, Dependabot alerts, CodeQL, and secret scanning
* Track pull requests and work items from the [engineering homepage](/ingesting-data-into-cortex/integrations/github#engineering-homepage) to keep delivery work visible alongside the rest of your catalog
* Use GitHub metrics in [Eng Intelligence](/improve/eng-intelligence) to understand service health, incident response patterns, and other key engineering signals
* Create [Scorecards](/ingesting-data-into-cortex/integrations/github#scorecards-and-cql) that drive alignment and measure progress on initiatives involving your repositories

You can also optionally integrate GitHub Copilot with Cortex to:

* Track Copilot adoption and measure its impact on engineering productivity within Eng Intelligence

> [!NOTE]
>
> **GitHub Copilot integration**
>
> If you installed the GitHub app prior to October 14, 2025, you must accept new permissions in order to access Copilot metrics in Cortex.
>
> In your email, locate the message with subject line "\[GitHub] Cortex App is requesting updated permissions" from `noreply@github.com` and click the link to review and accept the change. As a security best practice, always verify that the email was sent from a trusted domain. In GitHub, click **Accept new permissions**.
>
> Alternately, you can remove your GitHub integration in Cortex and re-configure it. The GitHub app is preconfigured to include the permissions necessary for the Copilot integration.

## Configuring GitHub

### Prerequisites

If you connect Cortex via a [custom GitHub app](/ingesting-data-into-cortex/integrations/github#custom-app), it must be configured with a [fine-grained personal access](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens) token containing the minimum permissions listed below. Note that the [Cortex GitHub app](/ingesting-data-into-cortex/integrations/github#cortex-github-app) is preconfigured with these permissions.

#### Repository permissions

| Permission | Requirement | Purpose in Cortex |
| - | - | - |
| **Actions** | `Read & write` |  • Read workflow run information for Git-based CQL rules • Artifact information for actions |
| **Administration** | `Read & write` | Create repositories |
| **Checks** | `Read & write` | Create and update check runs for linting and validation workflows, such as the `cortex.yaml` linter on pull requests |
| **Code scanning alerts** | `Read-only` | Get vulnerability information for Git-based CQL rules |
| **Commit statuses** | `Read & write` |  • Read commits for an entity's Git metadata • Read commits for Git-based CQL rules • Show pending status messages on the OpenAPI incompatibility check |
| **Contents** | `Read & write` |  • Read `cortex.yaml`, `cortex-properties.yaml`, and package/OpenAPI files • Read Git rules • Create file contents |
| **Custom properties** | `Read & write` | Used in [Workflows](/streamline/workflows) |
| **Dependabot alerts** | `Read-only` | Read vulnerability information for Git CQL rules (only relevant if using Dependabot) |
| **Deployments** | `Read & write` | Used in [Workflows](/streamline/workflows) |
| **Issues** | `Read & write` |  • Read associated issues with repositories for populating entity Git integration and for Git CQL rules • Create new issues based on [Initiatives](/improve/initiatives) |
| **Metadata** | `Read-only` | Read associated data with repositories for populating entity Git integration and for Git CQL rules |
| **Pull requests** | `Read & write` |  • Read pull request data for Git CQL rules and developer homepage "My PRs" tab • Comment if there are breaking OpenAPI changes on a PR |
| **Secret scanning alerts** | `Read-only` | Read vulnerability information for secret scanning |
| **Secrets** | `Read & write` | Optionally write repo secrets after creating new repo |
| **Single file** | `Read & write` (path to cortex.yaml) |  • Read `cortex.yaml` files • Create `cortex.yaml` files |
| **Workflows** | `Read & write` | Write in GitHub actions files |

#### Organization-level permissions

| Permission | Requirement | Purpose in Cortex |
| - | - | - |
| **Administration** | `Read-only` |  • Create repositories • Pull in Copilot data for [Eng Intelligence](/improve/eng-intelligence) |
| **Members** | `Read & write` |  • Read membership information for ownership and team composition • Write permission used in [Workflows](/streamline/workflows) |
| **GitHub copilot business** | `Read-only` | Read copilot-related metrics for AI Impact Dashboard |

#### Enabling PR webhooks (optional but recommended)

Cortex ingests pull request (PR) data via the GitHub API. Subscribing to GitHub's PR webhooks adds a real-time stream of PR events that Cortex cross-references against API data, which is the most efficient way to ensure every PR and event is captured without gaps.

**If you use the Cortex GitHub app, no action is required**. The Cortex GitHub app receives these PR webhook events by default, so you get real-time PR data out of the box.

**If you use a custom GitHub app or a personal access token (PAT)**, you must subscribe to the following events manually at the repository or organization level:

* Pull requests
* Pull request reviews
* Pull request review comments
* Pull request review threads
* Issue comments (GitHub delivers PR comments as issue-comment events)
* Organizations
* Repositories

For a custom GitHub app, select the above events under your app's **Permissions & events > Subscribe to events**, then click **Save**.
For a PAT connection, add the above events to your Cortex webhook under the repository or organization's **Settings > Webhooks**.

Cortex begins receiving PR webhook events immediately and automatically cross-references them against standard API ingestion to validate the data.

### Choosing a configuration option

There are multiple options for connecting Cortex to your GitHub instance:

* Through Cortex's official GitHub app
  * This option is supported for use with a single organization in GitHub.
* Through a custom GitHub app
  * By using Cortex's official GitHub app or a custom GitHub app, users can tag entities with Git details and enable GitOps-style configuration of data in Cortex.
* Using a personal access token
* Using Cortex Axon Relay, a relay broker that allows you to securely connect your on-premises GitHub data.

If your GitHub setup involves multiple organizations, you can add multiple GitHub apps, use a [personal access token](/ingesting-data-into-cortex/integrations/github#personal-access-token) that has access to all orgs, or create multiple configurations with corresponding aliases.

Expand the tabs below for instructions on each of the GitHub integration options.

> [!NOTE]
>
> If you're using a self-hosted instance of GitHub, you'll need to verify that your Cortex instance is able to reach the GitHub instance. Requests are routed through a static IP address.
>
> Contact support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your GitHub instance.

> **Cortex GitHub app**
>
> **Configure GitHub with the Cortex GitHub app**
>
> [Cortex's official GitHub app](https://github.com/apps/cortex-app) is the easiest way to connect your GitHub instance. It is preconfigured with the [permissions](/ingesting-data-into-cortex/integrations/github#prerequisites) needed to use this integration. Note that it is not available for Cortex Server.
>
> To set up the app:
>
> 1. In Cortex, navigate to the [GitHub settings page](https://app.getcortexapp.com/admin/integrations/github):
>    1. Click **Integrations** from the main nav. Search for and select **GitHub**.
> 2. On the GitHub settings page, next to `cortex`, click **Install**.
>
>    ![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/cortex-github.app.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=d7cae76d453104d74a000e1ad23790b3)
> 3. Follow the prompts, then click **Install & Authorize**.
>
> Cortex's GitHub app is preconfigured with:
>
> * Permissions for [catalogs](/ingesting-data-into-cortex/catalogs), [Scorecards](/standardize/scorecards), and the [Scaffolder](/streamline/workflows/scaffolder).
> * Webhooks to enable [GitOps](/configure/gitops).
> * Support for using [GitHub teams](https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams) as an ownership provider.
>
> The app comes with a built-in linter, which validates the format of a given `cortex.yaml` file and checks Cortex-specific items. **However, the linter DOES NOT validate data correctness.** For example, the linter will confirm that the format of a group block is correct, but will not check that the group exists.

> **Custom app**
>
> **Configure GitHub with a custom app**
>
> If you're using Cortex Server, or if you don't want to use the official Cortex app, you can connect a custom GitHub app.
>
> Make sure you have configured the permissions listed above under [Prerequisites](/ingesting-data-into-cortex/integrations/github#prerequisites).
>
> **Step 1: Register the custom app in GitHub**
>
> 1. [Register the app](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). When you're creating the app, make sure to follow these steps:
>    * **Disable** "Expire user authorization tokens." (Cortex does not support this OAuth workflow yet.)
>    * **Select** "Request user authorization (OAuth) during installation."
>    * **Callback URL:** `https://app.getcortexapp.com/github/redirect/{alias}`
>      * Make sure to use the GitHub configuration alias and not the tenant name in the URL.
>    * **Webhook URL:** `https://api.getcortexapp.com/api/internal/v1/github/webhook`
>    * **Add** a webhook secret of your choosing that will be identical to the webhook secret token configured later in Cortex settings.
>    * **Set** the repository and organization [permissions](/ingesting-data-into-cortex/integrations/github#prerequisites) outlined in the configuration modal.
>    * **Check** `Push` and `Check suite` under **Subscribe to events**.
> 2. After the app has been created, generate a client secret and private key.
>
> **Step 2: Configure the custom app in Cortex**
>
> 1. In Cortex, navigate to the [GitHub settings page](https://app.getcortexapp.com/admin/integrations/github):
>    * Click **Integrations** from the main nav. Search for and select **GitHub**.
> 2. Click **Add configuration**, then for the type, select **GitHub app**.
> 3. Fill in the form:
>    * **Alias:** Enter the name Cortex will associate with a given configuration.
>    * **Application ID:** Enter the ID for your custom GitHub ap.
>    * **Client ID:** Enter the unique [client ID](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app#registering-your-app) assigned to your app during registration.
>    * **Client secret:** Enter the unique client secret assigned to your app during registration.
>    * **Private key:** Enter the [private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys) to authenticate with your GitHub app.
>    * **Public link:** Enter the public URL of your GitHub app.
>    * **API endpoint (for GitHub enterprise):** Enter the endpoint root URL for self-managed GitHub setups.
> 4. Click **Save**.
> 5. On the GitHub Settings page in Cortex, under **Webhook**, choose your new configuration alias and enter the same **Secret token** that was entered in GitHub during the app configuration.
> 6. On the GitHub Settings page in Cortex, next to your custom app configuration's name, click **Install**.

> **Personal access token**
>
> **Configure GitHub with a personal access token**
>
> **Prerequisites**
>
> Before getting started, make sure your [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) has, at minimum, the `repo` and `read:org` permissions.
>
> Note: Beyond the minimum permissions indicated above, many scenarios will require that the user who generated the personal access token have organization ownership permissions within GitHub.
>
> **Configuration**
>
> 1. In Cortex, navigate to the [GitHub settings page](https://app.getcortexapp.com/admin/integrations/github):
>    * Click **Integrations** from the main nav. Search for and select **GitHub**.
> 2. Click **Add configuration**.
> 3. In the upper right corner of the modal, click the dropdown and select **Personal access token**.
>
>    ![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/github-pat%20%281%29.jpg)
> 4. Fill in the form:
>    * **Alias:** Enter a name that Cortex will associate with a given configuration.
>    * **Token:** Enter the Personal access token generated in GitHub.
>    * **API endpoint (for GitHub enterprise):** Enter the endpoint root URL for self-managed GitHub setups.
> 5. Click **Save**.

> **Axon Relay**
>
> **Configure GitHub with Cortex Axon Relay**
>
> See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for instructions. Make sure to follow the GitHub-specific instructions for the docker-compose.yml file.

#### **Configuring the integration for multiple GitHub accounts**

The GitHub integration has multi-account support. You can add a configuration for each additional organization, instance, or account by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated organization, instance, or account with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the GitHub page in your Cortex settings.

**To set the default configuration**:

1. From the main sidebar, select **Integrations**.
2. Locate GitHub, then click **Settings**.
3. Locate the configuration, then click the **pencil icon**.
4. From the **Category** drop-down menu, select a category. You must select at least one category before you can set the configuration as default.
5. Toggle on **Set as default**.

   \> **Tip**: If you only have one configuration, it's automatically set as the default.

Cortex supports mapping multiple identities for a single user if you have multiple configurations of GitHub. See [Configuring identity mappings](/configure/settings/managing-users/identity-mapping) for more information.

> [!NOTE]
>
> To write rules related to Dependabot alerts, you must verify the necessary permissions are set for repositories you'd like to see vulnerabilities reported on.
>
> To verify, navigate to a GitHub repo and click **Settings > Code security and analysis**. Ensure you are a member of a team under **Access to alerts**.

## Registration

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#importing-services-from-an-integration) for instructions on importing entities.

### Entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

**Repository**

You can define a GitHub repository for a given entity by adding the `x-cortex-git` block to the entity's descriptor. When you define a repository, Cortex checks for Security Advisory vulnerabilities from the GraphQL API and Advanced Security vulnerabilities from the Rest API.

```yaml theme={null}
x-cortex-git:
  github:
    repository: cortex/docs
    basepath: myService
    alias: myApp
```

| Field | Description | Required |
| - | - | - |
| `repository` | GitHub repository in the form `/` | **✓** |
| `basepath` | Subdirectory for the entity if it is in a monorepo. Note that setting a `basepath` filters the vulnerabilities that appear in Cortex; Advanced Security vulnerabilities will not appear. | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

Only one repository can be defined for in a given entity's YAML in the `x-cortex-git` block. Users looking to list additional repositories without the full functionality of GitOps can define the repos as custom data.

```yaml theme={null}
x-cortex-custom-metadata:
  second-git-repo:
    - `/`
  third-git-repo:
    - `/`
```

#### Syncing ownership from GitHub

You can define the following block in your Cortex entity descriptor to add your GitHub teams as owners. Be sure to include both your GitHub organization name and the team name in the `name` field.

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: cortex/engineering
    provider: GITHUB
    description: This is a description for this GitHub team that owns this entity.
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Ownership type; must be defined as `group` for GitHub teams | **✓** |
| `name` | GitHub team name in the form `/`Team names are generally converted to lowercase with `-` separators (`Team Name` would be `cortex/team-name`), but you can verify your exact name from the GitHub permalink | **✓** |
| `provider` | Name of integration (in this case, `GITHUB`) | **✓** |
| `description` | Description for the GitHub team | |

> [!WARNING]
>
> Multiple GitHub organizations are not supported for ownership, and Cortex will use the default configuration when fetching teams.

Cortex syncs GitHub teams and their members every day at 9 a.m. UTC. Cortex connects team members to their Cortex users through [identity mappings](#identity-mappings).

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

### Identity mappings

Cortex maps users' email addresses to discovered GitHub accounts, so you never need to define email ownership in an entity descriptor. Users must be members of GitHub teams to be pulled in to Cortex.

You can confirm users' GitHub accounts are connected from [GitHub identity mappings in settings](https://app.getcortexapp.com/admin/settings/github-mappings).

## Using the GitHub integration

### View GitHub data on entity pages in Cortex

The GitHub integration will populate the **Repo** and **Language** detail blocks on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). If a GitHub team has been [defined as the owner](/ingesting-data-into-cortex/integrations/github#syncing-ownership-from-github) for an entity, it will also appear in the **Owners** block.

#### Code & security

Vulnerabilities appear in the **Vulnerabilities** block under **Code & security** on an entity page overview.

Click **Code & security** in an entity's sidebar to view the full list of vulnerabilities for an entity. Cortex checks for:

* Security Advisory vulnerabilities from the GraphQL API
* [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) vulnerabilities
  * Cortex pulls data from code scanning, Dependabot alerts, CodeQL, and Secret scanning.
  * Dependency reviews are not supported.

GitHub Advanced Security vulnerabilities are not surfaced for monorepos.

> [!TIP]
>
> You can query for vulnerabilities with CQL and create Scorecard rules based on security metrics. See [Scorecards and CQL](/ingesting-data-into-cortex/integrations/github#scorecards-and-cql) below.

#### **Events**

Recent commits appear at the top of an entity's overview page.

You can also click **Events** in the entity's sidebar to see all commits and releases associated with that entity. Each is hyperlinked to the commit or release page in GitHub and includes a timestamp.

#### **Repository**

You can access more detailed information pulled from GitHub in the **Repository** page in the sidebar. At the top of the page, you'll find the repo(s) associated with that entity and the most-used language in files for that entity. In the **Top contributors** block, you'll find the three users who have contributed the most code and the number of their contributions.

In the **Commits** section, you'll find the 10 most recent commits and metadata about each. Below **Commits** is the **Recent releases** section, which includes the 5 most recent releases.

#### **Issue tracking**

From the **Issue tracking** page in the entity's sidebar, you can find a list of open [GitHub issues](https://docs.github.com/en/issues). Each issue will show the number, title, assignees, and date created.

#### **Packages**

Packages are automatically scraped from your Git repos or they can be submitted via the [packages API](/api/rest/packages). The package file must be in the root of your repository — or, if you're using `basepath`, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) using `packages()`.

To view packages, click **Packages** in the entity's sidebar.

The following package types are automatically scraped from repositories:

* JavaScript / Node.js: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Python: `requirements.txt`, `pipfile.lock`
* .NET (C#): `packages.lock.json`
* Java: `pom.xml`
* Go: `go.sum`

All other files of these types can be added via the [packages API](/api/rest/packages).

#### **CI/CD - GitHub workflows**

From the **CI/CD > GitHub workflows** page in the entity's sidebar, you can find a history of [GitHub workflow](https://docs.github.com/en/actions/using-workflows/about-workflows) runs for the past week. Each run is tagged with its status: `IN_PROGRESS`, `COMPLETED`, `SUCCESS`, `CANCELLED`, `FAILURE`, `PAUSED`.

The **GitHub workflows** page displays data about workflows in GitHub, **not** Workflows initiated via [Cortex's Workflows tool](/streamline/workflows).

### Team entity pages

When a [GitHub team is registered](/ingesting-data-into-cortex/integrations/github#syncing-ownership-from-github) with a team entity, Cortex will pull GitHub users in to the **Members** tab. When available, Cortex will pull in the profile picture and email address for each user.

### Engineering homepage

The GitHub integration enables Cortex to pull information about pull requests and issues into the [homepage](/streamline/homepage). You can find your open pull requests, any pull requests assigned to you for review, and any issues assigned to you.

Pull requests and issues from GitHub are refreshed every 2 minutes.

### Eng Intelligence

The [Eng Intelligence tool](/improve/eng-intelligence) uses pull request data from GitHub to generate metrics:

* Average PR open to close time
* Avg time to first review
* Avg time to approval
* PRs opened
* Weekly PRs merged
* Avg PRs reviewed/week
* Avg commits per PR
* Ave lines of code changed per PR

Eng Intelligence also pulls in data from Copilot to show AI impact in the [Copilot Dashboard](/improve/eng-intelligence/dashboards/ai-impact).

You can read more about how Eng Intelligence tracks metrics for teams and users in the [Eng Intelligence documentation](/improve/eng-intelligence).

To add deployments for your Github related entity, you can send a deployment event to the [Cortex API.](/api/rest/deploys)

### Bot-authored pull requests and reviews

Some pull requests and reviews in GitHub come from bot accounts, like Dependabot or a GitHub App that a team set up. Cortex ingests this activity along with everything else and attributes it to the bot that produced it, so you can include or exclude it deliberately.

**How Cortex identifies a bot**

Cortex uses the account type that GitHub reports. If GitHub identifies the account as a bot, Cortex marks its pull requests and reviews as bot generated. Automation that runs under a regular GitHub user account isn't marked as bot generated, because GitHub reports that account as a user.

**Where bot accounts appear**

* A pull request opened by a bot shows that bot's account name as the author, for example `dependabot[bot]`, rather than an empty author.
* In Eng Intelligence, bot accounts appear alongside people in the **User** filter and group-by options, so you can single out or exclude a specific bot.
* Eng Intelligence metric values don't change. These pull requests were always counted, so all that's new is the author attribution.

**Filtering bot activity in CQL**

`git.pullRequests()` and `git.reviews()` return bot activity by default. `GitPullRequest` and `GitReview` each have an `isBotGenerated` field, which is `true` when GitHub reports the account as a bot. For more information about writing queries, refer to [Cortex Query Language (CQL)](/standardize/cql).

To count only the pull requests opened by people:

```
git.pullRequests(lookback=duration("P14D")).filter((pr) => !pr.isBotGenerated).length > 0
```

To look at automated review activity on its own:

```
git.reviews(lookback=duration("P7D")).filter((review) => review.isBotGenerated).length > 0
```

**Availability**

Cortex began marking bot activity on August 18, 2026. Pull requests and reviews that Cortex ingested before then have `isBotGenerated` set to `false`, even when a bot produced them, so a query with a long lookback period can undercount bot activity.

### Scorecards and CQL

With the GitHub integration, you can create Scorecard rules and write CQL queries based on GitHub data.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Approvals required to merge**
>
> Number of approvals required to merge a pull/merge request into a repository. Defaults to 0 if no approvals are defined.
>
> **Definition**: `git.numOfRequiredApprovals()`
>
> **Examples**
>
> For a security or development maturity Scorecard, you can write a rule to make sure at least one approval is required to merge a pull/merge request:
>
> ```
> git.numOfRequiredApprovals() > 0
> ```
>
> By having a rigorous PR process in place for a repo, you can make sure changes aren't made that create vulnerabilities. This kind of rule could also be used in a best practices or project standards Scorecard.
>
> You can also use a similar expression in the Query Builder to find entities lacking approval:
>
> ```
> git.numOfRequiredApprovals() < 1
> ```

> **Git repository set**
>
> Check if an entity has a registered Git repository.
>
> **Definition:** `git (==/!=) null: Boolean`
>
> **Example**
>
> In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:
>
> ```
> git != null
> ```

> **Branches**
>
> List all live branches with some basic metadata.
>
> * Head
> * Is protected
> * Name
>
> **Definition**: `git.branches()`
>
> **Example**
>
> For a best practices Scorecard, you can make sure that branches associated with an entity match a standard naming convention:
>
> ```
> git.branches().all((branch) => branch.name.matches("(main|master|feat-.*|bug-.*|task-.*)"))
> ```

> **Branch protection details**
>
> > [!NOTE]
> >
> > `git.branchProtection()` now returns the **effective** branch protection for a branch by merging policies from both classic branch protection and GitHub rulesets into a unified view. This means it reflects what GitHub actually enforces, regardless of whether a repo uses classic rules, rulesets, or a combination of both.
>
> Find details for specified branch, or default branch if none is specified.
>
> * Branch name
> * Code owner reviews required
> * Dismiss stale reviews
> * Required status checks
> * Restrictions apply to admin
> * Review required
>
> **Definition:** `git.branchProtection()`
>
> **Examples**
>
> For a security Scorecard, you can write a rule to make sure the default branch is protected:
>
> ```
> git.branchProtection() != null
> ```
>
> Because vulnerabilities in the default branch are critical, this rule should be in one of the first couple levels.
>
> You can also use the Query Builder to find entities with unprotected default branches:
>
> ```
> git.branchProtection() = null
> ```

> **Branch rulesets**
>
> GitHub [branch rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets) are a newer, more flexible alternative to classic branch protection. Rulesets are layered (organization + repository), composed of typed rules, and can target multiple branches by pattern. Cortex exposes them in CQL through `git.branchRulesets(...)`.
>
> `git.branchRulesets(branchName?)` returns the effective ruleset for a branch, i.e. the rules from every active ruleset that targets that branch, merged together. Pass a branch name to target a specific branch; omit it to use the repo's default branch. Returns `null` if no ruleset applies.
>
> ```
> git.branchRulesets().rules.any((rule) =>
>     rule.type == "pull_request" && rule.requiredApprovingReviewCount >= 2
> )
> ```
>
> ```
> // Require Copilot code review on push for the default branch
> git.branchRulesets().rules.any((rule) =>
>     rule.type == "copilot_code_review" && rule.reviewOnPush == true
> )
> ```
>
> ```
> // Forbid pushes that match a banned commit-message pattern
> git.branchRulesets().rules.any((rule) =>
>     rule.type == "commit_message_pattern" && rule.patternOperator == "regex"
> )
> ```
>
> `GitBranchRulesets` **fields**
>
> | Field | Type | Description |
> | - | - | - |
> | `branchName` | `String` | Branch the rules apply to. |
> | `rules` | `List<GitBranchRule>` | All effective rules for the branch. |
>
> `GitBranchRule` **common fields**
>
> Present on every rule regardless of `type` .
>
> | Field | Type | Description |
> | - | - | - |
> | `type` | `String` | Rule type. See sections below for the full list. |
> | `rulesetSourceType` | `String` | Source level: `Repository`, `Organization`, or `Enterprise`. |
> | `rulesetSource` | `String` | Owner (for org), repo full name (for repository), or enterprise slug. |
> | `rulesetId` | `Long` | GitHub ID of the ruleset this rule came from. |
>
> All remaining fields below are nullable; only the fields associated with a rule's `type` are populated, and the rest are `null`.
>
> Rule type: `pull_request`
>
> | Field | Type | Description |
> | - | - | - |
> | `requiredApprovingReviewCount` | `Int?` | Minimum approvals required. |
> | `dismissStaleReviewsOnPush` | `Boolean?` | Dismiss prior approvals when new commits land. |
> | `requireCodeOwnerReview` | `Boolean?` | Require code-owner approval. |
> | `requireLastPushApproval` | `Boolean?` | The most-recent push must be approved by someone other than the pusher. |
> | `requiredReviewThreadResolution` | `Boolean?` | All review threads must be resolved before merging. |
> | `allowedMergeMethods` | `List<String>?` | One or several of `merge`, `squash`, `rebase`. |
> | `requiredReviewers` | `List<RequiredReviewerConfiguration>?` | (Beta) Reviewers required for changes matching specific file patterns. |
>
> Rule type: `required_status_checks`
>
> | Field | Type | Description |
> | - | - | - |
> | `requiredStatusCheckContexts` | `List<String>?` | Required check names. |
> | `strictRequiredStatusChecksPolicy` | `Boolean?` | Branch must be up-to-date before merging. |
> | `doNotEnforceOnCreate` | `Boolean?` | Allow repos/branches to be created even if a check would prohibit it. (Also populated for `workflows`.) |
>
> Rule type: `required_deployments`
>
> | Field | Type | Description |
> | - | - | - |
> | `requiredDeploymentEnvironments` | `List<String>?` | Required environment deployments. |
>
> Rule type: `update`
>
> | Field | Type | Description |
> | - | - | - |
> | `updateAllowsFetchAndMerge` | `Boolean?` | Branch can pull changes from its upstream repository. |
>
> Rule type: `merge_queue`
>
> | | | |
> | - | - | - |
> | `mergeQueueCheckResponseTimeoutMinutes` | `Int?` | Max time a required check has to report a conclusion before being considered failed. |
> | `mergeQueueGroupingStrategy` | `String?` | `ALLGREEN` or `HEADGREEN`. |
> | `mergeQueueMaxEntriesToBuild` | `Int?` | Maximum queued PRs being checked/built simultaneously. |
> | `mergeQueueMaxEntriesToMerge` | `Int?` | Maximum PRs merged together in one group. |
> | `mergeQueueMergeMethod` | `String?` | `MERGE`, `SQUASH`, or `REBASE`. (Uppercase here; lowercase on `allowedMergeMethods`.) |
> | `mergeQueueMinEntriesToMerge` | `Int?` | Minimum PRs in a merge group. |
> | `mergeQueueMinEntriesToMergeWaitMinutes` | `Int?` | Minutes to wait before merging a smaller-than-minimum group. |
>
> **Pattern rule types**
>
> Shared by `commit_message_pattern`, `commit_author_email_pattern`, `committer_email_pattern`, `branch_name_pattern`, `tag_name_pattern`. The same four fields are populated for any of these.
>
> | Field | Type | Description |
> | - | - | - |
> | `patternName` | `String?` | Display name for the pattern rule. |
> | `patternNegate` | `Boolean?` | If `true`, the rule fails when the pattern matches. |
> | `patternOperator` | `String?` | `starts_with`, `ends_with`, `contains`, or `regex`. |
> | `pattern` | `String?` | The pattern to match against. |
>
> Rule type: `workflows`
>
> | Field | Type | Description |
> | - | - | - |
> | `requiredWorkflows` | `List<WorkflowFileReference>?` | Workflows that must pass for the rule to pass. |
> | `doNotEnforceOnCreate` | `Boolean?` | Shared with `required_status_checks` . See above. |
>
> Rule type: `code_scanning`
>
> | Field | Type | Description |
> | - | - | - |
> | `codeScanningTools` | `List<CodeScanningTool>?` | Tools that must provide code-scanning results. |
>
> Rule type: `copilot_code_review`
>
> | Field | Type | Description |
> | - | - | - |
> | `reviewDraftPullRequests` | `Boolean?` | Copilot reviews draft PRs before they're marked ready. |
> | `reviewOnPush` | `Boolean?` | Copilot reviews every new push. |
>
> Rule type: `file_path_restriction`
>
> | Field | Type | Description |
> | - | - | - |
> | `restrictedFilePaths` | `List<String>?` | File paths restricted from being pushed. |
>
> Rule type: `max_file_path_length`
>
> | Field | Type | Description |
> | - | - | - |
> | `maxFilePathLength` | `Int?` | Maximum number of characters allowed in file paths. |
>
> Rule type: `file_extension_restriction`
>
> | Field | Type | Description |
> | - | - | - |
> | `restrictedFileExtensions` | `List<String>?` | File extensions restricted from being pushed. |
>
> Rule type: `max_file_size`
>
> | Field | Type | Description |
> | - | - | - |
> | `maxFileSize` | `Int?` | Maximum file size in megabytes (excluding Git LFS). |
>
> **Rule types without parameters**
>
> `creation`, `deletion`, `required_linear_history`, `non_fast_forward`, and `required_signatures` present in the rules list with only the common fields populated.
>
> **Nested types**
>
> `RequiredReviewerConfiguration` - each element of `pull_request.requiredReviewers`:
>
> | Field | Type | Description |
> | - | - | - |
> | `filePatterns` | `List<String>` | fnmatch patterns — PRs that change matching files require this reviewer. |
> | `minimumApprovals` | `Int` | Required approvals from this reviewer. Zero makes approval optional but still adds the reviewer. |
> | `reviewer` | `RulesetReviewer` | The reviewing team. |
>
> `RulesetReviewer` - nested in `RequiredReviewerConfiguration.reviewer`:
>
> | Field | Type | Description |
> | - | - | - |
> | `id` | `Long` | Reviewer ID. |
> | `type` | `String` | Reviewer kind. Currently always `Team`. |
>
> `WorkflowFileReference` - each element of `workflows.requiredWorkflows`:
>
> | Field | Type | Description |
> | - | - | - |
> | `path` | `String` | Path to the workflow file in the repository. |
> | `ref` | `String?` | Branch or tag ref of the workflow file to use. |
> | `repositoryId` | `Long` | ID of the repository where the workflow is defined. |
> | `sha` | `String?` | Commit SHA of the workflow file to use. |
>
> `CodeScanningTool` - each element of `code_scanning.codeScanningTools`:
>
> | | | |
> | - | - | - |
> | `alertsThreshold` | `String` | Severity at which alerts block a push: `none`, `errors`, `errors_and_warnings`, `all`. |
> | `securityAlertsThreshold` | `String` | Severity at which security alerts block: `none`, `critical`, `high_or_higher`, `medium_or_higher`, `all`. |
> | `tool` | `String` | Name of the code-scanning tool. |
>
> **Relationship with** `git.branchProtection()`
>
> `git.branchProtection()` returns the **effective** branch protection for a branch, merging policies from both classic branch protection and GitHub rulesets into a unified result. `git.branchRulesets()` remains available if you need granular access to individual ruleset rules (e.g. filtering by type, source, or ruleset ID).

> **Commits**
>
> Get the latest commits **(to a maximum of 100)** for a defined lookback period **(defaulting to 7 days)**.
>
> * Date
> * Message
> * SHA
> * URL
> * Username
>
> These results can be filtered based on branch name, using the default branch if no other branch is provided.
>
> **Definition:** `git.commits()`
>
> **Example**
>
> You can use the `git.commits()` expression in a security Scorecard to make sure entities have fewer than three commits to a "security-fixes" branch in the last week:
>
> ```
> git.commits(branchName="security-fixes").length < 3
> ```
>
> Entities passing this rule will include those that haven't needed three or more security fixes. This can indicate that there aren't vulnerabilities in a given entity's code, but could also suggest that fixes aren't being implemented. Using this rule in conjunction with one focused on vulnerabilities could provide the extra context needed to gain a better understanding of what's happening.

> **Default branch**
>
> Default branch for the repository, or `main` when null.
>
> **Definition:** `git.defaultBranch()`
>
> **Example**
>
> If default branches should always be named "main," you can write a rule to make sure entities follow this practice:
>
> ```
> git.defaultBranch().matches("main")
> ```

> **File contents**
>
> Load the contents of a file from the entity's associated repository.
>
> The contents can be validated by using string comparison operations or parsed by the built-in jq function. The jq function will automatically coerce file contents of JSON or YAML formats.
>
> **Definition:** `git.fileContents()`
>
> **Example**
>
> For a Scorecard focused on development maturity, you could use the `git.fileContents()` rule to enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline.
>
> ```
> git.fileContents("circleci/config.yml").matches(".*npm test.*")
> ```
>
> A best practices Scorecard, meanwhile, could use this expression for a number of rules:
>
> * To make sure node engine version in specified in the `package.json` file:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.node") != null
>   ```
> * To make sure TypeScript projects have a `tsconfig.json` file checked in:
>
>   ```
>   jq(git.fileContents("package.json"), ".devDependencies | with_entries(select(.key == \"typescript\")) | length") == 0 or git.fileExists("tsconfig.json")
>   ```
> * To make sure projects using yarn do not allow NPM:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.yarn") == null or jq(git.fileContents("package.json"), ".engine.npm") = "please-use-yarn"
>   ```
> * And to ensure the yarn version being used is not deprecated:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.yarn") == null or !(semver("1.2.0") ~= semverRange(jq(git.fileContents("package.json"), ".engines.yarn")))
>   ```

> **File exists**
>
> Check if file exists from within the entity's associated repository.
>
> **Definition:** `git.fileExists()`
>
> **Examples**
>
> For a Scorecard focused on best practices, you can make sure that repositories contain a README.md file:
>
> ```
> git.fileExists("README.md")
> ```
>
> This rule would make sense in the first level because it's so essential.
>
> A higher-level rule in a best practices Scorecard might confirm that developers are checking in lockfiles to ensure consistency in package installs:
>
> ```
> git.fileExists("yarn.lock") OR git.fileExists("package-lock.json")
> ```
>
> And/or a rule that makes sure there are unit tests enabled:
>
> ```
> git.fileExists("*Test.java")
> ```
>
> Finally, you could write a rule to make sure projects have a standard linter:
>
> ```
> git.fileExists(".prettierrc.json") OR git.fileExists(".eslintrc.js")
> ```

> **Number of Git vulnerabilities**
>
> Check the number of vulnerabilities for an entity's associated repository.
>
> You can filter by severity (by default searches by all severities) or source (by default only searches GitHub security advisories).
>
> **When using the GitHub Advanced Security source, severities displayed in the UI may not match severities returned by the API.**
>
> **Definition:** `git.numOfVulnerabilities()`
>
> **Examples**
>
> A security-focused Scorecard will likely include a rule making sure there are no Git vulnerabilities:
>
> ```
> git.numOfVulnerabilities() == 0
> ```
>
> You can use Scorecard levels to stratify vulnerabilities by risk. An initial level might make sure there are no critical vulnerabilities:
>
> ```
> git.numOfVulnerabilities(severity=["CRITICAL"]) == 0
> ```
>
> While a higher level might make sure there are no vulnerability warnings:
>
> ```
> git.numOfVulnerabilities(severity=["WARNING"]) == 0
> ```

> **List of Git vulnerabilities**
>
> Lists the vulnerabilities for an entity's associated repository. You can filter by severity (by default searches by all severities) or source (by default only searches GitHub security advisories). Note when using the GitHub Advanced Security source, severities displayed in the UI may not match severities returned by the API.
>
> **Definition**: `git.vulnerabilities()`
>
> **Examples**
>
> You could write a Scorecard rule that verifies an entity has fewer than 5 Git vulnerabilities:
>
> ```
> git.vulnerabilities().length < 5
> ```
>
> You could write a rule that verifies the entity has no vulnerabilities with "High" or "Critical" severity sourced from GitHub Advanced Security:
>
> ```
> git.vulnerabilities(severity=["CRITICAL", "HIGH"], source=["GITHUB_ADVANCED_SECURITY"]).length < 1
> ```

> **Has Cortex YAML**
>
> Check if a repository has a valid `cortex.yaml` file checked in at the root directory (when GitOps is enabled).
>
> **Definition:** `git.hasCortexYaml()`
>
> **Example**
>
> If you're using a Scorecard to track a migration from Cortex UI to GitOps, you can use this rule to make sure entities are set up for GitOps management of entity descriptors:
>
> ```
> git.hasCortexYaml() == true
> ```

> **Last commit details**
>
> Provides last commit details.
>
> * Date
> * Message
> * SHA
> * URL
> * Username
>
> **Definition:** `git.lastCommit()`
>
> **Examples**
>
> One of the first rules you might write for a Scorecard focused on development maturity or security is one validating that the last commit was within the last month:
>
> ```
> git.lastCommit().freshness < duration("P1M")
> ```
>
> As counterintuitive as it may seem, services that are committed too infrequently are actually at more risk. People who are familiar with the service may leave a team, institutional knowledge accumulates, and from a technical standpoint, the service may be running outdated versions of your platform tooling.
>
> Depending on best practices at your organization, you may want to confirm entities are updated within a week:
>
> ```
> git.lastCommit().freshness < duration("P7D")
> ```
>
> Confirming whether a service was updated within the last week can help team members catch outdated code sooner. Plus, if there is a security issue, you can quickly determine which services have or have not been updated to patch the vulnerability.

> **Pull requests**
>
> Lists the pull requests opened during a defined lookback period. Bot-authored pull requests are included by default, so filter them out if you only want activity from people.
>
> Each pull request has these properties:
>
> | Property | Description |
> | - | - |
> | `approvalDate` | When the pull request was approved. Returns `null` if not yet approved. |
> | `author` | The GitHub user account or bot account that opened the pull request. |
> | `dateClosed` | When the pull request was closed (merged or rejected). Returns `null` if still open. |
> | `dateOpened` | When the pull request was opened. Always present. |
> | `firstReviewDate` | When the pull request received its first review. Returns `null` if there are no reviews yet. |
> | `isBotGenerated` | Whether a bot account opened the pull request. |
> | `isDraft` | Whether the pull request is still a draft. Returns `null` if the data is unavailable. |
> | `labels` | A list of label names applied to the pull request in GitHub (e.g. `["bug", "small", "stale"]`). Returns `null` if no labels are present or the data is unavailable. |
> | `lastUpdated` | When the pull request last changed. |
> | `numCommits` | How many commits the pull request contains. |
> | `numLinesAdded` | How many lines the pull request adds. Returns `null` if the data is unavailable. |
> | `numLinesDeleted` | How many lines the pull request deletes. Returns `null` if the data is unavailable. |
> | `organization` | The GitHub organization that owns the repository. |
> | `repository` | The repository the pull request belongs to. |
> | `source` | The Git provider the pull request came from, e.g. `"GITHUB"`. |
> | `status` | The current state of the pull request: `"OPEN"`, `"CLOSED"`, `"MERGED"`, or `"UNKNOWN"`. |
> | `title` | The title of the pull request as set by the PR author in GitHub. Returns `null` if the title is unavailable. |
> | `url` | A link to the pull request in GitHub. |
>
> **Definition** - `git.pullRequests(lookback: Duration)`
>
> **Example**
>
> Use the `git.pullRequests()` expression to find entities with very few pull requests opened in the last two weeks:
>
> ```
> git.pullRequests(lookback=duration("P14D")).length < 3
> ```
>
> This surfaces entities that nobody has touched lately, which is useful when you need to confirm that a fix, like a vulnerability patch, is actually being picked up.
>
> **Example**
>
> Filter out drafts to count only the pull requests that are ready for review:
>
> ```
> git.pullRequests(lookback=duration("P14D")).filter((pr) => !pr.isDraft).length < 3
> ```
>
> **Example**
>
> Filter out bot accounts to count only the pull requests opened by people:
>
> ```
> git.pullRequests(lookback=duration("P14D")).filter((pr) => !pr.isBotGenerated).length < 3
> ```
>
> Reverse the filter to `pr.isBotGenerated` to look at automated activity on its own, for example to see how much of a repository's pull request volume comes from dependency bots.

> **Reviews**
>
> Lists the reviews left during a defined lookback period. Reviews left by bots are included by default, so filter them out if you only want reviews from people.
>
> Each review has these properties:
>
> | Property | Description |
> | - | - |
> | `isBotGenerated` | Whether a bot account left the review. |
> | `organization` | The GitHub organization that owns the repository. |
> | `repository` | The repository containing the pull request that was reviewed. |
> | `reviewDate` | When the review was left. |
> | `reviewer` | The GitHub user account or bot account that left the review. |
>
> **Definition** - `git.reviews(lookback: Duration)`
>
> **Example**
>
> A development maturity Scorecard might use the `git.reviews()` expression to make sure that a rigorous review process is in place before changes are implemented:
>
> ```
> git.reviews(lookback=duration("P7D")).length > 25
> ```
>
> This rule makes sure that more than 25 reviews were left in the last week.
>
> **Example**
>
> Because bot reviews count toward that total, filter them out to hold the threshold to reviews left by people:
>
> ```
> git.reviews(lookback=duration("P7D")).filter((review) => !review.isBotGenerated).length > 25
> ```
>
> Reverse the filter to `review.isBotGenerated` to measure automated review activity on its own.

> **Workflow runs**
>
> Get workflow runs meeting given filter criteria, including conclusions, statuses, and a lookback period.
>
> * Conclusion
> * Name
> * Run started at
> * Run time
> * Run updated at
> * Status
>
> Conclusions: `FAILURE`, `SUCCESS`, `TIMED_OUT`
>
> Statuses: `QUEUED`, `IN_PROGRESS`, `COMPLETED`
>
> The lookback period specifies a duration for which returned runs should be created within, defaulting to a period of 3 days.
>
> * The `runTime` of the `WorkflowRun` object represents the difference between `runStartedAt` and `runUpdatedAt` times in seconds.
>
> **Definition:** `git.workflowRuns()`
>
> **Example**
>
> To make sure an entity has had a successful workflow run within the last two weeks, you can write a rule like:
>
> ```
> git.workflowRuns(conclusions=["SUCCESS"], statuses=["COMPLETED"], lookback=duration("P14D")).length > 0
> ```
>
> This rule is checking for GitHub workflow runs with a `SUCCESS` conclusion and `COMPLETED` status during a 14-day lookback window.
>
> To find the percentage of successes in workflow runs, you could write a query similar to:
>
> ```
> (git.workflowRuns(conclusions=["SUCCESS"], lookback=duration("P1D")).length) / (git.workflowRuns(lookback=duration("P1D")).length) * 100
> ```

**Ownership CQL**

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity
>
> **Definition:** `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

**Copilot CQL**

> **AI adoption**
>
> The ratio of licensed seats that were active users of AI coding tools in a given time period. Returns a value between 0 and 1, where 1 represents 100% adoption. Note: This metric is only available for Team entities.
>
> **Definition**: `aiTools.analysis(lookback: Duration).aiAdoptionRate`
>
> **Example**
>
> You could create a Scorecard rule to make sure AI adoption rate is at least 50% over the previous 30 days:
>
> ```
> aiTools.analysis(lookback = duration("P30D")).aiAdoptionRate >= 0.5
> ```

> **Active AI users**
>
> The number of users who used AI coding tools in a given time period. Note: This metric is only available for Team entities.
>
> **Definition**: `aiTools.analysis(lookback: Duration).activeAiUsers`
>
> **Example**
>
> You could create a Scorecard rule to verify you had at least 5 active AI users in the last 7 days:
>
> ```
> aiTools.analysis(lookback = duration("P7D")).activeAiUsers >= 5
> ```

**External repositories**

By default, each GitHub rule is evaluated on the repository defined in a given entity descriptor. If the base path parameter has been set, CQL rules will automatically scope to the base path subdirectory.

To evaluate the rule for a service for an external repository, pass the repo identifier in the `git(repoIdentifier: Text)` command (e.g. `git("github:org/repositoryName")`).

This can be combined with other CQL rules. For example, a rule based on a dynamic external repository with custom data would be `git("github:" + custom("my-custom-repo")).fileExists("README.md")`.

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex syncs GitHub identities (teams and people) once a day, at 9 a.m. UTC.

Repository and pull request syncs start within 10 minutes of the previous sync's completion. In most cases, this means Cortex's GitHub data is no more than 10 minutes old, though a sync that takes longer than usual can push that slightly further out.

## FAQs and troubleshooting

**I'm getting this error: `"{"message":"Not Found", "documentation_url":"https://docs.github.com/rest/repos#get-a-repository"}"`.**

If you've set up multiple GitHub accounts/organizations, Cortex will not be able to identify the correct one unless the `alias` variable is defined.

**What if I have multiple email addresses set in my GitHub account?**

Cortex will only detect the primary email address associated with your GitHub account **if it is public**.

If Cortex is not correctly pulling in user emails, ensure the given user(s) have allowed their email address to be public. Make sure the **"Keep my email address private"** setting is **unchecked** in the user's personal GitHub settings.

**My ownership isn't being automatically mapped through GitHub.**

If the email address associated with your Cortex account is not the same as your GitHub email address, you need to add your Cortex email address to the **Public email** dropdown in GitHub settings.

Github OAuth, which you can configure in Cortex user settings, allows you to link your GitHub username with your Cortex account, even if you don't have a public email set up on GitHub.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# GitLab
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/gitlab



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[GitLab](https://about.gitlab.com/) is a Git-based version control system with cloud and self-hosted options.

Integrating GitLab with Cortex allows you to:

* Discover and track ownership of entities
* Follow a [GitOps](/configure/gitops) workflow with GitLab
* View commits alongside events and other data on [entity pages in Cortex](/ingesting-data-into-cortex/integrations/gitlab#view-gitlab-data-on-entity-pages-in-cortex)
* View information about merge requests in the [engineering homepage](/ingesting-data-into-cortex/integrations/gitlab#engineering-homepage)
* Use GitLab metrics in [Eng Intelligence](/ingesting-data-into-cortex/integrations/gitlab#eng-intelligence) to understand key metrics and gain insight into services, incident response, and more
* Create [Scorecards](/ingesting-data-into-cortex/integrations/gitlab#scorecards-and-cql) to monitor development maturity relating to GitLab projects

## How to configure GitLab with Cortex

There are two options for integrating GitLab: the default configuration method and Cortex Axon Relay, a relay broker allows you to securely connect your on-premises GitLab data.

### Prerequisites

Before getting started:

* A GitLab user with at least the `Maintainer` role must create a GitLab [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) or [group access token](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html) with the `read_api` scope.
  * We recommend that you create the token at the parent group level, as GitLab does not support using a scoped token to read members from a parent group. If you do not create the token at the parent level, then you will need to manually configure groups in your GitLab settings in order for identity mapping and teams to work as expected.
  * Note that `Maintainer` is sufficient for project/repo data, but retrieving user emails for identity mapping typically requires an `Owner`- or `Admin`-generated token with `api` or `read_user` scope, particularly in enterprise/SSO environments.
* If you're using the Scaffolder for entities in a given GitLab instance, make sure that configuration has the full `api` scope.

#### Self-hosted prerequisites

If you're using a self-hosted instance of GitLab, you'll need to verify that your Cortex instance is able to reach the GitLab instance.

We route our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your GitLab instance.

> **Standard configuration**
>
> **Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [GitLab settings page](https://app.getcortexapp.com/admin/integrations/gitlab):
>    * Click **Integrations** from the main nav. Search for and select **GitLab**.
> 2. Click **Add configuration**.
> 3. Configure the GitLab integration form:
>    * **Account alias**: Enter the alias you will use to tie entity registrations to different configuration accounts.
>    * **Token**: Enter your personal or group access token.
>    * **Host**: Enter your host. If using a custom GitLab instance, enter the URL without the API path (e.g. `https://gitlab.getcortexapp.com`)
>    * **Hide personal projects**: Toggle this setting on if you do not want your personal projects pulled in to Cortex. Toggle this setting off to allow Cortex to pull your personal projects.
> 4. Click **Save**.

> **Axon Relay**
>
> **Configure GitLab with Cortex Axon Relay**
>
> See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for instructions. Make sure to follow the GitLab-specific instructions for the docker-compose.yml file.

Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to **Remove Integration** in Settings.

You can also use the **Test all configurations** button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

**Configure the integration for multiple GitLab accounts**

The GitLab integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the GitLab page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.

Cortex supports mapping multiple identities for a single user if you have multiple configurations of GitLab. See the [Identity mapping documentation](/configure/settings/managing-users/identity-mapping) for more information.

## Enable GitOps for your GitLab integration

Cortex supports a GitOps approach, which allows you to manage entities in Cortex through your version control system. If you would prefer this workflow over the UI for the GitLab integration, you must create a webhook. Please see the [Cortex GitOps documentation](/configure/gitops) for instructions.

## How to connect Cortex entities to GitLab

### Import entities

Cortex will discover entities for import from your GitLab configuration(s). These will appear in the import entities workflow.

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#importing-services-from-an-integration) for instructions on importing entities manually.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

**Git**

By specifying the `x-cortex-git` field in your Cortex entity descriptor, you'll be able to see Git information in the entity page, including the top language, recent commits, and top contributors.

```yaml theme={null}
x-cortex-git:
  gitlab:
    repository: cortex/docs
    basepath: myService
    alias: myApp
```

| Field | Description | Required |
| - | - | :-: |
| `repository` | GitLab project ID or `namespace/repo` as defined in GitLab | **✓** |
| `basepath` | Subdirectory for the entity if it is in a monorepo | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

Only one repository can be defined for in a given entity's YAML in the `x-cortex-git` block.

#### Filter entities by GitLab repository in the API

To list the entities linked to a GitLab project, use the `gitRepositories` parameter on [List entities](/api/rest/catalog-entities/list-entities) (`GET /api/v1/catalog`). Prefix the project path or numeric project ID with `gitlab:`:

```bash theme={null}
# Filter by project path
GET /api/v1/catalog?gitRepositories=gitlab:cortex/docs

# Filter by project ID
GET /api/v1/catalog?gitRepositories=gitlab:2211

# Filter by more than one repository
GET /api/v1/catalog?gitRepositories=gitlab:cortex/docs,gitlab:2211
```

Cortex returns matching entities whether their `x-cortex-git.gitlab.repository` value is the project path or the project ID.

> [!NOTE]
>
> When you filter by path, an entity that references its project by ID is matched only if Cortex has discovered that project through the GitLab configuration set in `alias` (or your default configuration if no alias is set). If an entity is missing from path-based results, filter by its project ID instead.
>
> A project ID filter matches on every GitLab configuration. If you've opted into multi-account support, the results can include entities from more than one GitLab instance.

#### Syncing ownership from GitLab

You can define the following block in your Cortex entity descriptor to add your GitLab groups as owners.

Team name should match the group name in GitLab.

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: Team Name
    provider: GITLAB
    description: This is a description for this owner
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Ownership type; must be defined as `group` for GitLab teams | **✓** |
| `name` | GitLab team name | **✓** |
| `provider` | Name of integration (in this case, `GITLAB`) | **✓** |
| `description` | Description for the GitLab team | |

Cortex syncs GitLab identities every day at 10 a.m. UTC. Cortex connects group members to their Cortex users through [identity mappings](#identity-mapping).

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

### Identity mapping

Cortex maps users' email addresses to discovered GitLab accounts, so you never need to define email ownership in an entity descriptor.

You can confirm users' GitLab accounts are connected from [GitLab identity mappings in settings](https://app.getcortexapp.com/admin/settings/gitlab-mappings).

If users are not loading in the identity mapping page, make sure that you have created your GitLab personal access token from the parent level as described in the [Prerequisites](/ingesting-data-into-cortex/integrations/gitlab#prerequisites).

## Using the GitLab integration

### View GitLab data on entity pages in Cortex

Cortex uses the GitLab integration for a significant amount of data that appears on [entities' detail pages](/ingesting-data-into-cortex/entities-overview/entities/details).

The GitLab integration will populate the **Repo** and **Language** detail blocks on an entity's details page.

In the **Recent activity preview**, you'll find the recent commits and releases. These will also appear in the event timeline.

These data will appear for entities imported from a Git source or those that have a Git repo defined in their YAMLs.

#### **Events**

On an entity's **Events** page, you can find all of the commits and releases associated with that entity. Each is hyperlinked to the commit or release page in GitLab and includes a timestamp.

#### **CI/CD**

To see pipeline runs for GitLab, use the [deploys API](/ingesting-data-into-cortex/entities-overview/entities/deploys) to add deploy information. After doing this, from the **CI/CD > Deploys** page in the entity's sidebar, you will see a history of pipeline runs.

#### **Repository**

You can access more detailed information pulled from GitLab in the **Repository** page in the entity's sidebar. At the top of the page, you'll find the repo associated with that entity and the most-used language in files for that entity. In the **Top contributors** block, you'll find the three users who have contributed the most code and the number of their contributions.

In the Commits section, you'll find the 10 most recent commits and metadata about each. Below Commits is the Recent releases section, which includes the 5 most recent releases.

#### **Packages**

Packages are automatically scraped from your Git repos or they can be submitted via the [packages API](/api/rest/packages). The package file must be in the root of your repository — or, if you're using `basepath`, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) using `packages()`.

To view packages, click **Packages** in the entity's sidebar.

The following package types are automatically scraped from repositories:

* JavaScript / Node.js: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
* Python: `requirements.txt`, `pipfile.lock`
* .NET (C#): `packages.lock.json`
* Java: `pom.xml`
* Go: `go.sum`

All other files of these types can be added via the [packages API](/api/rest/packages).

#### Team pages

When a GitLab team is registered in a team entity descriptor, Cortex will pull GitLab users in to the **Members** tab. When available, Cortex will pull in the profile picture and email address for each user.

If team members are not appearing as expected, make sure that you have created your GitLab personal access token from the parent level as described in the [Prerequisites](/ingesting-data-into-cortex/integrations/gitlab#prerequisites).

### Engineering homepage

The GitLab integration enables Cortex to pull information about merge requests into the [homepage](/streamline/homepage). You can find your open merge requests and any merge requests assigned to you for review.

Merge requests from GitLab are refreshed every 2 minutes.

### Eng Intelligence

The [Eng Intelligence tool](/improve/eng-intelligence) also uses merge request data from GitLab to generate metrics:

* Average MR open to close time
* Avg time to first review
* Avg time to approval
* MRs opened
* Weekly MRs merged
* Avg MRs reviewed/week
* Avg commits per MR
* Avg lines of code changed per MR

You can read more about how Eng Intelligence tracks metrics for teams and users in the Eng Intelligence walkthrough.

To add deployments for your GitLab related entity, you can send a deployment event to the [Cortex API](/api/rest/deploys).

### Scorecards and CQL

With the GitLab integration, you can create Scorecard rules and write CQL queries based on GitLab data.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Approvals required to merge**
>
> Number of approvals required to merge a pull/merge request into a repository. Defaults to 0 if no approvals are defined.
>
> **Definition**: `git.numOfRequiredApprovals()`
>
> **Examples**
>
> For a security or development maturity Scorecard, you can write a rule to make sure at least one approval is required to merge a pull/merge request:
>
> ```
> git.numOfRequiredApprovals() > 0
> ```
>
> By having a rigorous PR process in place for a repo, you can make sure changes aren't made that create vulnerabilities. This kind of rule could also be used in a best practices or project standards Scorecard.
>
> You can also use a similar expression in the Query Builder to find entities lacking approval:
>
> ```
> git.numOfRequiredApprovals() < 1
> ```

> **Git repository set**
>
> Check if an entity has a registered Git repository.
>
> **Definition:** `git (==/!=) null: Boolean`
>
> **Example**
>
> In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:
>
> ```
> git != null
> ```

> **Pipeline build success rate**
>
> The percentage of build pipelines that complete successfully. This is calculated against builds on the default branch, for commits in the last 30 days. The calculation is # successful builds / (# successful + # failed).
>
> **Definition:** `git.percentBuildSuccess(): Number`
>
> **Example**
>
> In a Scorecard, you can write a rule that requires at least 90% of build runs to be successful:
>
> ```
> git.percentBuildSuccess() > 0.9
> ```

> **Branches**
>
> List all live branches with some basic metadata.
>
> * Head
> * Is protected
> * Name
>
> **Definition**: `git.branches()`
>
> **Example**
>
> For a best practices Scorecard, you can make sure that branches associated with an entity match a standard naming convention:
>
> ```
> git.branches().all((branch) => branch.name.matches("(main|master|feat-.*|bug-.*|task-.*)"))
> ```

> **Branch protection details**
>
> Find details for specified branch, or default branch if none is specified.
>
> * Branch name
> * Code owner reviews required
> * Dismiss stale reviews
> * Required status checks
> * Restrictions apply to admin
> * Review required
>
> **Definition:** `git.branchProtection()`
>
> **Examples**
>
> For a security Scorecard, you can write a rule to make sure the default branch is protected:
>
> ```
> git.branchProtection() != null
> ```
>
> Because vulnerabilities in the default branch are critical, this rule should be in one of the first couple levels.
>
> You can also use the Query Builder to find entities with unprotected default branches:
>
> ```
> git.branchProtection() = null
> ```

> **Commits**
>
> Get the latest commits **(to a maximum of 100)** for a defined lookback period **(defaulting to 7 days)**.
>
> * Date
> * Message
> * SHA
> * URL
> * Username
>
> These results can be filtered based on branch name, using the default branch if no other branch is provided.
>
> **Definition:** `git.commits()`
>
> **Example**
>
> You can use the `git.commits()` expression in a security Scorecard to make sure entities have fewer than three commits to a "security-fixes" branch in the last week:
>
> ```
> git.commits(branch="security-fixes", lookback=duration("P7D")).length < 3
> ```
>
> Entities passing this rule will include those that haven't needed three or more security fixes. This can indicate that there aren't vulnerabilities in a given entity's code, but could also suggest that fixes aren't being implemented. Using this rule in conjunction with one focused on vulnerabilities could provide the extra context needed to gain a better understanding of what's happening.

> **Default branch**
>
> Default branch for the repository, or `main` when null.
>
> **Definition:** `git.defaultBranch()`
>
> **Example**
>
> If default branches should always be named "main," you can write a rule to make sure entities follow this practice:
>
> ```
> git.defaultBranch().matches("main")
> ```

> **File contents**
>
> Load the contents of a file from the entity's associated repository.
>
> The contents can be validated by using string comparison operations or parsed by the built-in jq function. The jq function will automatically coerce file contents of JSON or YAML formats.
>
> **Definition:** `git.fileContents()`
>
> **Example**
>
> For a Scorecard focused on development maturity, you could use the `git.fileContents()` rule to enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline.
>
> ```
> git.fileContents("circleci/config.yml").matches(".*npm test.*")
> ```
>
> A best practices Scorecard, meanwhile, could use this expression for a number of rules:
>
> * To make sure node engine version in specified in the `package.json` file:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.node") != null
>   ```
> * To make sure TypeScript projects have a `tsconfig.json` file checked in:
>
>   ```
>   jq(git.fileContents("package.json"), ".devDependencies | with_entries(select(.key == \"typescript\")) | length") == 0 or git.fileExists("tsconfig.json")
>   ```
> * To make sure projects using yarn do not allow NPM:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.yarn") == null or jq(git.fileContents("package.json"), ".engine.npm") = "please-use-yarn"
>   ```
> * And to ensure the yarn version being used is not deprecated:
>
>   ```
>   jq(git.fileContents("package.json"), ".engines.yarn") == null or !(semver("1.2.0") ~= semverRange(jq(git.fileContents("package.json"), ".engines.yarn")))
>   ```

> **File exists**
>
> Check if file exists from within the entity's associated repository.
>
> **Definition:** `git.fileExists()`
>
> **Examples**
>
> For a Scorecard focused on best practices, you can make sure that repositories contain a README.md file:
>
> ```
> git.fileExists("README.md")
> ```
>
> This rule would make sense in the first level because it's so essential.
>
> A higher-level rule in a best practices Scorecard might confirm that developers are checking in lockfiles to ensure consistency in package installs:
>
> ```
> git.fileExists("yarn.lock") OR git.fileExists("package-lock.json")
> ```
>
> And/or a rule that makes sure there are unit tests enabled:
>
> ```
> git.fileExists("*Test.java")
> ```
>
> Finally, you could write a rule to make sure projects have a standard linter:
>
> ```
> git.fileExists(".prettierrc.json") OR git.fileExists(".eslintrc.js")
> ```

> **Number of Git vulnerabilities**
>
> Check the number of vulnerabilities for an entity's associated repository.
>
> **Definition:** `git.numOfVulnerabilities()`
>
> **Examples**
>
> A security-focused Scorecard will likely include a rule making sure there are no Git vulnerabilities:
>
> ```
> git.numOfVulnerabilities() == 0
> ```
>
> You can use Scorecard levels to stratify vulnerabilities by risk. An initial level might make sure there are no critical vulnerabilities:
>
> ```
> git.numOfVulnerabilities(severity=["CRITICAL"]) == 0
> ```
>
> While a higher level might make sure there are no vulnerability warnings:
>
> ```
> git.numOfVulnerabilities(severity=["WARNING"]) == 0
> ```

> **List of Git vulnerabilities**
>
> Find all vulnerabilities within a repository. Can filter by severity or scan type.
>
> **Definition**: `git.vulnerabilities()`
>
> **Examples**
>
> You could write a Scorecard rule that verifies an entity has fewer than 5 Git vulnerabilities:
>
> ```
> git.vulnerabilities().length < 5
> ```
>
> You could write a rule to verify that an entity has no critical vulnerabilities:
>
> ```
> git.vulnerabilities(severity=["CRITICAL"]).length == 0
> ```

> **Has Cortex YAML**
>
> Check if a repository has a valid `cortex.yaml` file checked in at the root directory (when GitOps is enabled).
>
> **Definition:** `git.hasCortexYaml()`
>
> **Example**
>
> If you're using a Scorecard to track a migration from Cortex UI to GitOps, you can use this rule to make sure entities are set up for GitOps management of entity descriptors:
>
> ```
> git.hasCortexYaml() == true
> ```

> **Last commit details**
>
> Provides last commit details.
>
> * Date
> * Message
> * SHA
> * URL
> * Username
>
> **Definition:** `git.lastCommit()`
>
> **Examples**
>
> One of the first rules you might write for a Scorecard focused on development maturity or security is one validating that the last commit was within the last month:
>
> ```
> git.lastCommit().freshness < duration("P1M")
> ```
>
> As counterintuitive as it may seem, services that are committed too infrequently are actually at more risk. People who are familiar with the service may leave a team, institutional knowledge accumulates, and from a technical standpoint, the service may be running outdated versions of your platform tooling.
>
> Depending on best practices at your organization, you may want to confirm entities are updated within a week:
>
> ```
> git.lastCommit().freshness < duration("P7D")
> ```
>
> Confirming whether a service was updated within the last week can help team members catch outdated code sooner. Plus, if there is a security issue, you can quickly determine which services have or have not been updated to patch the vulnerability.

> **Pull requests**
>
> Lists pull requests opened during a defined lookback period.
>
> * Approval date
> * Author
> * Date closed
> * Date opened
> * First review date
> * Is draft
> * Last updated
> * Number of commits
> * Number of lines added
> * Number of lines deleted
> * Organization
> * Repository
> * Source
> * Status
> * URL
>
> **Definition:** `git.pullRequests()`
>
> **Example**
>
> You can use the `git.pullRequests()` query to find entities that have a small number of pull requests opened in the last two weeks:
>
> ```
> git.pullRequests(lookback=duration("P14D")).length < 3
> ```
>
> This can highlight entities that haven't been updated recently, which may be especially useful when entities have to be updated to address a vulnerability.
>
> **Example**
>
> You can filter out draft pull requests to count only ready-for-review PRs:
>
> ```
> git.pullRequests(lookback=duration("P14D")).filter(pr => !pr.isDraft).length < 3
> ```

> **Reviews**
>
> List reviews left during a defined lookback period.
>
> * Organization
> * Repository
> * Review date
> * Reviewer
>
> **Definition:** `git.reviews()`
>
> **Examples**
>
> A development maturity Scorecard might use the `git.reviews()` expression to make sure that there is a rigorous review process in place before changes are implemented:
>
> ```
> git.reviews(lookback=duration("P7D")).length > 25
> ```
>
> This rule makes sure that there are more than 25 reviews left in the last week.

> **Workflow runs**
>
> Get workflow runs meeting given filter criteria, including conclusions, statuses, and a lookback period.
>
> * Conclusion
> * Name
> * Run started at
> * Run time
> * Run updated at
> * Status
>
> Conclusions: `FAILURE`, `SUCCESS`, `TIMED_OUT`
>
> Statuses: `QUEUED`, `IN_PROGRESS`, `COMPLETED`
>
> The lookback period specifies a duration for which returned runs should be created within, defaulting to a period of 3 days.
>
> * The `runTime` of the `WorkflowRun` object represents the difference between `runStartedAt` and `runUpdatedAt` times in seconds.
>
> **Definition:** `git.workflowRuns()`
>
> **Example**
>
> To make sure an entity has had a successful workflow run within the last two weeks, you can write a rule like:
>
> ```
> git.workflowRuns(conclusions=["SUCCESS"], statuses=["COMPLETED"], lookback=duration("P14D")).length > 0
> ```
>
> This rule is checking for GitHub workflow runs with a `SUCCESS` conclusion and `COMPLETED` status during a 14-day lookback window.

**Ownership CQL**

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity
>
> **Definition:** `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts a background sync of GitLab identities every day at 10 a.m. UTC. Merge requests are refreshed every 2 minutes.

## FAQ and Troubleshooting

**Why is my CQL query `git.branchProtection()` returning no results or a 403 error?**

This can happen if you do not have the `read_api` scope set for your access token, or if the GitLab user who generated the token does not have at minimum the `Maintainer` role.

**Why isn't Cortex pulling in user emails from GitLab (identity mapping / team members missing emails)?**

Email addresses are treated as sensitive user identity data in GitLab, not project data, so a `Maintainer`-level token isn't sufficient in most modern GitLab environments, especially enterprise instances with SSO or stricter privacy controls. Use a token created by an `Owner` or `Admin` user with the `api` (or `read_user`) scope.

Note that `Maintainer` tokens *may* work on loosely configured self-managed instances, but this is not reliable. Email visibility also depends on instance configuration and individual user privacy settings (e.g., hidden emails).

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Google Cloud Platform
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/google

Configuring the integration for Google Cloud Platform (GCP)

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Why use the integration for Google Cloud Platform

Google Cloud Platform (GCP) is Google's suite of cloud computing services, including compute, storage, data, and AI/ML products. Integrating Cortex with GCP gives you automatic visibility into your cloud infrastructure and how it connects to the rest of your catalog.

This integration works alongside Cortex's broader Google integration, which also connects to Google Workspace to sync ownership from Google Groups. Together, they help Cortex build a live picture of your cloud footprint and who owns it.

With the GCP integration, Cortex can:

* Automatically discover GCP entities, like Cloud Run services, BigQuery datasets, and Kubernetes Engine clusters, and add them to your catalog.
* Link those entities to the services that depend on them, using tags Cortex matches automatically or dependencies you define explicitly.
* Pull in Service Level Objectives (SLOs) from Google Cloud Observability and surface them on entity pages.
* Power Scorecards and CQL queries that check GCP configuration, SLO health, and ownership across your catalog.

Cortex connects to GCP through a service account with read-only permissions scoped to the entity types you want to sync. Cortex only reads from GCP; it doesn't make changes to your cloud resources.

> [!NOTE]
>
> For information on configuring Google SSO for logging in to Cortex, see the [Google SSO documentation](/configure/settings/managing-users/configuring-sso).

## Supported Google Cloud entity types

Cortex supports importing the following entity types from Google Cloud:

> **Supported Google Cloud entity types**
>
> * Google Cloud Vertex AI Batch Prediction Job
> * Google Cloud Vertex AI Dataset
> * Google Cloud Vertex AI Endpoint
> * Google Cloud Vertex AI Featurestore
> * Google Cloud Vertex AI Index
> * Google Cloud Vertex AI Model
> * Google Cloud Vertex AI Model Deployment Monitoring Job
> * Google Cloud Vertex AI Notebooks Instance
> * Google Cloud Vertex AI Pipeline Job
> * Google Cloud Vertex AI Platform Index Endpoint
> * Google Cloud Vertex AI Specialist Pool
> * Google Cloud Vertex AI Study
> * Google Cloud Vertex AI Tensorboard
> * Google Cloud Vertex AI Training Pipeline
> * Google Cloud Vertex AI Vision Application
> * Google Cloud Vertex AI Vision Cluster
> * Google Cloud Vertex AI Vision Index Point
> * Google Cloud Vertex AI Vision Operator
> * Google Cloud Vertex AI Vision Processor
> * Google Cloud Apigee Api
> * Google Cloud Apigee Instance
> * Google Cloud App Engine Service
> * Google Cloud Artifact Registry Repository
> * Google Cloud BigQuery Connection
> * Google Cloud BigQuery
> * Google Cloud Composer Environment
> * Google Cloud Functions
> * Google Cloud Kubernetes Engine Clusters
> * Google Cloud Kubernetes Engine Operations
> * Google Cloud IAM Service Account
> * Google Cloud Instance Group
> * Google Cloud HTTP(S) Load Balancing
> * Google Cloud Memorystore Memcached
> * Google Cloud Memorystore Redis
> * Google Cloud Project
> * Google Cloud Run Job
> * Google Cloud Run Service
> * Google Cloud Spanner Instance
> * Google Cloud Spanner Instance Config
> * Google Cloud SQL
> * Google Cloud Storage
> * Google Cloud Pub/Sub Topics
> * Google Cloud VM Instances
> * Google Cloud VPC Serverless Connector

## Configuring GCP

There are two ways to connect Google Cloud to Cortex:

* **Service account** - Cortex connects directly using a Google service account with domain-wide delegation. Follow the prerequisites and steps 1 and 2 below.
* **Cortex Axon Relay** - An agent running in your network authenticates to Google Cloud, so Cortex never stores a Google credential. See [Configuring GCP with Cortex Axon Relay](/ingesting-data-into-cortex/integrations/google#configuring-gcp-with-cortex-axon-relay).

### Prerequisites

1. Users with the `Configure Integrations` permission can configure GCP.
2. A [Google service account](https://docs.cloud.google.com/iam/docs/service-account-overview) and its client ID.
   * In the Advanced settings, enable **Domain-wide Delegation**.
   * Under Domain-wide Delegation, copy the client ID and store it in a secure location. Do not skip this step! You'll need the client ID to complete setup.
   * The service account must include permissions for each project to enable Google Cloud resources. See [Google service account permissions](/ingesting-data-into-cortex/integrations/google#google-service-account-permissions) below.
3. The [Google Admin SDK API](https://console.developers.google.com/apis/api/admin.googleapis.com/overview) is configured and enabled.
4. Google Cloud resource project permissions are enabled for each project. See [Google Cloud resource project permissions](/ingesting-data-into-cortex/integrations/google#google-cloud-resource-project-permissions) below.

#### Google service account permissions

> **Expand to view the list of Google service account permissions**
>
> * AI Platform → AI Platform Viewer, Dataform Viewer, Cloud Storage for Firebase Viewer, Data Catalog Viewer, Vision AI Viewer, Notebooks Viewer, Dataflow Viewer
> * Apigee → Cloud Api Hub Viewer
> * App Engine → App Engine Viewer
> * Artifact Registry → Artifact Registry Reader
> * BigQuery → BigQuery Metadata Viewer
> * BigQuery Connection → BigQuery Connection User
> * Cloud Asset → Cloud Asset Viewer
> * Cloud Asset → ListResource
>   * Note: This permission is necessary to run services and jobs.
> * Cloud Functions → Cloud Functions Viewer
> * Cloud Pub/Sub → Pub/Sub Viewer
> * Cloud Resource Manager → Browser
> * Cloud Run → Cloud Run Viewer
> * Cloud SQL → Cloud SQL Viewer
> * Cloud Storage → Storage Admin
> * Composer → Composer User
> * Compute Engine, VM Instances → Compute Viewer
> * Kubernetes Engine → Kubernetes Engine Viewer
> * Memorystore Memcached → Cloud Memorystore Memcached Viewer
> * Memorystore Redis → Cloud Memorystore Redis Viewer
> * Monitoring → Monitoring Viewer
> * Service Accounts → View Service Accounts
> * Spanner → Cloud Spanner Viewer
> * VM Instances Vulnerabilities → OS VulnerabilityReport Viewer
> * VPC Serverless Connector → Serverless VPC Access Viewer

To create a custom role with only the minimum required permissions, add the following:

> **Expand to view the list of custom role minimum permissions**
>
> ```
> aiplatform.datasets.get
> aiplatform.datasets.list
>
> aiplatform.endpoints.get
> aiplatform.endpoints.list
>
> aiplatform.featurestores.get
> aiplatform.featurestores.list
>
> aiplatform.indexEndpoints.get
> aiplatform.indexEndpoints.list
>
> aiplatform.batchPredictionJobs.get
> aiplatform.batchPredictionJobs.list
>
> aiplatform.modelDeploymentMonitoringJobs.get
> aiplatform.modelDeploymentMonitoringJobs.list
>
> aiplatform.trainingPipelines.get
> aiplatform.trainingPipelines.list
>
> aiplatform.pipelineJobs.get
> aiplatform.pipelineJobs.list
>
> aiplatform.specialistPools.get
> aiplatform.specialistPools.list
>
> aiplatform.tensorboardExperiments.get
> aiplatform.tensorboardExperiments.list
>
> aiplatform.studies.get
> aiplatform.studies.list
>
> aiplatform.apps.get
> aiplatform.apps.list
>
> aiplatform.indexes.get
> aiplatform.indexes.list
>
> aiplatform.models.get
> aiplatform.models.list
>
> aiplatform.tensorboards.get
> aiplatform.tensorboards.list
>
> iam.serviceAccounts.get
>
> apihub.apiHubInstances.get
>
> apihub.apis.get
> apihub.apis.list
>
> appengine.services.get
> appengine.services.list
>
> artifactregistry.repositories.get
> artifactregistry.repositories.list
>
> bigquery.connections.get
> bigquery.connections.list
>
> bigquery.datasets.get
> bigquery.routines.get
> bigquery.routines.list
>
> cloudasset.assets.listResource
>
> cloudfunctions.functions.get
> cloudfunctions.functions.list
>
> cloudsql.instances.get
> cloudsql.instances.list
>
> composer.environments.get
> composer.environments.list
>
> compute.urlMaps.list
> compute.urlMaps.get
> compute.instances.list
> compute.instances.get
> compute.instanceGroups.list
> compute.instanceGroups.get
>
> container.clusters.get
> container.clusters.list
>
> container.operations.get
> container.operations.list
>
> iam.serviceAccounts.get
> iam.serviceAccounts.list
>
> memcache.instances.list
> memcache.instances.get
>
> monitoring.services.get
> monitoring.services.list
> monitoring.slos.get
> monitoring.slos.list
> monitoring.timeSeries.list
>
> notebooks.instances.get
> notebooks.instances.list
>
> osconfig.vulnerabilityReports.get
>
> pubsub.topics.get
> pubsub.topics.list
>
> redis.instances.list
> redis.instances.get
>
> resourcemanager.projects.get
> resourcemanager.projects.list
>
> run.jobs.list
> run.jobs.get
>
> run.services.list
> run.services.get
>
> spanner.instances.get
> spanner.instances.list
>
> spanner.instanceConfigs.get
> spanner.instanceConfigs.list
>
> storage.buckets.get
> storage.buckets.list
>
> visionai.applications.get
> visionai.applications.list
>
> visionai.processors.get
> visionai.processors.list
>
> visionai.operators.get
> visionai.operators.list
>
> visionai.clusters.get
> visionai.clusters.list
>
> vpcaccess.connectors.get
> vpcaccess.connectors.list
>
> ```

#### Google Cloud resource project permissions

> **Expand to view the list of Google Cloud resources project permissions**
>
> * [App Engine Admin API](https://console.cloud.google.com/marketplace/product/google/appengine.googleapis.com)
> * [ArtifactRegistry API](https://console.cloud.google.com/marketplace/product/google/artifactregistry.googleapis.com)
> * [Apigee APIs](https://console.cloud.google.com/marketplace/product/google/apigee.googleapis.com)
> * [BigQuery API](https://console.cloud.google.com/marketplace/product/google/bigquery.googleapis.com)
> * [BigQuery Connection API](https://console.cloud.google.com/marketplace/product/google/bigqueryconnection.googleapis.com)
> * [Cloud Asset API](https://console.cloud.google.com/marketplace/product/google/cloudasset.googleapis.com)
> * [Cloud Composer API](https://console.cloud.google.com/marketplace/product/google/composer.googleapis.com)
> * [Cloud Functions](https://console.cloud.google.com/marketplace/product/google/cloudfunctions.googleapis.com)
> * [Cloud SQL Admin](https://console.cloud.google.com/marketplace/product/google/sqladmin.googleapis.com)
> * [Cloud Storage](https://console.cloud.google.com/marketplace/product/google/storage.googleapis.com)
> * [Compute Engine API](https://console.cloud.google.com/marketplace/product/google/compute.googleapis.com)
> * [Kubernetes Engine API](https://console.cloud.google.com/marketplace/product/google/container.googleapis.com)
> * [Memorystore for Memcached API](https://console.cloud.google.com/marketplace/product/google/memcached.googleapis.com)
> * [Memorystore for Redis API](https://console.cloud.google.com/marketplace/product/google/redis.googleapis.com)
> * [OS Config API](https://console.cloud.google.com/marketplace/product/google/osconfig.googleapis.com)
> * [Kubernetes Engine API](https://console.cloud.google.com/marketplace/product/google/container.googleapis.com)
> * [Resource Manager API](https://console.cloud.google.com/marketplace/product/google/cloudresourcemanager.googleapis.com)
> * [Spanner API](https://console.cloud.google.com/marketplace/product/google/spanner.googleapis.com)
> * [Serverless VPC Access API](https://console.cloud.google.com/marketplace/product/google/vpcaccess.googleapis.com)

For each project in Vertex AI, enable the following:

> **Expand to view the list of permissions needed for Vertex AI projects**
>
> * [Cloud Storage API](https://console.cloud.google.com/marketplace/product/google/storage-component.googleapis.com)
> * [DataCatalog API](https://console.cloud.google.com/marketplace/product/google/datacatalog.googleapis.com)
> * [Dataflow AI API](https://console.cloud.google.com/marketplace/product/google/dataflow.googleapis.com)
> * [DataForm API](https://console.cloud.google.com/marketplace/product/google/dataform.googleapis.com)
> * [Notebooks AI API](https://console.cloud.google.com/marketplace/product/google/notebooks.googleapis.com)
> * [Vertex AI API](https://console.cloud.google.com/marketplace/product/google/aiplatform.googleapis.com)
> * [Vision AI API](https://console.cloud.google.com/marketplace/product/google/visionai.googleapis.com)

### Step 1: Configuring the integration in GCP

1. In the [G Suite admin console](https://admin.google.com/), navigate to **Security > API Controls > Manage Domain Wide Delegation**. Click **Add new**.
2. Click **Add new**.
3. Add the client ID and include the following scopes:
   * `https://www.googleapis.com/auth/admin.directory.group.readonly`
   * `https://www.googleapis.com/auth/admin.directory.group.member.readonly`
4. Go to the service account you created for this integration.
5. Click **Keys**, then generate a key in JSON format.
6. Navigate to **Admin Roles > Groups Reader** and expand the Admins panel.
7. Click **Assign service accounts** then enter the email of the service account you created for this integration.

### Step 2: Configuring the integration in Cortex

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Google, then click **Install**. The Google side panel opens.
3. In the Google side panel, do the following:
   1. From the **Category** dropdown, select at least one category that applies to the integration (required).
   2. **Under Domain**, enter your organization's Google domain (required).
   3. Under **Service account user (email)**, enter the email address for the service account (required).
   4. Under **Credentials**, paste the service account JSON exactly as it is (required).
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

By default, a service depends on any resource whose Google Cloud tag has key "service" and value matching the service's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag). After saving the configuration, you can customize the key name or leave it blank to use "service".

#### **Customizing the key name**

Follow the steps below to customize the key name.

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Google, then click **Settings**.
3. In the **Details** section, enter the key name under **Custom label key**.
4. Click **Save custom label key**.

> [!NOTE]
>
> To modify an existing configuration, see [Modifying an integration configuration](/ingesting-data-into-cortex/integrations#modifying-an-integration-configuration).

### Configuring GCP with Cortex Axon Relay

Cortex Axon Relay lets you connect Google Cloud without giving Cortex a Google credential. The Axon agent runs in your network and gets a short-lived access token from Application Default Credentials (ADC). The agent attaches the token to each request before it leaves your network, so no Google access token ever reaches Cortex.

Because the agent uses ADC, it works the same way with whichever identity your environment already provides:

* Google Kubernetes Engine (GKE) Workload Identity
* Workload identity federation
* A mounted service account key

Relay doesn't require domain-wide delegation. Google Groups sync works in relay mode, too.

**Prerequisites**

* Your [Google Workspace customer ID](https://knowledge.workspace.google.com/admin/getting-started/find-your-customer-id). You'll enter it when you configure the relay in Cortex.
* The identity the agent runs as has the roles listed in Google service account permissions.
* The APIs listed in Google Cloud resource project permissions are enabled for each project.

Your IAM bindings control what Cortex can access. Cortex doesn't configure or enforce permissions on your behalf.

> [!NOTE]
>
> By default, the agent's accept file only allows requests to `*.googleapis.com`.

**Setting up the relay**

See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for setup instructions, and note these Google Cloud-specific details:

* When you configure the relay in Cortex, set the alias to `gcp` and enter your Google Workspace customer ID. You don't need to enter a Google domain.
* Follow the Google Cloud-specific instructions for the `docker-compose.yml` file.


# Connecting entities to Google Cloud Platform
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/google/connecting-entities-to-google-cloud-platform

Automatically import Google Cloud resources and Google Groups as entities, discover dependencies between them, and keep ownership in sync

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to connect entities to GCP. For configuration instructions, see [Configuring the integration for Google Cloud Platform](/ingesting-data-into-cortex/integrations/google/connecting-entities-to-google-cloud-platform). For instructions on using the integration, see [Using the integration for Google Cloud Platform](/ingesting-data-into-cortex/integrations/google/using-the-integration-for-google-cloud-platform).

## Connecting an entity to GCP

Cortex gives you two ways to connect entities to Google Cloud: automatically or manually.
Automatic connections rely on Cortex importing your Google Cloud resources and matching labels to discover dependencies, so entities stay up to date with little upkeep.
Manual connections let you define ownership, infrastructure resources, dependencies, and SLOs directly in the entity descriptor, giving you more control when automatic discovery doesn't fit your setup.
Most teams use a mix of both, depending on how consistently their Google Cloud resources are labeled.

### Automatically importing Google Cloud resources

> [!WARNING]
>
> This feature doesn't automatically import team entities. To import them, see [Adding team entities to Cortex](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#adding-team-entities-to-cortex).

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then expand **Entities**.
4. Select the **General** tab.
5. In the **Entity settings** section, toggle on **Auto import from AWS, Azure, and/or Google Cloud**.

   ![](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/auto-import-gcp.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=50716d34e176653f93dd5079c2da4b23)

### Manually importing Google Cloud resources via entity descriptor

To explicitly connect an entity to GCP, add the `x-cortex-infra` block to the entity's YAML, specifying the resource's name, project ID, and type.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

| Field | Description | Required? |
| - | - | - |
| `resourceName` | Name of the GCP resource. For functions, use the format `location/function`. | |
| `projectId` | The GCP project ID the resource belongs to | |
| `resourceType` | The resource type, e.g. `function`, `storage` | |

**Example**

```yaml theme={null}
x-cortex-infra:
  Google Cloud:
    resources:
      - resourceName: us-central1/send-invoice
        projectId: cortex-production
        resourceType: function
      - resourceName: cortex-invoice-exports
        projectId: cortex-production
        resourceType: storage
```

## Ownership and dependencies for Google Cloud entities

### Syncing ownership from Google Groups

Cortex can use Google Groups as an ownership provider, automatically syncing group memberships so entity ownership always reflects your current mailing lists.

> [!NOTE]
>
> Cortex runs this ownership sync for Google teams every day at 9 a.m. UTC.

Cortex uses [identity mappings](/configure/settings/managing-users/identity-mapping) to connect group members to Cortex users when they exist, and falls back to each member's email address from Google otherwise.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

To assign a Google Group as an owner in your entity descriptor, use the group's full email address:

| Field | Description | Required? |
| - | - | - |
| `type` | Must be `group` | |
| `name` | The full Google Group email address | |
| `provider` | Must be `GOOGLE` | |
| `description` | Free-text description of the owner | |

**Example**

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: checkout-team@cortex.io
    provider: GOOGLE
    description: Owns the checkout service and its dependencies
```

### Discovering dependencies automatically

By default, Cortex looks for a `service` label on your Google Cloud resources and matches its value against each entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) to automatically map dependencies. If needed, you can [customize the label key](/ingesting-data-into-cortex/integrations/google#customizing-the-key-name) in Cortex.

If you'd rather define these dependencies explicitly, add an `x-cortex-dependency` block to your entity descriptor:

| Field | Description | Required? |
| - | - | - |
| `key` | The label key on the GCP resource to match against | |
| `value` | The label value on the GCP resource to match against | |

**Example**

```yaml theme={null}
x-cortex-dependency:
  gcp:
    labels:
      - key: service
        value: checkout-service
      - key: env
        value: production
```

### Connecting SLOs

Reference a Service Level Objective (SLO) from Google Cloud Observability by adding its project and service ID to the entity's descriptor:

| Field | Description | Required? |
| - | - | - |
| `projectId` | The GCP project ID the SLO belongs to | |
| `serviceId` | The unique ID from the service's page in Google Cloud Observability | |

**Example**

```yaml theme={null}
x-cortex-slos:
  gcp:
    - projectId: cortex-production
      serviceId: iLE2e4HvR_service-checkout
    - projectId: cortex-production
      serviceId: iLE2e4HvR_service-billing
```

Find the `serviceId` value as the Unique ID on the [service page in Google Cloud Observability](https://console.cloud.google.com/monitoring/services).


# Using the integration for Google Cloud Platform
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/google/using-the-integration-for-google-cloud-platform

How to use the integration for GCP in Cortex

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for GCP. For configuration instructions, see [Configuring the integration for Google Cloud Platform](/ingesting-data-into-cortex/integrations/google/using-the-integration-for-google-cloud-platform). For instructions on connecting GCP to entities, see [Connecting entities to Google Cloud Platform](/ingesting-data-into-cortex/integrations/google/connecting-entities-to-google-cloud-platform).

## Viewing Google Cloud Observability data in entity pages

After connecting SLOs, Cortex surfaces Google Cloud Observability data directly on entity details pages:

* An entity's overview page shows a summary of its SLOs.
* Select **Monitoring > Google** in an entity's sidebar for more detail, including the SLO name, targets, status, current value, and the time range it's calculated over. For example, a time listed as "7 days ago" means the SLO covers the range from 7 days ago to now.

### Creating Scorecard rules and writing CQL queries with the GCP integration

With the Google integration, you can create Scorecard rules and write CQL queries based on GCP details, Google Cloud Observability SLOs, and Google teams.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **GCP details**
>
> Get the GCP details for the entity.
>
> **Definition** - `gcp.details()`
>
> **Examples**
>
> A Scorecard might include a rule to verify that an entity has GCP details:
>
> ```
> gcp.details() != null
> ```
>
> You might include a rule to check whether any labels on the GCP recourse are titled `origin`:
>
> ```
> jq(gcp.details(), ".resources[0].labels | any(\"origin\")")
> ```

> **SLOs**
>
> SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
>
> **Definition** - `slos: List<SLO>`
>
> **Example**
>
> In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
>
> ```
> slos().all((slo) => slo.passing) == true
> ```
>
> Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
>
> ```
> slos().filter((slo) => slo.name.matchesIn("latency") and slo.sliValue >= 0.9999).length > 0
> ```

**Ownership CQL**

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition -** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity.
>
> **Definition** - `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity.
>
> **Definition** - `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

## Viewing GCP integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

See frequently asked questions below.

> **The GCP integration only supports a single service account. Is there a workaround?**
>
> By default, GCP service accounts are restricted to the project they were created in. If other projects don’t explicitly allow that service account to access their resources, Cortex can’t collect data from them. To work around this, you can configure a [principal service account](https://docs.cloud.google.com/iam/docs/principals-overview) and associate it with multiple projects in GCP. Once the service account is linked to other projects, Cortex can use that service account to pull data from multiple GCP projects.
>
> After creating a service account that is linked to a project, open your second project in GCP and go to **IAM & Admin > IAM >** Click **+Add**. Using the service account ID that you already created, add a principal to the project. Repeat these steps for each project.


# Grafana
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/grafana



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Grafana](https://grafana.com/) is an open-source observability platform that provides monitoring and visual analytics for application performance. Use Grafana to [visualize](https://grafana.com/docs/grafana/latest/panels-visualizations/visualizations/) your data, from bar charts and histograms to pie charts and geomaps.

Integrating Grafana with Cortex allows you to:

* [View Grafana charts on entity pages](/ingesting-data-into-cortex/integrations/grafana#viewing-grafana-graphs-on-an-entity) in Cortex
* Create [Scorecards](/ingesting-data-into-cortex/integrations/grafana#scorecards-and-cql) that include rules related to Grafana dashboards

## How to configure Grafana with Cortex

### Prerequisites

Before getting started:

* Your Grafana dashboard must have [`allow_embedding` enabled](https://grafana.com/docs/grafana/next/setup-grafana/configure-grafana/#allow_embedding).
* Your [Grafana dashboard must be public](https://grafana.com/docs/grafana/latest/dashboards/share-dashboards-panels/shared-dashboards/) OR if you are on a [Self-managed Cortex](/self-managed) instance, then Cortex and Grafana must be accessible within the same private network (such as a VPN).
  * You will need the public embed link provided in the iframe snippet.

### Embed the chart in an entity's YAML file

Define the public embed link in the [entity descriptor YAML](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file) for each entity where you want to embed a chart.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

1. For the entity where you want to embed a chart, open its YAML file.
   * You can do this locally if following a [GitOps](/configure/gitops) approach, or you can edit a YAML file directly in the Cortex UI on the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. Add the `x-cortex-dashboards` block. Include the `type` (`grafana`) and the `url` (the public embed link you obtained from Grafana). See the example below:

```yaml theme={null}
x-cortex-dashboards:
  embeds:
    - type: grafana
      url: https://snapshots.raintank.io/dashboard-solo/snapshot/y7zwi2bZ7FcoTlB93WN7yWO4aMiz3pZb?from=1493369923321&to=1493377123321&panelId=4&orgId=0
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Type of embed (in this case, `grafana`) | **✓** |
| `url` | Embed URL for the Grafana dashboard | **✓** |

Repeat the steps above for each entity you want to add a Grafana chart to.

## Using the Grafana integration

### Viewing Grafana charts on an entity

Once you've defined the chart in an entity's YAML, you can view the graphs from an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

In an entity's sidebar, click **Dashboard**. All charts defined in the entity descriptor will be embedded on this page.

### Scorecards and CQL

With the Grafana integration, you can create Scorecard rules and write CQL queries based on Grafana charts.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Embeds**
>
> Query against embeds associated with an entity.
>
> **Definition:** `embeds()`
>
> **Example**
>
> If Grafana charts are a core part of operations at your organization, you can set a Scorecard rule to make sure entities have embedded charts.
>
> ```
> embeds().any((embed) => embed.type == "GRAFANA")
> ```

## Background sync

Grafana charts are updated in real time.

## FAQs and troubleshooting

**I've correctly added the embed URL, but the graph is showing an error or a blank screen.**

You may need to [enable embedding](https://grafana.com/docs/grafana/latest/administration/configuration/#allow_embedding) in your Grafana instance.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Harness
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/harness

Configuring the integration for Harness

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to configure the integration for Harness. For instructions on importing Harness pipelines and deployments and mapping them to entities, see [Importing data from Harness](/ingesting-data-into-cortex/integrations/harness/importing-data-from-harness). For instructions on using the integration, including viewing pipelines and deployments and triggering Harness pipelines from a Workflow, see [Using the integration for Harness](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness).

## Why use the integration for Harness

Harness is where your team builds and deploys software. Connecting it to Cortex ties your delivery pipelines to the services in your catalog, so your CI/CD platform and your system of record stay in sync.

With the Harness integration, you can:

* **See where every service deploys.** Cortex imports your Harness pipelines and deployments and shows them on each entity's page, with status, version, environment, and a link to the run in Harness. Deployments also feed Eng Intelligence metrics. This capability is in private beta.
* **Connect all of your Harness accounts.** Cortex supports multiple configurations, so you can connect several Harness accounts and tie each one to entities using its own alias.
* **Keep internally hosted instances private.** Use Cortex Axon Relay to connect a self-managed Harness instance without exposing it to the internet. The relay agent runs in your network and injects your API key locally, so credentials never leave your environment.
* **Verify your setup before you commit.** Test a configuration directly from the settings page to confirm Cortex can reach your Harness account, whether you use a personal access token or a service account token.
* **Run pipelines from a Workflow.** Use the **Execute pipeline** block to trigger a Harness pipeline as a step in a Cortex Workflow, without building a custom webhook trigger for each pipeline.

### What Cortex imports from Harness

> [!NOTE]
>
> Importing Harness pipelines and deployments is in Private Beta. To request access, contact the [Cortex Customer Engineering](mailto:help@cortex.io) team.

Cortex imports the following from each Harness configuration:

* Organizations and projects
* Services
* Environments
* Infrastructure definitions
* Pipelines
* Deployments, including failed deployments and rollbacks

Cortex doesn't import deployment logs. To see a run's logs, follow the link from Cortex to the run in Harness.

## Configuring Harness

There are two options for integrating Harness: the default token configuration method and Cortex Axon Relay, a relay broker that allows you to securely connect your internally hosted Harness instance.

### Prerequisites

1. Users with the `Configure Integrations` permission can configure Harness.
2. An API key in Harness. Cortex supports both personal access tokens and service account tokens. For instructions, refer to the [Harness API key documentation](https://developer.harness.io/docs/platform/automation/api/add-and-manage-api-keys/).
3. Your Harness account identifier. You can find this in Harness under **Account settings**, or in your Harness URL.

### **Configuring Harness with a token**

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Harness, then click **Install**. The Harness side panel opens.
3. In the Harness side panel, click **Token**.
4. Do the following:
   1. From the **Category** dropdown, select at least one category that applies to the integration (required).
   2. Under **Configuration alias**, enter the alias you'll use to tie entity registrations to different configuration accounts (required).
   3. Under **Account ID**, enter your Harness account identifier (required).
   4. Under **API key**, enter your Harness API key (required). This can be a personal access token or a service account token.
   5. Under **Host**, enter the URL of your self-managed Harness instance. If you leave this field blank, Cortex defaults to `https://app.harness.io`.
5. Click **Test connection**. A successful connection means your integration is configured correctly.
6. Click **Save**.

### Configuring Harness with Cortex Axon Relay

Use this option if your Harness instance is hosted in your own network and can't be reached directly by Cortex.

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Harness, then click **Install**. The Harness side panel opens.
3. Click **Relay**.
4. Do the following:
   1. From the **Category** dropdown, select at least one category that applies to the integration (required).
   2. Under **Configuration alias**, enter the alias you'll use to tie entity registrations to different configuration accounts (required).
   3. Under **Account ID**, enter your Harness account identifier (required).
   4. Under **Host**, enter the URL of your self-managed Harness instance. If you leave this field blank, Cortex defaults to `https://app.harness.io`.
5. Click **Save**.
6. Set up the Axon Relay agent in your network. See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for instructions. For Harness, the relay agent routes requests to your Harness instance and injects your API key, so your credentials never leave your network.

> [!WARNING]
>
> On some self-managed Harness instances, the `/ng` API path is restricted. If the credential check fails with 403, include `/gateway` in the host URL (e.g., `https://harness.example.com/gateway`) so the full API path resolves to `/gateway/ng/api/projects`

### Using multiple Harness configurations

The Harness integration supports multiple configurations. To add another:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Harness, then click **Settings**.
3. In the upper-right corner of the page, click **Add configuration**.
4. Follow the steps in either [Configuring Harness with a token](/ingesting-data-into-cortex/integrations/harness#configuring-harness-with-a-token) or [Configuring Harness with Axon Relay](/ingesting-data-into-cortex/integrations/harness#configuring-harness-with-cortex-axon-relay).

Each configuration requires an alias, which ties entity registrations to a specific account. If no alias is specified, Cortex uses the default configuration. To set a default:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Harness, then click **Settings**.
3. Click the **pencil icon** next to the configuration that should be the default.
4. Toggle on **Set as default**. If you only have one configuration, it's automatically set as the default.

## How Cortex syncs Harness data

Harness limits external API requests to 400 calls per minute per API key. Cortex stays within this limit when it pulls data from Harness, so an ingestion cycle can take a while on large Harness accounts. For very large accounts, a single cycle can take several hours.

Cortex doesn't sync Harness on a fixed schedule. Instead, it starts a new ingestion cycle within 10 minutes of the previous cycle finishing. The time between updates depends on the size of your Harness account, and changes you make in Harness appear in Cortex after the next cycle completes.

Cortex prioritizes your most active Harness projects so their deployments stay current. Each time Cortex checks a project and finds no new deployments, it waits longer before checking that project again. As soon as it finds a new deployment, it goes back to checking at the normal rate. This means a new deployment in a project that's been inactive for a while can take longer to appear in Cortex than one in an active project.

If ingestion takes too long for your account, you can ask Harness to raise your rate limit. If Harness increases it, contact the [Cortex Customer Engineering](mailto:help@cortex.io) team so Cortex can raise the limit it uses for your account.

For details on Harness API limits, refer to the [Harness platform rate limits documentation](https://developer.harness.io/docs/platform/rate-limits/).


# Importing data from Harness
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/harness/importing-data-from-harness

Automatically sync and map your Harness pipelines and deployments

PRIVATE BETA

> [!NOTE]
>
> Importing Harness pipelines and deployments is in Private Beta. To request access, contact the [Cortex Customer Engineering](mailto:help@cortex.io) team.

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how Cortex imports pipelines and deployments from Harness and maps them to your entities. For configuration instructions, see [Configuring Harness](/ingesting-data-into-cortex/integrations/harness). For what you can do once your data is imported, see [Using the integration for Harness](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness).

> [!NOTE]
>
> Harness limits API usage to 400 requests per minute, so syncing data can take a long time for larger accounts. For details, including how to request a higher rate limit, see [How Cortex syncs Harness data](/ingesting-data-into-cortex/integrations/harness#how-cortex-syncs-harness-data).

Cortex shows Harness pipelines and deployments on an entity once the entity is linked to one or more Harness services. There are two ways to link them:

* **Automatic matching** - Cortex links a Harness service to an entity when the service details match in both systems. You don't need to register anything.
* **Registration** - You choose the Harness services for an entity yourself, in the entity's YAML or from the entity's details page.

If an entity has registered Harness services, Cortex uses only those and ignores automatic matches for that entity.

## How Cortex matches Harness services automatically

Cortex compares the entity's tag (`x-cortex-tag`) to the following values on each Harness service, without regard to case:

* The service identifier.
* The service name.
* The value of the service's `cortex.entity` tag in Harness.

For example, an entity tagged `payments-api` matches a Harness service named `payments-api`, or a service with the Harness tag `cortex.entity: payments-api`. Because Harness removes hyphens from identifiers, the service name or the `cortex.entity` tag is often the more reliable match.

> [!NOTE]
>
> If your organization uses a different Harness tag key to name Cortex entities, contact the [Cortex Customer Engineering](mailto:help@cortex.io) team to add it to your account's matching rules.

## Registering Harness services for an entity

Register Harness services when automatic matching doesn't link the right service, or when one entity deploys through several services.

### Registering services from an entity's details page

1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. From the left sidebar, locate the **Connections** section, then select the **CI/CD** tab.
4. From the **Services** dropdown, select the Harness services to link to the entity.
5. Click **Save changes**.

### Registering services in the YAML

To register Harness services in the YAML, add an `x-cortex-ci-cd` block with a `harness` entry to the entity's descriptor.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-ci-cd:
  harness:
    services:
      - orgIdentifier: default
        projectIdentifier: payments
        identifier: paymentsapi
```

To link more than one service, add another entry under `services`:

```yaml theme={null}
x-cortex-ci-cd:
  harness:
    services:
      - orgIdentifier: default
        projectIdentifier: payments
        identifier: paymentsapi
      - orgIdentifier: default
        projectIdentifier: payments
        identifier: paymentsworker
```

Harness services have the following field definitions:

| Field | Description | Required |
| - | - | - |
| `orgIdentifier` | The identifier of the Harness organization that owns the service. | |
| `projectIdentifier` | The identifier of the Harness project that owns the service. | |
| `identifier` | The identifier of the Harness service. | |

You can find all three identifiers in the service's URL in Harness. Cortex skips any entry that is missing one of them.


# Using the integration for Harness
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness

How to use the integration for Harness in Cortex

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for Harness. For configuration instructions, see [Configuring Harness](/ingesting-data-into-cortex/integrations/harness). For instructions on importing Harness pipelines and deployments and mapping them to entities, see [Importing data from Harness](/ingesting-data-into-cortex/integrations/harness/importing-data-from-harness).

After you configure Harness, you can view Harness pipelines and deployments in Cortex, and trigger Harness pipelines directly from a Cortex Workflow using the **Execute pipeline** block.

## Viewing Harness pipelines and deployments

> [!NOTE]
>
> Importing Harness pipelines and deployments is in private beta. To request access, contact the [Cortex Customer Engineering](mailto:help@cortex.io) team.

Once Harness services are [mapped to entities](/ingesting-data-into-cortex/integrations/harness/importing-data-from-harness), you can view pipelines and deployments across your workspace, on each entity's details page, in Eng Intelligence, and in CQL.

### Pipelines and deploys across your workspace

The **Data** page shows every pipeline and deploy Cortex has imported from Harness, so you can check what's been imported and which entities it's linked to.

1. From the main sidebar, expand **Integrations**, then select **Data**.
2. Select the **Pipelines** tab or the **Deploys** tab.

The **Deploys** tab is sorted by newest deploy first. Use the search bar to find a specific pipeline or deploy, or click **Filter** to narrow the list.

> [!NOTE]
>
> The **Deploys** tab shows only deploys imported from Harness. Deploys sent through the [deploys API](/ingesting-data-into-cortex/entities-overview/entities/deploys) don't appear there.

### Pipelines and deployments on an entity's details page

1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the left sidebar, locate **Connections**, then expand **CI/CD**.
3. Select Harness.
4. Select the **Pipelines** or **Deployments** tab to view the pipelines or deployments for that entity.
   * **Pipelines** - Each Harness pipeline that deploys the entity, with the latest status for each environment it deploys to.
   * **Deployments** - The entity's deployment history, with the outcome (success, failure, or rollback), deployed version, environment, infrastructure, who started it, and when. Filter by environment or infrastructure, and click a deployment to open the run in Harness.

### Deployments in Eng Intelligence

Harness deployments count toward [Eng Intelligence](/improve/eng-intelligence) deployment metrics, including deployment frequency, rollback frequency, and change failure rate. Change failure rate counts both failed deployments and rollbacks.

### Harness data in CQL and Scorecards

Use the `cicd` CQL functions to write [Scorecard](/standardize/scorecards) rules and [CQL reports](/standardize/cql/cql-reports) based on Harness data. These functions are separate from `deploys()`, which only returns deploys sent through the deploys API.

> **Deployments**
>
> **Definition** - `cicd.deployments(lookback: Duration, environment: List, status: List, type: List, includeDetails: Boolean): List`
>
> Returns the entity's deployments that started within the lookback, newest first. `lookback` is required. The other arguments are optional filters:
>
> * `environment` - Environment names to keep, without regard to case.
> * `status` - Any of `SUCCEEDED`, `FAILED`, `ABORTED`, `SKIPPED`, `RUNNING`, `WAITING`, or `UNKNOWN`.
> * `type` - `DEPLOY` or `ROLLBACK`.
> * `includeDetails` - Set to `true` to include the full Harness record for each deployment under `provider.details`.
>
> A single evaluation can return up to 10,000 deployments. If more match, the rule fails with an error, so use a shorter lookback or add filters.
>
> Check that an entity deployed successfully to production at least four times in the last 30 days:
>
> ```
> cicd.deployments(lookback = duration("P30D"), environment = ["production"], status = ["SUCCEEDED"]).length >= 4
> ```
>
> Check that fewer than 1 in 4 deployments in the last month failed or were rolled back:
>
> ```
> (cicd.deployments(lookback = duration("P1M"), status = ["FAILED"]).length + cicd.deployments(lookback = duration("P1M"), type = ["ROLLBACK"]).length) / cicd.deployments(lookback = duration("P1M")).length < 0.25
> ```

> **Pipelines**
>
> **Definition** - `cicd.pipelines(includeDetails: Boolean): List`
>
> Returns the Harness pipelines that have deployed the entity.
>
> **Checking whether an entity is connected**
>
> `cicd` is `null` when an entity isn't linked to any Harness service. Use this to check whether an entity has CI/CD set up:
>
> ```
> cicd != null
> ```

## Triggering a Harness pipeline from a Workflow

The **Execute pipeline** block runs a Harness pipeline as a step in a Workflow. You can chain it with other blocks, for example to require a manual approval before a deploy, or to post the run link to Slack after the pipeline starts.

### Prerequisites

1. A configured Harness integration.
2. The Harness API key used in that configuration must have permission to execute the pipelines you want to run.
3. Permission to create or edit Workflows in Cortex. See [Creating a Workflow](/streamline/workflows/create).

**To add the Execute pipeline block to a Workflow**:

1. From the main sidebar, select **Workflows**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's Workflows.
   * Select the **Mine** tab to search and filter only the Workflows you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow you want to edit, click the **overflow menu** next to it, then select **Edit**.
4. Click the **+ icon**. The **Search for blocks** window opens.
5. Search for **Harness**, then select **Execute pipeline**.
6. In the side panel, configure the block metadata:
   1. **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
   2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
   3. **Alias** - From the dropdown, select the Harness configuration the block should use (required). See [Selecting the right configuration](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness#selecting-the-right-configuration) for more information.
   4. Enter the required parameter details:
      1. Under **Organization identifier**, enter the identifier of the Harness organization that owns the pipeline (required).
      2. Under **Project identifier**, enter the identifier of the Harness project that owns the pipeline (required).
      3. Under **Pipeline identifier**, enter the identifier of the pipeline you want to run (required).
   5. Optionally, add runtime inputs:
      1. Under **Runtime inputs**, enter the pipeline's runtime input values as YAML. Use this to pass values the pipeline expects at execution time, such as an environment or an image tag.
      2. Under **Notes**, enter a short description of the run. Cortex passes this to Harness so the execution is easier to identify in the Harness UI.
7. Click **Save**.

You can reference values from earlier blocks in any of these fields using Workflow state. See [Referencing Workflow state in a block](/streamline/workflows/blocks#referencing-a-workflow-state-in-a-block).

### Block outputs

When the pipeline is triggered successfully, the block returns:

* `execution_id` - The identifier of the Harness pipeline execution that was started.
* `status` - The execution status Harness reported at trigger time.
* `response` - The full response object from Harness, for any field not surfaced above.

Reference these in later blocks the same way you reference any other block output, for example to build a link to the execution or to branch on the returned status.

> [!NOTE]
>
> The **Execute pipeline** block is synchronous. It returns as soon as Harness acknowledges the run, so `status` reflects the state of the execution at trigger, not the final result of the pipeline. To act on the pipeline's outcome, poll Harness in a later block or have the pipeline notify Cortex when it finishes.

### How the block authenticates

The block authenticates with the API key stored in the Harness configuration you select, so the pipeline runs as the owner of that key. It doesn't run as the person who started the Workflow. Keep this in mind when you set up Harness permissions and when you review pipeline audit logs, since every run started from Cortex is attributed to the key's owner.

### Selecting the right configuration

If you have more than one Harness configuration, always select an explicit **Configuration alias** on the block. A block left on the default configuration uses the default account's credentials, which is a common cause of unexpected `401` errors when you meant to use a different account.

This matters most for internally hosted instances. See [Using the block with Cortex Axon Relay](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness#using-the-block-with-cortex-axon-relay).

## Using the block with Cortex Axon Relay

The **Execute pipeline** block works with internally hosted Harness instances connected through [Cortex Axon Relay](/ingesting-data-into-cortex/integrations/axon-relay). The relay agent runs in your network and injects your Harness API key locally, so your credentials never leave your environment. For setup instructions, see Internally hosted integrations.

Two things to know when you use the block over the relay:

* **Select the relay-backed configuration alias on the block.** Cortex only routes a request through the relay when the block names a configuration alias. If the block is left on the default configuration, the request goes directly to Harness instead of through the relay and fails to authenticate.
* **Your Harness API key stays on-premises.** Cortex sends the request with a placeholder credential, and the relay agent replaces it with your real key before the request reaches Harness. Both personal access tokens and service account tokens are supported.

## Viewing Harness integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

See frequently asked questions below.

> **The block returns a 401 or authentication error**
>
> Check the following:
>
> * The block has an explicit **Configuration alias** selected. If it's set to the default configuration and your Harness instance is behind Cortex Axon Relay, the request bypasses the relay and fails.
> * The API key in the selected configuration is still valid, and its owner has permission to execute the pipeline.
> * The organization and project identifiers on the block match the account the selected configuration points at.

> **A relay-backed Harness configuration shows as failing validation**
>
> A newly created relay-backed configuration can show a failed connection test on the integration settings page, even when the setup is correct. Click **Test connection** on the configuration to re-run the check. If it still fails, confirm the Axon Relay agent is running and can reach your Harness host.

> **The pipeline started, but the Workflow moved on before it finished**
>
> This is expected. The **Execute pipeline** block returns as soon as Harness acknowledges the run. Use the returned `execution_id` in a later block to check the execution's final state in Harness.

> **Harness data in Cortex is taking a long time to update**
>
> Harness limits external API requests to 400 calls per minute per API key, so ingestion cycles can take several hours on large Harness accounts. Cortex starts a new cycle within 10 minutes of the previous one finishing, so changes in Harness appear in Cortex after the next cycle completes. To speed up ingestion, ask Harness to raise your rate limit, then contact the [Cortex Customer Engineering](mailto:help@cortex.io) team so Cortex can match it. For more information, see [How Cortex syncs Harness data](/ingesting-data-into-cortex/integrations/harness#how-cortex-syncs-harness-data).
>
> Cortex also checks inactive Harness projects less often than active ones. If a project hasn't had a deployment in a while, its next deployment can take longer to appear.


# Humanitec
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/humanitec



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Humanitec](https://humanitec.com/) offers products to build on top of your Engineering Operations Platform for containerized workloads.

Integrating Humanitec with Cortex allows you to run a Humanitec pipeline directly from Cortex.

## How to integrate Humanitec with Cortex

### Prerequisites

Before getting started:

* You should have an app with a working pipeline configured in Humanitec.
* Create a service user in Humanitec, and create an [API token in Humanitec](https://developer.humanitec.com/platform-orchestrator/docs/platform-orchestrator/reference/api-references/#authentication) for the service user.

### Step 1: Create a Workflow in Cortex

1. Follow the instructions to [begin creating a Workflow](/streamline/workflows/create#step-1-choose-a-template-or-a-blank-workflow) and [configure its basic settings](/streamline/workflows/create#step-2-configure-your-workflow-settings).
2. Add an **HTTP request** block to your Workflow. Configure the block:
   * **Block name**: Enter a descriptive name for the block.
   * **Slug**: Enter a unique identifier for the block.
   * **HTTP method**: Select `POST`.
   * **URL**: Enter a Humanitec API URL based on the Humanitec call [`createPipelineRun`](https://api-docs.humanitec.com/#tag/PipelineRuns/operation/createPipelineRun), e.g., `https://api.humanitec.io/orgs/<your-Humanitec-org>/<your-app-ID>/pipelines/<pipeline-ID>/runs`
3. At the bottom of the side panel, click **Save**.
4. Make any other necessary changes to your Workflow, then in the upper right corner of the page, click **Save workflow**.

Alternatively, you can also use an **Async HTTP request** block in your Workflow, using the [Humanitec action `actions/humanitec/http@v1`](https://developer.humanitec.com/platform-orchestrator/docs/integration-and-extensions/humanitec-pipelines/available-actions/#actionshumanitechttpv1) to call back to Cortex.

### Step 2: Run the Workflow

* At the top of your Workflow in Cortex, click **Run**.

In your Humanitec workspace under your app's pipelines, you will see the run listed under the **Runs** tab:

![Runs are listed in Humanitec under the app's pipeline runs tab.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/humanitec-runs.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=9ebdc27a030568d2148046b116568652)

## Example using Cortex with AWS, Humanitec, and Terraform

See the video below where a member of the Humanitec team walks through advanced end-to-end setup on AWS using Cortex, Humanitec as the orchestrator, and Terraform modules deployed via ECS runners. The video demonstrates detecting a policy violation and remediating it.

[YouTube video player](https://www.youtube.com/embed/iFYO0TFF5cs?start=44)


# incident.io
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/incidentio



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to configure the integration for incident.io. For instructions on connecting incident.io to entities, see [Connecting entities to incident.io](/ingesting-data-into-cortex/integrations/incidentio/connecting-entities-to-incident.io). For information on how to use the integration, see [Using the integration for incident.io](/ingesting-data-into-cortex/integrations/incidentio/using-the-integration-for-incident.io).

## Why use the integration for incident.io

incident.io is an incident management platform that coordinates how teams declare, respond to, and resolve incidents. The integration brings that data into Cortex, so an entity's incident history and current on-call coverage sit alongside its ownership, dependencies, and Scorecard results.

The integration for incident.io brings the following into Cortex:

* **Incidents** - Active and historical incidents for an entity, with severity, status, and affected entities.
* **On-call schedules** - Who's on call now and who's on call next for an entity. Requires the **On-call** category.

You can also build Scorecard rules and Cortex Query Language (CQL) queries against incident and on-call data, and track incident frequency and mean time to resolution (MTTR) in Eng Intelligence.

### Using Cortex as a source of truth in incident.io

incident.io natively supports pulling Cortex teams and catalog entities into incident.io, so Cortex can serve as the source of truth for team and service data across both platforms. This is configured from the incident.io side. See [incident.io's Cortex integration docs](https://docs.incident.io/catalog/cortex) for setup instructions.

## Configuring incident.io

### Prerequisites

1. Users with the `Configure Integrations` permission can configure incident.io.
2. Create an [incident.io API key](https://app.incident.io/settings/api-keys) with the following scopes:
   * `Create incidents`
   * `View all incident data, including private incidents`
   * `View data like public incidents and organization settings`
   * `View catalog types and entries`
   * `schedules.view`
   * `catalog_entries.view`

### **Installing incident.io in Cortex**

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate incident.io, then click **Install**. The incident.io side panel opens.
3. In the incident.io side panel, do the following:
   1. From the **Category** dropdown, select the types of data to import (required):

      * **Incidents** - Imports incidents with severity, status, and affected entities.
      * **On-call** - Imports on-call schedules, including who's on call now and next.

      For more information, see [Integration categories](/ingesting-data-into-cortex/integrations/#integration-categories).
   2. Under **Configuration alias**, enter the alias you'll use to tie entity registrations to different configuration accounts (required).
   3. Under **API key**, enter your incident.io API key (required).
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

> [!NOTE]
>
> To modify an existing configuration, see [Modifying an integration configuration](/ingesting-data-into-cortex/integrations#modifying-an-integration-configuration).

### **Using multiple incident.io configurations**

The incident.io integration supports multiple configurations. To add another:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate incident.io, then click **Settings**.
3. In the upper-right corner of the page, click **Add configuration**.
4. Follow the steps in [Installing incident.io in Cortex](/ingesting-data-into-cortex/integrations/incidentio#installing-incident.io-in-cortex) above.

Each configuration requires an alias, which ties entity registrations to a specific account. If no alias is specified, Cortex uses the default configuration. To set a default:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate incident.io, then click **Settings**.
3. Click the **pencil icon** next to a configuration.
4. Toggle on **Set as default**. If you only have one configuration, it's automatically set as the default.


# Connecting entities to incident.io
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/incidentio/connecting-entities-to-incident.io



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to connect Cortex entities to incident.io. For configuration instructions, see [Configuring the integration for incident.io](/ingesting-data-into-cortex/integrations/incidentio). For what you can do once entities are connected, see [Using the integration for incident.io](/ingesting-data-into-cortex/integrations/incidentio/using-the-integration-for-incident.io).

There are two connections you can make, and they're independent of each other:

* **Incidents (through custom fields)** bring incident data into Cortex, so incidents appear on an entity's page and you can query them in CQL.
* **On-call schedules** bring on-call data into Cortex, so you can see who's on call for an entity.

Configuring one doesn't configure the other. If you want both incident and on-call data for an entity, set up both.

**How Cortex matches values**

For both connections, Cortex matches on name first, then falls back to the identifier.

For example, if your entity is named "Payment Service," Cortex looks for a value in incident.io of either `Payment Service` or `payment-service`. If your Cortex team is named "Data Team," Cortex looks for either `Data Team` or `data-team`.

## Connecting an entity to incident.io incidents

Cortex automatically matches incidents to Cortex entities using custom field values in incident.io. As long as the custom field value matches the entity's name or identifier, you don't need to register anything.

To point an entity at a specific custom field instead, add an `x-cortex-incident-io`  block to the YAML.

### Connecting incidents in the entity descriptor

Reference the custom field by its name:

```yaml theme={null}
x-cortex-incident-io:
  customFields:
    - name: Affected Service
      value: Payment Service
      alias: prod-account
```

If the custom field's name might change, reference it by ID instead. You can find the ID in the custom field's URL in incident.io.

```yaml theme={null}
x-cortex-incident-io:
  customFields:
    - id: 01HQ3W8ZK5MJTPV2N6RXBD4Y7C
      value: Payment Service
      alias: prod-account
```

Custom fields have the following field definitions:

| Field | Description | Required |
| - | - | - |
| `name` | The name of the custom field in incident.io. Use either `name` or `id`. | |
| `id` | The ID of the custom field in incident.io. Use either `name` or `id`. | |
| `value` | The value stored in that custom field for this entity. | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support). | |

## Connecting an entity to incident.io on-call schedules

Connect on-call schedules from incident.io to see current on-call information for an entity in the catalog. Unlike custom fields, on-call schedules aren't matched automatically. You link them in one of two ways:

* **By schedule** - Select one or more specific incident.io schedules to link directly to the entity.
* **By team** - Select a team from incident.io. Every schedule associated with that team is linked to the entity automatically, so new schedules for that team appear without additional configuration.

Link by team when the team owns the entity and you don't want to revisit the mapping each time its rotations change. Link by schedule when you need a specific rotation on the entity and not everything the team runs.

You can configure on-call from an entity page in Cortex, or in the YAML.

### Connecting from an entity's details page

1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. From the left sidebar, locate the **Connections** section, then select the **On-call** tab.
4. From the **Integration** dropdown, select incident.io.
5. Do one of the following:
   1. From the **Schedule name** dropdown, select a schedule to link to the entity.
   2. From the **Team name** dropdown, select a team to link to the entity.
6. Click **Save changes**.

### Connecting in the YAML

To register on-call in the YAML, add an `x-cortex-oncall` block to the entity's descriptor.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Registrations are made by ID, not by name, and don't take an alias.

On-call registrations have the following field definitions:

| Field | Type | Required? |
| - | - | - |
| `type` | Either `SCHEDULE` or `TEAM` | |
| `id` | ID of the incident.io schedule or team. | |

#### Schedules

To map a single schedule to an entity, use the schedule's ID. You can find it in incident.io in the schedule's URL.

```yaml theme={null}
x-cortex-oncall:
  incidentio:
    - type: SCHEDULE
      id: 01JXZXCV1NAT4B6NAVM5GMNM20
```

Multiple schedules can be mapped to an entity:

```yaml theme={null}
x-cortex-oncall:
  incidentio:
    - type: SCHEDULE
      id: 01JXZXCV1NAT4B6NAVM5GMNM20
    - type: SCHEDULE
      id: 01JXZXCV1NAT4B6NAVM5GMNM47
```

#### Teams

A `TEAM` registration maps every incident.io schedule whose team field matches that Cortex team. To map a team, use the team's ID. You can find it in incident.io in the team's URL.

```yaml theme={null}
x-cortex-oncall:
  incidentio:
    - type: TEAM
      id: 01JXZXCV1NAT4B6NAVM5GMNM13
```

Multiple teams can be mapped to an entity:

```yaml theme={null}
x-cortex-oncall:
  incidentio:
    - type: TEAM
      id: 01JXZXCV1NAT4B6NAVM5GMNM13
    - type: TEAM
      id: 01JXZXCV1NAT4B6NAVM5GMNM14
```

#### Schedules and Teams

You can register both on the same entity. Use this when a team owns the entity but you also want a specific shared rotation on it:

```yaml theme={null}
x-cortex-oncall:
  incidentio:
    - type: TEAM
      id: 01JZ7K2WN4CQD9BX5VHTF6RGA3
    - type: SCHEDULE
      id: 01JXZXCV1NAT4B6NAVM5GMNM20
```


# Using the integration for incident.io
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/incidentio/using-the-integration-for-incident.io



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for incident.io. For configuration instructions, see [Configuring the integration for incident.io](/ingesting-data-into-cortex/integrations/incidentio). For instructions on connecting incident.io to entities, see [Connecting entities to incident.io](/ingesting-data-into-cortex/integrations/incidentio/connecting-entities-to-incident.io).

## Viewing incident data

You can view incident data in the incident list and on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

### Incident list

See every incident across your organization in one place, with metadata including severity, status, and affected entities.

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incident-list.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=13c406f0ee0dd97f918e37745856beb8)

**To access the incident list**:

1. From the main sidebar, expand **Integrations**, then select **Data**.
2. Select the **Incidents** tab.

The list is sorted by most recently opened incidents first.

> [!NOTE]
>
> Cortex ingests all available incidents from incident.io. Incidents marked as [declined or merged](https://docs.incident.io/incidents/triaging) or [canceled](https://docs.incident.io/incidents/delete-incidents#can-i-delete-or-hide-an-incident) are treated as deleted in Cortex and won't appear in your catalog or contribute to Scorecards.

#### Searching across and filtering the incident list

There are several ways to search and filter the list:

* To find specific incidents, use the search bar in the upper-right corner of the page and type to search.
* By default, the list sorts by most recently opened incident. Click **Opened** to reverse the order, or click **Name** to sort alphabetically instead.
* Click **Filter** to narrow down your list by date range, severity level, or status.

### Incidents on an entity's details page

View incidents in the following places on an entity's details page:

* On the **Overview** tab; active incidents are prominently displayed at the top of the page

  ![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incidents-overview.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=47597d54e017259b6923ed5d2cb541c2)
* In the left details sidebar, locate **Connections**, then select **Incidents**

  ![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incidents-side-panel.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=d81efeab515878e496af6c2a8c1ecda7)

## Viewing on-call information

### **On-call shift data**

View all on-call shifts ingested via the incident.io integration in a single place. This allows you to see exactly what data Cortex has brought in from the integration and what entities it's been linked to within Cortex.

**To access the on-call list**:

1. From the main sidebar, expand **Integrations**, then select **Data**.
2. Select the **On-call shifts** tab.
3. Do one of the following:
   * Select the **All** tab to view all on-call shifts in your workspace.
   * Select the **Mine** tab to view only your on-call shifts.

The list is sorted alphabetically by schedule name. Click a row to open a side panel showing who's on call now, who's on call next, and the teams the schedule is associated with.

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incident-on-call-tab.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=d05a263f674f93fd29034b6c1fe71bf9)

#### **Searching across and sorting the on-call list**

To search and sort the list:

* Use the search bar in the upper-right corner of the page and type to search.
* By default, the list sorts alphabetically by schedule name. Click **Name** to sort from Z to A.

### On-call on an entity's details page

View current on-call information in the following places on an entity's details page:

* In the metadata sidebar in the **On-call now** block

  ![](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/oncall-block.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=143d3323e83228e4fd2ca4446c66c567)
* In the left details sidebar, locate **Connections**, then select **On-call**
  * Click a row to open a side panel showing who's on call now, who's on call next, and the teams the schedule is associated with.

    ![](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/oncall-sed.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=996fb23cb37999c18d3b5ef75c390e1e)

### Engineering homepage

View upcoming on-call rotations in the **My on-calls** block on your engineering homepage. Cortex shows on-call schedules up to six months out.

![](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/homepage-oncalls.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=891e6100fa27f48736a6b006120304fc)

## Creating Scorecard rules with incident.io data

### Incident expressions

CQL lets you write rules and queries against incident data. See the [CQL documentation](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Integrations\&path=incident.io) for the complete list of available incident expressions.

> [!NOTE]
>
> Create Scorecard rules using incident-based CQL expressions to track operational health. Common Scorecard rules built on incident data include:
>
> * Ensure services have had no critical incidents in the past 30 days.
> * Verify mean time to resolution meets your SLOs.
> * Check that all production services have on-call schedules configured.

### On-call expressions

CQL lets you write rules and queries against on-call data. See the [CQL documentation](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Integrations\&path=incident.io\&path=On-call) for the complete list of available on-call expressions.

> [!NOTE]
>
> Create Scorecard rules using on-call based CQL expressions to track operational readiness, for example:
>
> * Verify that all production services have an on-call schedule configured
> * Ensure critical services have on-call coverage before go-live

## Incident metrics in Eng Intelligence

Incident metrics in [Eng Intelligence](/improve/eng-intelligence) are powered by the same unified data pipeline as the incident list, so the numbers stay consistent across Cortex. Eng Intelligence supports the following incident metrics:

* Incident frequency
* Mean time to resolution (MTTR)

## Creating incidents with Workflows

Use the **Create incident** block to declare an incident.io incident from a [Workflow](/streamline/workflows). The block maps the new incident to a Cortex entity and attaches that entity's registered custom fields, so every incident starts with the right context. For example, you can add the block to an incident response or rollback Workflow, or use it to standardize how your teams create incidents.

For the block's inputs and requirements, see the incident.io section in [Adding blocks to a Workflow](/streamline/workflows/blocks#incident-io).

## Syncing data from incident.io

Cortex syncs data from incident.io as follows:

* Schedule data is synced every hour
* Incident data is synced every 15 minutes

## Viewing incident.io integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

> **I connected incident.io but no on-call data appears on my entity**
>
> On-call requires an explicit registration. Confirm the entity has a `SCHEDULE` or `TEAM` registration, either on the entity's details page or in the entity descriptor, and that the ID matches the one in incident.io.

> **I registered a team but see no schedules**
>
> A `TEAM` registration maps every schedule whose team field matches that team in incident.io. If the team has no schedules attached, nothing maps. Register the schedule directly instead.

> **An incident exists in incident.io but doesn't appear in Cortex**
>
> Incidents marked as declined, merged, or canceled are treated as deleted in Cortex. Check the incident's status in incident.io first. If the status looks right, confirm the custom field value on the incident matches the entity's name or identifier.


# Instana
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/instana



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

[IBM Instana Observability](https://www.ibm.com/products/instana) is a tool used for monitoring and performance management. Integrate Instana with Cortex allows you to pull in services from Instana.

## How to configure Instana with Cortex

### Prerequisite

Before getting started, [create an API token in Instana](https://www.ibm.com/docs/en/instana-observability/current?topic=api-authenticating-instana-rest).

### Configure the integration in Cortex

1. In Cortex, navigate to the [Instana settings page](https://app.getcortexapp.com/admin/integrations/instana):
   1. Click **Integrations** from the main nav. Search for and select **Instana**.
2. Click **Add configuration**.
3. Configure the Instana integration form:
   * **Tenant endpoint**: Enter your tenant endpoint. This can be found in your Instana app URL.
   * **API token**: Enter the API token you generated in Instana.
4. Click **Save**.

## How to connect Cortex entities to Instana

### Import services from Instana

Cortex automatically syncs from Instana APM at 7 a.m. UTC.

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#creating-services) for instructions on importing entities.

### Import Instana services from Discovery audit

Cortex will pull recent changes from Instana into the [discovered entities list](/ingesting-data-into-cortex/entities-overview/entities/discovery-audit). Here, you can find new entities in Instana that have not been imported into the catalog.

## View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Jenkins
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/jenkins



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Jenkins](https://www.jenkins.io/) is an open source automation server which enables developers to build, test, and deploy software.

Integrating Jenkins with Cortex allows you to:

* Send information about Jenkins deploys into Cortex
  * This data appears on [entity detail pages](/ingesting-data-into-cortex/integrations/jenkins#view-jenkins-deploys-on-entity-pages-in-cortex).
* Use [Cortex Workflows to kick off a Jenkins pipeline](/ingesting-data-into-cortex/integrations/jenkins#kick-off-a-jenkins-pipeline-in-a-cortex-workflow)
* See [deploy data for Jenkins in Eng Intelligence](/ingesting-data-into-cortex/integrations/jenkins#see-jenkins-data-in-eng-intelligence)

## How to integrate Jenkins with Cortex

### Prerequisites

Before getting started:

* Create a [Jenkins API key](https://www.jenkins.io/doc/book/system-administration/authenticating-scripted-clients/).
  * Note: This is only necessary if you plan to use Jenkins blocks in Cortex Workflows.

### Step 1: Install the Cortex Deployer app

This integration uses the Cortex Deployer app, an open-source app that makes it easier for teams to push information about deploys to Cortex. This app leverages Cortex's [deploy REST endpoint](/api/rest/deploys).

* Install the [Cortex Deployer app](https://github.com/cortexapps/solutions/tree/master/tools/deploy).

### Step 2: Add a step to your Jenkins pipeline

#### Jenkins secrets

To use the Cortex Deployer app, you will need the `x-cortex-tag` and a Cortex API token. In the example below, both are defined as [Jenkins secrets](https://www.jenkins.io/doc/developer/security/secrets/).

#### Jenkinsfile

To push information to Cortex about a deploy event, add a step to your Jenkins pipeline. Below is a snippet of what a Jenkinsfile may look like.

```
pipeline {
    agent any
    environment 
    stages {
        stage('update-cortex') { 
            steps {
                sh "docker run cortexapp/deployer:0.2 -i \"Jenkins deploy\" -k $CORTEX_API_TOKEN -s $GIT_COMMIT -t DEPLOY -e Prod -c '' -g $CORTEX_TAG" 
            }
        }
    }
}
```

For more details about the options passed to the Docker image, please refer to the [Deployer repository](https://github.com/cortexapps/solutions/tree/master/tools/deploy).

### Step 3: Configure Jenkins in Cortex to enable Jenkins Workflow blocks

If you plan to use Jenkins blocks in Cortex Workflows, you will need to configure Jenkins in your Cortex workspace:

1. In Cortex, navigate to the [Jenkins settings page](https://app.getcortexapp.com/admin/integrations/jenkins):
   * Click **Integrations** from the main nav. Search for and select **Jenkins**.
2. Click **+Add configuration**.
3. Configure the integration form:
   * **Alias**: Enter an alias for the integration.
   * **Username**: Enter your Jenkins username.
   * **API key**: Enter your Jenkins API key.
   * **Host**: Enter the base URL of your Jenkins instance.
4. Click **Save**.

## Using the Jenkins integration

### View Jenkins deploys on entity pages in Cortex

After you configure the integration, you will see data about Jenkins deploys in an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details):

* On the entity overview, Jenkins deploys will appear under the **Latest events** section.
* In the entity's sidebar, click **Events** to see a full list of events for the entity, including deploy events from Jenkins.
* In the entity's sidebar, click **CI/CD > Deploys** to see data from the [Cortex deploys API](/api/rest/deploys), including Jenkins deploys.

### Kick off a Jenkins pipeline in a Cortex Workflow

You can use a Workflow to kick off a Jenkins pipeline. See the [Jenkins Workflow guide](/guides/operational-readiness/jenkins-workflow) for more information.

### See Jenkins data in Eng Intelligence

Since the Jenkins integration uses Cortex's [deploys API endpoint](/api/rest/deploys), Jenkins data is included in Eng Intelligence deploy metrics. Learn more about [Eng Intelligence in the docs](/improve/eng-intelligence).

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Jira
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/jira



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Jira](https://www.atlassian.com/software/jira/guides/getting-started/introduction) is a project management tool that helps developers track and manage bugs and work items.

By integrating Jira with Cortex, you can drive improvements and coordinate issue management across teams. Through the integration, you can create Jira work items directly in Cortex based on an Initiative's action items. The integration also allows you to enhance insights into a number of key values for your entities:

* Customer facing incidents
* Security tickets
* Ongoing projects

## How to configure Jira with Cortex

It is possible to configure the integration with a Jira Cloud instance or a self-hosted Jira instance (using either basic auth or OAuth). You can also use Cortex Axon Relay to securely integrate your on-premises data. Expand the tabs below for instructions on each option.

> **Jira Cloud**
>
> **Jira Cloud**
>
> **Prerequisites**
>
> Before configuring Cortex with Jira Cloud:
>
> * Create a [Jira API token](https://id.atlassian.com/manage-profile/security/api-tokens). To generate a token, you must have the `Browse users and groups` permissions in Jira and access to the needed Jira projects.
> * If you are using a scoped token, you will need your [Atlassian Cloud ID](https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/). Scoped tokens must include the following scopes:
>   * Read: `jira-work`, `jira-user`, `project-category:jira`, `project:jira`, `project-version:jira`, `project.property:jira`, `project.component:jira`, `issue-type:jira`, `issue-type-hierarchy:jira`, `user:jira`, `avatar:jira`, `project.avatar:jira`, `application-role:jira`, `group:jira`
>   * Write: `jira-work`
>
> **Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Jira settings page](https://app.getcortexapp.com/admin/integrations/jira):
>    * Click **Integrations** from the main nav. Search for and select **Jira**.
> 2. Click **Add configuration**. then select **Cloud** for the integration type.
>    * If you are using a scoped token, select **Cloud (scoped token)**.
> 3. In the Jira integration modal, "Jira Cloud" is selected by default in the upper right corner. Configure the integration form:
>    * **Account alias**: Enter an alias for your account.
>    * **Subdomain**: Enter the subdomain for your Jira instance.
>      * For example, this field would take `cortex-docs` from `https://cortex-docs.atlassian.net`.
>    * **Base URL**: This field automatically populates `atlassian.net`.
>      * If you are using a legacy Jira Cloud instance (i.e., you access your Jira instance on `jira.com`), change the base URL from the dropdown.
>    * **Email**: Enter the email address associated with the user who generated the token in Jira.
>      * Note: The email address associated with a given Jira token **must** match the email address of the user associated with that token.
>    * **API token**: Enter your Jira API token.
> 4. Click **Save**.

> **On-prem (Basic)**
>
> **Jira on-prem (Basic)**
>
> **Prerequisite**
>
> If you're using a self-hosted instance of Jira, you'll need to verify that your Cortex instance is able to reach the Jira instance.
>
> We route our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Jira instance.
>
> **Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Jira settings page](https://app.getcortexapp.com/admin/settings/jira):
>    1. In Cortex, click your avatar in the lower left corner, then click **Settings**.
>    2. Under "Integrations," click **Jira**.
> 2. Click **Add configuration**.
> 3. In the upper right corner of the Jira integration modal, click the dropdown labeled `Cloud`. Select `On-prem (basic auth)`.
> 4. Configure the Jira integration form:
>    * **Account alias**: Enter an alias for your account.
>    * **Host**: Enter the URL for your Jira on-premises host.
>    * **Frontend host**: Enter the URL for your Jira on-premises frontend host.
>    * **Username** and **Password**: Enter your Jira username and password.
> 5. Click **Save**.

> **On-prem (OAuth)**
>
> **Jira on-prem (OAuth)**
>
> **Prerequisites**
>
> To integrate Cortex with Jira using OAuth, you must be running a self-hosted Jira instance with Jira server version 8.22 or higher.
>
> If you're using a self-hosted instance of Jira, you'll need to verify that your Cortex instance is able to reach the Jira instance.
>
> We route our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Jira instance.
>
> **Step 1: Create an application link from Jira**
>
> 1. In your Jira server, navigate to Settings > Applications > Application Links. Click **Create link**.
> 2. Configure the application link settings:
>    * **Application type**: Select `External`.
>    * **Direction**: Select `Incoming`.
>    * **Redirect URL**: For default configuration, enter the URL of your Cortex instance appended with `/oauth/internal/jira`. For a non-default configuration, enter the URL of your Cortex instance appended with `/oauth/internal/jira/`.
>    * **Permission**: Select `write`.
> 3. Click **Save**.
> 4. The application link will have an associated client ID and client secret. Copy these values and store them in a secure location, as you will need them in the next steps.
>
> **Step 2: Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Jira settings page](https://app.getcortexapp.com/admin/settings/jira):
>    1. In Cortex, click your avatar in the lower left corner, then click **Settings**.
>    2. Under "Integrations," click **Jira**.
> 2. Click **Add configuration**.
> 3. In the upper right corner of the Jira integration modal, click the dropdown labeled `Cloud`. Select `On-prem (OAuth)`.
> 4. Configure the Jira integration form:
>    * **Account alias**: Enter an alias for your account.
>    * **Host**: Enter the URL for your Jira on-premises host.
>    * **Frontend host**: Enter the URL for your Jira on-premises frontend host.
>    * **Client ID** and **Client secret**: Enter the client ID and secret associated with the application link you created in the previous steps.
> 5. Click **Save**.
> 6. You will be redirected to the Jira settings page. Click **Install** next to your integration name.
>    * A confirmation modal will appear, asking you to allow Cortex access to your Jira account.
>    * The accessing user can be a user persona or a system account. We recommend using a system account to maintain your organization's access in case the user who set up the integration leaves your organization.

> **Axon Relay**
>
> **Configure Jira with Cortex Axon Relay**
>
> See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for instructions.

**Configure the integration for multiple Jira accounts**

The Jira integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Jira page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.

## Set a default JQL query for your Jira integration

You can set a custom JQL query for your [Jira integration instances](/ingesting-data-into-cortex/integrations/jira#tenant-level) and for [individual entities](/ingesting-data-into-cortex/integrations/jira#entity-level). This allows you to filter which Jira work items are surfaced on entity pages or in other places in Cortex where CQL is used.

The default JQL applies to `jira.issues()` and `jira.numOfIssues()` but not to `jira.rawJql()`.

> [!WARNING]
>
> Note that if you define additional filter logic for your default JQL query when writing a Scorecard rule, you must add that logic in a filter clause. See [Adding filter logic to the default JQL query in a Scorecard](/ingesting-data-into-cortex/integrations/jira#adding-filter-logic-to-the-default-jql-query-in-a-scorecard) for more information.

> **Tenant level**
>
> **Set default JQL query at a tenant level**
>
> From the [Jira settings page](https://app.getcortexapp.com/admin/settings/jira) in Cortex, you can set a custom JQL query for your Jira integration.
>
> When Cortex queries for Jira work items, the `statusCategory` is directly grabbed from the [API response](https://docs.atlassian.com/DAC/javadoc/jira/reference/com/atlassian/jira/issue/status/category/StatusCategory.html).
>
> The default query — `statusCategory in ("To Do", "In Progress")` — will filter your Jira tickets to display only those with `To Do` and `In Progress` statuses, excluding closed tickets. The `indeterminate` status category will map to `In Progress` according to the API. Cortex does not use the `status` field for mapping these categories.
>
> Entering a custom JQL query on the Jira integration settings page allows you to override the default for all entities in your workspace. To map work items with a custom status, you can write a custom JQL query that uses `status` instead of `statusCategory`.

> **Entity level**
>
> **Set default JQL query at entity level**
>
> > [!NOTE]
> >
> > The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).
>
> You can configure default JQL for entities in their [entity YAML](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file). For example:
>
> ```yaml theme={null}
> x-cortex-issues:
>     jira:
>       projects:
>       - name: PROJECT_A
>         alias: Jira Project A
>       defaultJql: "project = project_a"
> ```
>
> > [!NOTE]
> >
> > Entity-level default JQL is not applied to project management metrics in Data Explorer. To filter those metrics, use the available filters in the Data Explorer UI.

### Fallback logic for default JQL

It is possible to set custom JQL at both the entity and tenant level, but note the fallback logic:

1. If any JQL is passed into a query, Cortex uses that.
2. If not, Cortex uses entity-level default JQL.
3. If not, Cortex uses tenant-wide default JQL.
4. If none, then no JQL is used for filtering.

### Adding filter logic to the default JQL query in a Scorecard

The CQL statement will use the default JQL setting in a Scorecard rule only if you do not define additional filter logic. Any filter logic applied to the statement will override the default JQL query.

To work around this: If you need to include additional filter logic on your query in a Scorecard, you can move the filter logic to the filter clause.

For example, if your default JQL query is set to `"project = project_a"`, then you can add `jira.issues()` to a Scorecard rule to automatically surface only the work items relating to Project A. However, you cannot use `jira.issues(some_other_filter_logic)` in a Scorecard; Cortex will not append your default JQL to the additional filter logic.

In this example, the workaround would be to add a filter clause:\

`jira.issues().filter(some_other_filter_logic)`.

## How to connect Cortex entities to Jira labels, components, or projects

### Discovery

By default, Cortex will tie Jira tickets to entities by searching for any tickets where the `label`, `component`, or `project` field for the work item includes the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag). For example, if your Cortex tag is “my-entity,” then the corresponding tickets in Jira should have “my-entity” as a label, component, or project.

If your Jira label/component/project doesn't cleanly match the Cortex tag, you can override this in the Cortex [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file).

Without an override, a ticket's label, component, or project must **exactly match** the Cortex tag in the descriptor.

### Connecting via YAML or the Cortex UI

> **Cortex UI**
>
> **Connect Jira entities via the Cortex UI**
>
> 1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details) in Cortex.
> 2. In the upper right corner, click **Configure entity**.
>
>    ![In the upper right side of an entity, click 'Configure entity.'](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/configure-entity-team.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=51dcaf582d93349b8f5ac706ee913e5c)
> 3. Click the **Project management** tab, then click **+Add**.
>
>    ![Click Project management, then click Add.](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/jira-ui.jpg?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=8c731f365a4943855976c7476f6ec5a3)
> 4. In the side panel, configure the details:
>    * **Jira service type**: Choose component, label, or project.
>    * **Alias**: If you have multiple Jira configurations, select which one this service is associated with.
>    * **Name**: Enter the name of the service.
> 5. At the bottom of the side panel, click **Add**.

> **Entity YAML**
>
> **Editing the entity descriptor**
>
> If you need to override automatic discovery, you can define `x-cortex-issues` blocks in your Cortex entity descriptor.
>
> Note: For all of the following, `alias` is optional, and the default Jira configuration will be used if not provided. You can use Jira `labels`, `components`, or `projects` to match entities.
>
> Each of these blocks has the same field definitions.
>
> | Field | Description | Required |
> | - | - | :-: |
> | `name` | Label name in Jira | **✓** |
> | `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |
>
> ```yaml theme={null}
> x-cortex-issues:
>   jira:
>     labels:
>       - name: labelA
>         alias: alias1
>       - name: labelB
> ```
>
> ```yaml theme={null}
> x-cortex-issues:
>   jira:
>     components:
>       - name: component1
>         alias: alias1
> ```
>
> ```yaml theme={null}
> x-cortex-issues:
>   jira:
>     projects:
>       - name: project1
>         alias: alias1
> ```
>
> ```yaml theme={null}
> x-cortex-issues:
>   jira:
>     labels:
>       - name: label1
>       - name: label2
>       - name: label3
>     components:
>       - name: component1
>       - name: component2
> ```
>
> By default, Cortex will surface outstanding issues per entity in the catalog with a default [JQL](https://www.atlassian.com/blog/jira-software/jql-the-most-flexible-way-to-search-jira-14) query: `statusCategory in ("To Do", "In Progress")`. If you'd like to override this, you can provide a new default query with:
>
> ```yaml theme={null}
> x-cortex-issues:
>   jira:
>     defaultJql: 'status = "In Progress"'
> ```

### Identity mappings

Cortex maps Jira accounts to team members defined in the team catalog, so you do not need to define Jira users in a team member's YAML file.

You can confirm that users' Jira accounts are connected from the [Jira user mappings section in Settings](https://app.getcortexapp.com/admin/settings/jira-mappings).

## Using the Jira integration

#### Entity pages

Once the integration is established, you'll be able to pull in data about the work items in any linked Jira instances for a given entity:

* **Number of issues:** Unresolved issues associated with an entity that have the JQL status "in progress" or "to do"
* **Number of issues from JQL query:** Issues associated with an entity that match an arbitrary JQL query

Cortex will tie Jira tickets directly to entities within the catalog. Click **Issue tracking** in the entity's sidebar to see associated Jira tickets.

From this tab you can find a list of all issues with a label that matches the Cortex tag.

* **Key:** The issue key (or "ticket number") for a Jira work item.
* **Issue summary:** Title of the Jira work item and the user designated as the issue reporter.
* **Assignee:** User designated as the work item assignee.
* **Priority:** The work item's priority level in Jira - Lowest, Low, Medium, High, Highest. This will display with the [icon](https://support.atlassian.com/jira-service-management-cloud/docs/what-are-priority-levels-in-jira-service-management/) that corresponds to the priority level in your Jira instance.
* **Created:** Date the work item was created.
* **Due:** Due date for the work item, if applicable.

This list will also be available from a team's homepage when the team's Cortex tag matches a `label`, `component`, or `project` in Jira.

#### Initiatives

Initiatives allow you to set deadlines for specific rules or a set of rules in a given Scorecard and send notifications to users about upcoming due dates.

From the Issues tab of an Initiative, you can automatically create a Jira ticket from a failing rule.

Read about creating Jira issues from Initiatives in the documentation: [Creating issues based on initiatives](/improve/initiatives/issue-config).

#### Dev homepage

The Jira integration enables Cortex to pull information about issues into the [dev homepage](/streamline/homepage). You can find open work items assigned to you under the [Issues tab](https://app.getcortexapp.com/admin/home?activeTab=Issues). The work items that display will depend both on the Jira instances you've connected and the JQL query defined in Settings.

Work items are refreshed every 5 minutes. You can use the **Refresh work items** button to manually refresh issues at any point.

### Scorecards and CQL

With the Jira integration, you can create Scorecard rules and write CQL queries based on Jira work items.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Issues**
>
> Number of **unresolved** issues associated with the entity, where unresolved is defined as the JQL status = "Open" OR status = "To Do".
>
> **Definition:** `jira.numOfIssues()`
>
> **Example**
>
> For a Scorecard measuring entity maturity, you can use this expression to make sure entities have fewer than 3 Jira issues:
>
> ```
> jira.numOfIssues() <= 10
> ```

> **Issues from JQL query**
>
> Number of issues associated with the entity based on arbitrary JQL query.
>
> **Definition:** `jira.numOfIssues(jqlQuery: Text | Null)`
>
> **Example**
>
> For a more specific rule in an entity maturity Scorecard, you can use this expression with a JQL query to make sure entities have no more than 3 open customer-facing tickets.
>
> ```
> jira.numOfIssues("status = \"Open\" and labels = \"customer-facing\"") <= 3
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

The [engineering homepage](/streamline/homepage) runs a background job every 5 minutes to refresh the Issues tab.

## Troubleshooting and FAQ

See frequently asked questions below.

> **I've added a Jira integration, but I'm not sure what JQL is being generated to query Jira.**
>
> When running Scorecard rules, Cortex appends `AND (component = cortex-tag OR labels = cortex-tag OR project = cortex-tag)` to the [JQL you defined](/ingesting-data-into-cortex/integrations/jira#jira-default-jql), where `cortex-tag` is the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag).

> **My Scorecard rules are failing, even though there are tickets in my Jira instance.**
>
> Make sure that the ticket has a label, component, or project that matches **exactly** with the Cortex tag or the list defined in your entity descriptor.

> **I received this error: 'Configuration error: Integration error for Jira - Unexpected HTTP response 0'.**
>
> When using Jira Cloud, you'll need to create a Jira API token and add it on in Jira Settings in Cortex. The email address in Settings **must be the same as the user that the token is associated with**. Cortex also expects only the subdomain of your Jira instance, not the entire URL.

> **I received this error: 'Configuration error: Jira - Unexpected HTTP response 403: Forbidden'.**
>
> 1. Make sure that the entity name in Cortex matches the label, component, or project name in Jira.
> 2. Make sure the subdomain and base URL correspond with the Jira instance you're trying to connect.
> 3. Verify that the Jira token you added is still valid. You can run the following [curl command](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/#supply-basic-auth-headers) to confirm:
>
> ```
>   curl -D- \
>   -X GET \
>   -H "Authorization: Basic {{your-token}}" \
>   -H "Content-Type: application/json" \
>   "https://{{your-domain}}.atlassian.net/rest/api/2/issue/{{valid-ticket-number}}"
> ```

> **I configured the integration, but I am not seeing Work Items populate.**
>
> The background job fetches work items every 5 minutes. However, a fresh integration configuration may result in longer waiting times, as it also fetches historical data.


# Kubernetes
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Why use the integration for Kubernetes

Kubernetes (K8s) is a container orchestration system that automates software deployment, scaling, and management. The Cortex Kubernetes agent is a lightweight agent that collects information from your cluster and surfaces it in your Cortex workspace's catalog, Scorecards, and more.

Integrating Kubernetes with Cortex allows you to:

* Discover and import entities directly from Kubernetes clusters, which keeps the catalog in sync with what's actually running in production. See [Connecting entities to Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes).
* View Kubernetes data on entity pages, which gives you visibility into your infrastructure and how entities are deployed. See [Viewing Kubernetes data on entity pages](/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes#view-kubernetes-data-on-entity-pages).
* Create Scorecards to track progress, drive alignment on projects relating to Kubernetes, and enforce Kubernetes best practices. See [Scorecards and CQL](/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes#scorecards-and-cql).

## Supported Kubernetes entity types

The k8s agent collects the following Kubernetes workload types:

* Deployments
* StatefulSets
* Argo Rollouts
* CronJobs

## Configuring Kubernetes

### Prerequisites

1. Users with the `Configure Integrations` permission can configure Kubernetes in Cortex.
2. Reach out to the [Cortex Customer Engineering team](mailto:help@cortex.io) for the Helm chart used for deployment, and for a username and password.
3. Generate an [API key](/configure/settings/api-keys#create-api-key) in Cortex. Ensure the key has the `User` (edit catalog entities) role at a minimum. Alternatively, you can also create the API key programmatically with the [Cortex API](/api/rest/api-keys).

### Security considerations

The k8s agent uses a push model, so you don't need to expose your cluster to the public internet. Communication out of the cluster to Cortex happens over HTTPS, and there is no inbound traffic to the agent.

The Helm chart also comes with a predefined ClusterRole that provides the correct role-based access controls (RBACs):

* **Permissions** - `["get", "watch", "list"]`
* **Resources** - `["deployments", "services", "pods", "replicationcontrollers", "statefulsets", "rollouts", "cronjobs"]`
* **API groups** - `["apps", "argoproj.io", "batch"]`

### Installing the Cortex k8s agent in your Kubernetes cluster

To connect Cortex to your Kubernetes instance, install the k8s agent in your cluster. The agent is lightweight and adds negligible impact.

1. Create a Docker image pull secret:

   ```
   kubectl create secret docker-registry cortex-docker-registry-secret 
   --docker-server=ghcr.io 
   --docker-username={provided by Cortex} 
   --docker-password={token provided to you by the Cortex team} 
   --docker-email={email address}
   ```
2. Run the following command, replacing `your API key` with the value of your Cortex API key, to create a secret in your cluster:

   ```
   kubectl create secret generic cortex-key --from-literal api-key=<your API key>
   ```
3. Install the Helm chart provided by Cortex:

   ```
   helm install <a name to assign to the installed helm chart> ./helm-chart
   ```

> [!NOTE]
>
> **Running more than one agent?** \\
>
> Set `app.clusterName` to a unique value for each agent you install. Agents that share a cluster name conflict with each other, which can cause intermittent 409 errors and make Kubernetes data disappear from entity pages.
>
> ```
> helm install <a name to assign to the installed helm chart> ./helm-chart --set app.clusterName=<a unique name for this cluster>
> ```
>
> You need a unique `app.clusterName` any time more than one agent reports to the same Cortex account, including when an agent is deployed inside a parent Argo environment or when you run an agent in each of several clusters.
>
> The value you set here is the value Cortex uses for the `cluster` field when you map Kubernetes resources to entities in an entity descriptor. For more information, refer to [Mapping resources in the YAML](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes#mapping-resources-in-the-yaml).


# Connecting entities to Kubernetes
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes



This article explains how entities in Cortex get associated with Kubernetes resources. For configuration instructions, see [Configuring the integration for Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes). For instructions on using the integration, see [Using the integration for Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes).

## Discovery

By default, Cortex uses the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) as a best guess for the Kubernetes resource. For example, if your Cortex tag is `my-entity`, the corresponding resource in Kubernetes should also be `my-entity`.

If your Kubernetes resources don't cleanly match the Cortex tag, you can override this behavior.

### Methods for mapping Kubernetes resources

There are three ways to map Kubernetes resources to Cortex entities:

| Method | Use case | What you do |
| - | - | - |
| [Annotation-based mapping](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes#annotation-based-mapping) | Entities that own their Kubernetes infrastructure. | Add a `cortex.io/tag` annotation to the Kubernetes resource. This is the default behavior. |
| [Label-based auto-mapping](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes#label-based-auto-mapping) | Shared infrastructure, or entities managed outside your team. | Specify a list of metadata label keys on the Kubernetes settings page in Cortex. |
| [Mapping in the YAML](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes#mapping-resources-in-the-entity-descriptor) | Complex or legacy workloads. | Add the resource to the YAML by hand. |

#### Annotation-based mapping

You can link a Kubernetes deployment to a Cortex entity by adding an annotation to the deployment's metadata. By default, Cortex maps Kubernetes deployments with a `cortex.io/tag` annotation to Cortex entities with the same tag.

Use `cortex.io/tag` as the key, and the value of `x-cortex-tag` in the entity's cortex.yaml as the value.

For example, if the `cortex.yaml` file is:

```yaml theme={null}
openapi: 3.0.1
info:
  title: My Service
  x-cortex-tag: my-service
  x-cortex-type: service
  description: This is my cool service.
```

Then the `deployment.yaml` file should be configured as:

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-name
  namespace: my-namespace
  annotations:
    cortex.io/tag: my-service
```

Cortex reads the top-level metadata annotations on the Deployment object itself (`metadata.annotations`), not the pod template annotations (`spec.template.metadata.annotations`).

**Customizing annotation mapping**

You can customize annotation mapping in Cortex:

1. From the main sidebar, select **Integrations**.
2. Locate Kubernetes, then click **Settings**.
3. From the **Integration settings** tab, locate the **K8s annotation mapping customization** section.
4. Enter a `jq` mapping in the annotation mapping field.
5. Click **Save mapping**.

If auto-mapping isn't working as expected, confirm that the annotation mapping is at the default absolute path of `.metadata.annotations."cortex.io/tag"`. If it isn't, update the annotation mapping on the Kubernetes settings page to match the exact absolute path of the Cortex tag.

**Example**

Say your `deployment.yaml` includes `my.service` as the `cortex.io/tag`:

```yaml theme={null}
metadata:
  name: my-name
  namespace: my-namespace
  annotations:
    cortex.io/tag: my.service
```

If this deployment should map to a Cortex entity with the tag `my-entity`, enter the following `jq` expression to convert all periods in the deployment annotation tag to dashes:

```
.metadata.annotations."cortex.io/tag" | gsub("\\."; "-")
```

### Label-based auto-mapping

You can override Cortex tag discovery and have Cortex discover Kubernetes resources by their metadata labels instead:

1. From the main sidebar, select **Integrations**.
2. Locate Kubernetes, then click **Settings**.
3. From the **Integration settings** tab, locate the **K8s auto-mapping customization** section.
4. Enter a list of metadata label keys.
5. Click **Save**.

Once the list is saved, Cortex discovers all Kubernetes resources that meet both of the following criteria:

* The resource's spec metadata key contains any of the specified labels.
* The key values match a Cortex entity tag.

**Example**

Say you have two Cortex entities, `example` and `entity`, and the following Kubernetes JSON blob:

```
{
  "name": "Sample Kubernetes resource",
  "metadata": {
    "labels": {
      "app": "example",
      "another": "entity"
    }
  }
}
```

By default, `example` and `entity` have no Kubernetes resource mappings. If the list of metadata labels is set to `["app"]`, then the entity example is associated with "Sample Kubernetes resource." If the list is set to `["app", "another"]`, then both example and entity are associated with the resource.

### Mapping resources in the YAML

Cortex accepts several Kubernetes resource types, which can be on different clusters: Deployments, Argo Rollouts, StatefulSets, and CronJobs.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

All of these resource types share the same field definitions:

| Field | Description | Required? |
| - | - | - |
| `identifier` | `namespace/name` as found in Kubernetes. | |
| `cluster` | The name of the cluster, set with the `app.clusterName` Helm value when you deploy the agent. If you run more than one agent, each one needs a unique cluster name. For more information, refer to [Installing the Cortex k8s agent in your Kubernetes cluster](/ingesting-data-into-cortex/integrations/kubernetes#installing-the-cortex-k8s-agent-in-your-kubernetes-cluster). | |

**Argo Rollouts**

```yaml theme={null}
x-cortex-k8s:
  argorollout:
    - identifier: namespace/name
      cluster: dev
```

**StatefulSets**

```yaml theme={null}
x-cortex-k8s:
  statefulset:
    - identifier: namespace/name
      cluster: dev
```

**CronJobs**

```yaml theme={null}
x-cortex-k8s:
  cronjob:
    - identifier: namespace/name
      cluster: dev
```

### Importing entities from Kubernetes

For instructions on manually importing entities, see [Adding services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services).


# Using the integration for Kubernetes
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes



This article explains how to use the integration for Kubernetes. For configuration instructions, see [Configuring the integration for Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes). For instructions on connecting Kubernetes resources to entities, see [Connecting entities to Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes).

## Viewing Kubernetes data on entity pages

Kubernetes deployment data is available in the Kubernetes block on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details) for entities imported from Kubernetes or linked to a Kubernetes resource.

In the entity's side panel, click Environments to see Kubernetes deployments, clusters, active replicas, and pending deployments, as well as:

* **Replicas** - The number of available, ready, and desired replicas.
* **Containers** - Resource containers, including requested memory, memory limit, and CPU data. This also includes the full container definition.

## Creating Scorecard rules and writing CQL queries with the Kubernetes integration

With the Kubernetes integration, you can create Scorecard rules and write Cortex Query Language (CQL) queries based on Kubernetes resources. For an example, see Cortex's prebuilt [Kubernetes Deployment Baseline Scorecard](/guides/migrations-and-modernization/accelerate-migration-to-k8s#create-a-kubernetes-scorecard) template.

See more rule examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Cluster information**
>
> Data about k8s clusters associated with a given entity.
>
> **Definition** - `k8s.clusters()`
>
> **Examples**
>
> You can use the `k8s.clusters()` expression in the Query Builder to find all clusters that start with "dev":
>
> ```
> k8s.clusters.all((cluster) => cluster.name.matches("""dev-.*"""))
> ```
>
> Or any cluster named "prod":
>
> ```
> k8s.clusters.any((cluster) => cluster.name.matches("prod"))
> ```

> **Deployment labels**
>
> Checks deployment metadata.
>
> **Definition** - `k8s.metadata()`
>
> **Examples**
>
> You can use this expression in a production readiness Scorecard to check ownership:
>
> ```
> k8s.metadata().labels.any((label) => label.get("ownership") == "ownership_team")
> ```
>
> This rule checks an entity's metadata labels for the ownership annotation and will pass if "ownership\_team" is defined.
>
> You can also use this expression in the Query Builder to find all k8s deployments with the label "environment":
>
> ```
> k8s.metadata().labels.all((label) => label.containsKey("environment")) == true
> ```
>
> Or you could refine the query further to find k8s deployments with an "environment" label and that are in production:
>
> ```
> k8s.metadata().labels.all((label) => label.get("environment")?.matches("prod")") == true
> ```

> **K8s resource is set for entity**
>
> Checks whether a k8s resource of any type is associated with an entity.
>
> **Definition** - `k8s != null`
>
> **Example**
>
> For a Scorecard focused on automation or development maturity, you can set a rule to make sure a k8s resource is mapped:
>
> ```
> k8s != null
> ```

> **Kubernetes spec YAML**
>
> The Cortex k8s agent periodically sends the raw spec definitions for all entities. The spec JSON is equivalent to the **root spec field** of the entity descriptor (deployments, StatefulSet, etc.) and fully conforms to that format.
>
> You can find the official documentation for these resource objects in the [Kubernetes Workload Docs](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/).
>
> You can use this list of JSON specs combined with JQ or [Open Policy Agent (OPA) language](https://www.openpolicyagent.org/docs/v0.52.0/) to write complex assertions such as "all resources must have specific annotations set" or "all containers should have a CPU resource limit defined."
>
> The list of JSON specs can also be filtered to only ones in a specific cluster by specifying the cluster name: `k8s.spec("prod")`.
>
> **Definition:** `k8s.spec()`
>
> **Examples**
>
> You can use this expression to write a wide range of rules. For a best practices Scorecard, you can make sure that resource definitions have set CPU requests:
>
> ```
> jq(k8s.spec(), ".[].template.spec.containers[].resources.requests.cpu") != null
> ```
>
> Or that all resource definitions expose only TCP ports:
>
> ```
> jq(k8s.spec(), ".[].template.spec.containers[].ports[].protocol") == "TCP"
> ```

> **Replica information**
>
> Number of replicas available, current, desired, ready, unavailable, or updated.
>
> **Definition** - `k8s.replicas()`
>
> **Example**
>
> You can use this expression in a development maturity Scorecard to make sure an entity has at least two available instances:
>
> ```
> k8s.replicas().numAvailable >= 2
> ```

## Viewing Kubernetes integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

The Cortex k8s agent is a cron job that runs every five (5) minutes by default.

## Troubleshooting and FAQ

See frequently asked questions below.

> **When I try to import entities, I don't see all the supported workload types (deployments, ArgoCD rollout, StatefulSet, CronJob)**
>
> Make sure that the types you expected to see are in the cluster you are attempting to import.

> **Namespaces are missing from Kubernetes discovery**
>
> If you're using Cortex's k8s agent to import entities into Cortex but don't see all expected namespaces during the import process, make sure `app.namespace` is commented out in `values.yaml`:
>
> ```
> app:
>   # baseURL: 
>   baseURL:
>   keySecret:
>   # namespace: exampleNamespace
> ```
>
> If `app.namespace` is defined the Cortex k8s agent will only be able to discover services from that namespace. This behavior can be confirmed with a backend log similar to:
>
> ```
> INFO 1 --- [ scheduling-1] k8sagent : Looking for stateful sets in namespace 
> ```
>
> Once `app.namespace` is commented out, restart your pods. You will then be able to see all expected namespaces when importing new services.

> **Kubernetes data disappears from entity pages, or the agent logs 409 errors**
>
> This usually means two or more Cortex k8s agents are reporting under the same cluster name. Each agent overwrites the other's data, so Kubernetes information appears and disappears from entity pages, and the agent logs show intermittent 409 errors.
>
> Check whether you're running more than one agent. This is easy to miss when an agent is deployed inside a parent Argo environment, because the parent and child environments can each run one.
>
> To fix it, give every agent a unique cluster name. You can set it in `values.yaml`:
>
> ```
> app:
>   # baseURL: 
>   baseURL:
>   keySecret:
>   clusterName: my-cluster-name
> ```
>
> Or pass it at install time:
>
> ```
> helm install <a name to assign to the installed helm chart> ./helm-chart --set app.clusterName=<a unique name for this cluster>
> ```
>
> Restart the pods after you change the value. Keep in mind that changing a cluster name changes the value Cortex expects in the `cluster` field of any entity descriptor that maps resources from that cluster, so update those descriptors to match.

> **The agent is blocked after an upgrade because of the deprecated Docker registry**
>
> If your Cortex agent in Kubernetes clusters is blocked due to deprecation of Docker registry after an upgrade, you can make these direct edits using the same credentials:
>
> 1. **Access the image** from `ghcr.io` instead of `docker.pkg.github.com`.
>
>    ```
>    image: ghcr.io/cortexapps/k8s-agent...
>    ```
> 2. **Update the registry secret**, setting the server to `https://ghcr.io`.
>
> If you are unable to make these changes, please reach out to [help@cortex.io](mailto:help@cortex.io) and request a new Helm chart with this change already reflected.

> **The agent logs failing Argo Rollouts errors, but I don't use Argo Rollouts**
>
> When running the self-hosted Kubernetes agent successfully, users may see failing ArgoCD rollouts errors while not using this tool.
>
> ```
> Error polling argocd rollouts from Kubernetes API
>
> io.kubernets.client.openapi.ApiException:
> [...]
>   at com.brainera.k8sSDKClient.getArgoRollouts(k8sClient.kt:101) ~[app:/na]
> ```
>
> Cortex logs this exception for verbosity - this error is harmless if not using ArgoCD tool.

> **Can I deploy on prem if I don’t use Kubernetes?**
>
> Yes. The Cortex Helm chart deploys two Cortex-specific pods from images for the frontend and backend, as well as a data store. You can use these images to run Docker containers on other platforms, such as ECS.


# LaunchDarkly
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/launchdarkly



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[LaunchDarkly](https://launchdarkly.com/) is a feature flag management platform.

Integrating Cortex with LaunchDarkly allows you to:

* Track LaunchDarkly feature flags on entities in the catalog.
* Create [Scorecards](/standardize/scorecards) that track progress and drive alignment on projects involving your LaunchDarkly feature flags.
* Perform tasks relating to LaunchDarkly feature flags as a part of a [Workflow](/streamline/workflows).
  * For example, you can include a "Create feature flag" step within a Workflow.

## How to configure LaunchDarkly with Cortex

### Prerequisites

Before getting started, create a [LaunchDarkly access token](https://app.launchdarkly.com/settings/authorization) with:

* The `Writer` role
  * If you are not adding LaunchDarkly-related tasks to your [Workflows](/streamline/workflows), you can configure the token with the `Reader` role.
* `20220603` as the API version

### Configure the integration in Cortex

1. In Cortex, navigate to the [LaunchDarkly settings page](https://app.getcortexapp.com/admin/integrations/launchdarkly):
   * Click **Integrations** from the main nav. Search for and select **LaunchDarkly**.
2. Click **Add configuration**.
3. Configure the integration details:
   * **Account alias**: Enter the alias for this configuration.
   * **Access token**: Enter your LaunchDarkly access token.
   * **Environment**: Select your environment.
4. Click **Save**.

#### **Configure the integration for multiple LaunchDarkly accounts**

The LaunchDarkly integration has multi-account support. You can add a configuration for each additional organization, instance, or account by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated organization, instance, or account with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the LaunchDarkly page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.

## How to connect Cortex entities to LaunchDarkly

### Discovery

By default, Cortex will try to "best-guess" the corresponding project in LaunchDarkly based on the key or tags.

Cortex first looks up a LaunchDarkly project using the entity name (e.g. `My Service`), then the entity identifier (e.g. `my-service`). For example, if your entity name is “My Service”, then the corresponding LaunchDarkly project's key or tag should contain either “My Service” or "my-service".

If no project was matched, Cortex will try to "best-guess" feature flags from all available projects using feature flag tags.

### Editing the entity descriptor

You can find the project key and tags in LaunchDarkly under **Account settings > Projects**. The URL for the project will contain the key. For example: `https://app.launchdarkly.com/projects/default/settings/environments`.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

If you prefer to use the project tags in the registration instead, you can find it in the projects table or project settings page.

```yaml theme={null}
x-cortex-launch-darkly:
  projects:
    - key: project-key
      environments: # Optional
        - environmentName: prod
        - environmentName: staging
      alias: alias-1 # alias is optional and only relevant if you have opted into multi account support
    - tag: project-tag
      environments: # Optional
        - environmentName: prod
      alias: alias-2 # alias is optional and only relevant if you have opted into multi account support
  feature-flags:
    - tag: feature-flag-tag
      environments: # Optional
        - environmentName: staging
      alias: alias-3 # alias is optional and only relevant if you have opted into multi account support
```

## Using the LaunchDarkly integration

### Scorecards and CQL

With the LaunchDarkly integration, you can create Scorecard rules and write CQL queries based on LaunchDarkly projects.

See more examples in the [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if LaunchDarkly project is set**
>
> Check if entity has a registered LaunchDarkly project in its [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file). If no registration exists, we'll try to automatically detect which corresponding LaunchDarkly project is associated with the entity.
>
> **Definition**: `launchDarkly (==/!=) null`
>
> **Example**
>
> For example, you could write a rule in a Scorecard to check whether an entity has a LaunchDarkly project set:
>
> ```
> launchDarkly != null
> ```

> **Feature flags**
>
> List of flags
>
> **Definition**: `launchDarkly.flags()`
>
> **Example**
>
> In a Scorecard, you could write a rule to check whether an entity has fewer than 10 flags:
>
> ```
> launchDarkly.flags().length < 10
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## FAQs and troubleshooting

#### **How often does the integration poll for new flags?**

A scheduled job runs every 2 hours to check for new flags.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Lightstep
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/lightstep



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

### Overview

[ServiceNow Cloud Observability](https://www.servicenow.com/products/observability.html), formerly known as Lightstep, helps you detect changes in your logs, metrics, and traces. Integrate Lightstep with Cortex to drive insights into SLOs and latency and error rate metrics.

### How to configure Lightstep with Cortex

#### Prerequisite

Before getting started, create a [Lightstep API key](https://docs.lightstep.com/docs/create-and-manage-api-keys).

#### Configure the integration in Cortex

1. In Cortex, navigate to the [Lightstep settings page](https://app.getcortexapp.com/admin/integrations/lightstep):
   * Click **Integrations** from the main nav. Search for and select **Lightstep**.
2. Click **Add configuration**.
3. Configure the Lightstep integration form:
   * **Org ID**: Enter your Lightstep organization ID.
     * You can find this in your Lightstep project settings.
   * **Project ID**: Enter the Lightstep project ID.
     * You can find this in your Lightstep project URL, e.g., `https://app.lightstep.com/PROJECT_ID/project`
   * **API key**: Enter the API key you generated in Lightstep.
4. Click **Save**.

### Linking SLOs in Cortex

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can create and manage SLOs by listing relevant latency SLIs through [Streams](https://docs.lightstep.com/docs/monitor-a-service-level-indicator-with-streams). Cortex will pull data from Lightstep, and track against your specified SLO. For example:

```yaml theme={null}
x-cortex-slos:
  lightstep:
    - streamId: sc4jmdXT
      targets:
        latency:
          - percentile: 0.5
            target: 2
            slo: 0.9995
```

| Field | Description |
| - | - |
| streamId | ID of your Lightstep stream, which can be found in Lightstep, through the URL. `https://app.lightstep.com//stream/my-stream/` |
| percentile | Percentile latency for your given streamId, out of 1 |
| target | Latency targets in ms. Latency is currently the only target supported |
| slo | SLO percentile, out of 1 |

## Using the Lightstep integration

### Entity pages

When an SLO is defined in an entity's descriptor, you'll see detailed data about SLOs in the **Overview** tab.

On the left side of an entity, click **Monitoring > Lightstep** to view the SLO query, target(s), current value for each SLO, a graph of SLO performance over time, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.

### Scorecards and CQL

With the Lightstep integration, you can create Scorecard rules and write CQL queries based on Lightstep SLOs.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **SLOs**
>
> SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
>
> **Definition:** `slos: List<SLO>`
>
> **Example**
>
> In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
>
> ```
> slos().all((slo) => slo.passing) == true
> ```
>
> Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
>
> ```
> slos().filter((slo) => slo.name.matchesIn("latency") and slo.sliValue >= 0.9999).length > 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Mend
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/mend



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

[Mend](https://www.mend.io/) is an automated application security and remediation platform. Integrate Cortex with Mend to drive insights into potential vulnerabilities in your code and your third-party libraries.

Cortex supports integrating with:

* [Mend Static Application Security Testing (SAST)](https://www.mend.io/sast-lp): This product scans for vulnerabilities in the code you write.
* [Mend Software Composition Analysis (SCA)](https://www.mend.io/sca/): This product scans for vulnerabilities in your third-party libraries.

## How to configure Mend with Cortex

Expand the tabs below for instructions on configuring Mend SAST and Mend SCA.

> **Mend SAST**
>
> **Prerequisite**
>
> Before getting started, [create an API token in Mend](https://docs.mend.io/legacy-sast/latest/api-token).
>
> If you're using a self-hosted instance of Mend, you'll need to verify that your Cortex instance is able to reach the Mend instance.
>
> Cortex routes requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Mend instance.
>
> **Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Mend settings page](https://app.getcortexapp.com/admin/integrations/mend):
>
> * Click **Integrations** from the main nav. Search for and select **Mend**.
>
> 2. Click **Add configuration**.
>
> 3. Configure the Mend SAST integration form:
>
> * **API token**: Enter the API token you created in Mend.
>
> 4. Click **Save**.

> **Mend SCA**
>
> **Prerequisite**
>
> Before getting started, create an [Organization API key](https://docs.mend.io/legacy-sca/latest/global-organization-product-project-api) and a [user key](https://docs.mend.io/legacy-sca/latest/user-level-access-control-in-integrations-and-apis) in Mend.
>
> If you're using a self-hosted instance of Mend, you'll need to verify that your Cortex instance is able to reach the Mend instance.
>
> Cortex routes our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Mend instance.
>
> **Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Mend settings page](https://app.getcortexapp.com/admin/settings/mend):
>
> 2. In Cortex, click your avatar in the lower left corner, then click **Settings**.
>
> 3. Under "Integrations", click **Mend**.
>
> 4. Click **Add configuration**.
>
> 5. Configure the Mend SCA integration form:
>
> * **Organization type**: Select `Global` or `Single`.
>
> * **Organization API token**: Enter your Global organization key or a single organization key.
>   * This can be found in Mend SCA under the [Integrate tab](https://saas.mend.io/Wss/WSS.html#!adminOrganization_integration).
>
> * **User key**: Enter your Mend user key.
>   * This can be found in Mend under **User profile > User keys**.
>
> * **URL type**: Select your Mend URL type depending on the server URL for your Mend instance.
>   * Select **NEW** if the server URL is `saas.mend.io`.
>   * Select **LEGACY** if the server URL is `saas.whitesourcesoftware.com`.
>   * Select **CUSTOM** if using a dedicated instance.
>
> * **Custom URL**: If using a dedicated instance, enter your Mend server URL.
>
> 4. Click **Save**.

### Advanced configuration

If you’re unable to expose your Mend instance to be reachable by Cortex, you can set up a Custom Integration Webhook.

## How to connect Cortex entities to Mend

#### Discovery

By default, Cortex will use your associated Git repository (e.g. `repo-name`) as the "best guess" for the Mend SAST application name and the Mend SCA project name.

If your repository names don’t cleanly match the Mend SAST application names or Mend SCA project names, you can override this in the Cortex Service Descriptor.

#### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-static-analysis:
  mend:
    applicationIds:
      - mend_id_1
      - mend_id_2
    projectIds:
      - project_id_1
      - project_id_2
```

The application IDs can be found in the Mend SAST web interface.

A project ID can be found in the Mend SCA web interface; while viewing the project, the ID appears in the URL after `project;id=`.

## Using the Mend integration

### Entity pages

From the **Overview** tab on an entity page, you can find vulnerabilities in the **Code and Security** block.

In the left sidebar of an entity, click **Code & security > Mend** to view the total number of vulnerabilities, a risk score, and a list of vulnerabilities including the risk rating and creation date.

### Scorecards and CQL

With the Mend integration, you can create Scorecard rules and write CQL queries based on Mend projects and applications.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Mend project is set**
>
> Check if entity has a registered Mend project
>
> **Definition:** `mend (==/!= null): Boolean`
>
> **Examples**
>
> In a Scorecard, you can write a rule to make sure an entity has a Mend project set:
>
> ```
> mend != null
> ```

> **Vulnerabilities**
>
> List of vulnerabilities, filterable on risk and source
>
> **Definition:** `mend.vulnerabilities(): List`
>
> **Examples**
>
> In a Scorecard, you can write a rule to make sure an entity has fewer than 10 vulnerabilities from both SAST and SCA sources:
>
> ```
> mend.vulnerabilities(source = ["SAST", "SCA"]).length < 10
> ```
>
> You can write a rule to make sure an entity has fewer than 3 vulnerabilities with a risk level of "Medium" or "High":
>
> ```
> mend.vulnerabilities(risk = ["Medium", "High"]).length <= 3
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Microsoft Teams
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/microsoftteams



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Microsoft Teams](https://www.microsoft.com/en-us/microsoft-teams/group-chat-software) is a communication and collaboration platform designed to promote greater productivity through messaging and file-sharing tools.

Integrating Microsoft Teams with Cortex allows you to:

* Quickly find the relevant MS Teams channel to communicate with the right team, allowing for easier collaboration on projects and faster communication during an incident
  * MS Teams channels appear in the **Owners** block on [entity details pages](/ingesting-data-into-cortex/entities-overview/entities/details) as a way to contact the entity's owners. Channels are contacts, not owners, so they don't count toward ownership. See [Owners, on-call, and contact channels](/ingesting-data-into-cortex/entities-overview/entities/ownership#owners-on-call-and-contact-channels).
* Receive actionable [notifications](/ingesting-data-into-cortex/integrations/microsoftteams#managing-microsoft-teams-notifications) directly in MS Teams for Scorecard changes, upcoming Initiatives, weekly summaries of entity performance, and more
* Create [Scorecards](/standardize/scorecards) that enforce standards such as having an MS Teams channel set for projects

## How to configure Microsoft Teams with Cortex

> [!WARNING]
>
> This page describes how to integrate Microsoft Teams with Cortex cloud. If you're using a self-managed Cortex instance, you'll need to follow a manual configuration process to use Cortex's app for Microsoft Teams. Follow the [self-managed Teams guide here](/self-managed/features/integrations/ms-teams).

### Step 1: Configure the integration in Cortex

1. In Cortex, navigate to the [Microsoft Teams settings page](https://app.getcortexapp.com/admin/integrations/microsoftteams).
   1. Click **Integrations** from the main nav. Search for and select **Microsoft Teams**.
2. Click **Add configuration**.
3. In the side panel, click **Connect account via Microsoft Teams OAuth**. A popup window will appear.
4. In the pop-up window, follow the prompts to log in to your Microsoft account. The user configuring the integration must accept the delegated permissions listed below:

| Permission | Requirements | Description |
| - | - | - |
| [Get user profile](https://learn.microsoft.com/en-us/graph/api/user-get) | `User.Read` | Read the signed-in user's profile |
| [Get users](https://learn.microsoft.com/en-us/graph/api/user-list?view=graph-rest-1.0\&tabs=http) | `User.ReadBasic.All` | Pulls Teams users into Cortex |
| [Get channels](https://learn.microsoft.com/en-us/graph/api/channel-list?view=graph-rest-1.0\&tabs=http) | `Channel.ReadBasic.All` | Enables channel connection on entity pages and notifications |
| [Get teams](https://learn.microsoft.com/en-us/graph/api/teams-list?view=graph-rest-1.0\&tabs=http) | `Team.ReadBasic.All` | Enables notifications to teams |
| [Get channel members](https://learn.microsoft.com/en-us/graph/api/team-list-members) | `ChannelMember.Read.All` | Enables Scorecard rule for Teams |

After authenticating, you will be redirected to the Microsoft Teams integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Microsoft Teams was configured properly.

### Step 2: Install the Cortex app for Teams through Microsoft AppSource

1. On the [Microsoft Teams settings page](https://app.getcortexapp.com/admin/settings/microsoftteams) in Cortex, click the [Microsoft AppSource](https://appsource.microsoft.com/en-us/product/teams-app/WA200005959) link.
2. In AppSource, click **Get it now**. You will be redirected to a page where you can choose whether to download a desktop app or use the web app.

### Step 3: Configure a setup policy for Cortex in Teams

MS Teams admins can configure a setup policy for Cortex, can choose whether to automatically download the Cortex app into the personal Teams environments for users, and can choose to pin the app to make it more easily accessible.

If admins do not add a policy to install the Cortex app, then users will need to download the app during setup.

1. Navigate to the Teams [admin center](https://admin.teams.microsoft.com/) under **Teams app > Setup policies**.
2. Click **Add** to start configuring a setup policy for the Cortex app.
3. After configuring a policy, navigate to the **Installed apps** section. Add the Cortex app here.
   * This will automatically download the app in users' personal Teams environments.
   * MS Teams admins can also apply the policy to specific users in the Teams admin center under **Users > Manage Users**.
4. To pin the app, follow [Microsoft's instructions on pinning apps](https://learn.microsoft.com/en-us/microsoftteams/teams-app-setup-policies#pin-apps).

### Limitations

Cortex does not automatically discover MS Teams channels based on a [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) so you must [define channels for each entity](/ingesting-data-into-cortex/integrations/microsoftteams#editing-the-entity-descriptor) as described below.

## How to connect Cortex entities to Microsoft Teams

In order to use this integration's functionality, your MS Teams channels need to be associated with entities in Cortex. Cortex does not automatically discover channels for MS Teams, so you must define them in the [entity descriptor](/ingesting-data-into-cortex/integrations/microsoftteams#editing-the-entity-descriptor).

### Editing the entity descriptor

To associate a Microsoft Teams channel with an entity, define a `x-cortex-microsoft-teams` block in an [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-with-yaml) as shown in the example below.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Defining a Teams channel will provide [direct access to the channel via the entity page](/ingesting-data-into-cortex/integrations/microsoftteams#viewing-microsoft-teams-information-across-cortex) in Cortex.

```yaml theme={null}
x-cortex-microsoft-teams:
    channels:
    - name: team-engineering
      teamName: engineering
      description: This is a description for the engineering channel in Teams.
      notificationsEnabled: true
```

| Field | Description | Required |
| - | - | :-: |
| `name` | Microsoft Teams channel name **(exact match)** | **✓** |
| `teamName` | Team name **(exact match)** | **✓** |
| `description` | Description for the Teams channel | |
| `notificationsEnabled` | Boolean to enable/disable notifications | |

## Using the Microsoft Teams integration

### Viewing Microsoft Teams information across Cortex

* [Entity details page](/ingesting-data-into-cortex/entities-overview/entities/details): After MS Teams channels are defined in an entity's YAML, MS Teams channels will appear at the top of an entity's overview page in the **MST channels** block. Channels are also listed in the **Owners** block in an entity's sidebar as contacts. They don't make the channel an owner of the entity. You can click any channel name to go directly to that channel in Microsoft Teams.

  ![The MS Teams channels appear in the upper right side of an entity details page.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/msteams-entity.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=59eaaa401e33eef36f2f19da9d616888)
* You can write CQL queries and Scorecard rules based on Microsoft Teams channels. Learn more under [Scorecards and CQL](/ingesting-data-into-cortex/integrations/microsoftteams#scorecards-and-cql).

### Managing Microsoft Teams notifications

After configuring the Microsoft Teams integration, you can choose whether to allow Microsoft Teams notifications for your workspace.

![A notification in MS Teams includes actionable information.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/msteams-notification.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=bb0c3c253f465dedbe347d37dc03a4ad)

In Cortex under **Settings > Notifications**, an admin or a user with the `Configure workspace notification settings` permission can enable or disable the option to receive notifications via MS Teams for each type of notification. Users can also adjust their [personal notification settings](/configure/settings/notifications#adjusting-your-personal-notification-subscriptions) to control which notifications they receive via MS Teams.

#### Team, user, and entity MS Teams notifications

Notifications are [user-based, team-based, or entity-based](/configure/settings/notifications#enabling-notifications-for-users-teams-and-entities). DMs and channel notifications are sent from the Cortex app.

* User-based notifications are sent to users via a DM from the Cortex app.
* Team-based notifications are sent to the MS Teams channel associated with a team.
* Entity-based notifications are sent to the MS Teams channel associated with an entity.

Learn more about notifications in the [Notifications docs](/configure/settings/notifications).

### Scorecards and CQL

With the Microsoft Teams integration, you can create Scorecard rules and write CQL queries based on Microsoft Teams channels.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Microsoft Teams channel is set**
>
> Checks if a given entity has a registered Teams channel in its entity descriptor.
>
> **Definition:** `microsoftTeams (==/!=) null`
>
> Example
>
> For a Scorecard focused on team operations, you can make sure that each team entity has registered a Microsoft Teams channel:
>
> ```
> microsoftTeams != null
> ```

> **Number of Microsoft Teams channels**
>
> Counts the number of Microsoft Teams channels for a given entity.
>
> * Channel name
> * Team name
>
> **Definition**: `microsoftTeams.channels().length`
>
> Example
>
> You can use this expression in the Query builder to identify teams missing a Microsoft Teams channel:
>
> ```
> microsoftTeams.channels().length < 1
> ```

> **Total number of members across Microsoft Teams channels registered for the entity**
>
> Counts the total number of members across all Microsoft Teams channels registered for a given entity.
>
> * Channel name
> * Member name
> * Team name
>
> **Definition:** `microsoftTeams.members().length`
>
> Example
>
> For a Scorecard focused on team operations, you can verify that the Microsoft Teams channel has at least one member in it:
>
> ```
> microsoftTeams.members().length > 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Privacy Policy

We will retain basic Microsoft Teams metadata like user IDs for the period necessary to fulfill the purposes outlined in our [Privacy Policy](https://www.cortex.io/legal/privacy-policy) unless a longer retention period is required or permitted by law, or where the Customer Agreement requires or permits specific retention or deletion periods.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# New Relic
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/newrelic



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[New Relic](https://newrelic.com/) is a performance tracking and analytics tool that helps engineers gain visibility into their software. Integrating New Relic with Cortex allows you to:

* Discover entities and track ownership
* View SLO and monitoring information on entity pages in Cortex
* Embed New Relic dashboards on entity pages in Cortex
* Create Scorecards to drive alignment on projects involving New Relic metrics

## How to configure New Relic with Cortex

### Prerequisite

Before getting started:

* As a full platform user in New Relic, create a [New Relic user key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key).
  * New Relic user keys are linked to the account they were created from, so if this account is ever deleted, the integration with Cortex will stop working.

### Configure the integration in Cortex

1. In Cortex, navigate to the [New Relic settings page](https://app.getcortexapp.com/admin/integrations/newrelic):
   1. Click **Integrations** from the main nav. Search for and select **New Relic**.
2. Click **Add configuration**.
3. Configure the New Relic integration form:
   * **Account alias:** Enter a name for this account.
   * **Personal key:** Enter the user key you generated in New Relic.
   * **Account ID:** Enter the [ID for the account](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/account-id/) that the user key was generated with.
   * **Use EU region:** Optionally enable this toggle to use the EU region of New Relic.
4. Click **Save**.

Once you save your configuration, you'll see it listed on the integration's settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to **Remove Integration** in Settings.

You can also use the **Test all configurations** button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

#### Cross-account access

After setting up the integration, you will be redirected to the [New Relic settings page](https://app.getcortexapp.com/admin/settings/newrelic) where you can enable the cross-account access feature. If you have an account that supports subordinate accounts, you can enable this setting to fetch applications and SLOs for all the accounts that are under the configured one.

### **Configure the integration for multiple New Relic accounts**

The New Relic integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the New Relic page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.

## How to connect Cortex entities to New Relic

#### Auto discovery

There are two ways to auto-map New Relic applications and services to Cortex entities:

* By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) or its name as the "best guess" for New Relic applications. For example, if your Cortex tag is `my-entity`, then the corresponding application in New Relic should also be `my-entity`. The name is not case-sensitive.
  * If your New Relic applications don’t cleanly match the Cortex tag or name, you can override this in the Cortex entity descriptor.
* Cortex also supports mapping New Relic applications to Cortex entities via New Relic tagKeys. By default, a Cortex entity will be mapped to a New Relic application or service with New Relic tag key = "service" and tag value = the service's Cortex tag.
  * You can customize the tag key names on the [New Relic settings page](https://app.getcortexapp.com/admin/settings/newrelic) in Cortex.

**Note:** Cortex does not support auto-mapping of SLOs. SLOs have to be defined via the entity YAML or attached to a mapped application or service.

**Dependencies**

Cortex automatically maps dependencies between your entities by utilizing New Relic's [Service Map](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/ui-data/service-maps/service-maps/) data.

Say you have two applications in NewRelic (Application A and Application B), and in the service map Application A calls Application B. In Cortex you have two Entities (Cortex Entity A and Cortex Entity B), where Cortex Entity A is mapped to New Relic Application A and Cortex Entity B is mapped to New Relic Application B. Cortex will take the mapped relationship from Application A to Application B and create a dependency from Cortex Entity A to Cortex Entity B.

### Import entities from New Relic

See the [Create services documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#creating-services) for instructions on importing entities.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

**APM services**

New Relic application metrics can be fetched for each entity using application IDs or tags.

```yaml theme={null}
x-cortex-apm:
  newrelic:
    applications:
    - applicationId: 1234567
      alias: Default-App
    - applicationId: 8904321
      alias: Another-App
```

While the `applications` wrapper format is the recommended format, Cortex also supports a flat array:

```yaml theme={null}
x-cortex-apm:
  newrelic:
    - applicationId: 1234567
```

| Field | Description | Required |
| - | - | :-: |
| `applications` | Specifies that the APM service should be found by application ID | **✓** |
| `applicationID` | ID for the application that the service belongs to | **✓** |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

```yaml theme={null}
x-cortex-apm:
  newrelic:
    tags:
    - tag: tagKey
      value: tagValue
      alias: Default-App
```

| Field | Description | Required |
| - | - | :-: |
| `tags` | Specifies that the APM service should be found by tag | **✓** |
| `tag` | Tag key for the APM service(s) | **✓** |
| `value` | Tag value for the APM service(s) | **✓** |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

Instructions to find your Application ID can be found in the [New Relic docs](https://docs.newrelic.com/docs/apis/rest-api-v2/get-started/get-app-other-ids-new-relic-one). You can also find the Application ID in the URL in New Relic.

You can also find information on finding and managing tags in the [New Relic docs](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/use-tags-help-organize-find-your-data/#filter-tags).

**OpenTelemetry**

[OpenTelemetry](https://opentelemetry.io/) services can be associated with the entity only using tags. For this type of service New Relic doesn't generate application ID.

```yaml theme={null}
x-cortex-apm:
  newrelic:
    tags:
    - tag: tagKey
      value: tagValue
      alias: Default-App
```

| Field | Description | Required |
| - | - | :-: |
| `tags` | Specifies that the OpenTelemetry service should be found by tag | **✓** |
| `tag` | Tag key for the APM service(s) | **✓** |
| `value` | Tag value for the APM service(s) | **✓** |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

Cortex fetches OpenTelemetry data every 5 minutes, but the data refresh may take longer depending on how much data you have.

**Embeds**

Cortex can also embed dashboards from New Relic.

```yaml theme={null}
x-cortex-dashboards:
  embeds:
    - type: newrelic
      url: https://chart-embed.service.newrelic.com/example/1a234bc5-d6e7-890f-g123-456h7ij8901 
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Specifies the source of the embed; in this case, should be `newrelic` | **✓** |
| `url` | URL for the dashboard. It must be publicly accessible, or if you can access the iFrame via VPN, it should be accessible in Cortex while also on the VPN. | **✓** |

Learn more about embedding charts in the [Adding external docs](/ingesting-data-into-cortex/entities-overview/entities/external-docs) page.

**SLOs**

SLO can be fetched for each entity using New Relic entity GUID for respective SLO or associated service. Detailed instructions how to obtain entity GUID can be found in [New Relic docs](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#find).

Fetched SLO information can be found in the `Operations` and `Integrations` sections of an entity page.

```yaml theme={null}
x-cortex-slos:
  newrelic:
    - id: MjU5ODYxOXxFWFR8U0VSVklDRV9MRVZFTHiw0TI5ODQ
      alias: my-default-alias
    - id: MjU5ODYxOXxFWFR8U0VSVklDRV9MRVZFTHiw0TI76QB
      alias: my-other-alias
    - id: MjU5ODYxOXxFWFRAB6VSVklDRV9MRVZFTHiw0TI76QD
```

| Field | Description | Required |
| - | - | :-: |
| `id` | New Relic entity guid for the SLO or the associated service; if you use the GUID for a parent service, all SLOs associated with it will be imported into Cortex | true |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

If the alias is not specified, like with the third ID above, Cortex will use the default configuration.

If you use the GUID for a parent service to define the SLOs for a given entity, Cortex will import all SLOs associated with that service.

## Using the New Relic integration

### View New Relic data on entity pages

When entities are tied to New Relic, SLO and monitoring information appear under the Monitoring section on the overview of the [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details).

More data is available under the **Monitoring** page in the entity's sidebar:

* Throughput
* Response time
* Error rate
* Apdex target
* Apdex score
* Host count
* Instance count
* Concurrent instance count

In the SLOs section, you'll be able to see a list of all SLOs tied to that entity, the target and current SLO score, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now\..

The SLO name will display in green when passing and orange when failing.

If you've defined [dashboards](/ingesting-data-into-cortex/entities-overview/entities/external-docs#embedded-dashboards) in an entity's YAML, you'll be able to view the graphs from an entity's details page. Open the **Dashboard** page in the entity's sidebar. All dashboards defined in the descriptor will be embedded on this page.

New Relic dashboards must be defined individually for each entity.

### Relationship graphs

[Dependencies](/ingesting-data-into-cortex/integrations/newrelic#dependencies) detected from New Relic will appear in [Relationship graphs](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph). You can [manually sync dependencies](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies#sync-dependencies) in the Relationship Graph.

### Scorecards and CQL

With the New Relic integration, you can create Scorecard rules and write CQL queries based on New Relic performance metrics.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Application summary**
>
> Fetch high-level [summary data](https://docs.newrelic.com/docs/apis/rest-api-v2/application-examples-v2/summary-data-examples-v2) for a given New Relic application.
>
> This expression enables you to score entities on reliability metrics:
>
> * Apdex score
> * Apdex target
> * Concurrent stance count
> * Error rate
> * GUID
> * Host count
> * ID
> * Instance count
> * Name
> * Response time
> * Throughput
> * Type
>
> **If there is not an application ID set in the entity descriptor, a Scorecard rule based on this expression will fail.**
>
> **Definition:** `newrelic.applications()`
>
> **Example**
>
> You can use this expression in a Scorecard rule to make sure entities' Apdex score is at least 0.9:
>
> ```
> newrelic.applications().all(application) => application.apdexScore >= 0.9
> ```

> **New Relic application is set**
>
> Check if entity has a New Relic application ID set in its entity descriptor.
>
> This can be a good companion to other rules that will fail without a defined application ID, like `newrelic.applications()`.
>
> **Definition:** `newrelic (==/!=) null`
>
> **Example**
>
> You can use this expression in an onboarding Scorecard to make sure that entities have a New Relic application ID set:
>
> ```
> newrelic != null
> ```

> **Raw NRQL query**
>
> Execute an arbitrary NRQL query and capture the [raw JSON back out](https://api.newrelic.com/docs/).
>
> This expression is not inherently tied to a single entity and requires a custom query to pull the specific data what you need. The raw JSON can be parsed using JQ or [Open Policy Agent](https://www.openpolicyagent.org/docs/v0.52.0/) language.
>
> **Definition:** `newrelic.rawNrql(query: Text)`
>
> **Examples**
>
> You can use this expression in a Scorecard measuring performance to make sure that the 95th percentile of latency has been less than 500ms in the last 3 weeks for a given entity:
>
> ```
> jq(newrelic.rawNrql("SELECT percentile(duration) FROM PageView WHERE = '" + newrelic.applications().firstOrNull().name + "' SINCE 3 weeks ago COMPARE WITH 1 week AGO TIMESERIES AUTO"), "[.[].\"percentile.duration\".\"95\"] | add / length") < 500
> ```
>
> Or you can use this expression in a CQL report to read the timeseries of the `process.cpu.usage` metric for the last 30 minutes using NRQL and a New Relic service GUID:
>
> ```
> newrelic.rawNrql("SELECT latest(`process.cpu.usage`) FROM Metric WHERE `entity.guid` = '"+newrelic.applications().getOrNull(0)?.guid+"' SINCE 30 MINUTES AGO TIMESERIES")
> ```

> **SLOs**
>
> SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it and if those SLOs are passing.
>
> SLOs
>
> * History
> * ID
> * Name
> * Operation
> * Remaining budget
> * SLI value
> * SLO target
> * Source
> * Thresholds
>
> SLO datum (timeseries data for the SLI)
>
> * Datum
> * Ts
>
> Named threshold (SLOs thresholds like "warning" or "error" states)
>
> * Name
> * Threshold
>
> **Definition:** `slos`
>
> **Examples**
>
> You can use SLO data from New Relic to evaluate entities in Scorecards. For an onboarding Scorecard, you can make sure that entities have at least 1 SLO defined:
>
> ```
> slos().length > 0
> ```
>
> For a project standards Scorecard, you can also use this expression to make sure entities are passing all of their SLOs:
>
> ```
> slos().all((slo) => slo.passing) == true
> ```

**OpenTelemetry metrics**

OpenTelemetry metrics available in the [New Relic Metrics Exlorer](https://docs.newrelic.com/docs/query-your-data/explore-query-data/browse-data/introduction-data-explorer/) can be accessed or manipulated for a given entity by combining CQL and [NRQL](https://docs.newrelic.com/docs/nrql/nrql-syntax-clauses-functions/) native query.

> **Accessing OpenTelemetry data with CQL and NRQL**
>
> In Cortex, you can access OpenTelemetry data by incorporating a raw NRQL query into this CQL expression with the associated [New Relic GUID](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#find).
>
> **Definition:** `newrelic.applications().getOrNull(0)?.guid`
>
> **Example**
>
> You can execute raw NRQL query to collect average `http.server.requests` in a CQL report:
>
> ```
> newrelic.rawNrql("SELECT average(`http.server.requests`) FROM Metric WHERE `entity.guid` = '"+newrelic.applications().getOrNull(0)?.guid+"' SINCE 7 DAYS AGO")
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Okta
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/okta



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

[Okta](https://www.okta.com/) is an identity and access management (IAM) platform. Integrate Cortex with Okta to drive insights into authentication and ownership.

After configuring the integration, you can set Okta teams and team members as owners of entities.

For information on configuring Okta SSO or Okta SCIM for logging in to Cortex, see the [Okta SSO documentation](/configure/settings/managing-users/configuring-sso) and [Okta SCIM documentation](/configure/settings/managing-users/scim/okta-scim).

## How to configure Okta with Cortex

### Prerequisites

Before getting started:

* An Okta administrator, with at least the [View groups](https://help.okta.com/en-us/Content/Topics/Security/custom-admin-role/about-role-permissions.htm) permissions, must [create an Okta API token](https://developer.okta.com/docs/guides/create-an-api-token/create-the-token/).
  * Grant the following scopes for the API token:
    * `okta.groups.read`
    * `okta.profileMappings.read`
    * `okta.users.read`
* Obtain your Okta domain.
  * This can be found in the prefix of your Okta URL. For example, `https://domain.okta.com`.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Okta settings page](https://app.getcortexapp.com/admin/integrations/okta):
   * Click **Integrations** from the main nav. Search for and select **Okta**.
2. Click **Add configuration**.
3. Configure the Okta integration form:
   * **Domain**: Enter your Okta domain.
   * **API token**: Enter your Okta API token.
   * **Group types**: Specify which group types to include.
4. Click **Save**.

## How to connect Cortex entities to Okta

### Import teams from Okta

See the [Create teams documentation](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#importing-teams-from-an-integration) for instructions on importing entities.

### Syncing ownership from Okta

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

To assign an Okta group as an owner, add it to the entity descriptor:

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: Engineering # group name in Okta
    provider: OKTA
    description: This is a description for this owner # optional
```

The group name is case-sensitive and should be exactly the same as in Okta.

Cortex syncs Okta teams every day at 3 p.m. UTC. Cortex uses [identity mappings](/configure/settings/managing-users/identity-mapping) to connect group members to Cortex users when they exist, and falls back to each member's email address from Okta otherwise.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

## Using the Okta integration

### Scorecards and CQL

With the Okta integration, you can create Scorecard rules and write CQL queries based on Okta teams.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity
>
> **Definition:** `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts an ownership sync for Okta teams every day at 3 p.m. UTC.

## Troubleshooting and FAQ

**I've added an API token but the login is still using Google.**

To set up Okta for SSO, use the [Okta SSO guide](/configure/settings/managing-users/configuring-sso/okta).

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Opsgenie
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/opsgenie



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

> [!CAUTION]
>
> Atlassian is deprecating the Opsgenie product and encouraging their customers to migrate to Jira Service Management. Read more about moving from Opsgenie to Jira Service Management on [Atlassian's website](https://support.atlassian.com/jira-service-management-cloud/docs/start-shifting-from-opsgenie-to-jira-service-management/).
>
> Cortex doesn't currently offer a Jira Service Management integration. Support for Jira Service Management incident and on-call data is under consideration.

[Opsgenie](https://www.atlassian.com/software/opsgenie) is an alert and on-call management platform from Atlassian.

Integrating Opsgenie with Cortex allows you to:

* Pull in on-call rotation data and escalation policies
  * The on-call user or team will appear in the **Current On-call** block on an entity's details page.
  * You can also view on-call information on an entity page in its side panel under **Integrations > On-call**.
* View alerts from Opsgenie in an entity's event timeline
* Create [Scorecards](/ingesting-data-into-cortex/integrations/opsgenie#scorecards-and-cql) that track progress and drive alignment on projects involving your on-call schedules and alerts

## How to configure Opsgenie with Cortex

### Prerequisite

Before getting started, create an [Opsgenie API key](https://support.atlassian.com/opsgenie/docs/api-key-management/) with the following permissions:

* `Read`
* `Configuration Access`

### Configure the integration in Cortex

1. In Cortex, navigate to the [Opsgenie settings page](https://app.getcortexapp.com/admin/integrations/opsgenie):
   * Click **Integrations** from the main nav. Search for and select **Opsgenie**.
2. Configure the Opsgenie integration form:
   * **Subdomain**: Enter the subdomain assigned to your Opsgenie instance.
   * **API key**: Enter your Opsgenie API key.
   * **Use European service region**: Optionally, toggle this setting on to enable the EU region of Opsgenie.
3. Click **Save**.

## How to connect Cortex entities to Opsgenie

### Discovery

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" value for the `backend` and `service` tags on your alerts. For example, if your alert in Opsgenie has the tag `backend:my-entity`, the alert will be automatically associated with the entity in Cortex with a unique identifier of `my-entity`.

If your Opsgenie tags don’t cleanly match the Cortex tag, or you use different identifying tags, you can override this in the Cortex entity descriptor.

### Entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-alerts:
  - type: opsgenie
    tag: different-tag
    value: my-entity-override-tag
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Type of alert (in this case, `opsgenie`) | **✓** |
| `tag` | Type of tag in Opsgenie (e.g. `backend`) | **✓** |
| `value` | Alert in Opsgenie (e.g. `my-entity-override-tag`) | **✓** |

For example, for the tag `different-tag:my-entity-override-tag`, the entity descriptor would have `different-tag` in the **tag** field and `my-entity-override-tag` in the **value** field.

You can add a list of tags to use for lookup. Cortex will use an `OR` operator when querying Opsgenie (e.g. `backend:my-entity OR service:another-value`).

The `value` field also supports wildcards (e.g. `value: my-entity*`).

**Adding a schedule**

You can define the following block in an entity descriptor to add an Opsgenie schedule. Cortex supports adding a schedule by ID or UUID. You can add one schedule per entity.

The UUID for the schedule can be found in URL when viewing schedule details by clicking on the schedule name under who is on-call.

```yaml theme={null}
x-cortex-oncall:
  opsgenie:
    type: SCHEDULE
    id: Cortex-Engineering
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Opsgenie component being added (in this case, `SCHEDULE`) | **✓** |
| `id` | Schedule ID or UUID | **✓** |

#### Syncing ownership from Opsgenie

You can define the following block in your Cortex entity descriptor to add your Opsgenie teams as owners.

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: My Opsgenie Team
    provider: OPSGENIE
    description: This is a description for this owner
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Ownership type (in this case, `group`) | **✓** |
| `name` | Name of the team defined in Opsgenie (\*\*case-sensitive) | **✓** |
| `provider` | Identity provider (in this case, `OPSGENIE`) | **✓** |
| `description` | Description for the team, to be displayed in Cortex | |

Cortex syncs Opsgenie teams every day at 9 a.m. UTC and Opsgenie identities every day at 10 a.m. UTC. Cortex connects team members to their Cortex users through [identity mappings](#identity-mappings).

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

#### Identity mappings

Cortex maps email addresses in your Opsgenie instance to email addresses that belong to team members in Cortex. When identity mapping is set up, users will be able to see their personal on-call status from the developer homepage.

## Using the Opsgenie integration

After setting up the integration, Opsgenie information will appear in several places across Cortex.

### Viewing on-call information for an entity

On an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details), current on-call information from Opsgenie will display in the **On-call** block.

Escalation policy, the level associated with the policy, and other on-call information will also appear in the entity's sidebar in the "On-call & incidents" page. Owners assigned to each level will also be hyperlinked to the user or team page in Opsgenie.

![On-call information appears on the right side of an entity details page.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/on-call-block.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=6a3273e51b2259c2f016038d2d089b7e)

### Viewing recent Opsgenie events

Click **Events** in an entity's sidebar to view recent events pulled in from Opsgenie.

### Viewing on-call information on the dev homepage

The Opsgenie integration enables Cortex to pull on-call information into the on-call block on the Dev homepage. On-call data from Opsgenie is refreshed every 1 minute.

### Scorecards and CQL

With the Opsgenie integration, you can create Scorecard rules and write CQL queries based on Opsgenie on-call schedules and alerts.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if on-call is set**
>
> Check if entity has a registered schedule.
>
> **Definition:** `oncall (==/!=) null`
>
> **Example**
>
> For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
>
> ```
> oncall != null
> ```
>
> This rule will pass if an entity has an on-call schedule set.

> **Number of alerts**
>
> Number of alerts for a given lookback period that match a given [search query](https://support.atlassian.com/opsgenie/docs/search-queries-for-alerts/).
>
> **Definition:** `oncall.numOfAlerts(lookback=,query=).length`
>
> **Example**
>
> For a Scorecard focused on maturity or quality, you can use this expression to make sure a given entity has fewer than two alerts in the last month:
>
> ```
> oncall.numOfAlerts(lookback=duration("P1M"),query="status: open").length < 2
> ```
>
> You could also refine this rule by specifying priority level:
>
> ```
> oncall.numOfAlerts(lookback=duration("P1M"),query="priority: P1").length < 2
> ```
>
> Entities will pass this rule if they have fewer than 2 alerts with priority level "P1" in the last month.

> **Number of escalations**
>
> Number of escalation tiers in escalation policy.
>
> **Definition:** `oncall.numOfEscalations()`
>
> **Example**
>
> This expression could be used in a Scorecard focused on production readiness or service maturity. For example, you can check that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup:
>
> ```
> oncall.numOfEscalations() >= 2
> ```
>
> While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.

> **On-call metadata**
>
> On-call metadata.
>
> * ID
> * Name
> * Type
>
> **Definition:** `oncall.details()`
>
> **Example**
>
> To find all entities without a schedule-type on-call registration, you can use this expression in the Query builder:
>
> ```
> oncall.details().type =! "schedule"
> ```
>
> If you're migrating on-call policies, you could use this rule to check for outdated policies. Let's say, for example, all outdated Opsgenie policies start with "Legacy" in their titles.
>
> ```
> oncall.details().id.matches("Legacy*") == false
> ```
>
> Entities with on-call policies that start with "Legacy" will fail, while those with other policy names will pass.

**Ownership CQL**

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity
>
> **Definition:** `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex performs the following background jobs:

* **Ownership**: A sync for Opsgenie teams every day at 9 a.m. UTC.
* **Identity mapping**: A sync for Opsgenie identities every day at 10 a.m. UTC.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# PagerDuty
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty

Configuring the integration for PagerDuty

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Why use the integration for PagerDuty

PagerDuty is an incident response platform for managing alerts, on-call rotations, and escalation policies. The integration for PagerDuty syncs your PagerDuty services, on-call schedules, escalation policies, and incidents into Cortex, connecting each service's operational data to its ownership and metadata in your software catalog.

Instead of switching tools to answer "who is on call for this service?", you can see current on-call information on an entity's details page, view PagerDuty incidents in its event timeline, and trigger incidents without leaving Cortex. When an incident is triggered, the [On-call Assistant](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant) notifies users via Slack with runbooks, dependencies, and key information about the affected entity. Because PagerDuty data is available in CQL, you can also create Scorecards that enforce on-call standards at scale and track metrics like mean time to resolution (MTTR) in Eng Intelligence.

Integrating PagerDuty with Cortex allows you to:

* Pull in PagerDuty services, on-call schedules, and escalation policies. The on-call user or team appears in the **On-call** block on an entity's metadata sidebar, and on the entity's details page under **Connections > On-call**.
* Trigger incidents in PagerDuty directly from Cortex.
* Automatically surface vital information about entity health and metadata when an incident is triggered, using the On-call Assistant.
* View incidents from PagerDuty in an entity's event timeline.
* View on-call information from PagerDuty on the Engineering homepage.
* Use PagerDuty metrics in Eng Intelligence to gain insight into services, incident response, and more.
* Create Scorecards that track progress and drive alignment on projects involving your on-call schedules and alerts.

## Configuring PagerDuty

### Prerequisites

1. Users with the `Configure Integrations` permission can configure PagerDuty.

### Step 1: Creating an API key in PagerDuty

1. In PagerDuty, go to **Integrations > API Access Keys**.
2. [Create a PagerDuty API key](https://support.pagerduty.com/docs/generating-api-keys).
   1. When adding the API key, you have the option to set read or write permissions:
      1. `Read-only` - Enables Cortex to read any and all data from PagerDuty
         1. If you create an API key with `Read-only` permissions, and you want to use the On-call Assistant in Slack, you also need to [configure a webhook](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant#configuring-a-webhook-for-read-only-api-keys) to get the Assistant working.
      2. `Write` - Allows users to trigger incidents from an entity page in Cortex, and enables the On-call Assistant
3. Copy the API key. Don't skip this step! You'll need the key to complete the setup.

#### A note about Scoped OAuth apps

If you registered a Scoped OAuth app in PagerDuty, you must also grant the following permissions:

* `incident.write` to create incidents
* `escalation_policies.write` to create escalation policies
* `schedules.write` to create schedules
* `services.write` to create services
* `teams.write` to create teams

### Step 2: Installing the PagerDuty integration in Cortex

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate PagerDuty, then click **Install**. The PagerDuty side panel opens.
3. In the PagerDuty side panel, do the following:
   1. From the **Category** dropdown, select at least one category that applies to the integration (required).
   2. Under **API key**, paste the API key you generated in PagerDuty (required).
   3. Optionally, toggle on **Read-only API key** if you created the key with read-only permissions.
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

> [!NOTE]
>
> To modify an existing configuration, see [Modifying an integration configuration](/ingesting-data-into-cortex/integrations#modifying-an-integration-configuration).


# Connecting entities to PagerDuty
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty

Connect entities to PagerDuty automatically or manually via the entity's descriptor YAML

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to connect entities to PagerDuty. For configuration instructions, see [Configuring the integration for PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty#configuring-pagerduty). For instructions on using the integration, see [Using the integration for PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty/using-the-integration-for-pagerduty).

> [!NOTE]
>
> Cortex runs the following background jobs for PagerDuty:
>
> * On-call information on the Engineering homepage is refreshed every 60 minutes.
> * Services used for automapping and active incidents are fetched approximately every 5 minutes, or however long the refresh takes.
> * User data for identity mapping is synced daily at 10 a.m. UTC.

## Connecting an entity to PagerDuty

Cortex entities are connected to PagerDuty in one of two ways: automatically through discovery, or explicitly by defining a PagerDuty service, schedule, or escalation policy in the entity's descriptor YAML.

### Discovering entities automatically

By default, Cortex uses the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `checkout-api`) or the entity's name as the "best guess" for PagerDuty services. For example, if the Cortex tag is `checkout-api`, the corresponding service in PagerDuty should also be `checkout-api`.
If your PagerDuty services don't cleanly match the Cortex tag or name, define the connection in the [entity descriptor](/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty#connecting-via-an-entity-descriptor) instead.

#### Considerations for registering PagerDuty entities

Cortex recommends setting up PagerDuty at the **service level** by registering service entities with PagerDuty services, rather than configuring team entities with a PagerDuty schedule.

If PagerDuty is set up on a service level, you can see current on-call information listed within a given service's page. If PagerDuty is set up on the team level, you can only view on-call rotation information from a team page.

Other benefits of setting up PagerDuty on a service level include:

* Structuring PagerDuty 1-1 with services enables better alert routing and analytics, something organizations struggle with more when PagerDuty is set up on a team level.
* With a service-level setup, it's easier to enforce a compliant on-call policy for all services in PagerDuty, especially when making use of Scorecards.
* The service-level setup is less reliant on team members tagging incidents with service information because services and incidents are already linked.
* You gain the ability to get data from your Cortex catalog into PagerDuty, such as tier and criticality. By tying the service entities in the catalog to those in PagerDuty, you can automate processes and streamline severity protocols.

#### Viewing on-call data only

If you only want to view on-call data for entities, and do not want incidents displayed in Cortex, you can register the escalation policy ID for an entity. See [Defining an escalation policy](/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty#defining-an-escalation-policy) below.

### Connecting via entity descriptor

To explicitly connect an entity to PagerDuty, add the `x-cortex-oncall` block to the entity's YAML, specifying a PagerDuty service, schedule, or escalation policy.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

| Field | Description | Required? |
| - | - | - |
| `id` | PagerDuty ID for the service, schedule, or escalation policy | |
| `type` | SERVICE, SCHEDULE, or ESCALATION\_POLICY | |

> [!WARNING]
>
> You can only set up one of the three options below per entity.

#### Defining a PagerDuty service

In PagerDuty, find the [service ID value](https://support.pagerduty.com/main/docs/service-directory#configure-service-standards-settings). The URL for the service contains the ID, e.g. `PDEF456` in `https://yourdomain.pagerduty.com/services/PDEF456`.
You can only configure one service ID per entity.

```yaml theme={null}
x-cortex-oncall:
  pagerduty:
    id: PDEF456
    type: SERVICE
```

#### Defining a schedule

In PagerDuty, find the [schedule ID](https://developer.pagerduty.com/api-reference/3f03afb2c84a4-get-a-schedule). The URL for the schedule contains the ID, e.g. `PABC123` in `https://yourdomain.pagerduty.com/schedules/PABC123`.
You can only configure one schedule per entity.

```yaml theme={null}
x-cortex-oncall:
  pagerduty:
    id: PABC123
    type: SCHEDULE
```

#### Defining an escalation policy

In PagerDuty, find the [escalation policy ID](https://developer.pagerduty.com/api-reference/51b21014a4f5a-list-escalation-policies). The URL for the escalation policy contains the ID, e.g. `P7LVMYP` in `https://yourdomain.pagerduty.com/escalation_policies/P7LVMYP`. You can only configure one escalation policy per entity.

Linking a Cortex entity to a PagerDuty escalation policy surfaces only on-call information in Cortex, not incidents. This is useful for teams that want to show on-call schedules without incident visibility.

```yaml theme={null}
x-cortex-oncall:
  pagerduty:
    id: P7LVMYP
    type: ESCALATION_POLICY
```

### Identity mappings

Cortex maps email addresses in your PagerDuty instance to email addresses that belong to team members in Cortex. When [identity mapping](/configure/settings/managing-users/identity-mapping) is set up, users can see their personal on-call status from the [Engineering homepage](/streamline/homepage).

## Enabling the On-call Assistant

> [!NOTE]
>
> The On-call Assistant only works for service-level PagerDuty registrations, since these notifications are related to affected services.

After configuring the integration, you can turn on the On-call Assistant, which notifies users via Slack when an incident is triggered in PagerDuty. Notifications include runbooks, links, dependencies, and key information about the affected entity. For instructions, see [On-call Assistant](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant).\


# Using the integration for PagerDuty
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty/using-the-integration-for-pagerduty

How to use the integration for PagerDuty in Cortex

This article explains how to use the integration for PagerDuty. For configuration instructions, see [Configuring the integration for PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty/using-the-integration-for-pagerduty#configuring-pagerduty). For instructions on connecting PagerDuty to entities, see [Connecting entities to PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty).

After you configure the PagerDuty integration, Cortex surfaces on-call and incident data across the app on:

### Entity pages

View current on-call information in the **On-call** block on an entity's metadata sidebar, and on the entity's details page under **Connections > On-call**.

![On-call information on an entity's details page.](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/pagerduty-entity.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=c18325c8fe6cb1184271ce17a8541574)

Select the **Events** tab in an entity's left side panel to view recent events pulled in from PagerDuty.

![The Events page.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-events.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=bed8222438adf143fe95fc163f7ab739)

> [!NOTE]
>
> Escalation policy and service details are hyperlinked to the corresponding pages in your PagerDuty instance.

### Engineering homepage

The PagerDuty integration allows Cortex to pull on-call information into the **My on-calls** block on the Engineering homepage. On-call data from PagerDuty is refreshed every 60 minutes.

![The 'My on-calls' section of the Engineering homepage.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-homepage.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=965869e071b1f1fb575c9e860e4dc3af)

### Eng Intelligence

Cortex also pulls in metrics from PagerDuty for Eng Intelligence, which displays MTTR, incidents opened, and incidents opened per week.

## Other ways to use the integration for PagerDuty

### Retrieving on-call information in Slack

If you have the Slack integration set up, you can ask the AI Assistant for current on-call information. Mention `@Cortex` in a channel or direct message and ask a question like "Who's on call for payments-api?" This works for both services and teams with registered PagerDuty schedules or escalation policies.

For setup and usage details, refer to [Using the AI assistant](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#using-the-ai-assistant).

### Creating Scorecard rules and writing CQL queries with the PagerDuty integration

With the PagerDuty integration, you can create Scorecard rules and write CQL queries based on incidents, escalations, and on-call metadata.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if on-call is set**
>
> Check if entity has a registered service, schedule, or escalation policy. If the service does not have any registrations in its entity descriptor, Cortex searches for PagerDuty services matching the tag defined in the entity's `x-cortex-tag` field.
>
> **Definition** - `oncall (==/!=) null`
>
> **Example**
>
> For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
>
> ```
> oncall != null
> ```
>
> This rule passes if an entity has a service, schedule, or escalation policy set.

> **Forbidden contact methods**
>
> Number of users in each entity's escalation policy with missing or forbidden contact methods.
>
> Allowed contact methods:
>
> * "SMS"
> * "PHONE"
> * "EMAIL"
> * "PUSH\_NOTIFICATION"
> * "SLACK"
>
> **Definition** - `oncall.usersWithoutContactMethods(allowed=<allowed>, onlyCurrentOncall=<boolean>).length`
>
> **Example**
>
> For a Scorecard focused on ownership, you can use this expression to make sure users have required contact methods enabled:
>
> ```
> oncall.usersWithoutContactMethods(allowed=["SMS", "PHONE"]).length == 0
> ```
>
> This rule passes if every user in an associated escalation policy has either SMS or phone calls enabled as their contact method.
>
> You can also use this expression in the query builder to find users that lack the required contact method:
>
> ```
> oncall.usersWithoutContactMethods(allowed=["EMAIL"]) > 0
> ```
>
> This query surfaces users without email addresses.
>
> If you want to check only current on-call users, you can use the `onlyCurrentOncall` parameter:
>
> ```
> oncall.usersWithoutContactMethods(allowed=["EMAIL"], onlyCurrentOncall=true) > 0
> ```
>
> When this parameter is set to `false` or omitted, the expression checks all users in the associated escalation policy for the next 3 months.

> **Incident response analysis**
>
> Get detailed [on-call analysis stats](https://developer.pagerduty.com/api-reference/694e92fe4f943-get-aggregated-service-data) for each entity:
>
> * Mean assignment count
> * Mean engaged seconds
> * Mean engaged user count
> * Mean seconds to engage
> * Mean seconds to first ack
> * Mean seconds to mobilize
> * Mean seconds to resolve
> * Total business-hour erruptions
> * Total engaged seconds
> * Total escalation count
> * Total off-hour erruptions
> * Total sleep-hour erruptions
> * Total snoozed seconds
> * Total incident count
> * Up time percent
>
> PagerDuty updates its analytics data once per day, and it can take up to 24 hours before new incidents appear in the analytics API.
>
> **Note that this only works if the entity has a registered PagerDuty service ID or if the PagerDuty service name matches the entity tag.**
>
> **Definition** - `oncall.analysis(lookback = <duration>, priority = <List<String>>)`
>
> **Examples**
>
> PagerDuty analytics can easily be used to craft rules for a DORA metrics Scorecard.
>
> For **mean time to acknowledge**, you can use the `meanSecondsToFirstAck` schema definition:
>
> ```
> oncall.analysis(lookback = duration("P7D"), priority = ["P1", "P2"]).meanSecondsToFirstAck <= 300
> ```
>
> Entities pass this rule if incidents in the last week were acknowledged within 5 minutes.
>
> For **mean time to resolve**, you can use `meanSecondsToResolve` to make sure that incidents were handled within an hour:
>
> ```
> oncall.analysis(lookback = duration("P7D"), priority = ["P1"]).meanSecondsToResolve < 3600
> ```
>
> You can also use this expression to write a rule that checks an entity's change failure rate:
>
> ```
> oncall.analysis(lookback = duration("P7D")).totalIncidentCount == 0
> ```
>
> This rule passes if there weren't any incidents in the last week.

> **Incidents**
>
> Get incident data for each entity:
>
> * Assignee ID
> * Created at
> * Incident ID
> * Last updated
> * Resolved at
> * Service ID
> * Status
>
> **Note that this only works if the entity has a registered PagerDuty service ID or if the PagerDuty service name matches the entity tag.**
>
> **Definition** - `oncall.incidents(lookback = <duration>)`
>
> **Examples**
>
> For a Scorecard focused on service maturity or quality, you can use this expression to check the number of incidents opened in the last month:
>
> ```
> oncall.incidents(lookback = duration("P1M")).length < 15
> ```
>
> Entities pass this rule if they have fewer than 15 incidents opened in the last month.
>
> You can also use this expression to make sure there aren't incidents that remained open over the last month:
>
> ```
> oncall.incidents(lookback=duration("P1M")).filter((incident) => incident.status.matches("TRIGGERED|ACKNOWLEDGED")).length < 1
> ```
>
> Or you can check for incidents that took a certain amount of time to resolve:
>
> ```
> oncall.incidents(lookback=duration("P1M")).filter((incident) => incident.createdAt.until(incident.resolvedAt) > duration("P-2D")).length < 2
> ```
>
> Entities pass this rule if there were 0 or 1 incidents in the last month that took more than 2 days to resolve.

> **Number of escalations**
>
> Number of escalation tiers in escalation policy.
>
> **Definition** - `oncall.numOfEscalations()`
>
> **Example**
>
> This expression could be used in a Scorecard focused on production readiness or service maturity:
>
> ```
> oncall.numOfEscalations() >= 2
> ```
>
> This rule checks that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup.
>
> While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.

> **On-call metadata**
>
> On-call metadata, including type, id, and name.
>
> **Definition** - `oncall.details()`
>
> **Examples**
>
> To find all entities with a schedule-type on-call registration, you can use this expression in the Query builder:
>
> ```
> oncall.details().type == "schedule"
> ```
>
> If you're migrating on-call policies, you could use this rule to check for outdated policies. For example, assume that all outdated PagerDuty policies start with "Legacy" in their titles.
>
> ```
> oncall.details().id.matches("Legacy*") == false
> ```
>
> Entities with on-call policies that start with "Legacy" fail, while those with other policy names pass.

## Triggering an incident

A given entity can have a PagerDuty service, schedule, or escalation policy defined, as described in [Connecting via an entity descriptor](/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty#connecting-via-an-entity-descriptor). Only entities with a PagerDuty service defined include the option to trigger an incident directly from Cortex.

Your PagerDuty API key must include the `Write` permission to trigger incidents from an entity.

**To trigger an incident in PagerDuty**:

1. In Cortex, navigate to an entity.
2. From the entity's left sidebar, select **Incidents**.

   ![The 'Incidents' tab on the entity's left sidebar.](https://mintcdn.com/cortex-290c0c42/fKqTUx7McPYDap8G/images/pagerduty-incidents.png?fit=max\&auto=format\&n=fKqTUx7McPYDap8G\&q=85\&s=1034a670d1a58a71e3f53d461cf289ab)
3. In the upper-right corner of the **Incidents** page, click **Trigger incident**. The **Trigger incident** side panel opens.
4. Do the following:
   1. Under **Title**, enter a name for the incident (required).
   2. Under **Description**, enter a description of the incident.
   3. From the **Urgency** dropdown, select a severity level.
5. Click **Trigger incident**.
6. Click **Click here** to view the incident in PagerDuty.
7. Click **Close** to collapse the **Trigger incident** side panel.

## Viewing PagerDuty integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.


# Prometheus
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/prometheus



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

[Prometheus](https://prometheus.io/) is an open-source monitoring and analytics platform that allows customers to analyze, visualize, automate, and alert on metrics data.

Integrating Cortex with Prometheus allows you to:

* [View SLO information](/ingesting-data-into-cortex/integrations/prometheus#view-prometheus-data-in-entity-pages) from Prometheus on entity pages in Cortex
* Create [Scorecards](/ingesting-data-into-cortex/integrations/prometheus#scorecards-and-cql) that track progress and drive alignment on projects involving Prometheus SLOs

## How to configure Prometheus with Cortex

There are two options for integrating Prometheus: the default configuration method and Cortex Axon Relay, a relay broker allows you to securely connect your on-premises Prometheus data.

### Prerequisite

Before getting started, set up [basic authentication](https://prometheus.io/docs/guides/basic-auth/) credentials in Prometheus.

> **Default configuration**
>
> **Configure the integration in Cortex**
>
> 1. In Cortex, navigate to the [Prometheus settings page](https://app.getcortexapp.com/admin/integrations/prometheus):
>
> * Click **Integrations** from the main nav. Search for and select **Prometheus**.
>
> 2. Click **Add integration**.
>
> 3. Configure the Prometheus integration form:
>
> * **Account alias**: Enter your account alias.
> * **Username** and **Password**: Enter your Prometheus basic auth credentials.
> * **Host**: Enter your self-managed Prometheus hostname.
> * **Tenant ID**: Optionally, enter your tenant ID.
>   * If you have multiple tenants, you can enter an ID here to monitor a specific tenant.
>
> 4. Click **Save**.

> **Axon Relay**
>
> **Configure Prometheus with Cortex Axon Relay**
>
> See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for instructions. Make sure to follow the Prometheus-specific instructions for the `docker-compose.yml` file.

**Configure the integration for multiple Prometheus accounts**

The Prometheus integration has multi-account support. You can add a configuration for each additional by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the Prometheus page in your Cortex settings. Select the edit icon next to a given configuration and toggle **Set as default** on. If you only have one configuration, it will automatically be set as the default.

## Connecting Cortex entities to Prometheus

### Linking SLOs in Cortex

You can create and manage SLOs by listing relevant SLIs through queries.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-slos:
  prometheus:
    - errorQuery: sum(rate(http_server_requests_seconds_count{code=~"(5..|429)"}[5m]))
      totalQuery: sum(rate(http_server_requests_seconds_count[5m]))
      slo: 99.95
      alias: my-prometheus-instance # alias is optional and only relevant if you have opted into multi account support
      name: my-slo-name
```

| Field | Description |
| - | - |
| errorQuery | Query that indicates error events for your metric. |
| totalQuery | Query that indicates all events to be considered for your metric. |
| slo | Target number for SLO. |
| alias | Ties the SLO registration to a Prometheus instance listed under Settings → Prometheus. The alias parameter is optional, but if not provided the SLO will use the default configuration under Settings → Prometheus. |
| name | The SLO's name in Prometheus. The name parameter is optional. |

### How Cortex calculates Prometheus SLOs

When Cortex gets an SLO from Prometheus, the following query is calculated for it:

```
(1 - ({errorQuery}) / ({totalQuery}))
```

This value is calculated and resolved on an hour window, and calculated back for 7 days. Cortex averages the value for each 1-hour window, then averages each of those hourly averages across the lookback period, before displaying it in your Cortex workspace.

The value is updated when the entity page is loaded and when Scorecards are evaluated.

## Using the Prometheus integration

### View Prometheus data in entity pages

When an SLO is defined in an entity's descriptor, you'll see detailed data about SLOs in the **Monitoring** page in the sidebar of an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details). See the SLO query, target, the current value for each SLO, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now\..

### Scorecards and CQL

With the Prometheus integration, you can create Scorecard rules and write CQL queries based on Prometheus SLOs.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **SLOs**
>
> SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
>
> **Definition:** `slos: List<SLO>`
>
> **Examples**
>
> In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
>
> ```
> slos().all((slo) => slo.passing) == true
> ```
>
> Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
>
> ```
> slos().filter((slo) => slo.name.matchesIn("latency") and slo.sliValue >= 0.9999).length > 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Rollbar
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/rollbar



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Rollbar](https://rollbar.com/) is an error tracking tool that helps developers discover and resolve crashes and errors.

Integrating Rollbar with Cortex allows you to:

* [View errors on entity pages in Cortex](/ingesting-data-into-cortex/integrations/rollbar#viewing-rollbar-errors-on-an-entity), giving you insight into your entity's operational maturity
* Create [Scorecards](/ingesting-data-into-cortex/integrations/rollbar#scorecards-and-cql) that include rules relating to error data from Rollbar, motivating team members to improve their code quality

## How to configure Rollbar with Cortex

### Prerequisites

Before getting started:

* Create a [Rollbar access token](https://explorer.docs.rollbar.com/#section/Authentication/Account-Access-Tokens).
  * The token requires `read` permissions at minimum. This allows Cortex to automatically look up project tokens for each Rollbar project and attempt to reuse them to access project details.
  * Granting the token `read` and `write` permissions enables Cortex to automatically create an access token if none exists for a given project.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Rollbar settings page](https://app.getcortexapp.com/admin/integrations/rollbar):
   1. Click **Integrations** from the main nav. Search for and select **Rollbar**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **Account access token**: Enter the access token you generated in Rollbar.
   * **Account name**: Enter your Rollbar account name, found in your Rollbar settings.
     * The name also appears in the URL for your Rollbar instance, e.g.,
4. Click **Save**.

After saving your configuration, you are redirected to the Rollbar integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Rollbar was configured properly.

## How to connect Cortex entities to Rollbar projects

### Discovery

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" for Rollbar projects. For example, if your Cortex tag is `my-entity`, then the corresponding project in Rollbar should also be `my-entity`.

If your Rollbar projects don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can define projects under the `x-cortex-rollbar` block in an [entity's YAML](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file):

```yaml theme={null}
x-cortex-rollbar:
  project: my-project
```

| Field | Description | Required |
| - | - | :-: |
| `project` | Project name as defined in Rollbar | **✓** |

## Using the Rollbar integration

### Viewing Rollbar errors on an entity

Error data from Rollbar will appear on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). In an entity's sidebar, click **Error tracking** to view detected issues for each Rollbar project. At the top of the page, see the associated project tag and the project framework.

Under **Items**, see a list of detected errors and their statuses. Next to the error name, you can also see badges for `# seen` and the type of event: `error`, `warning`, or `info`.

### Scorecards and CQL

With the Rollbar integration, you can create Scorecard rules and write CQL queries based on Rollbar projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Rollbar project is set**
>
> Check if entity has a registered Rollbar project.
>
> **Definition:** `rollbar (==/!=) null`
>
> **Example**
>
> You can define a rule in an operational readiness Scorecard to make sure each entity has a registered Rollbar project.
>
> ```
> rollbar != null
> ```
>
> This is also a good way to confirm the integration is synced and reporting frequently.
>
> You could also query for entities that don't have a registered Rollbar project to quickly identify those that need to be updated:
>
> ```
> rollbar == null
> ```

> **RQL query**
>
> Evaluate an [RQL](https://docs.rollbar.com/docs/rql) query for the Rollbar project.
>
> If the entity does not have a Rollbar project set, the rule will fail. An empty result set will result in null.
>
> **Definition:** `rollbar.rql(<query>)`
>
> **Example**
>
> An operational maturity Scorecard, you can use this expression to make sure entities have fewer than 100 open errors.
>
> ```
> rollbar.rql("SELECT count(*) FROM item_occurrence WHERE status = 1") < 100
> ```
>
> Or you can set a rule that gauges errors over time:
>
> ```
> rollbar.rql("SELECT count(*) / 30 FROM item_occurrence WHERE timestamp > unix_timestamp() - 60 * 60 * 24 * 30") < 5
> ```
>
> This rule checks that entities have fewer than 5 new errors per day on average over the last 30 days.

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Rootly
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/rootly



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to configure the integration for Rootly. For instructions on connecting Rootly to entities, see [Connecting entities to Rootly](/ingesting-data-into-cortex/integrations/rootly/connecting-entities-to-rootly). For information on how to use the integration, see [Using the integration for Rootly](/ingesting-data-into-cortex/integrations/rootly/using-the-integration-for-rootly).

## Why use the integration for Rootly

Rootly is an on-call and incident response platform. The integration brings that data into Cortex, so an entity's incident history and current on-call coverage sit alongside its ownership, dependencies, and Scorecard results.

The integration for Rootly brings the following into Cortex:

* **Incidents** - Active and historical incidents for an entity, with severity, status, and affected entities. Requires the **Incidents** category.
* **On-call schedules** - Who's on call now and who's on call next for an entity. Requires the **On-call** category.

You can also build Scorecard rules and Cortex Query Language (CQL) queries against incident and on-call data, and track incident frequency and mean time to resolution (MTTR) in Eng Intelligence.

### Setting up Rootly's Cortex integration first

Rootly has its own Cortex integration, configured from the Rootly side, that syncs your Cortex catalog into Rootly. When it's set up, each Rootly service carries the ID of its matching Cortex entity, and Cortex uses that ID to map Rootly incidents to the right entities. This is the most reliable way to connect the two platforms, so set it up before you configure the integration in Cortex. See [Rootly's Cortex integration docs](https://docs.rootly.com/integrations/cortex/overview) for setup instructions.

## Configuring Rootly

### Prerequisites

1. Users with the `Configure Integrations` permission can configure Rootly.
2. Create an [API token in Rootly](https://rootly.com/api#/). Make sure the Rootly user account represented by the token has admin permissions in Rootly.

### Installing Rootly in Cortex

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Rootly, then click **Install**. The Rootly side panel opens.
3. In the Rootly side panel, do the following:
   1. From the **Category** dropdown, select the types of data to import (required):

      * **Incidents** - Imports incidents with severity, status, and affected entities.
      * **On-call** - Imports on-call schedules, including who's on call now and next.

      For more information, see [Integration categories](/ingesting-data-into-cortex/integrations#integration-categories).
   2. Under **Configuration alias**, enter the alias you'll use to tie entity registrations to different configuration accounts (required).
   3. Under **API token**, enter your Rootly API token (required).
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

> [!NOTE]
>
> To modify an existing configuration, see [Modifying an integration configuration](/ingesting-data-into-cortex/integrations#modifying-an-integration-configuration).

> [!NOTE]
>
> If you configured Rootly in Cortex before October 27, 2026, your configuration has been moved to the new integration automatically, and you don't need to set it up again. To bring in on-call data, make sure the **On-call** category is selected on your configuration. See [Changing categories on an existing configuration](/ingesting-data-into-cortex/integrations#changing-categories-on-an-existing-configuration).

### Using multiple Rootly configurations

The Rootly integration supports multiple configurations. To add another:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Rootly, then click **Settings**.
3. In the upper-right corner of the page, click **Add configuration**.
4. Follow the steps in [Installing Rootly in Cortex](/ingesting-data-into-cortex/integrations/rootly#installing-rootly-in-cortex) above.

Each configuration requires an alias, which ties entity registrations to a specific account. If no alias is specified, Cortex uses the default configuration. To set a default:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Rootly, then click **Settings**.
3. Click the **pencil icon** next to a configuration.
4. Toggle on **Set as default**. If you only have one configuration, it's automatically set as the default.


# Connecting entities to Rootly
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/rootly/connecting-entities-to-rootly



PRIVATE BETA

> [!NOTE]
>
> Connecting entities to Rootly is in Private Beta. To request access, contact the [Cortex Customer Engineering](mailto:help@cortex.io) team.

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to connect Cortex entities to Rootly. For configuration instructions, see [Configuring the integration for Rootly](/ingesting-data-into-cortex/integrations/rootly). For what you can do once entities are connected, see [Using the integration for Rootly](/ingesting-data-into-cortex/integrations/rootly/using-the-integration-for-rootly).

There are two kinds of data you can connect:

* **Incidents (through Rootly services)** bring incident data into Cortex, so incidents appear on an entity's page and you can query them in CQL.
* **On-call (through Rootly services, teams, or schedules)** brings on-call data into Cortex, so you can see who's on call for an entity.

When an entity matches a Rootly service, Cortex uses that match for both incidents and on-call. On-call registrations for teams and schedules only affect on-call data.

## Connecting an entity to Rootly incidents

Each Rootly incident lists the services it affects. Cortex matches each of those services to an entity, checking in this order:

1. **A registration in the entity descriptor** - If an entity registers the Rootly service in its `x-cortex-rootly` block, Cortex uses that registration.
2. **The Cortex ID on the Rootly service** - If you've set up [Rootly's Cortex integration](/ingesting-data-into-cortex/integrations/rootly#set-up-rootlys-cortex-integration-first), each Rootly service stores the ID of its Cortex entity, and Cortex matches on it.
3. **The Rootly service name** - Cortex matches the service name against the entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag). The match isn't case-sensitive.

Cortex doesn't automatically match on Rootly service slugs. If neither the Cortex ID nor the service name lines up with an entity, register the service in the entity descriptor.

Incidents also appear on the pages of the Cortex teams responsible for them.

### Connecting incidents in the entity descriptor

You can register Rootly services by ID or slug.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

| Field | Description | Required |
| - | - | - |
| `id` | The ID of the Rootly service. Use either `id` or `slug`. | |
| `slug` | The slug of the Rootly service. Use either `id` or `slug`. | |

**Service ID**

```yaml theme={null}
x-cortex-rootly:
  services:
    - id: ASDF1234
```

**Service slug**

```yaml theme={null}
x-cortex-rootly:
  services:
    - slug: service-slug
```

## Connecting an entity to Rootly on-call schedules

Cortex links Rootly on-call to entities automatically in two ways:

* **Through services** - A Rootly service may have no escalation policy, which determines who's paged for that service. When a Rootly service matches an entity, Cortex shows who's on call for that service's escalation policy on the entity. Cortex matches services the same way it does for incidents: by an `x-cortex-rootly` registration, by the Cortex ID on the Rootly service, or by the service name. See [Connecting an entity to Rootly incidents](#connecting-an-entity-to-rootly-incidents).
* **Through teams** - Each Rootly schedule has an owning team. Cortex matches that team to a Cortex team, either by the Cortex ID that Rootly's Cortex integration stores on the team, or by matching the Rootly team name against the Cortex team's tag. The schedule links only to the entity that matched. In this case, it is only linked to the matched cortex team, not to the services the team owns.

To link schedules explicitly, register them in one of two ways:

* **By schedule** - Select one or more specific Rootly schedules to link directly to the entity.
* **By team** - Select a team from Rootly. Every schedule associated with that team is linked to the entity automatically, so new schedules for that team appear without additional configuration.

Link by team when the team owns the entity and you don't want to revisit the mapping each time its rotations change. Link by schedule when you need a specific rotation on the entity and not everything the team runs.

You can configure on-call from an entity page in Cortex, or in the YAML.

### Connecting from an entity's details page

1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. From the left sidebar, locate the **Connections** section, then select the **On-call** tab.
4. From the **Integration** dropdown, select Rootly.
5. Do one of the following:
   1. From the **Schedule name** dropdown, select a schedule to link to the entity.
   2. From the **Team name** dropdown, select a team to link to the entity.
6. Click **Save changes**.

### Connecting in the YAML

To register on-call in the YAML, add an `x-cortex-oncall` block to the entity's descriptor.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Registrations are made by ID, not by name.

On-call registrations have the following field definitions:

| Field | Description | Required? |
| - | - | - |
| `type` | Either `SCHEDULE` or `TEAM` | |
| `id` | ID of the Rootly schedule or team. | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support). | |

#### Schedules

To map a schedule to an entity, use the schedule's ID. You can find it in Rootly in the schedule's URL.

```yaml theme={null}
x-cortex-oncall:
  rootly:
    - type: SCHEDULE
      id: 018a6d0b-7d54-42c3-8770-46adc8e1300b
```

#### Teams

A `TEAM` registration maps every Rootly schedule owned by that team. To map a team, use the team's ID.

```yaml theme={null}
x-cortex-oncall:
  rootly:
    - type: TEAM
      id: 3f2c9a7e-1b4d-4e8a-9c6f-2d5b8e1a7c40
```

#### Schedules and teams

You can register both on the same entity, and map more than one of each. Use this when a team owns the entity but you also want a specific shared rotation on it:

```yaml theme={null}
x-cortex-oncall:
  rootly:
    - type: TEAM
      id: 3f2c9a7e-1b4d-4e8a-9c6f-2d5b8e1a7c40
    - type: SCHEDULE
      id: 018a6d0b-7d54-42c3-8770-46adc8e1300b
      alias: prod-account
```


# Using the integration for Rootly
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/rootly/using-the-integration-for-rootly



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for Rootly. For configuration instructions, see [Configuring the integration for Rootly](/ingesting-data-into-cortex/integrations/rootly). For instructions on connecting Rootly to entities, see [Connecting entities to Rootly](/ingesting-data-into-cortex/integrations/rootly/connecting-entities-to-rootly).

## Viewing incident data

You can view incident data in the incident list and on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

### Incident list

See every incident across your organization in one place, with metadata including severity, status, and affected entities.

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incident-list.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=13c406f0ee0dd97f918e37745856beb8)

**To access the incident list**:

1. From the main sidebar, expand **Integrations**, then select **Data**.
2. Select the **Incidents** tab.

The list is sorted by most recently opened incidents first.

#### Searching across and filtering the incident list

There are several ways to search and filter the list:

* To find specific incidents, use the search bar in the upper-right corner of the page and type to search.
* By default, the list sorts by most recently opened incident. Click **Opened** to reverse the order, or click **Name** to sort alphabetically instead.
* Click **Filter** to narrow down your list by date range, severity level, or status.

### Incidents on an entity's details page

View incidents in the following places on an entity's details page:

* On the **Overview** tab; active incidents are prominently displayed at the top of the page

  ![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incidents-overview.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=47597d54e017259b6923ed5d2cb541c2)
* In the left details sidebar, locate **Connections**, then select **Incidents**

  ![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incidents-side-panel.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=d81efeab515878e496af6c2a8c1ecda7)

## Viewing on-call information

### On-call shift data

View all on-call shifts ingested via the Rootly integration in a single place. This allows you to see exactly what data Cortex has brought in from the integration and what entities it's been linked to within Cortex.

**To access the on-call list**:

1. From the main sidebar, expand **Integrations**, then select **Data**.
2. Select the **On-call shifts** tab.
3. Do one of the following:
   * Select the **All** tab to view all on-call shifts in your workspace.
   * Select the **Mine** tab to view only your on-call shifts.

The list is sorted alphabetically by schedule name. Click a row to open a side panel showing who's on call now, who's on call next, and the teams the schedule is associated with.

![](https://mintcdn.com/cortex-290c0c42/HbTtnyKVq-sSUnnp/images/incident-on-call-tab.png?fit=max\&auto=format\&n=HbTtnyKVq-sSUnnp\&q=85\&s=d05a263f674f93fd29034b6c1fe71bf9)

#### Searching across and sorting the on-call list

To search and sort the list:

* Use the search bar in the upper-right corner of the page and type to search.
* By default, the list sorts alphabetically by schedule name. Click **Name** to sort from Z to A.

### On-call on an entity's details page

View current on-call information in the following places on an entity's details page:

* In the metadata sidebar in the **On-call now** block

  ![](https://mintcdn.com/cortex-290c0c42/IxDb4qc9F4yJyBqi/images/oncall-block.png?fit=max\&auto=format\&n=IxDb4qc9F4yJyBqi\&q=85\&s=143d3323e83228e4fd2ca4446c66c567)
* In the left details sidebar, locate **Connections**, then select **On-call**
  * Click a row to open a side panel showing who's on call now, who's on call next, and the teams the schedule is associated with.

    ![](https://mintcdn.com/cortex-290c0c42/0i_zoxXu6S5DvfC0/images/rootly-on-call.png?fit=max\&auto=format\&n=0i_zoxXu6S5DvfC0\&q=85\&s=3d5e63066c7feceeb755410455032ae1)

### Engineering homepage

View upcoming on-call rotations in the **My on-calls** block on your engineering homepage. Cortex shows on-call schedules up to six months out.

![](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/homepage-oncalls.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=891e6100fa27f48736a6b006120304fc)

## Creating Scorecard rules with Rootly data

### Incident expressions

CQL lets you write rules and queries against incident data. See the [CQL documentation](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Integrations\&path=Rootly) for the complete list of available incident expressions.

> [!NOTE]
>
> Create Scorecard rules using incident-based CQL expressions to track operational health. Common Scorecard rules built on incident data include:
>
> * Ensure services have had no critical incidents in the past 30 days.
> * Verify mean time to resolution meets your SLOs.

### On-call expressions

CQL lets you write rules and queries against on-call data. See the [CQL documentation](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Integrations\&path=Rootly\&path=On-call) for the complete list of available on-call expressions.

> [!NOTE]
>
> Create Scorecard rules using on-call based CQL expressions to track operational readiness, for example:
>
> * Verify that all production services have an on-call schedule configured.
> * Ensure critical services have on-call coverage before go-live.

## Incident metrics in Eng Intelligence

Incident metrics in [Eng Intelligence](/improve/eng-intelligence) are powered by the same unified data pipeline as the incident list, so the numbers stay consistent across Cortex. Eng Intelligence supports the following incident metrics:

* Incident frequency
* Mean time to resolution (MTTR)

## Viewing Rootly integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

> **I connected Rootly but no on-call data appears on my entity**
>
> Check that the **On-call** category is selected on your Rootly configuration. Then confirm the entity is connected to Rootly on-call: through a Rootly service that matches the entity, through a schedule's owning team, or through a `SCHEDULE` or `TEAM` registration. A Rootly schedule only has on-call coverage once an escalation policy in Rootly points to it, and a service only shows on-call if it has an escalation policy. If a schedule shows no coverage in Rootly, it won't show any in Cortex either.

> **I registered a team but see no schedules**
>
> A `TEAM` registration maps every schedule owned by that team in Rootly. If the team doesn't own any schedules, nothing maps. Register the schedule directly instead.

> **An incident exists in Rootly but doesn't appear on the entity in Cortex**
>
> Check that the incident lists the affected service in Rootly. Then confirm the service matches the entity, either through the Cortex ID from Rootly's Cortex integration, a service name that matches the entity's Cortex tag, or an `x-cortex-rootly` registration in the entity descriptor. Cortex doesn't automatically match on service slugs.


# Semgrep
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/semgrep



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Semgrep](https://semgrep.dev/) is static application security testing (SAST) tool that includes software composition analysis (SCA). It detects security vulnerabilities in your code and analyzes your open-source dependencies for vulnerabilities. You can use it to scan local repositories or integrate it into your CI/CD pipeline.

Integrating Semgrep with Cortex allows you to:

* Display the latest scans and vulnerability data [on entity details pages in Cortex](/ingesting-data-into-cortex/integrations/semgrep#viewing-semgrep-information-in-cortex)
* Create [Scorecards](/ingesting-data-into-cortex/integrations/semgrep#scorecards-and-cql) that track progress and drive alignment on projects involving Semgrep security data, allowing you to address and remediate vulnerabilities more efficiently

## How to configure Semgrep with Cortex

### Prerequisites

Before getting started:

* Create an [API token in Semgrep](https://semgrep.dev/api/v1/docs/#section/Introduction) with [`GET scan details`](https://semgrep.dev/api/v1/docs/#tag/Scan/operation/semgrep_app.foundations.scan.handlers.scan.openapi_get_scan) and [`GET List code or supply chain findings`](https://semgrep.dev/api/v1/docs/#tag/Finding) permissions.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Semgrep settings page](https://app.getcortexapp.com/admin/integrations/semgrep):
   * Click **Integrations** from the main nav. Search for and select **Semgrep**.
2. Click **Add configuration**.
3. Configure the Semgrep integration form:
   * **Alias**: Enter an alias for this integration.
   * **API key**: Enter the value of the API token you created in Semgrep.
   * **Organization ID**: Enter your organization ID for Semgrep.
   * **Organization slug**: Enter your organization slug for Semgrep.
4. Click **Save**.

After saving your configuration, you are redirected to the Semgrep integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Semgrep was configured properly.

## How to connect Cortex entities to Semgrep

### Match entity names to Semgrep projects

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-service`) as the "best guess" for Semgrep projects. For example, if your entity name is "My Service" or your tag is `my-service`, then the corresponding project name in Semgrep should also be "My Service" or `my-service`.

If your Semgrep project names don’t cleanly match the Cortex entity name or tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Under the `x-cortex-semgrep` block in an [entity's YAML](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file), you can define the projects you want based on the Semgrep project ID. For example:

```yaml theme={null}
x-cortex-semgrep:
  projects:
  - alias: my_org 
    projectId: 1234567
  - alias: other_org
    projectId: 7654321
```

## Using the Semgrep integration

### Viewing Semgrep information in Cortex

Semgrap vulnerabilities and scans appear on [entity details pages](/ingesting-data-into-cortex/entities-overview/entities/details):

* in the **Code & security** block in the entity's overview:

  ![See Semgrep data on an entity's overview.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/semgrep-entity-overview.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=200503a264a0b066dcb12e1a365955ee)
* in the entity's sidebar in **Code & security.**

  * This page contains scan results and vulnerability metrics from Semgrep. Click **Filter** at the top of the vulnerability list to filter by severity.

  ![On an entity, click Code & security > Semgrep to view vulnerability details from Semgrep.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/semgrep-entity-details.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=8e0aa6678b2bb2a6df7a4411257ab27d)

### Scorecards and CQL

With the Semgrep integration, you can create Scorecard rules and write CQL queries based on Semgrep projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Semgrep project is set**
>
> Check if entity has a registered Semgrep project in its entity descriptor.
>
> **Definition:** `semgrep (==/!=) null: Boolean`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to make sure entities are associated with a Semgrep project:
>
> ```
> semgrep != null
> ```
>
> Setting a `semgrep != null` rule can also serve as a secondary check to confirm an entity is synced properly with Semgrep and is reporting frequently.

> **List vulnerabilities**
>
> List of Semgrep vulnerabilities by severity or type.
>
> **Definition:** `semgrep.vulnerabilities()`
>
> **Example**
>
> You can write a rule to verify an entity has fewer than 10 vulnerabilities:
>
> ```
> semgrep.vulnerabilities().length < 10
> ```

> **Get scan results for an entity**
>
> Get Semgrep scan results for an entity.
>
> **Definition**: `semgrep.scans()`
>
> You could write a Scorecard rule to ensure an entity has fewer than 10 scans:
>
> ```
> semgrep.scans().length < 10
> ```
>
> You could write a rule to ensure an entity has had fewer than 10 new scans in the last week:
>
> ```
> semgrep.scans("firstSeen:-1w") <= 10
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Sentry
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/sentry



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Sentry](https://sentry.io/welcome/) is an application monitoring platform that helps developers identify, debug, and resolve issues.

Integrating Sentry with Cortex allows you to:

* [View errors on entity pages in Cortex](/ingesting-data-into-cortex/integrations/sentry#viewing-sentry-errors-on-an-entity), giving you insight into your entity's operational maturity
* [Pull a list of recent Sentry issues directly in Slack](/ingesting-data-into-cortex/integrations/sentry#using-the-cortex-slack-bot-with-sentry), using the Cortex Slack Bot
* Create [Scorecards](/ingesting-data-into-cortex/integrations/sentry#scorecards-and-cql) that include rules related to Sentry errors

## How to configure Sentry with Cortex

### Prerequisites

Before getting started:

* Create a [personal token](https://docs.sentry.io/api/auth/#user-authentication-tokens) in your Sentry user settings.
  * The token requires `Read` [permissions](https://docs.sentry.io/api/permissions/) for the **Issue & Event** and **Project** scopes.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Sentry settings page](https://app.getcortexapp.com/admin/integrations/sentry):
   * Click **Integrations** from the main nav. Search for and select **Sentry**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **Auth token**: Enter the personal token you generated in Sentry.
   * **Organization slug**: Enter your Sentry organization slug.
     * You can find this in your Sentry URL, e.g., `https://sentry.io/organizations/{SLUG}/issues/`.
   * **Host**: If using a self-hosted Sentry instance, enter the URL here *without* the API path (e.g., `bugsnag.getcortexapp.com`).
4. Click **Save**.

After saving your configuration, you are redirected to the Sentry integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Sentry was configured properly.

## How to connect Cortex entities to Sentry projects

### Discovery

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g., `my-entity`) as the best guess for Sentry projects. For example, if your Cortex tag is `my-entity`, then the corresponding project in Sentry should also be `my-entity`.

If your Sentry projects don't cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can define projects under the `x-cortex-sentry` block:

```yaml theme={null}
x-cortex-sentry:
  projects:
  - name: my-project
  - name: my-second-project
```

| Field | Description | Required |
| - | - | :-: |
| `name` | Project ID or slug defined in Sentry.Note that this is case sensitive. | **✓** |

## Using the Sentry integration

### Viewing Sentry errors on an entity

Error data will appear on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). In an entity's sidebar, click **Error tracking** to view detected issues for each Sentry project. At the top of the page, see a list of Sentry projects associated with an entity. Each project listed in Cortex links back to the [project details page in Sentry](https://docs.sentry.io/product/projects/project-details/).

Under the **Issues** header on the **Error tracking** page, you'll find a list of all issues related to the projects that Cortex detected in Sentry. Each issue in the list links back to that [issue's details page in Sentry](https://docs.sentry.io/product/issues/issue-details/). Cortex will pull in the title and tags for each issue.

**Events**

Sentry issues and events will also appear in an entity's event timeline, found under **Events** in the sidebar. This allows users to contextualize Sentry issues with other key data - like deploys or errors discovered from other integrations - during incidents or migrations.

### Retrieving issues in Slack

If you've also configured the Slack integration, you can ask the AI Assistant for an entity's recent Sentry issues. Mention `@Cortex` in a channel or direct message and ask a question like "Show me recent Sentry issues for payments-api," identifying the entity by its [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag).

For setup and usage details, refer to [Using the AI assistant](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#using-the-ai-assistant).

### Scorecards and CQL

With the Sentry integration, you can create Scorecard rules and write CQL queries based on Sentry projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Sentry project is set**
>
> Check if entity has a registered Sentry project.
>
> **Definition:** `sentry (==/!=) null`
>
> **Example**
>
> For a production readiness Scorecard, you can use this expression to make sure entities are linked to a Sentry project.
>
> ```
> sentry != null
> ```
>
> This can also serve as a way to confirm that entities are synced with Sentry and reporting frequently.

> **Number of events**
>
> Counts Sentry events for a given [custom query](https://docs.sentry.io/concepts/search/#query-syntax) **to a max of 1,000**.
>
> If no query is provided, the rule will count `unresolved` events by default.
>
> **Definition:** `sentry.numOfIssueEvents((<query>))`
>
> **Example**
>
> For a Scorecard focused on operational maturity, you can check for any unresolved issues that were first seen within a week.
>
> ```
> sentry.numOfIssueEvents("is:unresolved firstSeen:-1w") <= 10
> ```

> **Number of issues**
>
> Counts Sentry issues for a given custom query **to a max of 300**.
>
> If no query is provided, the rule will count `unresolved` issues by default.
>
> **Definition:** `sentry.numOfIssues((<query>))`
>
> **Example**
>
> For a Scorecard focused on operational maturity, you can pull in the number of Sentry issues to make sure entities are functioning as expected.
>
> ```
> sentry.numOfIssues() < 100
> ```
>
> For a Scorecard focused on code quality, you can write a more focused rule to make sure there haven't been any issues in production environments in the last week.
>
> ```
> sentry.numOfIssues("is:unresolved environment:[production,prod] lastSeen:-1w") < 2
> ```

> [!WARNING]
>
> The maximum number of Sentry events fetched for any query is 1,000, while the maximum number of issues fetched is 300.

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# ServiceNow
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/servicenow



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[ServiceNow](https://www.servicenow.com/) is a CMDB (configuration management database) to define, manage, automate and structure IT services. Cortex integrates with ServiceNow to provide engineers with better developer experience while adhering to governance standards. The integration syncs data between systems so both stay current.

Integrating your ServiceNow instance with Cortex allows you to:

* [Import teams](/ingesting-data-into-cortex/integrations/servicenow#syncing-ownership-from-servicenow) from ServiceNow and track ownership of entities
* [Automatically import domains and domain relationships](/ingesting-data-into-cortex/integrations/servicenow#enable-automated-import-of-domains-for-servicenow) from ServiceNow
* [Create Workflows](/ingesting-data-into-cortex/integrations/servicenow#workflows) to trigger ServiceNow actions, create tickets, or update records.
* [Use the ServiceNow Incidents plugin](/ingesting-data-into-cortex/integrations/servicenow#servicenow-incidents-plugin) to view ServiceNow incidents directly on entity details pages.
* Create [Scorecards](/ingesting-data-into-cortex/integrations/servicenow#scorecards-and-cql) that track progress and drive alignment on projects involving your ServiceNow teams

> [!TIP]
>
> Some Cortex users link business applications to ServiceNow projects, creating a clear map of ownership and project alignment. This enables visibility into which projects tie to which business apps, helping track migrations, risk programs, and compliance projects.

## How to configure ServiceNow with Cortex

### Prerequisites

Your ServiceNow user must have the `sn_cmdb_user` permission enabled.

You must have the `Configure Integrations` [permission](/configure/settings/managing-users/permissioning) in Cortex.

### Step 1: Configure the integration in Cortex

1. In Cortex, navigate to the [ServiceNow settings page](https://app.getcortexapp.com/admin/integrations/servicenow):
   * Click **Integrations** from the main nav. Search for and select **ServiceNow**.
2. Click **Add configuration**.
3. Configure the ServiceNow integration form:
   * **Instance name**: Enter your instance identifier.
     * This can be found in your instance URL, e.g., `<instance-identifier>.service-now.com`.
   * **Username** and **Password**: Enter your ServiceNow username and password.
4. Click **Save**.

Stay on this page for the next steps.

### Step 2: Configure table mappings

> [!NOTE]
>
> You can add more than one table mapping for the same domain relationship. This is useful if your ServiceNow domain hierarchy has more levels than a single table can represent, for example a division that rolls up through several layers of committees before reaching a business unit. Add a separate table mapping for each level, and Cortex builds the full hierarchy from the combined mappings.

1. On the ServiceNow integrations settings page, click **Add table mapping** on the right.
2. Configure the "Add table mapping" form:

   * Choose a mapping type: Select whether your data will map to Domains, Services or Teams.

   ![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202026-03-23%20at%204.18.04%E2%80%AFPM.png)

   * **Table name**: Enter a descriptive name.
   * **Table filter query**: Optionally, enter a table filter query.
   * **ID column name**: Enter the column name that contains the ID of the record.
   * **Name column name**: Enter the column name that contains the name of the record.
   * **Description column name**: Enter the column name that contains the description of the record.

   ![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202026-03-23%20at%204.04.21%E2%80%AFPM.png)

   * Note: To import teams, you must configure table mappings for the team, its team members, and their relationships.
3. Click **Preview.**
4. From the preview screen, you will be able to view summary counts, warnings, entity tree, and raw table data that was found based on the the configuration details. Once you've confirmed the data looks correct, you can select **save**.

## How to connect Cortex entities to ServiceNow

To import entities from ServiceNow, follow the steps described below.

### Import entities from ServiceNow

See the documentation on:

* [Importing teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#importing-teams-from-an-integration)
* [Importing services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services#importing-services-from-an-integration)
* [Importing domains](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains#importing-domains-from-an-integration)
  * You can [enable automated import of domains](/ingesting-data-into-cortex/integrations/servicenow#enable-automated-import-of-domains-for-servicenow).
  * Domain relationships cannot be manually imported; these are automatically imported via the automatic import setting described below.

### Enable automated import of domains for ServiceNow

You must have the `Configure Settings` permission.

Enabling automated domain import ensures that your domain structure in Cortex stays up-to-date with your ServiceNow configuration.

1. In Cortex, go to the [ServiceNow settings page](https://app.getcortexapp.com/admin/integrations/servicenow).
2. Toggle the setting **on** to enable the automated import of any domains and domain relationships from ServiceNow.

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202026-03-23%20at%204.28.31%E2%80%AFPM.png)

The automatic sync runs daily at 2 p.m. UTC.

#### Manually sync domains

You must have the `Enable Relationship graph` permission.

To force a sync of newly-discovered domains:

1. Go to [**Tools > Relationship graphs**](https://app.getcortexapp.com/admin/graph) and select **Domains**.
2. Click the 3 dots icon in the upper right, then click **Sync**.

   ![](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/sync-dependencies.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=b1d362f5d6daf7b58cddfc7dc1eaa84b)

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

When an entity is connected to ServiceNow, the entity YAML will look like the following:

```yaml theme={null}
x-cortex-servicenow:
  services:
  - tableName: cortex-services
    id: 1
```

#### Syncing ownership from ServiceNow

To import teams, [configure the table mappings](/ingesting-data-into-cortex/integrations/servicenow#step-2-configure-table-mappings) to pull teams, team members, and their relationships from ServiceNow. After doing so, [follow the steps to import them](/ingesting-data-into-cortex/integrations/servicenow#import-entities-from-servicenow).

When an entity is owned by a ServiceNow team, the YAML will look like the following:

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: My ServiceNow Team
    provider: SERVICE_NOW
    description: This is a description for this owner # optional
```

The value for `name` should be the name of the team as defined in ServiceNow (case-sensitive).

Cortex syncs ServiceNow teams every day at 9 a.m. UTC. You don't need identity mappings for ServiceNow teams.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

## Using the ServiceNow integration

### Scorecards and CQL

With the ServiceNow integration, you can create Scorecard rules and write CQL queries based on ownership and team details.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity
>
> **Definition:** `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

### Workflows

After integrating, you can set up [Workflows](/streamline/workflows) to trigger actions in ServiceNow. See an example of this in Guides > Create ServiceNow incident.

### ServiceNow Incidents plugin

You can install a plugin that makes ServiceNow incidents more visible on your entity details pages:

![](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/servicenow-plugin.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=459e35fad0c29292616b8e503b7d8f9b)

Learn more about installing the plugin in [Cortex Plugin Marketplace](/streamline/plugins/marketplace#cortex-built-plugins). You must have the `Edit Plugins` permission.

### Background sync

Cortex conducts a background sync of ServiceNow domains, domain relationships, and services every day at 2 p.m. UTC. Teams sync separately, every day at 9 a.m. UTC.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Slack
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/slack

Configuring the integration for Slack

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Why use the integration for Slack

Slack is where your team already communicates. Connecting it to Cortex brings your ownership, standards, and alerts into the same place, so you spend less time switching tools.

With the Slack integration, you can:

* **Ask questions, get answers.** Query Cortex in natural language instead of clicking through the UI. Mention `@Cortex` and ask things like "Which entities do I own?" or "Show me all critical services failing the Production Readiness Scorecard."
* **Reach the right team faster.** Slack channels appear in the **Communications** block on entity details pages, so you always know where to go when you're coordinating work or responding to an incident.
* **Stay on top of what matters.** Get notified in Slack when Scorecard results change, when an Initiative deadline is coming up, and when your weekly entity performance summary is ready, so you don't have to watch a dashboard.
* **Enforce communication standards.** Make having a Slack channel part of your definition of production-ready. Write a Scorecard rule that checks whether an entity defines a Slack channel in its YAML, so every service is held to the same bar. Teams can see which entities are missing one, and you can attach the rule to an Initiative when you need a deadline.

## Configuring Slack

> [!WARNING]
>
> Interacting with Cortex in Slack requires the latest version of the [Cortex Slack app](/ingesting-data-into-cortex/integrations/slack#configuring-slack). If you installed the app before February 2025, you'll need to update it before you can chat with Cortex. Slack administrator permissions are required to perform the update.
>
> To install, go to the Slack settings (**Integrations > Slack > Settings**) in Cortex. Delete the existing configuration and reinstall following the prompts.

### Prerequisites

1. Users with the `Configure Integrations` permissions can configure Slack in Cortex.
2. You must be an admin in your Slack account.
3. The Slack account must not be linked to another Cortex tenant.

> [!WARNING]
>
> For on-premises Cortex instances, follow the manual configuration process. See [self-managed Slack](/self-managed/features/integrations/slack).

### Step 1: Configuring Slack in Cortex

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Slack, then click **Install**. The Slack side panel opens.
3. In the Slack side panel, click **Add to Slack**. The **Allow access** window opens.
4. From the **Workspace** dropdown, select your workspace.
5. Review the app permissions, then click **Allow**.
   * After signing in to Slack and granting permission for Cortex to access the Slack workspace, you are redirected to the Slack settings page in Cortex.
6. In the upper-right corner of the page, click **Test configuration** to test the connection. A successful connection means your integration is configured correctly.

> [!NOTE]
>
> Slack channels are cached and refreshed every four (4) hours, so newly added or updated channels may not appear immediately in the UI or on an entity's details page.

### Step 2: Configuring app settings

Follow the steps below to configure additional settings in the Cortex Slack app.

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Slack, then click **Settings**.
3. From the **Integration settings** tab, do any of the following:
   1. In the **Configurations** section:
      1. Click the **trash icon** to delete the current configuration.
   2. In the **Slack app settings** section:
      1. Click **Notification settings** to configure notifications to be sent via Slack for your organization. See [Managing Slack notifications](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#managing-slack-notifications) for more information.
      2. Click **Identity mappings** to map email addresses from your Slack workspace to email addresses of team members in Cortex, making sure the integration works as expected for users. See [Configuring identity mappings](/configure/settings/managing-users/identity-mapping) for more information.

## Privacy policy

Cortex retains basic Slack metadata like user IDs for the period necessary to fulfill the purposes outlined in our [Privacy Policy](https://www.cortex.io/legal/privacy-policy) unless a longer retention period is required or permitted by law, or where the Customer Agreement requires or permits specific retention or deletion periods.

To request to access, transfer, or delete data, you can reach out to the Cortex support team.

## AI disclosure

Cortex uses large language models (LLM) to generate responses to user queries within Slack. While we've designed the app to be helpful and accurate, AI-generated content can sometimes be incorrect, incomplete, misleading, or out of date. The model may occasionally produce responses that sound plausible but are factually wrong ("hallucinations"). Responses may contain factual errors, outdated information, or fabricated details presented confidently. The model does not have real-time knowledge of your organization's specific data unless explicitly provided in context. Output should be reviewed by a human before being used for decision-making, shared externally, or treated as authoritative. Cortex is not a substitute for professional advice (legal, financial, medical, or otherwise), and responses should not be relied upon as a sole source of truth for important decisions. We encourage users to independently verify any information provided by the app before acting on it.


# Slack integration FAQ and troubleshooting
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/slack/slack-integration-faq-and-troubleshooting



See common frequently asked questions and troubleshooting information below.

**General**

> **Can I disable some of the notifications I receive in Slack?**
>
> You can adjust your personal notification settings, but note that [some types of notifications cannot be disabled](/configure/settings/notifications#notifications-that-cannot-be-disabled).

> **Is the Slack integration required to add Slack channels to a team?**
>
> No, the Slack integration is not required to add channels to Cortex teams. You can [add any Slack channels](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#connecting-an-entity-to-a-slack-channel) without setting up the Slack integration or [via the API](/api/rest/teams) for a team’s metadata.

> **Why isn't my Slack channel showing up after I've added it to an entity's YAML configuration?**
>
> Slack channels are cached and refreshed every four (4) hours, so newly-added channels may not appear immediately in the UI.

**AI Assistant**

> **The AI assistant isn't responding to my messages**
>
> Ensure `@Cortex` has been invited to the channel. The assistant works in public and private channels, and via DMs. Make sure your Slack identity is also mapped. See [Configuring identity mappings](/configure/settings/managing-users/identity-mapping).

> **A user gets an access\_denied error when they mention @Cortex in Slack**
>
> The AI assistant requires a Cortex user account. This error usually means the person doesn't have one, or their Slack identity isn't mapped to their Cortex account. Confirm they have an active Cortex account, then check their identity mapping. See [Configuring identity mappings](/configure/settings/managing-users/identity-mapping).
>
> Turning off **Require Cortex account to use Cortex's Slack app** doesn't resolve this, because that setting applies to slash commands only.

> **The AI assistant lost context from earlier in the thread**
>
> Very long threads may exceed the conversation context window. If this happens, start a new thread and re-state the relevant context in your first message.

> **Can I make changes to Cortex via the AI assistant?**
>
> No. The app is read-only and only handles `GET` requests. It cannot modify or write data in your Cortex workspace. It can, however, provide guidance and syntax on using our API or updating data to help you make any changes!

> **Can I use the AI assistant with Microsoft Teams?**
>
> No. It is not currently compatible with Microsoft Teams.

> **Can users access information via the AI Assistant if they haven't logged in to Cortex?**
>
> No. Chatting with `@Cortex` in Slack always requires a Cortex user account with a mapped Slack identity, no matter how the Slack app settings are configured.
>
> The **Require Cortex account to use Cortex's Slack app** setting on the Slack integration settings page applies to slash commands only. Turn it off, and people without a Cortex account can run commands like `/cortex oncall` and `/cortex search`. Turn it on, and slash commands work only for users who have Cortex accounts. Either way, the AI assistant requires an account.
>
> To give someone access to the AI assistant, create a Cortex user account for them and confirm their Slack identity is mapped. See [Configuring identity mappings](/configure/settings/managing-users/identity-mapping).


# Using the integration for Slack
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant

How to use the integration for Slack in Cortex

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for Slack. For configuration instructions, see [Configuring the integration for Slack](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant).

> [!NOTE]
>
> Cortex conducts a background sync of Slack identities every day at 10 a.m. UTC.

## Connecting an entity to a Slack channel

Slack channels can be associated with entities in Cortex. Connect them through the Cortex UI or via YAML. Slack channels can also be added as [external documentation links](/ingesting-data-into-cortex/entities-overview/entities/external-docs) on an entity, even without configuring the integration.

### Connecting via the Cortex UI

1. Go to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).
2. In the upper-right corner, click **Configure entity**.
3. In the left entity menu, select **Communications**.
4. In the Slack channels section, click **Add**.
5. In the Slack side panel, do the following:
   * From the **Channel name** dropdown, type in or select your Slack channel's name (required).
   * Under **Description**, add a description to help others understand the purpose of the Slack channel.
   * Optionally, toggle on **Notifications** to receive notifications about this entity to the selected Slack channel.
6. Click **Add**.

### Connecting via YAML

#### **Editing the YAML**

For any entity type, you can define Slack channels in its YAML by name or ID, and turn notifications on or off for each channel. Those channels then appear on the entity's details page in Cortex, including the **Owners** block in the entity's sidebar.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

> [!NOTE]
>
> Slack channels are contacts, not owners. They show people where to reach an entity's owners, but they don't count toward ownership. To assign owners, use `x-cortex-owners`. See [Owners, on-call, and contact channels](/ingesting-data-into-cortex/entities-overview/entities/ownership#owners-on-call-and-contact-channels).

#### **When to define by channel name vs. channel ID**

Defining by name is more easily recognizable to users when viewing the entity's YAML. However, if a Slack channel's name is likely to change, it's better to define by ID as it won't break the entity's Slack link in Cortex.

Slack channels registered by ID alone in `x-cortex-slack` automatically resolve to their channel names in the entity sidebar. If no cached name is available, the channel ID is shown as a fallback.

**Defining by channel names**

It's recommended to register Slack channels by ID, rather than by name, as channel names may change over time. When you register a channel by ID, Cortex resolves the channel name automatically for display in the entity view.

```yaml theme={null}
x-cortex-slack:
  channels:
  - name: team-engineering
    notificationsEnabled: true
    description: Hangout spot for the engineering team.
```

| Field | Description | Required? |
| - | - | - |
| `name` | Slack channel name | |
| `notificationsEnabled` | Boolean to enable or disable notifications in Slack | |
| `description` | Description of the Slack channel | |

**Defining by channel IDs**

```yaml theme={null}
x-cortex-slack:
  channels:
  - id: ABCDEF123
    notificationsEnabled: true
    description: Hangout spot for the engineering team.
```

| Field | Description | Required? |
| - | - | - |
| `id` | Slack channel ID | |
| `notificationsEnabled` | Boolean to enable or disable notifications in Slack | |
| `description` | Description of the Slack channel | |

**Connect channels to entities without configuring the integration for Slack**

You can connect Slack channels to entities without configuring the Slack integration. Note that this method only provides a link to Slack from the entity; it won't include any features of the Slack integration, such as ownership tracking, notifications, Slack Bot, and the ability to use CQL to query Slack data.

Use [Slack's redirect link](https://api.slack.com/reference/deep-linking#deep-linking-into-your-slack-app) format, `https://slack.com/app_redirect?channel={channel_name}`, to add the link to an entity YAML, under the `x-cortex-slack` block. Make sure to replace `channel_name` with your Slack channel's name.

```yaml theme={null}
x-cortex-slack:
  channels:
  - name: https://slack.com/app_redirect?channel=team-engineering
```

### Viewing Slack information in Cortex

Slack channels appear at the top of an entity's details page in the **Communications** block. Click a channel name to go directly to that channel in Slack.

![](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/comms-block.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=74ec1f9aae0df3f30caafecbb5e5d3fb)

If a Slack channel is registered for an entity but isn't showing up on the entity's details page, check that the **Communications** block is enabled in the [entity's metadata sidebar](/ingesting-data-into-cortex/entities-overview/entities/details#configuring-the-entity-metadata-sidebar). If it's disabled, registered channels are hidden from view.

## Using the AI assistant

To use the AI assistant in Slack, you must be a member of your organization's Cortex workspace, and your Cortex account must be mapped to your Slack identity.

The AI assistant does two things: it answers questions in natural language, and it delivers notifications.

**Natural-language chat**

Mention `@Cortex` in a channel or direct message and ask a question in plain language, such as "Which services does my team own?" This works best for open-ended or analytical questions. Cortex responds in a thread. See Cortex's [prompt library](/get-started/cortex-ai-assistant/library) for more examples.

To ask a follow-up, reply in that same thread. Cortex keeps the context of the conversation, so you can drill down without repeating information. Context is scoped to the thread: a new top-level message starts a fresh conversation with no prior context.

The AI assistant is read-only. It can query Cortex, but it can't make changes or write data.

When you mention `@Cortex`, Cortex:

1. Interprets your question.
2. Determines which Cortex API endpoints to call.
3. Retrieves the relevant data from your Cortex workspace.
4. Returns a formatted response in Slack.

Each response includes reaction options. React with `:thumbs_up:` or `:thumbs_down:` to rate the answer. Cortex uses this feedback to improve future responses.

**Notifications**

The AI assistant also delivers Scorecard, Initiative, and weekly summary notifications to users and channels. See [Managing Slack notifications](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#managing-slack-notifications) below.

### Adding the AI assistant to a Slack channel

You must add the AI assistant to a channel before you can use it there. Both public and private channels are supported.

1. Open the Slack channel where you want to add the app.
2. Type `@Cortex` and press **Enter**.

   Slack prompts you to take action.
3. Click **Add them**.

   The AI Assistant is added to the channel.

### Available capabilities

The following API endpoints are accessed when chatting with Cortex:

| Capability | Description |
| - | - |
| **Entity details** | Look up ownership, metadata, and custom data for any entity |
| **Entity descriptors** | View and list entity descriptors (YAML definitions) |
| **Dependencies** | List incoming and outgoing dependencies for an entity |
| **Docs search** | Look up and access information in Cortex docs, as well as CQL formatting |
| **On-call** | Check who is currently on-call for an entity |
| **Scorecards** | List Scorecards, view scores, and get next-step recommendations |
| **Initiatives** | List and inspect Initiatives and their progress |
| **Relationships** | Explore entity relationships and relationship types |
| **Team details** | View team membership, sourcing, and contact channels |
| **Workspace context** | Query "my" entities and how they perform against Scorecards |
| **Eng Intelligence metrics / traces** | Query DORA metrics, incident trends, PR data, and other engineering performance indicators |
| **Deployments** | Search deployments across the workspace by environment, type, entity, and time range; list available deployment environments |

## Creating Scorecard rules and writing CQL queries with the Slack integration

See examples below.

> **Check if Slack channel is set**
>
> Checks if an entity has a registered Slack channel in its entity descriptor.
>
> **Definition** -  `slack (==/!=) null`
>
> **Example**
>
> For a Scorecard focused on onboarding entities, you can define a rule to make sure each entity has a registered Slack channel:
>
> ```
> slack != null
> ```
>
> Defining a rule to make sure a Slack channel is set is a good way to make sure that users can reach out to entity owners for more information or if an issue arises.

> **Number of Slack channels**
>
> Counts the number of Slack channels registered for a given entity.
>
> **Definition** -  `slack.channels().length`
>
> **Example**
>
> Similar to `slack != null`, you can use this expression to write a rule checking that entities are linked to a Slack channnel:
>
> ```
> slack.channels().length > 0
> ```
>
> This rule makes sure that there is at least one Slack channel set.

> **Total number of members across Slack channel**
>
> Counts the total number of members across all registered Slack channels.
>
> **Definition** -  `slack.numOfMembers()`
>
> **Example**
>
> You can use this expression in the Query Builder to find entities linked to empty Slack channels:
>
> ```
> slack.numOfMembers() < 1
> ```
>
> If an entity is linked to an empty Slack channel, it might indicate a gap in your notification process.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer).

## Managing Slack notifications

Slack notifications are controlled at two levels:

* **Workspace settings** - In Cortex, admins (or users with the `Configure Workspace Notification Settings` permission) can enable or disable Slack as a delivery channel for each notification type. This determines which notifications are available to send via Slack across the workspace.
  * Note that if a notification type is disabled at the workspace level, users won't be able to opt into it in their personal settings.
* **Personal settings** - Individual users can then choose which of the available Slack notifications they want to receive in their own personal notification settings.

**How notifications are routed**

Notifications are delivered by the integration and are routed based on their type:

* **User-based notifications** are sent as direct messages to the relevant user.
* **Team-based notifications** are sent to the Slack channel associated with a team.
* **Entity-based notifications** are sent to the Slack channel associated with an entity.

Notifications can be delivered to private Slack channels, but the Cortex AI assistant must be a member of the channel for messages to come through.

Additionally, the AI assistant sends user-based and team-based weekly reports. The user-based weekly report summarizes how their entities are tracking against Scorecards and Initiatives. The team-based report delivers the same summary for entities owned by that team.

See [Notifications](/configure/settings/notifications) for more information.

## Viewing Slack integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

Integration logs provide visibility into the activity between Cortex and Slack, making them a useful first stop when troubleshooting. You can use them to investigate failed notifications, confirm that webhooks are being delivered, and verify that recent configuration changes are working as expected.

1. From the main sidebar, select **Integrations**.
2. Locate Slack, then click **Settings**.
3. Select the **Logs** tab. Note that logs are retained for 7 days.

See [Troubleshooting with integration logs](/ingesting-data-into-cortex/integrations#troubleshooting-with-integration-logs) for more information.


# Snyk
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/snyk



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Snyk](https://snyk.io/) is a cybersecurity platform that scans for and surfaces vulnerabilities across your codebase.

Integrating Snyk with Cortex allows you to:

* [View vulnerabilities on entity pages in Cortex](/ingesting-data-into-cortex/integrations/snyk#viewing-snyk-vulnerabilities-on-an-entity), quickly connecting issues to entities and their owners
  * Enhance the Snyk experience by aggregating issues into an entity's event timeline so they can be understood in the context of other events, like deploys and on-call incidents
* Use [Scorecards](/ingesting-data-into-cortex/integrations/snyk#scorecards-and-cql) to measure entity quality based on Snyk data and drive quality improvements to your security practices

## How to configure Snyk with Cortex

### Prerequisites

Before getting started:

* Create a [Snyk API token](https://docs.snyk.io/snyk-api/authentication-for-api). The token will need the following read permissions:
  * `View Organization Reports`: Lists reporting issue counts.
  * `View Organization`: Allows Cortex to get a flattened list of all projects across all orgs.
  * `View Project History`: Allows Cortex to get project history.
  * `View Project`: Lists issues for a project.

### Configure the integration in Cortex

Once you've created an API token in Snyk, you can create a configuration from [Snyk settings](https://app.getcortexapp.com/admin/settings/snyk).

1. In Cortex, navigate to the [Snyk settings page](https://app.getcortexapp.com/admin/integrations/snyk):
   * Click **Integrations** from the main nav. Search for and select **Snyk**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **API token**: Enter the API token you generated in Snyk.
   * **Region**: Enter the Snyk [region](https://docs.snyk.io/working-with-snyk/regional-hosting-and-data-residency#what-regions-are-available) where your data is hosted. The default region is USA.
4. Click **Save**.

After saving your configuration, you are redirected to the Snyk integration settings page in Cortex. On this page, you'll see a list of detected organizations pulled from Snyk, along with the unique Snyk ID and internal name associated with each organization.

## How to connect Cortex entities to Snyk projects

### Discovery

Cortex uses the Git repository as the "best guess" for the corresponding Snyk project since Snyk projects are connected to repositories. Cortex will search for all Snyk projects across all Snyk organizations and pull in projects associated with the same repository. For example, if the GitHub repo associated with your Snyk instance is `my-org/repo`, then the entities in Cortex should also be associated with `my-org/repo`.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can define projects under the `x-cortex-snyk` block:

```yaml theme={null}
x-cortex-snyk:
  projects:
    - organization: org-name
      projectId: 01234567-e65f-4b7b-a8b1-5b642894ec37
      source: CODE
```

| Field | Description | Required |
| - | - | :-: |
| `organization` | The `organizationID` or `organizationSlug` in Snyk | **✓** |
| `projectId` | The `projectID` defined in Snyk | **✓** |
| `source` | [Enum field](https://en.wikipedia.org/wiki/Enumerated_type) that can be set to either `CODE` or `OPEN_SOURCE` to indicate the Snyk product type; defaults to `OPEN_SOURCE` when not set | |

You can define `organization` with the organization ID or its slug in Snyk.

## Using the Snyk integration

### Viewing Snyk vulnerabilities on an entity

Once the Snyk integration is set up, you'll be able to find information about vulnerabilities for each entity linked to a discovered repo.

#### Entity page overview

On an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details) overview, see vulnerabilities listed under the **Code & security** block. Within this block, issues and vulnerabilities are grouped by severity: `Critical`, `High`, `Medium`, and `Low`. Click into any of these to open a list of all applicable issues and vulnerabilities.

#### Entity code & security sidebar

In an entity's sidebar, click **Code & security > Snyk** to view detected issues and vulnerabilities from Snyk, including the associated organization name and project name.

Because Snyk aggregates problems as "issues," data pulled in from Snyk will be listed as **issues**, while data pulled in from a Git source will be listed as **vulnerabilities**.

Vulnerabilities pulled from Git sources display the project name and a severity tag. Each issue pulled from Snyk displays the following information, when available:

* Title
* Issue ID (linked to the issue in Snyk)
* Publish date
* Severity tag
* Priority score tag

**Event timeline**

Issues from Snyk and vulnerabilities detected in Git appear in the entity's event timeline, which you can find from the **Events** link in the entity's sidebar. Issues and vulnerabilities display alongside other events, such as K8s changes, Git commits, and on-call incidents.

### Scorecards and CQL

With the Snyk integration, you can create Scorecard rules and write CQL queries based on Snyk projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Snyk project is set**
>
> Check if entity has a registered Snyk project in its entity descriptor. If no registration exists, but there is a Git repository registration, Cortex will try to automatically detect which corresponding Snyk project is associated with a given entity.
>
> **Definition:** `snyk (==/!=) null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to make sure entities are associated with Snyk project - without this, Cortex won't pick up data about issues from Snyk.
>
> ```
> snyk != null
> ```
>
> Setting a `snyk != null` rule can also serve as a secondary check to confirm an entity is synced properly with Snyk and is reporting frequently.

> **Number of Snyk issues**
>
> List all [aggregated issues](https://snyk.docs.apiary.io/#reference/projects/aggregated-project-issues/list-all-aggregated-issues) for a given entity's Snyk project.
>
> * Project registration
> * Aggregated issues for an entity's project
> * Details about issues (when available)
>   * CVSS score
>   * Disclosure time
>   * Exploit maturity
>   * Issue ID
>   * Language
>   * Nearest fixed version
>   * Original severity
>   * Package name
>   * Priority score
>   * Publication time
>   * Severity
>   * Type
>   * URL
>   * Boolean characteristics:
>     * Fixable or partially fixable
>     * Ignored
>     * Malicious
>     * Patchable or patched
>     * Pinnable
>     * Upgradable
>
> **Definition:** `snyk.issues().length`
>
> **Example**
>
> The Scorecard's top level might include a rule to ensure that entities have a low number of Snyk issues.
>
> ```
> snyk.issues().length < 3
> ```
>
> To indicate progress over time and incentivize further improvement, you could set an intermediate rule with a slightly higher count of Snyk issues.
>
> ```
> snyk.issues().length < 5
> ```
>
> If an entity has a Snyk project set and only one or two issues, it will achieve the highest level by these standards. An entity with a Snyk project set and three or four issues will achieve the next-highest level, while an entity with a Snyk project set and five or more issues will achieve the lowest level. Entities without a Snyk project will not achieve any level, regardless of how many issues they have.
>
> You can also write more complex rules to set more specific standards. Instead of setting a rule for a moderate number of Snyk issues, you could check that entities have no outstanding critical issues.
>
> ```
> snyk.numOfIssues(severity=["CRITICAL"], fixability=["FIXABLE"]) <= 0
> ```

> [!WARNING]
>
> Snyk does not currently support aggregated issues in regions outside of the U.S.A. Please use `.issues()` rather than `.numOfIssues()` if in a non-U.S.A. region.

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex fetches issues and vulnerabilities from Snyk and Git sources in real time. Depending on the volume of data, it may take additional time for the data to load on an entity page.

Projects from Snyk are synced every 6 hours.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# SonarQube
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/sonarqube



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[SonarQube](https://www.sonarsource.com/products/sonarqube/) is an open-source platform that empowers developers to write clean and safe code by continuously inspecting code quality and reviewing for bugs, vulnerabilities, and code duplication.

Integrating SonarQube with Cortex allows you to:

* Pull in code smells, bugs, code coverage, vulnerabilities, and custom metrics on [entity details pages](/ingesting-data-into-cortex/entities-overview/entities/details)
* Create [Scorecards](/standardize/scorecards) that track progress and drive alignment on projects involving your SonarQube projects

This integration is supported for both SonarQube Server and SonarQube Cloud.

## How to configure SonarQube with Cortex

### Self-hosted prerequisites

If you’re using a self-hosted instance of SonarQube, you’ll need to verify that your Cortex instance is able to reach the SonarQube instance.

If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your SonarQube instance.

### Configure the integration

There are two options for integrating SonarQube: the default configuration method and Cortex Axon Relay, a relay broker allows you to securely connect your on-premises SonarQube data.

> **Default**
>
> **Configure SonarQube with the default method**
>
> **Prerequisites**
>
> Before getting started, create a SonarQube user token:
>
> * [SonarQube Server token instructions](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/managing-tokens/)
> * [SonarQube Cloud token instructions](https://docs.sonarsource.com/sonarqube-cloud/managing-your-account/managing-tokens/)
>
> **Configuration**
>
> 1. In Cortex, navigate to the [SonarQube settings page](https://app.getcortexapp.com/admin/integrations/sonarqube).
>
> * Click **Integrations** from the main nav. Search for and select **SonarQube**.
>
> 2. Click **Add configuration**.
>
> 3. Configure the SonarQube integration form:
>
> * **Account alias**: Enter the alias you will use to tie entity registrations to different configuration accounts.
> * **Token**: Enter your user token from SonarQube.
> * **SonarQube URL**: Enter the URL for your SonarQube instance.
>   * For example, `https://sonarcloud.io` if you are on SonarQube Cloud, or `https://sonarqube.mycompany.com` if your organization has their own instance.
>
> 4. Click **Save**.

> **Axon Relay**
>
> **Configure SonarQube with Cortex Axon Relay**
>
> See [Internally hosted integrations](/ingesting-data-into-cortex/integrations/axon-relay) for instructions. Make sure to follow the SonarQube-specific instructions for the docker-compose.yml file.

#### Integrate via custom webhook

If you’re unable to expose your SonarQube instance to be reachable by Cortex, you can set up a [custom integration webhook](/ingesting-data-into-cortex/integrations/webhook). To learn more about SonarQube webhooks, visit their [webhook documentation](https://docs.sonarqube.org/latest/project-administration/webhooks/).

## How to connect Cortex entities to SonarQube projects

### Discovery

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" for SonarQube component key. For example, if your Cortex tag is `my-entity`, then the corresponding component key in SonarQube should also be `my-entity`.

If your SonarQube component key doesn't cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

> [!WARNING]
>
> If you’re using build-system tooling to push analysis to SonarQube, the plugin (e.g. Gradle, Maven) may be automatically generating a project key that’s different from the repo name.

### Connect entities via YAML or the Cortex UI

> **Cortex UI**
>
> **Connect SonarQube entities via the Cortex UI**
>
> 1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details) in Cortex.
> 2. In the upper right corner, click **Configure entity**.
>
>    ![In the upper right side of an entity, click 'Configure entity.'](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/configure-entity-team.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=51dcaf582d93349b8f5ac706ee913e5c)
> 3. Click the **Code quality** link in the sidebar.
>
>    ![Click Code quality, then enter your SonarQube project details.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/sonarqube-ui.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=694ff735bfa324d1894f1faf6d7b310b)
> 4. In the center of the page, configure the details for your SonarQube project:
>    * **Alias**: If you have multiple configurations, select the one that this project is associated with.
>    * **Project**: Enter the project's name.
> 5. Click **Save changes**.

> **Entity YAML**
>
> **Editing the entity descriptor**
>
> When managing entities via the [YAML entity descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file), you can configure SonarQube projects under the `x-cortex-static-analysis` block:
>
> ```yaml theme={null}
> x-cortex-static-analysis:
>   sonarqube:
>     project: sonar-project-key
>     alias: sonarqube-alias
> ```
>
> | Field | Description | Required |
> | - | - | :-: |
> | `project` | Project key defined in Sonarqube | **✓** |
> | `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support) | |

> [!WARNING]
>
> Cortex only supports one SonarQube project per entity.

## Using the SonarQube integration

### View SonarQube data on entity pages

Once the integration is established, data from SonarQube will be available in the **Code & security** page in an [entity's sidebar,](/ingesting-data-into-cortex/entities-overview/entities/details#entity-details-sidebar) as well as under the Overview tab. You can pull in data on **code smells, bugs, code coverage, vulnerabilities, and any custom metrics** available through Sonar. You can read more about metric definitions in Sonar's [documentation](https://docs.sonarsource.com/sonarqube/latest/user-guide/metric-definitions/).

* Metrics
  * Complexity
  * Duplications
  * Issues
  * Maintainability
  * Quality gates
  * Reliability
  * Security
  * Size
  * Tests
* Code freshness
* Code coverage

### Scorecards and CQL

With the SonarQube integration, you can create Scorecard rules and write CQL queries based on SonarQube projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Analysis freshness**
>
> Duration since the last analysis was uploaded to SonarQube for a given project (with granularity of days).
>
> **Definition:** `sonarqube.freshness()`
>
> **Example**
>
> For a Scorecard focused on operational readiness, you can use this expression to evaluate the freshness of static analysis metrics from SonarQube.
>
> ```
> sonarqube.freshness() <= duration("P7D")
> ```
>
> This rule checks that an analysis has been uploaded to SonarQube within the past week, which developers can use to make sure the metrics being pulled aren't stale.
>
> This same rule would work in a security Scorecard - by making sure a SonarQube analysis has been uploaded within the last seven days, you make sure teams are monitoring for compliance to coding rules.

> **Metric**
>
> Query metrics generated by static analysis of your projects and sent to SonarQube:
>
> * Alert status
> * Bugs
> * Code smells
> * Coverage
> * Duplicated lines
> * Duplicated lines density
> * Lines of code
> * New blocker violations
> * New bugs
> * New code smells
> * New coverage
> * New security hotspots
> * New violations
> * Reliability rating
> * Security hotspots
> * Security rating
> * Security review rating
> * SQALE rating
> * Vulnerabilities
>
> **Definition:** `sonarqube.metric("<metric>")`
>
> **Examples**
>
> **Development maturity Scorecard**
>
> **Code coverage**
>
> For a Scorecard focused on development maturity, you can set a rule to make sure entities have greater than 80% code coverage.
>
> ```
> sonarqube.metric("coverage") > 0.80
> ```
>
> Developers can then immediately identify entities that are falling behind to make improvements to testing effectiveness. This Scorecard can also give users a more comprehensive sense of how well code is being tested, and where gaps exist.
>
> This rule also serves as a secondary check that a given entity is hooked up to SonarQube and reporting frequently.
>
> **Security Scorecard**
>
> **Vulnerabilities**
>
> You can also use the `sonarqube.metric("<metric>")` expression to write a rule for a security Scorecard, making sure production entities aren't deployed with a high number of security vulnerabilities. In an initial level of a Scorecard, you might write a rule to enforce 2 or less vulnerabilities:
>
> ```
> sonarqube.metric("vulnerabilities") <= 2
> ```
>
> Sonar recommends 0 vulnerabilities to achieve an A rating for Security, so a higher level in your Scorecard could enforce 0 vulnerabilities:
>
> ```
> sonarqube.metric("vulnerabilities") = 0
> ```
>
> **Code coverage**
>
> In a security Scorecard, you could also use the following expression to evaluate code coverage. The [Sonar way quality gate](https://docs.sonarsource.com/sonarqube-server/quality-standards-administration/managing-quality-gates/introduction-to-quality-gates) requires code coverage to be at 80% or higher:
>
> ```
> sonarqube.metric("coverage") > 80
> ```
>
> Entities with low code coverage scores are more likely to be vulnerable to attack, so a lower threshold might make sense for certain security Scorecards.
>
> **Security hotspots**
>
> Rules focused on [security hotspots](https://docs.sonarsource.com/sonarqube/9.8/user-guide/security-hotspots/#what-is-a-security-hotspot) can also make sure entities are operating with minimal security issues. Hotspots highlight a security-sensitive piece of code where the overall application security may not be impacted; Sonar recommends reviewing 100% of hotspots. In the following rule example, you can aim for less than 2 hotspots that need review:
>
> ```
> sonarqube.metric("security_hotspots") < 2
> ```

> **Project existence**
>
> SonarQube project exists for an entity.
>
> **Definition:** `sonarqube != null`
>
> **Example**
>
> For a Scorecard focused on operational readiness, you can write a rule to make sure an entity has an associated SonarQube project.
>
> ```
> sonarqube != null
> ```
>
> Because having a SonarQube project set would be key for an entity to be evaluated via other SonarQube-related expressions, this rule would make sense in a Scorecard's initial level.

> **Issues**
>
> Query issues identified by static analysis of your projects and sent to SonarQube, including bugs, vulnerabilities, code smells, and more. If the statuses are not filled in, they will default to "OPEN" and "REOPENED" statuses to prevent fetching of resolved issues.
>
> Sonar recommends targeting 0 new issues.
>
> **Definition:** `sonarqube.issues("<types>", "<rules>", "<severities>", "<statuses>", "<lookback>"): List<SonarqubeIssue>`
>
> **Example**
>
> You can write a rule to check that an entity has fewer than 3 major java:S2142 bugs:
>
> ```
> sonarqube.issues(types = ["bug"], rules = ["java:S2142"], severities = ["major"]).length <= 3
> ```
>
> **Code smells**
>
> In an initial level of a Scorecard, you could write a rule to check that an entity has fewer than 5 minor code smells:
>
> ```
> sonarqube.issues(types = ["code_smell"], severities = ["minor"]).length < 5
> ```
>
> In higher levels of the Scorecard, you could verify that the entity has 0 code smells, per Sonar's recommended best practices:
>
> ```
> sonarqube.issues(types = ["code_smell"]).length < 1
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Troubleshooting and FAQ

See frequently asked questions below.

> **Does Cortex support SonarCloud?**
>
> Yes. You can integrate with SonarCloud by following the same steps as integrating with SonarQube. In the URL field, use your `https://sonarcloud.io/` URL. You can also use multi-account support to add a self-hosted or SonarCloud instance by adding the URL for that instance during configuration.

> **I’m seeing “Socket timed out when trying to connect to SonarQube” for all of my entities in Scorecards.**
>
> This means that Cortex is unable to talk to your SonarQube instance. Make sure that your instance is running and accessible to Cortex.

> **I’m using Gradle and I’ve verified that my project is in SonarQube, but Cortex is still showing me an error.**
>
> Gradle automatically generates a project key which is equal to `[$:]$`. As a result, automatic discovery won’t work. You’ll need to override the project key in your Cortex [entity descriptor](/ingesting-data-into-cortex/integrations/sonarqube#entity-descriptor).

> **My project is in Sonar and Cortex is able to talk to SonarQube, but my score isn’t showing up.**
>
> Try the following troubleshooting steps:
>
> 1. Make sure the project key in your YAML is exactly the same as the key in SonarQube.
> 2. Verify that the scores are in the “default branch” in SonarQube. If your scores are showing up in a `branch-a` in SonarQube, but your SonarQube default branch is `main`, Cortex will not be able to retrieve the scores.
> 3. Run the following curl command and verify there are metrics showing up in the response:
>
> ```bash theme={null}
>     curl -v -u : "https://[SONARQUBE HOST]/api/measures/
>     component_tree?component=[SONARQUBE PROJECT KEY]&metricKeys=ncloc,coverage"
> ```

> **What if I want to send custom data, but I don't have control over the integration touchpoint?**
>
> If you don't have control of or access to the integration touchpoint (for example, if you're using a SonarQube notification webhook) you'll want to use the API to send custom data. You can find information on sending data to a custom data webhook [here](/api#tag/Custom-Data).

> **Why might I see the SonarQube connection error `Component key not found`?**
>
> For SonarQube (and all integrations), Cortex will map the Cortex tag defined in the cortex.yaml for a given entity. For SonarQube specifically, the tag must **exactly match** the project ID in SonarQube. If these are not one-to-one, we recommend using the override detailed above to define the proper mapping for project ID and entity name.

> **Why might I see the error `Sonarqube: Fail to request url` on my integration page or a `validity check failed` error while creating a Workflow?**
>
> This can happen if your external DNS certificate expired. Ensure that any certificates you're using are valid.


# Splunk Observability Cloud (SignalFx)
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/splunk-observability



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

Splunk Observability Cloud ([formerly known as SignalFx](https://www.splunk.com/en_us/newsroom/press-releases/2019/splunk-closes-acquisition-of-cloud-monitoring-leader-signalfx.html)) is a monitoring and analytics platform that allows customers to evaluate, visualize, automate, and alert on metrics.

Integrating Splunk Observability Cloud with Cortex allows you to:

* [View SLO information on entity pages](/ingesting-data-into-cortex/integrations/splunk-observability#viewing-slo-information-on-an-entity) in Cortex
* Create [Scorecards](/ingesting-data-into-cortex/integrations/splunk-observability#scorecards-and-cql) that include rules related to your Splunk Observability Cloud SLOs

## How to configure Splunk Observability Cloud with Cortex

### Prerequisites

Before getting started:

* Create an [access token](https://docs.splunk.com/observability/en/admin/authentication/authentication-tokens/org-tokens.html#create-an-access-token) in Splunk.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Splunk Observability settings page](https://app.getcortexapp.com/admin/integrations/splunk-observability):
   1. Click **Integrations** from the main nav. Search for and select **Splunk Observability**.
2. Click **Add configuration**.
3. Configure the integration form:
   * **Realm**: Enter your Splunk Observability realm.
     * You can find it in the URL for your instance, e.g., `https://app.{REALM}.signalfx.com/#/metrics`.
   * **Access token**: Enter the access token you generated in Splunk.
4. Click **Save**.

After saving your configuration, you are redirected to the Splunk Observability integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Splunk Observability was configured properly.

## How to connect Cortex entities to Splunk Observability SLOs

### Editing the entity descriptor

SLOs can be defined in the [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file).

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can pull in data about SLOs and manage them in Cortex by defining relevant SLIs through queries, along with a threshold and a comparator. Cortex will pull data from Splunk Observability Cloud and roll up the query with a specified `rollup` function.

```yaml theme={null}
x-cortex-slos:
  signalfx:
    - query: sf_metric:"jvm.memory.max" AND area:"nonheap"
      rollup: AVERAGE
      target: 5120000
      lookback: P1Y
      operation: "<="
```

| Field | Description | Required |
| - | - | :-: |
| `query` | [Elasticsearch query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) for your metric: Use `sf_metric` to filter by the given metric and add additional dimensions to narrow the searchQueries resulting in multiple datasets will be rolled up according to `rollup` | **✓** |
| `rollup` | `SUM` or `AVERAGE` | **✓** |
| `target` | Target number for the SLO | **✓** |
| `lookback` | [ISO-8601 duration](https://www.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) (`P[n]Y[n]M[n]DT[n]H[n]M[n]S`) | **✓** |
| `operation` | `>`, `<`, `=`, `=` | **✓** |

## Using the Splunk Observability integration

### Viewing SLO information on an entity

When an SLO is defined in an entity's descriptor, SLO information appears in the **Monitoring** block on an [entity details page's](/ingesting-data-into-cortex/entities-overview/entities/details) overview.

**Monitoring**

* Click **Monitoring > Data overview** in the entity's sidebar to see the query, target, and current value for each SLO from any integrations you're pulling SLOs from. Each SLO also includes the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.

  ![View SLOs in the entity sidebar under Monitoring > Data overview.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/splunk-entity-details.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=54606c82dc060032b18d09b7e2fcf4c1)
* Click **Monitoring > Splunk Observability** to view a graph of SLO performance over time.

  ![View a graph of SLO performance.](https://mintcdn.com/cortex-290c0c42/K6GZjp5BfPGK-s1-/images/splunk-slo-graph.jpg?fit=max\&auto=format\&n=K6GZjp5BfPGK-s1-\&q=85\&s=c318dac8d2b8244e773ae3a59fb1776f)

### Scorecards and CQL

With the Splunk Observability Cloud integration, you can create Scorecard rules and write CQL queries based on Splunk Observability Cloud SLOs.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **SLOs**
>
> SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
>
> **Definition:** `slos: List<SLO>`
>
> **Example**
>
> In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
>
> ```
> slos().all((slo) => slo.passing) == true
> ```
>
> Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
>
> ```
> slos().filter((slo) => slo.name.matchesIn("latency") and slo.sliValue >= 0.9999).length > 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Splunk On-Call (VictorOps)
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/splunk-oncall



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

Splunk On-Call (formerly known as [VictorOps](https://www.splunk.com/en_us/about-splunk/acquisitions/splunk-on-call.html)) is an alert and on-call management platform.

Integrating Cortex with Splunk On-Call allows you to:

* Pull in on-call rotation data and escalation policies
  * The on-call user or team will appear in the **Current On-call** block on an entity's details page.
  * You can also view on-call information on an entity page in its side panel under **Integrations > On-call**.
* Create [Scorecards](/ingesting-data-into-cortex/integrations/splunk-oncall#scorecards-and-cql) that track progress and drive alignment on projects involving your on-call schedule

## How to configure Splunk On-Call with Cortex

### Prerequisites

Before getting started:

* Create a [Splunk On-Call API key](https://help.victorops.com/knowledge-base/api/).
  * Note: If the key is granted `Read-only` permissions, Cortex will only perform `GET` requests.
* Obtain your Splunk API ID.
  * In your Splunk On-Call portal, navigate to the **Integrations** page then click the **API** tab. Your API ID is displayed above your API keys.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Splunk On-call settings page](https://app.getcortexapp.com/admin/integrations/splunk-oncall):
   1. Click **Integrations** from the main nav. Search for and select **Splunk On-call**.
2. Click **Add configuration**.
3. Configure the VictorOps integration form:
   * **API ID**: Enter your API ID from Splunk On-Call.
   * **API key**: Enter your API key from Splunk On-Call.
   * **Organization slug**: Enter your Splunk On-Call organization slug.
     * This can be found at the end of the URL for your Splunk On-Call portal (e.g., `https://portal.victorops.com/dash/`)
   * **Client ID** and **Client secret**: Enter the client ID and secret associated with the application link you created in the previous steps.
4. Click **Save**.

## How to connect Cortex entities to Splunk On-Call

### Editing the entity descriptor

With the Splunk On-Call integration, you can tie on-call rotations to entities under the `x-cortex-oncall` block with your schedule metadata. You can use the team ID, or you can filter beyond the team ID and use the policy ID. Using the policy ID is helpful if your team has multiple policies available.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Team ID in entity descriptor:

```yaml theme={null}
x-cortex-oncall:
  victorops:
    type: SCHEDULE
    id: team-abcd12345
```

Policy ID in entity descriptor:

```yaml theme={null}
x-cortex-oncall:
  victorops:
    type: SCHEDULE
    id: team-abcd12345
    policyIds:
      - 12345
      - 56789
```

| Field | Description | Required |
| - | - | :-: |
| `type` | Type of on-call data (in this case, `SCHEDULE`) | **✓** |
| `id` | ID for the team assigned to the given schedule | **✓** |

You can find the team ID in the Splunk On-Call portal on the teams page (e.g., `https://portal.victorops.com/dash/cortex-app#/team//users`).

## Using the Splunk On-Call integration

#### Entity pages

Once a Splunk On-Call schedule is defined in an entity descriptor, the user or team who is on call will appear in the **Current On-call** block on that [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

You can also find on-call information for a given entity on the **On-call & incidents** page in the entity's sidebar.

### Scorecards and CQL

With the Splunk On-Call integration, you can create Scorecard rules and write CQL queries based on Splunk On-Call schedules.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if on-call is set**
>
> Check if entity has a registered team.
>
> **Definition:** `oncall (==/!=) null`
>
> **Example**
>
> For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
>
> ```
> oncall != null
> ```
>
> This rule will pass if an entity has a service, schedule, or escalation policy set.

> **Number of escalations**
>
> Number of escalation tiers in escalation policy.
>
> **Definition:** `oncall.numOfEscalations()`
>
> **Example**
>
> This expression could be used in a Scorecard focused on production readiness or service maturity:
>
> ```
> oncall.numOfEscalations() >= 2
> ```
>
> This rule checks that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup.

> **On-call metadata**
>
> On-call metadata, including type, ID, and name.
>
> **Definition:** `oncall.details()`
>
> **Example**
>
> You can use this expression in the Query builder to find all entities with an on-call rotation that includes a specific team. Let's say we want to find all entities that the "Sample Team" team is on-call for and the team's ID in Splunk On-Call is `sample-team1234`. Our query would then be:
>
> ```
> oncall.details().id == "sample-team1234"
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Sumo Logic
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/sumologic



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Overview

[Sumo Logic](https://www.sumologic.com/) is a cloud-based observability platform that provides log management and analytics. Integrate Sumo Logic with Cortex to drive insights into service-level objectives (SLOs).

## How to configure Sumo Logic with Cortex

### Prerequisites

Before getting started:

* [Generate an access key](https://help.sumologic.com/docs/api/getting-started/#authentication) in Sumo Logic.
* Determine your [assigned deployment](https://help.sumologic.com/docs/api/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) in Sumo Logic.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Sumo Logic settings page](https://app.getcortexapp.com/admin/integrations/sumologic):
   * Click **Integrations** from the main nav. Search for and select **Sumo Logic**.
2. Click **Add configuration**.
3. Configure the Sumo Logic integration form:
   * **Access ID**: Enter the access ID for Sumo Logic.
   * **Access key**: Enter the access key you generated in Sumo Logic.
   * **Deployment**: Enter your Sumo Logic deployment.
4. Click **Save**.

### Linking SLOs in Cortex

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can create and manage SLOs by listing SLO IDs in the entity descriptor:

```yaml theme={null}
x-cortex-slos:
  sumologic:
    - id: 000000000001234
    - id: 000000000006789
```

## Using the Sumo Logic integration

#### Entity pages

When an SLO is defined in an entity's descriptor, you'll see an overview of SLO information in the **Monitoring** block on an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details) overview.

On the left side of an entity, click **Monitoring > Sumo Logic** to view the SLO query, target(s), current value for each SLO, a graph of SLO performance over time, and the period of time the SLO is being calculated for. For example, if the time listed is "7 days ago," then the SLO is looking at the time range starting 7 days ago to now.

### Scorecards and CQL

With the Sumo Logic integration, you can create Scorecard rules and write CQL queries based on Sumo Logic SLOs.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **SLOs**
>
> SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it, and if those SLOs are passing.
>
> **Definition:** `slos: List<SLO>`
>
> **Example**
>
> In a Scorecard, you can use this expression to make sure an entity is passing its SLOs:
>
> ```
> slos().all((slo) => slo.passing) == true
> ```
>
> Use this expression to make sure latency Service Level Indicator (SLI) value is above 99.99%:
>
> ```
> slos().filter((slo) => slo.name.matchesIn("latency") and slo.sliValue >= 0.9999).length > 0
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Syntasso Kratix Enterprise (SKE)
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/syntasso



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Syntasso Kratix Enterprise (SKE)](https://www.syntasso.io/) is an enterprise-grade platform orchestrator built on [Kratix](https://kratix.io/), an open-source framework for building internal developer platforms on Kubernetes. SKE enables platform teams to deliver self-service infrastructure and services through composable, API-driven abstractions called [Promises](https://docs.kratix.io/main/reference/promises/intro).

Integrating SKE with Cortex allows you to:

* Dynamically create [Workflows](/streamline/workflows) in Cortex that map to Kratix Promises, enabling developers to self-service Kubernetes resources
* Register and update entities in Cortex that represent Kubernetes resource definitions managed by SKE
* Provide a portal-driven experience where developers can request and manage platform capabilities without needing to learn YAML or kubectl

> [!NOTE]
>
> This integration was built and is maintained by the Syntasso team. For setup and configuration, refer to the [SKE documentation](https://docs.kratix.io/ske).

## How to configure SKE with Cortex

### Prerequisites

Before getting started:

* You should have a working [SKE installation](https://docs.kratix.io/ske).
* You should have Promises configured in your SKE environment.
* You will need a [Cortex API key](/configure/settings/api-keys) to connect SKE to your Cortex workspace.

### Configure the integration

SKE connects to Cortex via the [Cortex API](/api). Configuration is managed on the SKE side — refer to the [SKE documentation](https://docs.kratix.io/ske) for detailed setup instructions.

Once configured, SKE will automatically create and manage [Workflows](/streamline/workflows) in Cortex based on the Promises defined in your platform.

## How the integration works

### Kratix Promises

Promises are the core abstraction in Kratix and SKE. A Promise defines a platform capability — such as a database, CI/CD pipeline, or Kubernetes cluster — as a self-service API. Promises encapsulate validation, provisioning, policy enforcement, and Day 2 lifecycle management into a single, governed contract between platform and development teams.

When SKE is integrated with Cortex, these Promises are surfaced as Workflows, allowing developers to request resources through the Cortex UI.

## Using the SKE integration

As platform adoption grows, a common challenge emerges: *What do we actually have, who owns it, and is it compliant?* The SKE integration with Cortex connects orchestration with organizational visibility, helping teams treat their platform as a product — one that is not only easy to consume but also measurable, governable, and continuously improved.

Once configured, SKE dynamically creates, adds, and updates Promises for Kubernetes resource definitions in Cortex, giving platform teams a unified portal experience for managing platform capabilities.

## Demo

See the video below for a demonstration of the Kratix integration with Cortex.

[YouTube video player](https://www.youtube.com/embed/28v8X3mNnPU)

## Learn more

* [Syntasso website](https://www.syntasso.io/)
* [Kratix documentation](https://docs.kratix.io/)
* [SKE documentation](https://docs.kratix.io/ske)

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don't have a Slack channel? Talk with your Customer Success Manager.


# Veracode
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/veracode



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Veracode](https://www.veracode.com/) is an automated security platform that identifies and remediates vulnerabilities in software applications. DAST, SAST, and SCA are supported.

Integrating Veracode with Cortex allows you to:

* [View Veracode findings on entity pages](/ingesting-data-into-cortex/integrations/veracode#view-veracode-data-on-ntity-pages) in Cortex
* Create [Scorecards](/ingesting-data-into-cortex/integrations/veracode#scorecards-and-cql) that track progress and drive alignment on Veracode vulnerability metrics

## How to configure Veracode with Cortex

### Prerequisite

Before getting started:

* Create an [API ID in Veracode](https://docs.veracode.com/r/c_api_credentials3).
  * If using XML, configure the ID with the following permissions:
    * `get Detailed report`
    * `get Build list`
    * `get sandbox list`
    * `get application list`
  * If using REST, configure the ID with the following permissions:
    * `get application`
    * `get findings`
* Create a [secret key in Veracode](https://docs.veracode.com/r/c_api_credentials3) with the following roles:
  * Creator or Security Lead
  * Reviewer or Security Lead
  * Results API

If you're using a self-hosted instance of Veracode, you'll need to verify that your Cortex instance is able to reach the Veracode instance.

We route our requests through a static IP address. Reach out to support at [help@cortex.io](mailto:help@cortex.io) to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your Veracode instance.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Veracode settings page](https://app.getcortexapp.com/admin/integrations/veracode):
   1. Click **Integrations** from the main nav. Search for and select **Veracode**.
2. Click **Add configuration**.
3. Configure the Veracode integration form:
   * **Key ID**: Enter your Veracode API ID.
   * **Secret key**: Enter the secret key associated with your API ID.
   * **Region**: Enter your Veracode instance [region](https://docs.veracode.com/r/Region_Domains_for_Veracode_APIs).
4. Click **Save**.

### Advanced configuration

If you’re unable to expose your Veracode instance to be reachable by Cortex, you can set up a [custom integration webhook](/ingesting-data-into-cortex/entities-overview/entities/custom-data).

## How to connect Cortex entities to Veracode

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

You can set up the Veracode integration for an entity by specifying its Veracode application names or sandboxes in the `x-cortex-static-analysis` section of the entity descriptor. For example:

```yaml theme={null}
x-cortex-static-analysis:
  veracode:
    applicationNames:
      - My Application
      - Second Application
    sandboxes:
      - applicationName: My Application
        sandboxName: My Sandbox
      - applicationName: Second Application
        sandboxName: Second Sandbox
```

The application and sandbox names must appear exactly as they are in Veracode.

## Using the Veracode integration

### View Veracode data on entity pages

On an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details) overview, Veracode findings will appear the **Code and Security** block.

When viewing an entity, click **Code & security > Veracode** to see the DAST findings count, SAST findings count, SCA findings count, and a list of findings that can be filtered by severity and source. The data syncs automatically every hour, or you can click **Sync findings** in the upper right side of the entity's Veracode page to trigger a sync.

### Scorecards and CQL

With the Veracode integration, you can create Scorecard rules and write CQL queries based on Veracode findings.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Veracode application is set**
>
> Check if entity has Veracode application or sandbox specified in its entity descriptor.
>
> **Definition:** `veracode (==/!= null): Boolean`
>
> **Example**
>
> In a Scorecard, you can write a rule to verify that an entity has a Veracode application or sandbox specified:
>
> ```
> veracode != null
> ```

> **Findings**
>
> List of findings, filterable on risk, source, and status.
>
> **Definition:** `veracode.findings(): List`
>
> **Example**
>
> In a Scorecard, you can write a rule to verify that an entity has fewer than 10 Veracode findings from two of the sources:
>
> ```
> veracode.findings(source = ["STATIC", "SCA"]).length < 10
> ```
>
> You can write a rule to verify that an entity has fewer than 3 findings with a risk level of 0 or 2:
>
> ```
> veracode.findings(risk = ["0", "2"]).length <= 3
> ```
>
> You can write a rule to verify that an entity has fewer than 5 findings with a status of "OPEN":
>
> ```
> veracode.findings().filter((f) => f.findingStatus.status == "OPEN").length < 5
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Background sync

Cortex conducts an entity sync for Veracode every hour.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Custom webhook integrations
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/webhook



Custom webhook integrations allow you to POST data to a unique endpoint in Cortex, map the payload to existing entities, and make that data available for use in [Scorecards](/standardize/scorecards), [CQL queries](/standardize/cql), and on [entity detail pages](/ingesting-data-into-cortex/entities-overview/entities/details).

Using a custom webhook is especially helpful if:

* You have internal tools, homegrown systems, or third-party services that Cortex doesn't integrate with yet.
* You want to automate the process of sending custom metrics, events, or other data into Cortex without building and maintaining additional infrastructure.
* You want to pre-process data before it reaches Cortex, such as adding extra metadata or transforming the payload format.

This can be done without auth or an explicit [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) in the URL if you do not have access to the Cortex tag or the ability to add authentication headers.

> [!NOTE]
>
> You can also add custom metadata manually to an entity descriptor or programmatically via the API. Learn more in [Adding custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data).

Below the instructions, see an example demonstrating how to [send additional GitHub metadata into Cortex via webhook](/ingesting-data-into-cortex/integrations/webhook#example-github-webhook).

## How to create a custom webhook integration in Cortex

### Step 1: Configure the custom integration in Cortex

1. In Cortex, navigate to **Integrations**. On the left side of the Integrations page, click [**Custom integrations**](https://app.getcortexapp.com/admin/integrations#integration-category-custom).
2. Click **+Add custom integration**.

   ![Click +Add custom integration.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/custom-integration.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=9fc2d427c1a87b18cbe7566c870530e6)
3. Configure the integration details:
   * **Integration name**: Enter a name for the integration.
   * **Entity tag JQ**: Enter the JQ that will be used to extract the entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) from the data. This tells Cortex where in the payload body we can find the Cortex tag.
     * For example, the payload shown in [Step 2](/ingesting-data-into-cortex/integrations/webhook#step-2-send-data-to-the-webhook) would have `.data.codeTag` as the JQ, and `frontend-service` would be the entity's Cortex tag.
     * If the tag Cortex extracts from the payload does not match an existing Cortex tag, it will result in a 400 error and the custom metadata will not be updated. Learn about [alternate mappings below](/ingesting-data-into-cortex/integrations/webhook#changing-the-mappings-for-entities).
   * **Key**: Enter the custom metadata key.
     * Data will be stored under the key for entities, similar to adding data via [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file) or [API](/api/rest/custom-data).
     * In the [example below](/ingesting-data-into-cortex/integrations/webhook#step-2-post-json-with-curl), the key is `mydata`.
4. Click **Save**.
5. Copy the provided webhook URL.

### Step 2: Send data to the webhook

Note that the entity must exist in Cortex before you send the payload.

cURL is a quick and flexible method to post to the webhook and verify that it's receiving data.

1. Save your payload as a .json file. Include the field that matches the JQ expression configured in the previous steps, so Cortex can map the data to the correct entity.

   For example, the payload might look like this:

```json theme={null}
{
  "data": {
    "codeTag": "frontend-service",
    "mydata": "4"
  }
}
```

2. In your terminal, use cURL to POST the JSON, using a command similar to the following:

   `curl -X POST -H "Content-Type: application/json" --data <path to json file> <webhook URL>`

   * For example: `curl -X POST -H "Content-Type: application/json" --data @/tmp/payload.json https://api.getcortexapp.com/api/v1/custom-integrations/data/12345abcdef`

After sending data, the JSON payload is written to the entity's key that you configured for the custom webhook in [Step 1](/ingesting-data-into-cortex/integrations/webhook#step-1-configure-the-custom-integration-in-cortex).

### **Changing the mappings for entities**

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

If the webhook payload does not contain a value that maps to the exact [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag), you can configure alternative mappings to look up when processing payloads. Use the `x-cortex-custom-integration-mappings` block in the [entity descriptor YAML](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file). For example:

```yaml theme={null}
x-cortex-custom-integration-mappings:
  - frontend
  - brain-service
```

When processing a payload, Cortex takes the output of the **Entity tag JQ** field in Step 1 above and searches for an entity with that value as a Cortex tag. If no such entity exists, Cortex checks whether an entity has registered the value as an alternative mapping; if so, the payload is attached to that entity.

## View custom integration data in Cortex

Similar to when you [add custom metadata to an entity](/ingesting-data-into-cortex/entities-overview/entities/custom-data), custom integration data appears in the sidebar on an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details) within the **Custom data & metrics** page. It appears with an `INTEGRATION` tag next to the key name.

![The 'Custom data and metrics' page in an entity's sidebar displays data from webhook integrations.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/custom-webhook.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=9ee00ba46e788e709bad278041d49f1b)

## Example: GitHub webhook

In this example, we create a webhook integration to send GitHub data into Cortex.

While Cortex does offer a native integration with [GitHub](/ingesting-data-into-cortex/integrations/github), there may be scenarios where you want to send additional metadata that isn't included in the native integration.

1. [Create a custom webhook integration](/ingesting-data-into-cortex/integrations/webhook#step-1-configure-the-custom-integration-in-cortex) in Cortex.
   * Enter a descriptive name so others understand the purpose of this webhook, such as "GitHub metadata."
   * In this example, we use the **Service query** `.repository.name` and the **Key** `githubTest`.
2. Copy the webhook URL generated in Cortex for this integration.
3. In GitHub, under **Settings > Webhooks**, create a webhook.
   * In the webhook's settings under **Payload URL**, paste in the webhook URL from Cortex.
   * Set the **Content type** to `application/json`.
4. Push a commit to your GitHub repository.
   * In your GitHub settings under **Webhooks**, click the **Recent Deliveries** tab to see the payload that will be sent. Because you set the JQ query to `.repository.name`, the repository name value in the payload will correspond with the Cortex tag in Cortex.

     In the example screen shot, the repository name is "michigan":

     ![The repository name appears in the 'Recent deliveries' tab for the webhook in GitHub.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/github-webhook-payload.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=ad866fc7dee897d3297ecec7538c53fe)
5. Navigate to the entity in Cortex.
   * In this example, the repository name is "michigan," so we can search in Cortex to find an entity with "michigan" as its Cortex tag.
6. On the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details), click **Custom data & metrics** from the entity's sidebar.
   * Next to the `githubTest` key, you will see the payload sent from GitHub:

     ![The custom webhook data appears next to the key on the entity page.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/example-webhook.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=d39626c864ac50f05b897ffc1d7bc7cb)


# Wiz
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/wiz



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[Wiz](https://www.wiz.io/) is a security platform that allows teams to find and fix issues in their code. Cortex integrates with Wiz to bring cloud and container vulnerabilities into your catalog.

Integrating Wiz with Cortex allows you to:

* [Automatically map projects to entities](/ingesting-data-into-cortex/integrations/wiz#match-entity-names-to-wiz-projects), eliminating the overhead of manually maintaining project-to-entity relationships
* [View Wiz issues directly on entity pages](/ingesting-data-into-cortex/integrations/wiz#view-wiz-information-on-entity-pages) in Cortex
  * Leverage Wiz scanning capabilities earlier in the development lifecycle and enable visibility into security issues
* Create [Scorecards](/ingesting-data-into-cortex/integrations/wiz#scorecards-and-cql) that track progress and drive alignment on projects involving Wiz projects and issues

## How to configure Wiz with Cortex

### Prerequisites

Before getting started:

* [Create a service account in Wiz](https://docs.wiz.io/docs/service-accounts-settings).
* Obtain your [data center and authentication provider from Wiz](https://docs.wiz.io/docs/using-the-wiz-api).
* If you have IP restrictions in place in Wiz, [add Cortex's public IPs to your allowlist](https://docs.wiz.io/docs/req-urls-ip-addr) to ensure that Cortex is allowed to make requests to Wiz.
  * Contact the Cortex Customer Engineering team for a list of IPs.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Wiz integration settings page](https://app.getcortexapp.com/admin/integrations/wiz):
   1. Click **Integrations** from the main nav. Search for and select **Wiz**.
2. Click **Add configuration**.
3. Configure the Wiz integration form:
   * **Client ID** and **Client secret**: Enter your client ID and client secret from Wiz.
   * **Tenant data center**: Enter the data center from Wiz.
   * **Authentication provider**: Select your authentication provider. You can confirm the provider in Wiz under **User Settings > Tenant**.
4. Click **Save**.

If you see a "No address associated with hostname" error, verify that you have entered the correct authentication provider.

## How to connect Cortex entities to Wiz

### Match entity names to Wiz projects

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-service`) as the "best guess" for Wiz project. For example, if your entity name is "My Service" or your tag is `my-service`, then the corresponding project name in Wiz should also be My Service or `my-service`.

If your Wiz project names don’t cleanly match the Cortex entity name or tag, you can override this in the Cortex entity descriptor.

#### Considerations for mapping Wiz projects to entities

Expand the tile below to see how Cortex customers have modeled their data when mapping Wiz projects to entities.

> **Wiz project mapping best practices**
>
> **Domain-level auto-mapping**
>
> Some customers organize their Cortex domain structure to match their Wiz projects, enabling auto-mapping across domains based on their name.
>
> For example:
>
> * **Cortex domain entity name**: Engineering project
>   * **Entity tag**: `engineering-project`
> * **Wiz project name**: Engineering project
>
> **Auto-mapping across multiple integrations**
>
> Some customers organize multiple integrations to use consistent names and tags across all of them.
>
> For example:
>
> * **Cortex domain entity name**: Engineering project
>   * **Entity tag**: `engineering-project`
> * **Wiz project name**: Engineering project
> * **Jira project name**: engineering-project
>   * When you [integrate Cortex with Jira](/ingesting-data-into-cortex/integrations/jira), Cortex will tie Jira tickets to entities by searching for any tickets where the `label`, `component`, or `project` field for the work item includes the Cortex tag.
>
> **Service-level auto-mapping based on repo structure**
>
> Some customers use a standardized repository naming convention that makes service-level auto-mapping simple and automated to the Wiz projects.
>
> For example:
>
> * **Repository name**: engineering/integrations/eng-repo
> * **Cortex domain entity name**: Eng Repo
>   * **Entity tag in Cortex**: eng-repo
> * **Wiz project name**: eng-repo

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

Define the following block in your Cortex entity descriptor:

```yaml theme={null}
x-cortex-wiz:
  projects:
    - projectId: 01234567-e65f-4b7b-a8b1-5b642894ec37
```

## Using the Wiz integration

### View Wiz information on entity pages

On an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details), you'll see Wiz issues, listed by risk level, under the **Code and Security** header.

In the entity's sidebar, click **Code & Security > Wiz** to view a list of Wiz issues including their severity, status, basic details, and a link to view the issue directly in Wiz:

![View Wiz issues on the entity details page under Code & security.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/wiz-issues-entity.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=a88b2f259747f79427b613e322f61b2a)

### Scorecards and CQL

With the Wiz integration, you can create Scorecard rules and write CQL queries based on Wiz projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if Wiz project is set**
>
> Check if entity has a registered Wiz project in its entity descriptor.
>
> **Definition:** `wiz (==/!=) null: Boolean`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to make sure entities are associated with Wiz project:
>
> ```
> wiz != null
> ```
>
> Setting a `wiz != null` rule can also serve as a secondary check to confirm an entity is synced properly with Wiz and is reporting frequently.

> **Wiz issues**
>
> List of Wiz issues, filterable on severity and status
>
> **Definition:** `wiz.issues(): List`
>
> **Example**
>
> The Scorecard's top level might include a rule to ensure that entities have fewer than 3 issues in OPEN status:
>
> ```
> wiz.issues(statuses = ["OPEN"]).length <= 3
> ```
>
> You could set rule to verify an entity has less than 10 issues with a HIGH or CRITICAL severity:
>
> ```
> wiz.issues(severity = ["CRITICAL", "HIGH"]).length < 10
> ```
>
> You can write a rule to verify an entity has less than 25 issues:
>
> ```
> wiz.issues().length < 25
> ```

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Workday
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/workday

Configuring the integration for Workday

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

## Why use the integration for Workday

Workday is the system of record for your people, teams, and reporting relationships. However, that organizational structure often lives separately from the tools your engineers use day to day. The integration for Workday bridges that gap by syncing your Workday ownership data directly into Cortex, automatically importing employees, teams, and hierarchies so that ownership in your software catalog stays aligned with how your organization is actually structured.

Instead of manually maintaining team rosters and reporting lines in two places, you can rely on Workday as the source of truth and let Cortex handle the rest: connecting people to the services, resources, and entities they own, enforcing accountability through Scorecards, and ensuring that as teams reorganize or employees change roles, your ownership model evolves with them. This is especially valuable for organizations that want to drive operational excellence at scale, where knowing who owns what—and being able to trust that information—is foundational to incident response, compliance, and engineering productivity.

## Configuring Workday

### Prerequisites

1. Users with the `Configure Integrations` permissions can configure Workday.

### Step 1: Generating an ownership report in Workday

1. In Workday, generate an ownership report. Depending on how you want to manage teams and the corresponding hierarchy, you can choose one of the following options:

   * Manage teams based on Workday supervisory organizations
   * Manage teams based on Workday teams

   Note that the required fields in the report differ depending on which option you choose. See the table below.

| Field | Description | Required for supervisory orgs? | Required for Workday teams? |
| - | - | - | - |
| `email` | Email address for employee. Use the same address that employees will use to access Cortex. | | |
| `employeeId` | Unique employee ID. | | |
| `firstName` | Employee first name (displayed in Cortex). | | |
| `lastName` | Employee last name (displayed in Cortex). | | |
| `employeeRole` | Employee role (displayed in Cortex). | optional | optional |
| `employeeSupervisoryOrgId` | Supervisory org ID for employee. Cortex uses this field to group employees. Any changes to this field results in the creation of a new team as this is how Cortex identifies teams. | | |
| `teamName` | Team name for employee. This field is used to group employees into teams in Cortex. Any changes to this field results in the creation of a new team as this is how Cortex identifies teams. | | |
| `teamDisplayName` | Display name for team. This is used for the title and tag for any teams imported from Workday. If not included, `teamName` is used instead. This should be the same for all employees on the same team. | | optional |
| `teamEmployeeManages` | The team this employee manages. Include this field if your report identifies a team's manager on the team record. If you omit it, Cortex treats the person in `managerEmail` as the manager. | optional | optional |
| `managerEmail` | Email address for employee's manager. Cortex uses this field to create team hierarchies. If Cortex detects an employee with the same email as the `managerEmail`, that employee is added to the team with a **Manager** role. **Omit this field** if you **do not** want to auto-import teams and the corresponding hierarchy from Workday. | | |
| `teamSupervisoryOrgId` | Supervisory org ID for the employee's team. This org becomes the parent of `employeeSupervisoryOrgId` in the team hierarchy. | | |
| `teamListKey` | Key for the list of teams associated with a given user. This field is for a single employee on multiple teams. | | |

### Step 2: Configuring the Workday integration

1. From the main sidebar in Cortex, expand **Integrations**, then select **Configurations**.
2. Locate Workday, then click **Install**. The Workday side panel opens.
3. In the Workday side panel, do the following:
   1. From the **Category** dropdown, select at least one category that applies to the integration (required). **Team** is the default category.
   2. Under **Username**, enter the username associated with the Workday account used to generate the ownership report (required).
   3. Under **Password**, enter the password associated with the Workday username (required).
   4. Under **Ownership report URL**, enter the URL for the ownership report you generated (required).
      1. Provide the base report URL. Do not include query parameters in the URL. If necessary, Cortex appends `?format=json` when making requests.
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

> [!NOTE]
>
> To modify an existing configuration, see [Modifying an integration configuration](/ingesting-data-into-cortex/integrations#modifying-an-integration-configuration).

### Step 3: Configuring the report mappings in Cortex

After saving the configuration, you can configure how you want the fields to map to different elements in Cortex. The options available in each drop-down menu mirror the fields included when generating the ownership report.

**Note on field mapping availability**

When you first add or update a Workday report URL, Cortex runs a background sync job to fetch and cache the report's column structure. The field mapping dropdowns on the configuration page are populated from this cache.

If you open the configuration page immediately after adding or rotating credentials, the dropdowns may appear empty or validation errors like ***Employee Id is required*** may surface before the sync completes. If this occurs, wait a few minutes and refresh the page—the column options populate once the background sync has finished.

The dropdowns include fields that appear on only some rows of your report, as well as fields nested inside a team list, so every employee record doesn't need to carry every field.

> [!NOTE]
>
> Cortex runs a daily sync to keep the field cache up-to-date. If your Workday report structure changes, the latest mapping drop-downs are reflected within 24 hours.

**To configure report mappings**:

1. From the main sidebar, expand **Integrations**, then select **Configurations**.
2. Locate Workday, then click **Settings**.

   ![The 'Settings' button next to the Workday integration on the Integrations page.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/workday-settings.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=9070d6172ed09f480b1ae6977e2e5363)
3. From the **Integration settings** tab, do the following:
   1. In the **Employee attributes** section, map report fields that pertain to employees:
      1. From the **Employee ID** dropdown, select a report field for the unique employee identifier (required).
      2. From the **Email** dropdown, select a report field for the employee's email address (required). This is what Cortex matches against a user's login.
      3. From the **First Name** dropdown, select a report field for the given name shown in Cortex.
      4. From the **Last Name** dropdown, select a report field for the surname shown in Cortex.
      5. From the **Role** dropdown, select a report field for the employee's role, displayed as a badge next to their name on the team's **Members** tab.
      6. From the **Manager Email** dropdown, select a report field for the manager's email. This is used to identify a team's manager.
      7. Click **Save**.
   2. In the **Team attributes** section, map report fields that pertain to employees' teams.
      1. From the **Team type** dropdown, select the shape of the report:
         1. **One Employee-Multiple Teams** - Select this option if your report includes employees who belong to multiple teams.
            1. From the **Team List Key** dropdown, select a report field that contains the teams you want imported into Cortex for a given employee entry (required). This requires the `teamListKey` field in the Workday report. The `teamListKey` should be a list of objects, where each object has at least `teamName` and `teamId` properties:
            2. From the **Team ID** dropdown, select a report field for the team ID. New teams are imported based on this ID (required). If the identifier changes, Cortex creates a new team.
            3. From the **Team ID-Fallback** dropdown, enter a fallback team for a user who does not have an associated `teamListKey`.
            4. From the **Team Name** dropdown, select a report field for the team name. Cortex updates this name if changes are detected in Workday.
            5. From the **Team Name-Fallback** dropdown, enter a fallback team name for the fallback team ID defined above.
            6. From the **Team Employee Manages** dropdown, select a report field that names the team an employee manages. If you set this, Cortex assigns managers based on this field. If you leave it empty, Cortex uses the person in **Manager Email** as the team's manager.

               > [!NOTE]
               >
               > Set **Team Employee Manages** if your teams are nested and each one has its own manager. Without it, Cortex assigns the parent team's manager to every child team below it.For example, if a Customer Experience team has Customer Success, Customer Support, and Customer Education as child teams, leaving **Team Employee Manages** empty makes the Customer Experience manager the manager of all three.
            7. Click **Save**.
         2. **One Employee - Multiple Teams (Multiple Fields)** -
            1. Click **Add team**.
            2. Configure the team:
               1. From the **Team ID** dropdown, select a report field for the team ID. New teams are imported based on this ID (required). If the identifier changes, Cortex creates a new team.
               2. From the **Team Name** dropdown, select a report field for the team name. Cortex updates this name if changes are detected in Workday.
               3. From the **Parent Team ID** Field, select a report field that identifies the parent team.
               4. Click **Save**.
         3. **One Employee - One Team** -Select this option if your report includes employees who belong to a single team. This is best if you are configuring the integration based on [supervisory orgs](/ingesting-data-into-cortex/integrations/workday#step-1-generating-an-ownership-report-in-workday) and/or if users manage teams they belong to.
            1. From the **Team ID** dropdown, select a report field for the team ID. New teams are imported based on this ID (required). If the identifier changes, Cortex creates a new team.
            2. From the **Team Name** dropdown, select a report field for the team name. Cortex updates this name if changes are detected in Workday.
            3. Click **Save**.
   3. In the **Hierarchy fields** section, configure the hierarchy fields mappings. This is only required if you want to automatically import Workday teams. Note that you must [enable the option to auto-import Workday teams](/ingesting-data-into-cortex/integrations/workday/using-the-integration-for-workday#importing-teams-automatically) in order for new teams to be created automatically. Hierarchy relationships are written for existing teams on manual import and whenever hierarchy field mappings are updated, regardless of whether auto-import is enabled.
      1. From the **Field on parent team** dropdown, select a report field whose value identifies a team as a parent (required).
      2. Optionally, toggle on **Is List** when the parent field holds a list rather than a single value, so one entry can be the parent of several teams.
      3. From the **Field on parent team-Fallback** dropdown, select an alternate field for the parent identifier.
      4. Optionally, toggle on **Is List-Fallback** so Cortex reads the fallback field when the primary field is missing from a record, which is useful when your report doesn't populate every field on every row.
      5. From the **Field on child team** dropdown, select a report field on a team's record whose value points at that team's parent (required).
      6. From the **Field on child team-Fallback** dropdown, select an alternate field for the parent pointer.
      7. From the **Root Team IDs** dropdown, select the ID for the team you expect to be at the top of the hierarchy. If set, Cortex uses this to [break cycles](/ingesting-data-into-cortex/integrations/workday/using-the-integration-for-workday#known-limitations) that may be in the hierarchy.
      8. Click **Save**.


# Using the integration for Workday
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/workday/using-the-integration-for-workday

How to use the integration for Workday in Cortex

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to use the integration for Workday with Cortex. For configuration instructions, see [Configuring the integration for Workday](/ingesting-data-into-cortex/integrations/workday).

> [!NOTE]
>
> Cortex conducts a background sync of Workday identities every day at 9 a.m. UTC.

## Connecting an entity to Workday

### Discovering entities automatically

By default, Cortex matches entities to Workday teams using the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag). For example, an entity with the tag `platform-infra` maps to a Workday team named `platform-infra`. If your Workday team names don't align with your Cortex tags, override the mapping in the entity descriptor.

> [!NOTE]
>
> Team names are case-sensitive and must exactly match the `teamDisplayName` or `teamName` field in your Workday report.

### Importing teams automatically

You can choose to automatically import discovered teams and team relationships from Workday into Cortex. Before enabling auto import, make sure your Workday report includes the `managerEmail` field to ensure that team relationships are imported.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. In the Settings menu, locate the **Workspace** section, then expand **Entities**.
4. Select **Teams**.
5. In the Team settings section, toggle on **Auto import Workday teams**.

   ![The 'Auto import Workday teams' option.](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/ay-auto-import.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=46bfe33d8a76ee5b8a43594d08cc653f)
6. At the top of the page, select the **Identity providers** tab.

   ![The 'Identity providers' tab.](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/identity-providers-tab.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=e6b52e3c181958d8ff9cdd5954c5e7dc)
7. Locate Workday, then toggle on the **Enabled** option.

The next automatic import occurs when the background entities sync runs at 9 a.m. UTC.

> [!NOTE]
>
> If a Workday team you're importing shares a tag with an existing Cortex entity, Cortex appends `-team` to the imported team's tag to avoid a collision.
>
> For example, if the tag `payments` already exists in Cortex when you import a Payments team from Workday, Cortex imports the team's tag as `payments-team`.

> [!NOTE]
>
> When Cortex processes a sync, it checks whether a deleted team is backed by a non-Cortex provider before re-creating it. A Workday-managed team is only re-created if (1) a service YAML references it as an owner, or (2) the team's own YAML is re-processed.

### Importing teams from the catalog

If you'd rather choose which Workday teams to bring into Cortex than import all of them, you can select them from the catalog. Cortex builds the team hierarchy as part of the import, so the teams arrive with their parent and child relationships already in place.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Click **Import entities**, then select **Import discovered entities**.
3. Select Workday as the source.
4. On the **Select entities to import** page, click **Sync entities**.
   * The daily background sync also stores the hierarchy, so an integration that's been connected longer than a day is already covered.
5. Select the teams you want, then click **Next step**. The **Edit details** page is displayed.
6. Review the information, make any necessary changes, then click **Confirm import**. See [Importing teams from an integration](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams#importing-teams-from-an-integration) for more information.

Cortex creates the teams, their members, and their hierarchy relationships.

> [!NOTE]
>
> Cortex stores your Workday hierarchy separately from your teams, so you can delete Workday teams and import them again without losing their relationships. To pick up an org structure change from Workday, run a sync before you import again.

#### **Triggering a sync manually**

You can sync teams manually at any time. Note that performing a manual sync does not create new teams, but it does update membership and hierarchy relationships for existing Workday-managed teams.

1. From the main sidebar, select **Integrations**.
2. Locate Workday, then click **Settings**.
3. In the **Sync team for Workday** section, click **Sync teams**.

   ![The 'Sync teams' option.](https://mintcdn.com/cortex-290c0c42/cWUAMd9sewD6GxO9/images/sync-teams.png?fit=max\&auto=format\&n=cWUAMd9sewD6GxO9\&q=85\&s=3aeb4b624795ba6101f3ff028c3cdf4a)

> [!NOTE]
>
> Manual sync updates membership and hierarchy for existing Workday-managed teams. It does not create new teams and will not re-create a deleted team unless a service YAML references it as an owner or the team's own YAML is re-processed.

### Syncing ownership from Workday

For any entity type, use the entity descriptor to assign Workday teams as owners by referencing the team's Cortex tag. Assigned teams then appear as owners on the entity's page in Cortex, linking it to the team members and hierarchy imported from Workday.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-owners:
  - type: group
    name: workday-team-tag
    provider: CORTEX
    description: This is a description for this owner.
```

| Field | Description | Required? |
| - | - | - |
| `type` | Ownership type (in this example, `group`). | |
| `name` | The [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#unique-identifiers-for-entities) linked to the auto-created Workday team. | |
| `provider` | The source of the team (in this example, a Cortex-created team). | |
| `description` | Description for the owner. | |

Cortex syncs Workday identities every day at 9 a.m. UTC. You don't need identity mappings for Workday teams. Cortex uses each member's email address from Workday.

To compare ownership sources, see the [Ownership sources reference](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-sources).

## Using the Workday integration

#### Entity pages

Once you set up the integration, Cortex imports and structures your team hierarchy automatically. Imported Workday teams display the description ***Automatically created by Cortex***.

Each team's details page lists detected members under the **Members** tab. If your Workday report includes the `role` field, Cortex displays each member's role in a badge next to their name.

### Creating Scorecard rules and writing CQL queries with the Workday integration

See examples below.

> **All ownership details**
>
> A special built-in type that supports a null check or a count check, used to enforce ownership of entities.
>
> **Definition:** `ownership: Ownership | Null`
>
> **Example**
>
> An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:
>
> ```
> ownership.teams().length > 0
> ```

> **All owner details**
>
> List of owners, including team members and individual users, for each entity.
>
> **Definition:** `ownership.allOwners()`
>
> **Example**
>
> The Scorecard might include a rule to ensure that entity owners all have an email set:
>
> ```
> ownership.allOwners().all((member) => member.email != null)
> ```

> **Team details**
>
> List of teams for each entity.
>
> **Definition:** `ownership.teams(): List<Team>`
>
> **Example**
>
> The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:
>
> ```
> ownership.teams().all(team => team.description != null and team.isArchived == false)
> ```

## Viewing Workday integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Known limitations

Cortex does not support hierarchies with cycles.

For example, if **Employee A** is on the platform team and **Employee B** is on the frontend team, and both report to **Manager C** on the engineering team, the hierarchy is valid. But if **Manager C** also reports to someone on the platform team, that creates a cycle between the platform and engineering teams which Cortex cannot resolve.

If your Workday data contains cycles, set **Root Team Ids** in the **Hierarchy Fields** section of your report mappings to the team you expect at the top of the hierarchy. Cortex uses it to break cycles it finds below that team.

Teams created outside the catalog import flow, such as through the Cortex API, don't get their Workday hierarchy right away. Their relationships are created on the next sync, either the daily background sync or a manual sync.


# xMatters
Source: https://docs.cortex.io/ingesting-data-into-cortex/integrations/xmatters



> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

[xMatters](https://www.xmatters.com/) is an on-call management platform.

Integrating Cortex with xMatters allows you to:

* Pull in on-call rotation data and escalation policies
  * The on-call user or team will appear in the **Current On-call** block on an entity's details page.
  * You can also view on-call information on an entity page in its side panel under **Integrations > On-call**.
* Trigger xMatters incidents from Cortex
* Create [Scorecards](/ingesting-data-into-cortex/integrations/xmatters#scorecards-and-cql) that track progress and drive alignment on projects involving your xMatters services

## How to configure xMatters with Cortex

### Configure the integration in Cortex

1. In Cortex, navigate to the [xMatters settings page](https://app.getcortexapp.com/admin/integrations/xmatters):
   1. Click **Integrations** from the main nav. Search for and select **xMatters**.
2. Click **Add configuration**.
3. Configure the xMatters integration form:
   * **Username** and **Password**: Enter your xMatters username and password.
   * **Organization slug**: Enter the organization slug for your xMatters instance.
     * This can be found in the URL for your instance (e.g., `https://.xmatters.com`)
4. Click **Save**.

## Trigger an incident

While viewing an entity in Cortex, you can trigger an incident in xMatters:

1. In Cortex, navigate to an entity. On the left side of an entity details page, click **On-call & incidents**.
2. In the upper right side of the entity's "On-call" page, click **Trigger incident**.
3. Configure the incident modal:
   * **Summary**: Enter a title for the incident.
   * **Description**: Enter a description of the incident.
   * **Severity**: Select a severity level.
4. At the bottom of the modal, click **Trigger incident**.
   * A confirmation screen will appear. In the confirmation, click the link to view the incident in xMatters.

## How to connect Cortex entities to xMatters

### Discovery

By default, Cortex will use the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) (e.g. `my-entity`) as the "best guess" for xMatters group. For example, if your Cortex tag is `my-entity`, then the corresponding group in xMatters should also be `my-entity`.

If your xMatters group don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

```yaml theme={null}
x-cortex-oncall:
  xmatters:
    id: engineering_group
    type: SERVICE
```

| Field | Description | Required |
| - | - | :-: |
| `id` | Name of the group in xMatters | **✓** |
| `type` | `SERVICE` | **✓** |

## Using the xMatters integration

#### Entity pages

Once the integration with xMatters is configured, you'll be able to find the user or team on call in the **Current On-call** block on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details).

You can find more detailed information from the xMatters integration in the entity sidebar under **On-call & incidents > xMatters**.

The schedule associated with a given entity will be hyperlinked in the **Escalation Policy** block and the group will be hyperlinked in the **Service** block.

Under the Escalations section, you'll find each level associated with the policy. Owners assigned to each level will also be hyperlinked to the user or team's on-call page in xMatters.

### Scorecards and CQL

With the xMatters integration, you can create Scorecard rules and write CQL queries based on xMatters services.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

> **Check if on-call is set**
>
> Check if entity has a registered group.
>
> **Definition:** `oncall (==/!=) null`
>
> **Example**
>
> For a Scorecard focused an production readiness, you can use this expression to make sure on-call is defined for entities:
>
> ```
> oncall != null
> ```
>
> This rule will pass if an entity has an on-call schedule set.

> **Number of escalations**
>
> Number of escalation tiers in escalation policy.
>
> **Definition:** `oncall.numOfEscalations()`
>
> **Example**
>
> This expression could be used in a Scorecard focused on production readiness or service maturity. For example, you can check that there are at least two tiers in an escalation policy for a given entity, so that if the first on-call does not ack, there is a backup:
>
> ```
> oncall.numOfEscalations() >= 2
> ```
>
> While making sure an on-call policy set is a rule that would be defined in a Scorecard's first level, a rule focused on escalation tiers would make more sense in a higher level.

> **On-call metadata**
>
> On-call metadata, including type, ID, and name.
>
> **Definition:** `oncall.details()`
>
> **Example**
>
> You can use this expression in the Query builder to find all entities with an on-call rotation associated with a given group. Let's say we want to find all entities that the "Sample team" is on-call for.
>
> ```
> oncall.details().id.matches("Sample*") == true
> ```
>
> Because the team/group name is registered in the `ID` field in the entity descriptor, we would use `.id` instead of `.name`.

### View integration logs

> [!NOTE]
>
> This feature is available in Cortex cloud.

While viewing an integration's settings page, select the **Error logs** tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

![The 'Logs' tab on an integration's settings page shows error information over the past 7 days.](https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max\&auto=format\&n=ovmDVVMNC2L6Yw7I\&q=85\&s=dffdc901a9ce0232aedd090bb3a4531c)

Click into a row to get more information, including time stamp, status code, full error, and request path.

## Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: [help@cortex.io](mailto:help@cortex.io), or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


# Ingesting data into Cortex
Source: https://docs.cortex.io/ingesting-data-into-cortex/overview



Bringing your data into Cortex unlocks everything else the platform can do. It's the foundation for data-driven decisions, clearer accountability, and a shared understanding of how your engineering organization actually works.

Once your services, repositories, teams, and infrastructure are connected, Cortex stitches it all into a complete, always-current view of your ecosystem. That view is what makes it possible to track ownership, enforce production readiness through Scorecards, standardize common developer Workflows, and give every engineer the context they need to find what they're looking for, see how the pieces fit together, and make better decisions at every stage of the development lifecycle.

## How Cortex handles data modeling

Cortex is built to mirror how your organization actually works. You get the flexibility to model your business logic across your data, and the structure to make sure that logic stays consistent everywhere it appears so your workspace reflects reality instead of forcing your team to work around it.

Cortex solves for this by giving you the flexibility to mirror your unique business logic across your data, and the structure to persist that logic everywhere:

* **Foundational, configurable data models**. A strong starting point you can shape to fit your environment.
* **Available, extensible integrations**. Connect the tools you already use, and extend them as your needs grow.
* **Complete, customizable experience**. A polished workspace out of the box, ready to be tailored to your team.

**The result**: a consistent developer workflow and an experience built around how your organization actually operates, making it easier to represent your services and infrastructure accurately in Cortex.

See an [overview of Cortex data concepts below](/ingesting-data-into-cortex/overview#cortex-data-concepts-reference-table).

> [!TIP]
>
> **Need assistance with data modeling?**\
> \
> To ensure a smooth implementation, most of our customers partner with Cortex Professional Services (PS) for hands-on assistance, including expert guidance on data modeling. Contact [help@cortex.io](mailto:help@cortex.io) to learn more.

## Connecting your data

Connecting your data in Cortex comes down to three building blocks: **entities**, **catalogs**, and **integrations**. Together, they determine what lives in your workspace and how it stays accurate over time.

[Entities](/ingesting-data-into-cortex/entities-overview/entities) are the foundation. An entity is an object that represents a software construct such as a service, a piece of infrastructure, a team, or anything else worth tracking. Entities are defined in YAML, can pull in data from your integrations, can have dependencies, can be organized into hierarchies, and can connect to other entities through entity relationships. You can also enforce standards across them using Scorecards.

[Catalogs](/ingesting-data-into-cortex/catalogs) are how you organize entities into meaningful groups. A catalog is a defined selection of entities used to track and store information about the components that make up your infrastructure.

[Integrations](/ingesting-data-into-cortex/integrations) are how the data flows in. Cortex supports a broad set of integrations that pull live data from the tools your team already uses, creating a single pane of glass across your engineering ecosystem.

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy course on [Catalogs, Entities, and Relationships](https://academy.cortex.io/courses/understanding-understanding-catalogs-entities-and-relationships).

## Cortex data concepts reference table

Learn about the basic data concepts for Cortex below.

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Concept</th>
      <th>Definition</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Team**</td>
      <td>A group of humans responsible for something</td>
    </tr>

    <tr>
      <td>**Service**</td>
      <td>A running technical component (API, job, infra service)</td>
    </tr>

    <tr>
      <td>**Domain**</td>
      <td>A foundational grouping layer that represents a logical or functional area of your organization. Domains form the base hierarchy that organizes entities under stable, high-level boundaries. Each domain reflects a cohesive area of ownership, business function, or technical responsibility.</td>
    </tr>

    <tr>
      <td>**Custom entity**</td>
      <td>Any other trackable thing - ML models, Clients, environment, release, Products. Use this when "service" doesn't fit.</td>
    </tr>

    <tr>
      <td>**Catalog**</td>
      <td>A folder-like visual container, for UI organization only</td>
    </tr>

    <tr>
      <td>**Group**</td>
      <td>A logical collection for search, filtering, and reporting—similar to a label or tag</td>
    </tr>

    <tr>
      <td>**Dependency**</td>
      <td>One entity relies on another; enables impact analysis and notifications</td>
    </tr>

    <tr>
      <td>**Ownership**</td>
      <td>The accountability link between a team and entity</td>
    </tr>

    <tr>
      <td>**Entity relationship**</td>
      <td>The generic link between entities</td>
    </tr>

    <tr>
      <td>**Hierarchy**</td>
      <td>Parent-child or part-of structure; enables inheritance ownership</td>
    </tr>
  </tbody>
</table>


# Cortex beta program and release phases
Source: https://docs.cortex.io/resources/beta



At Cortex, we're constantly building new features to improve operational maturity and reduce developer friction through engineering operations. Our beta program allows you to get early access to upcoming features, help shape their development, and provide valuable feedback before they reach general availability.

## Release phases

Cortex uses a phased approach to release new features, allowing us to gather feedback and iterate based on real-world usage. Understanding these phases helps you know what to expect when trying out new features.

| Release phase | Who can access? | Purpose | Support |
| - | - | - | - |
| Private Beta | Select group of customers by invitation only | Test real-world use cases and gather targeted feedback from pilot customers who can handle pre-release features | Direct support from the Cortex product team |
| Public Beta | All customers have it turned on by default, but certain features may only be available to cloud customers | Offer new features more broadly while still refining details and fixing bugs based on real-world usage at scale | Standard Cortex support channels |
| Research Preview | Depending on the feature, a select group of customers by invitation or all cloud customers | Quickly ship and iterate on AI features | Standard Cortex support channels |
| General Availability (GA) | All customers by default | Full-fledged, stable release ready for production use | Standard Cortex support channels |

## Current beta features

We're currently running beta programs for several exciting features:

| Feature | Status | Get Access |
| - | - | - |
| [AI Impact Dashboard](/resources/beta#ai-impact-dashboard-for-github-copilot-public-beta) | Public Beta | Default |
| [OpEx Review](/resources/beta#opex-review-public-beta) | Public Beta | Default |
| [Cortex MCP with OAuth](/resources/beta#cortex-mcp-with-oauth-public-beta) | Public Beta | Default |
| [Ownership Recommendations](/resources/beta#ownership-recommendations-private-beta) | Private Beta | Default |
| [Harness CD pipelines and deployments](/resources/beta#harness-cd-pipelines-and-deployments-private-beta) | Private Beta | Default |
| [Rootly on-call and incidents](/resources/beta#rootly-on-call-and-incidents-private-beta) | Private Beta | Default |
| [Cortex AI Chat](/resources/beta#cortex-ai-chat-research-preview) | Research Preview | Default |

### AI Impact Dashboard for GitHub Copilot (Public Beta)

> [!NOTE]
>
> This feature is available for Cortex cloud.

Measure adoption and impact of AI coding tools, starting with GitHub Copilot, across your engineering teams. [Learn more](/improve/eng-intelligence/dashboards/ai-impact)

**Key features:**

* Team-level AI adoption correlated with delivery and reliability
* Impact of recent AI usage on engineering performance
* Detailed user-level AI adoption trends over time

### OpEx Review (Public Beta)

> [!NOTE]
>
> This feature is available for Cortex cloud.

OpEx Review is an AI-powered operational excellence review based on the DRIVE framework that turns your Eng Intelligence data into a recurring, narrated report. On a schedule you set, Cortex summarizes what changed since the last cycle and highlights the trends worth your attention, so leaders can spend less time assembling metrics and more time acting on them. [Learn more](/improve/opex-review)

**Key features**:

* **Scheduled, narrated reports** - Cortex generates a report on the cadence you choose and writes a plain-language overview of each cycle.
* **Metrics organized by operational pillars** - Related metrics are grouped into pillars, each with an AI insight explaining what the movement means.
* **AI insights on every metric** - Each metric includes its current value, the change from the prior period, its trend over time, and AI-generated insights that explain what's driving the movement and how it connects to other metrics.
* **Cortex AI chat** (Research Preview) - Open a chat with Cortex AI about any metric; ask follow-up questions, dig into why a metric moved, and pull in related data without leaving the report. [Learn more](/cortex-ai-chat)

### Ownership Recommendations (Private Beta)

> [!NOTE]
>
> This feature is available for Cortex cloud.

Cortex predicts owners with a machine learning model that matches services and service-like entities in your catalog with teams in your catalog. It draws on the structure of your entire catalog, including code contribution activity, the owners of related services, service names and descriptions, domain structure, service metadata, and connections to other tools, such as on-call and issue tracking tools. [Learn more](/ingesting-data-into-cortex/entities-overview/entities/ownership/assigning-owners-to-entities#assigning-ownership-via-cortex-recommendations)

**Key features:**

* View all ownership recommendations in a single page
* Accept or reject recommendations

### Cortex MCP with OAuth (Public Beta)

> [!NOTE]
>
> This feature is available for Cortex cloud.

Connect your MCP client to the remote Cortex MCP by logging in with your Cortex account, with no personal access token required. Add your workspace's MCP server URL to your client, then sign in to Cortex in your browser to authorize the connection. [Learn more](/get-started/cortex-ai-assistant/mcp/mcp-oauth)

**Key features:**

* **Browser-based sign-in** - Authenticate with your Cortex login instead of creating a token and pasting it into your client's configuration.
* **Automatic client registration** - MCP clients register themselves with Cortex through Dynamic Client Registration (DCR), so you don't need a client ID or secret.
* **Works with popular MCP clients** - Connect from Claude Code or any MCP client that supports remote servers over HTTP with OAuth.
* **US and EU regions** - Use the server URL for the region your Cortex workspace is hosted in.

### Harness CD pipelines and deployments (Private Beta)

> [!NOTE]
>
> This feature is available for Cortex cloud.

Cortex now imports pipelines and deployments from Harness and connects them to the services in your catalog. Service owners can see where each service deploys, whether each deployment succeeded, failed, or rolled back, and which version went out, with a link to the run in Harness. [Learn more](/ingesting-data-into-cortex/integrations/harness/importing-data-from-harness)

**Key features:**

* **Pipelines and deployments on entity pages** - View each entity's Harness pipelines and deployment history, filtered by environment or infrastructure.
* **Automatic service matching** - Cortex links Harness services to entities by name, identifier, or `cortex.entity` tag. You can also register services in the entity YAML or from the entity's details page.
* **Workspace-wide view** - See every imported pipeline and deploy on the **Integrations › Data** page.
* **Eng Intelligence metrics** - Harness deployments count toward deployment frequency, rollback frequency, and change failure rate.
* **CQL and Scorecards** - Write rules on Harness data with `cicd.deployments()` and `cicd.pipelines()`.

### Rootly on-call and incidents (Private Beta)

> [!NOTE]
>
> This feature is available for Cortex cloud.

Cortex now imports on-call schedules from Rootly alongside incidents, and connects both to the entities in your catalog. Service owners can see who's on call now and next, and which incidents affected their services, without leaving Cortex. [Learn more](/ingesting-data-into-cortex/integrations/rootly/connecting-entities-to-rootly)

**Key features:**

* **On-call on entity pages** - View who's on call now and next for an entity, and see upcoming rotations in the **My on-calls** block on your homepage.
* **Automatic matching** - Cortex links Rootly services to entities by the Cortex ID from Rootly's Cortex integration or by service name, and links on-call through each service's escalation policy and each schedule's owning team. You can also register services, schedules, and teams in the entity YAML or from the entity's details page.
* **Workspace-wide view** - See every imported incident and on-call shift on the **Integrations › Data** page.
* **Eng Intelligence metrics** - Rootly incidents count toward incident frequency and mean time to resolution (MTTR).
* **CQL and Scorecards** - Write rules on Rootly incident and on-call data.

### Cortex AI Chat (Research Preview)

> [!NOTE]
>
> This feature is available for Cortex cloud.

Cortex's AI-powered chat assistant answers questions about your engineering data in plain language and grounded in your real Cortex data. Open it beside whatever page you're on with ⌘J, or give it a full page of its own for longer sessions. [Learn more](/cortex-ai-chat)

**Key features**:

* **Ask from anywhere** - A side panel that opens over your current page, plus a dedicated page with conversation history.
* **Grounded in the page you're on** - Ask "who owns this?" on an entity or Scorecard page without naming it.
* **Reaches your workspace** - Catalog, Scorecards, Initiatives, Workflows, Engineering Intelligence metrics, the Cortex documentation, and more.

## Join our beta program

### Why join?

* **Early Access.** Be among the first to try new features before they're available to everyone.
* **Shape the Product.** Your feedback directly influences feature development and prioritization.
* **Exclusive Perks.** Beta participants may receive special recognition, early access to future features, or other benefits.
* **Direct Collaboration.** Work closely with our product team to ensure private beta features meet your needs.

### How to join

1. Review the current beta features listed above to see what interests you.
2. Try out any public beta features already enabled and provide any feedback through the link on the feature's public beta banner.
3. Click **Request Access** on any private beta feature you'd like to try.
4. Fill out the brief form to tell us about your use case.
5. We'll review your request and follow up within 3-5 business days.

Not all requests can be accommodated for private beta features due to capacity constraints, but we'll do our best to include as many participants as possible.

### What we ask of beta testers

* **Provide Feedback.** Share your experiences, both positive and negative, through our feedback channels.
* **Report Bugs.** Help us identify issues by reporting them promptly with detailed information.
* **Be Patient.** Beta features may have rough edges or change during the testing period.


# Further help
Source: https://docs.cortex.io/resources/help



Whether you're just getting started with Cortex or looking to deepen your expertise, we offer several ways to find answers, build skills, and stay in the loop. This article walks through four resources that extend beyond our standard help articles: **AI Docs Assistant**, **Cortex Academy**, **Cortex Blog**, and **Cortex Professional Services**.

# AI Docs Assistant

The AI Docs Assistant, powered by Kapa, is your fastest path to an answer. It's a conversational assistant trained on the Cortex documentation, so instead of searching through articles, you can simply ask a question and get a direct response with links to the relevant docs.

**Where to find it:**

* **In the help center** - At the top of the docs, click **Ask**, or use the keyboard shortcut `CMD+K` to open the AI Docs Assistant. Ask questions in natural language and get instant, accurate answers.

  ![The AI Docs Assistant icon at the top of the docs answers a user query.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/docs-ai-search.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=33c82db4e05fb975a263932d5246a925)
* **In Cortex** - Click **Search** (or use `CMD+K`), then click the **Ask AI icon** . Type in a question and get answers without having to leave Cortex.\


  ![The AI Docs Assistant in the Cortex app.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/ai-docs-assistant-in-app.png?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=b721c297bd5e5bb40dda49adf4c6afcc)

**What it's great for:**

* Quick how-to questions, e.g. ***How do I set up a Scorecard?***
* Troubleshooting common issues
* Understanding a feature before you dive in
* Pointing you to the right doc when you're not sure where to look

The AI Docs Assistant works best when you ask specific, focused questions. If you need a step-by-step walkthrough or want to validate a complex configuration, follow the doc links it provides for the full context.

# Cortex Academy

[Cortex Academy](https://academy.cortex.io/) is our learning management system (LMS), built for teams who want structured, hands-on training. Whether you're a brand-new admin standing up Cortex for the first time or a power user looking to master advanced features, the Academy has a course for you.

**What you'll find:**

* **Role-based learning paths** - Curated tracks for admins, developers, platform engineers, and engineering leaders.
* **Self-paced courses** - Work through lessons on your own schedule, with progress saved as you go.
* **Hands-on exercises** - Apply what you learn in guided scenarios that mirror real Cortex workflows.
* **Certifications** - Earn credentials that demonstrate your Cortex expertise to your team and the broader community.

The Academy is a great option when you want to go beyond "how do I do this one thing" and build a deeper, more durable understanding of the platform. Many customers roll the Academy into their onboarding process for new engineers joining a Cortex-powered organization.

> [!TIP]
>
> Looking for a quick introduction to Cortex? Check out the [Cortex 101 video](https://academy.cortex.io/learn/video/cortex-101).

# Cortex Blog

The [Cortex Blog](https://www.cortex.io/blog) is where we share what's new, what we're learning, and what's working for the engineering teams we partner with. It's the best place to stay current between product releases and to pick up ideas from the broader EngOps community.

**What we publish:**

* **Engineering insights** - Deep dives on developer experience, platform engineering, service ownership, and the practices behind high-performing engineering organizations.
* **Product updates** - Release notes, feature announcements, and previews of what's coming next.
* **Best practices** - Tips, patterns, and customer stories that show how teams are getting the most out of Cortex.

If you want to keep a pulse on Cortex without checking back manually, subscribe to the blog or follow us on LinkedIn for new posts as they go live.

# Cortex Professional Services

To ensure a smooth implementation, partner with Cortex Professional Services (PS) for expert guidance and hands-on assistance with data modeling, entity ownership, and more. Reach out to [help@cortex.io](mailto:help@cortex.io) to learn how we can support your implementation and adoption journey.

# Choosing the right resource

Each of these resources serves a different need:

* **Have a quick question right now?** Start with the AI Docs Assistant.
* **Want to build real expertise?** Enroll in Cortex Academy.
* **Curious what's new or how others are doing it?** Browse the Cortex Blog.
* **Looking for guided implementation?** Reach out to Cortex Professional Services.

Our [help center articles](https://docs.cortex.io) remain the source of truth for detailed product documentation. And if you can't find what you need across any of these channels, our support team is always happy to help!

**Opening a support ticket:**

* **In Cortex** - From the main sidebar, click your avatar in the bottom-left corner. Click **Help & docs**. Select **Submit a request**.

  ![In App Help](https://mintcdn.com/cortex-290c0c42/4tRxSDOxhMkPeY0E/images/in-app-help.png?fit=max\&auto=format\&n=4tRxSDOxhMkPeY0E\&q=85\&s=b6cc1c0b794f3d78dd5c2891d0bd4cf3)
* **In Customer Portal** - Go to [https://support.cortex.io](https://support.cortex.io/).
* **In Slack** - If your organization has a connected Slack channel, a support workflow is automatically added to your account. To reach our team, either mention '@CortexTechnicalSupport' or add a `:ticket:` reaction to any message, and the team will respond directly in the thread.
* **In Microsoft Teams** - If your organization has a shared Microsoft Teams channel with Cortex, a support workflow is automatically added to your account. To reach our team, add a `:ticket:` reaction to any message and the team will respond directly in the thread.
* **Via Email** - Send a message to [help@cortex.io](mailto:help@cortex.io).

Don't have a Slack or Microsoft Teams channel set up yet? Reach out to your Customer Success Manager to get one configured.


# Cortex Query Language (CQL)
Source: https://docs.cortex.io/standardize/cql



Cortex Query Language (CQL) is a proprietary domain-specific language (DSL) you can use to query details in-depth about your Cortex entities. CQL is at the core of many Cortex features, from defining how [Scorecards](/standardize/scorecards) evaluate health and readiness to deciding which entities a [plugin](/streamline/plugins) should appear on.

With CQL, you can:

* Query your data immediately (including from third-party integrations or [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data)), without having to move it, transform it, or wait for batch jobs
  * Cortex does not require you to configure custom processes for each new standard you want to track
  * You can [utilize JQ in CQL](/standardize/cql/using-jq), allowing you to do arbitrary JSON manipulations (e.g., fetch nested fields, group by, sum over, etc.). Cortex can transition seamlessly between CQL and JQ data types.
* Use basic arithmetic and utility functions to get the data you need
* Customize [Scorecard](/standardize/scorecards) rules to query information needed to assess your processes quickly
  * For example, you can [use CQL captures to display the cause of rule failures in a Scorecard](/standardize/scorecards/scorecard-examples#using-cql-captures-to-display-the-cause-of-rule-failures).
* Create reusable [CQL reports](/standardize/cql/cql-reports) to view any query result, such as the number of incidents your services had in the last week

> [!TIP]
>
> CQL allows you to ask multi-source questions, such as, "Who's on call for services in our payment product?" or "Which services are still on the old secrets manager?"
>
> It also provides a consistent way to write rules, regardless of the data source. For example, you can use `git.fileExists()` to search across all of your Git repositories without needing to specify the Git provider.

## CQL basics

See additional CQL instructions and examples in the [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) in your workspace.

### CQL format and data sources

CQL queries use the format `data source` `function` `quantifier`, with the `function` and `quantifier` options differing depending on the data source and type.

The data sources for CQL are:

* **Entity metadata**: Core entity details
  * Example query: `dependencies.in().length`
* **Integrations**: Data from [third-party sources](/ingesting-data-into-cortex/integrations)
  * Example query: `jira.numOfIssues()`
* **Custom data**: Data attached to the entity, [sent via API](/api/rest/custom-data) or defined in the [entity YAML](/ingesting-data-into-cortex/entities-overview/entities/custom-data#editing-the-entity-descriptor)
  * Example query: `custom("cloud-cost") .cost.compute.actual`
* **Custom metrics**: Time series data from custom metrics you've defined
  * Example query: `customMetrics(key="error-rate", lookback=duration("P30D")).map((m) => m.value).average()`

CQL expressions return different data types, and each type supports specific operations within queries. See the available data types and their supported operations in the [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer?path=CQL+explorer,Data+types).

Some data sources return a list of records rather than a list of numbers. To aggregate a single field across those records, use `map()` to extract the field first, then apply the aggregation. For an example, see [Querying custom metric data with CQL](/improve/eng-intelligence/custom-metrics#querying-custom-metric-data-with-cql).

### Combining CQL expressions

You can combine CQL expressions in multiple ways:

* Use `AND` to require multiple conditions to be true
  * Example: `entity.type() == "container" AND entity.tag() == "production"`
* Use `OR` to allow for multiple possibilities
  * Example: `entity.type() == "container" OR entity.type() == "function"`
* Combine `AND` and `OR` with parentheses
  * Example: `(entity.type() == "container" OR entity.type() == "function") AND entity.tag() == "production"`
* Use `!` to negate a condition
  * Example: `!entity.tag() == "production"`

### Captures

You can include entity or CQL evaluation data in a rule's description and failure message using captures. This will enable you to create a Scorecard rule description or failure message that reflects the rule’s score and affected entity descriptor information (including dependencies and custom data if set in the YAML). Captures allow you to update your rule expressions to “capture” certain pieces of an expression into variables.

> [!NOTE]
>
> Learn more about captures
>
> * See additional instructions on using captures in [Cortex's CQL explorer](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Captures).
> * Read about a capture use case in [Scorecard examples: Using CQL captures to display the cause of rule failures](/standardize/scorecards/scorecard-examples#using-cql-captures-to-display-the-cause-of-rule-failures).

### The context object

When you write a Scorecard rule's description or failure message, you have access to a `context` object that includes data about the entity and evaluation. In addition to `context.evaluation.captures` (see [Captures](/standardize/cql#captures) above), you can reference `context.entity.id` (the entity's unique Cortex ID) to build direct links to that entity's page in Cortex. Entity page URLs are keyed on this ID, following the pattern `/admin/<category>/<cid>/<tab>`.

For example, the following failure message links directly to the failing entity:

```
This entity is failing a Scorecard rule. [View entity](https://app.getcortexapp.com/admin/service/{{context.entity.id}})
```

This failure message links to the entity's **Deploys** tab:

```
This entity is failing a Scorecard rule. [View deploys](https://app.getcortexapp.com/admin/resources/{{context.entity.id}}/deploys)
```

### CQL testing

Anywhere in Cortex where you use CQL, testing functionality allows you to quickly review and iterate on your queries. Below the CQL editor, select up to 10 entities to test against then click **Test**. Test results appear per entity below the editor.

![Enter a CQL expression and click Test. Results will appear below the text editor.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/test-cql-queries.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=881b82116233aeee695e429a1079e395)

You can test both boolean and non-boolean expressions anywhere in Cortex, but you can only save non-boolean expressions in [CQL Reports](/standardize/cql#cql-reports).

## CQL tools

### The Query builder tool

The Query builder allows you to leverage all of CQL's power to investigate information about your entities without building an entire Scorecard.

The functionality of the Query builder depends on your [permissions](/configure/settings/managing-users/permissioning). Users who have the ability to edit Scorecards can run queries that talk to third-party integrations. Users without those permissions can run queries on custom data and anything else that exists within Cortex. Users classified as viewers are not able to run queries.

To see the Query builder, click **Tools > Query builder** in the main nav.

![Click Tools > Query builder from the main nav.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/tools-query-builder.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=7e09383c5e1fa5dfc88375bb810fc27c)

> [!TIP]
>
> **Using custom data in CQL queries**
>
> You can add [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data) to any entity, and you can access custom data from any [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details). For example, if you run a security scanning tool that isn't in the list of existing integrations, you may run a vulnerability scan as part of your CI process and then send that data to Cortex.
>
> With the Query builder, you can query against any of this custom data. Anything that can be evaluated with a Scorecard will display in the Query builder, which allows you to essentially use Cortex as a database. Because Cortex is able to pull data from many data sources, the Query builder can even provide more insight than GitHub search.

### CQL explorer

[CQL explorer](https://app.getcortexapp.com/admin/cql-explorer) contains instructions and examples for specific data types, entity metadata, custom data, and more.

You can access it via Query builder or as a standalone page:

* **On the Query builder page**: On the right side of the Query builder, click the **CQL explorer** tab to view CQL instructions and examples for specific data types, entity metadata, custom data, and more.

  ![CQL explorer is on the right side of the Query builder.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/cql-explorer-sidepanel.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=c5d32197278b334425e44d4ffecfe7c1)
* **As a standalone page**:
  1. Click the flag icon on the right side of your Cortex workspace.

     ![Click the purple flag icon on the right side of your workspace.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/resource-flag.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=1426a5a212b5d2f29a8726511e5c44ff)
  2. In the Help & Docs side panel, click **CQL explorer**.

     ![Click the CQL explorer link in the 'Help and docs' sidebar.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/cql-explorer-link.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=78469c99c3931fa6bcdc7cb62c7b3166)

### CQL reports

CQL reports allow you to query all of the raw data in Cortex and build a custom report on the data. Learn more in [Using CQL reports](/standardize/cql/cql-reports).

## Running and saving CQL queries

To learn about running queries and saving queries, see [Running and saving CQL queries](/standardize/cql/run).


# Using CQL reports
Source: https://docs.cortex.io/standardize/cql/cql-reports



CQL reports let you query your entities with Cortex Query Language (CQL) and visualize the raw results. Use them when you need to extract, analyze, or share detailed data that goes beyond pass/fail checks, or when you want a reusable report that refreshes on its own.

CQL reports give you more flexibility than Scorecards or Query builder:

* View any expression result, such as the exact number of incidents, deployment counts, or custom data values for each entity. Scorecards and Query builder require expressions to evaluate to a boolean.
* Build custom reports that aggregate and display data from entity metadata, integrations, and custom data.
* Debug Scorecard results by surfacing the underlying data that drives rule outcomes.
* Export filtered data for further analysis or sharing.

## Creating a CQL report

Users with the `Run Query Builder` permission can create and run a CQL report. To run queries on third-party integrations, the `Run Query Builder with Third-party Integrations` permission is also needed.

**To create a CQL report**:

1. From the main sidebar, expand **Tools**, then select **CQL reports**.
2. In the upper-right corner of the CQL reports page, click **Create CQL report**.
3. Do one of the following:
   * Click **Start from scratch** to build your own report.
   * Select a template to start from a prebuilt report.
     * Templates include your organization's own and Cortex's built-in options, so your report follows best practices from the start.
4. Configure the report details:
   1. In the **Details** section:
      1. **CQL report name** - Enter a name for the report (required).
      2. **Description** - Enter a description for the report. This helps others in your workspace understand the purpose of the report.
      3. **Enable auto refresh** - Toggle on this setting if the report should be automatically evaluated on a specified interval.
         1. **Evaluation window** - Set how often Cortex evaluates the report. Cortex evaluates the report every 24 hours by default. The shortest window you can set is 12 hours and the longest is 336 hours. Choosing a longer window can help you stay within your integrations' rate limits.
   2. In the **Apply to specific entities** section:
      1. Narrow the report's scope by selecting entity types from the **Search entity types** dropdown. Leave it blank to apply the report to all entities.
      2. **Advanced options** - Refine your selection further by including or excluding groups. You can [test and iterate](/standardize/cql#cql-testing) on a CQL expression as you write it.
         * You can't query third-party integrations when refining the entity selection for a CQL report.
   3. In the **Columns** section:
      1. Click **Add column** to add new CQL expressions to the report. When you add or edit columns, choose how to define them: write a CQL expression in the **Query builder**, or select rules from your configured integrations in the **Form builder**. In the **Add column** side panel, do the following:
         1. From the **CQL** tab:
            1. Click **Add CQL query** to open the **Query builder**.
            2. Add and test your query.
            3. Click **Save query**.
            4. Under **Name**, enter a name for the column (required).
            5. Optionally, enter a description of the column.
            6. Click **Save column**.
         2. From the **Form** tab:
            1. Select an integration from the **Integration** dropdown.
            2. Select a rule from the **Rule** dropdown.
            3. Under **Name**, enter a name for the column (required).
            4. Optionally, enter a description of the column.
            5. Click **Save column**.
5. If you want your report to be publicly available to other users in your workspace, toggle on **Public**.
6. Click **Create**.

> [!NOTE]
>
> A cell value can hold a maximum of 12 KB (12288 bytes). If a return value exceeds that (e.g. a 5 MB JSON file), the cell errors out, so define raw values for your outputs.

**To edit an existing CQL report**:

1. Open the CQL report you want to edit.
2. In the upper-right corner of the page, click **Edit**.
3. Make any necessary changes, then click **Save**.

## Viewing a CQL report

To view a CQL report, expand **Tools** from the main sidebar, then select **CQL reports**.

> [!NOTE]
>
> Select the **All** tab to view every CQL report in your organization, including drafts. Select the **Public** tab to view only published reports.

![The CQL reports page in Cortex.](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/cql-report-list.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=56ff8680b60a0323a9d15a14f21df296)

### Sorting and filtering a CQL report

Every CQL report has a toolbar above the results table. Use it to narrow a report down to the entities and columns you care about.

You can sort by each column of the report, select which columns are displayed, search across the values in any of the report's columns, and filter by AWS account, AWS region, domain, entity, entity type, group, owner, or team.

**Sorting the results**

Click a column header to sort by that column, then click it again to reverse the direction.

You can also click the sort button in the toolbar, which is labeled with the field you're currently sorting by, e.g. Name. Select a column, then click the arrow next to your selection to switch between ascending and descending.

![](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/cql-name.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=b022c70ca40ddd680f35e266b6ed0106)

**Choosing which columns appear**

Click **Display** to show or hide columns. Click **Show all** to turn on every column, or **Reset display** to go back to the report's default columns. Click **Done** when you're finished.

![](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/cql-display.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=b173509bde7d03b4f93dc951125979d8)

**Filtering the results**

1. In the toolbar, click **Filter**.
2. Select a field from the panel on the left: AWS accounts, AWS regions, Domains, Entities, Entity types, Groups, Owners, or Teams.
3. From the dropdown, select the values you want to keep. Search for a specific value, click **Select all**, or turn on **Show only selected** to review what you've picked.
4. Repeat for as many fields as you need.
5. Click **Apply**.

![](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/cql-filter.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=dd10c54ffed6d7093c099e38e3b76b68)

The Filter button shows how many filters are active. To remove one filter, click the **trash icon** on its card. To clear all of them, click the **X** next to the filter count, or click **Reset filters**. Cancel discards any changes you haven't applied yet.

### Sharing a CQL report

A report must be set to **Public** in order to share it.

You may need to share a CQL report with teams or leaders to provide detailed, custom insights into entity data, compliance, or operational metrics.

In the upper-right corner of the page, click **Export CSV** to download a CSV file of the report data:

![The 'Export CSV' button in the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/cql-export-csv.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=d58fd0efd20dc3f76e235fbc883c801d)

Large reports can take a while to download. While the download is in progress, click **Email me** in the notification in the bottom-right corner of the page to have the CSV sent to your Cortex login email instead:

!['Email me' button in the notification in the bottom-right corner of the page.](https://mintcdn.com/cortex-290c0c42/uWo5OVZ0DdR5tZ8Q/images/email-me-toast.png?fit=max\&auto=format\&n=uWo5OVZ0DdR5tZ8Q\&q=85\&s=e36cae63b4f73121d8f4dc22a9887672)

### Refreshing a CQL report

Cortex doesn't refresh a CQL report on its own unless you turn on auto refresh. The top right of a report page shows when its data was last refreshed, or tells you the data has expired and needs a refresh.

**To refresh a report manually**:

1. Open the report.
2. Click the **overflow menu icon** in the upper-right corner of the page.
3. Click **Refresh CQL report**.

**To enable auto refresh**:

Auto refresh is off by default. You can turn it on while you create a CQL report, or edit an existing report to add it later.

1. Open the report.
2. In the upper-right corner of the page, click **Edit**.
3. In the **Details** section, toggle on **Enable auto refresh**.
4. Set the **Evaluation window (in hours)**. Cortex evaluates the report every 24 hours by default. The shortest window you can set is 12 hours and the longest is 336 hours. Choosing a longer window can help you stay within your integrations' rate limits.
5. Click **Save**.

> [!WARNING]
>
> If a report contains expressions written with an outdated version of CQL, a warning banner at the top of the page tells you the report can't be refreshed. Update the outdated queries, then refresh the report.

## Using CQL reports to debug Scorecards

You can use CQL reports to help interpret unexpected results from Scorecards.

For example, let's say you have a service that is failing the rule `README created`. However, you believe the service does have a `README`, and you aren't sure why it's failing this rule.

![](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/cql-report-example%20%281%29.jpg)

You can create a CQL report from scratch and add a new column for the `README` CQL expression to check for `README.md` in the git repo:

![](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/cql-readme.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=9dce43702861a58e9418ef6a8ad89dbd)

After saving the CQL report, you can view the results to see the contents of `README` files for each entity. In this report, you can see if the `README` contains an error such as "The result is too large to store," which would explain why the entity is failing that rule in the Scorecard.


# Running and saving CQL queries
Source: https://docs.cortex.io/standardize/cql/run



Learn about CQL basics and CQL tools (Query builder and CQL explorer) in [Cortex Query Language (CQL)](/standardize/cql).

## Running a CQL query

The [Query builder](/standardize/cql#the-query-builder-tool) allows you to define your query without needing to learn CQL upfront.

You will need the `Run query builder` permission. If you are running queries on third-party integrations, you will also need the `Run query builder with third-party integrations` permission.

### Step 1: Build a query

1. On the right side of the Query builder page, click the **CQL builder** tab. \\

   ![CQL builder is on the right side of the Query builder page.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/cql-builder-tab.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=17334738cca161fc6c1cd761a7dd9094)
2. In the CQL builder, choose and integration and a rule to evaluate.
   * The rules available in the dropdown menu will depend on the integration you've selected.
   * Depending on the rule you choose, you may need to configure additional fields.
3. Click **Use query**. The query will automatically populate into the CQL text editor on the left side of the page.\\

   ![Click 'Use query' in CQL builder, then the query populates the CQL search field.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/use-query.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=b46adabec7d971abe58e7143b92a0f6a)

### Step 2: Test the query

1. Under the CQL editor on the left, open the **Select entities** dropdown.
2. Optionally, to narrow the list of entities, click **All entity types**, then select one or more entity types. You can search the list by type name, and clear your selections to return to the full list.\


   ![](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/cql-all-entity-types.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=53d9605e386046c7c590b4663ecb8dbf)
3. After you've selected the entity type, select the entity or entities you want to test the query against.\


   ![](https://mintcdn.com/cortex-290c0c42/QcQzHjqU3EBU2R8X/images/cql-select-entities.png?fit=max\&auto=format\&n=QcQzHjqU3EBU2R8X\&q=85\&s=d50c0ce8473e300101437aaa5a8a0c12)
4. Click **Test**. The results appear under the text editor. Review the results to verify that the query is working as you expect.\


   ![](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/test-query.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=d4a9157d7dd7e2a7bd1c7ca6e74f0cd7)

### Step 3: Run the query

1. In the lower right corner of the page, click **Run query**.
2. In the side panel that opens, choose whether to run the query on all entities or select specific entities.

   ![Choose which entities to run the query on](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/run-query-panel.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=0487378b3ab07e1c477fb82c45c5d1a4)
3. At the bottom of the side panel, click **Run query**.
4. In the confirmation modal that appears, click **Yes, run query**.

### View and share results

After running the query, the page displays a list of all entities matching the criteria. In the upper right corner of the list, you can sort and filter the list. As you apply filters to your list, Cortex will also update the number of matching entities, so you can easily see at a glance how many entities match your requirements.

You can share the results in two ways:

* **Send a link**: Click **Share** in the upper right corner of the results list to copy the URL to your clipboard. You can share the link with anyone who has access in your Cortex workspace.
* **Export as CSV**: In the upper right corner of the page, click **Export CSV** to download a CSV file of the data.

### Running rules on multiple queries

If you want to run a query on more than one rule, you can join multiple queries together with `AND` and `OR`.

For example:

```
git.commits().length == 2 AND azureDevops.workItems().length > 4
```

### CQL errors

The following errors may occur when running a CQL query:

* `400`: This typically indicates a misconfiguration with an integration. For example, you may be missing an entity registration required for an integration.
* `403`: This occurs if there are missing or improper [permissions](/configure/settings/managing-users/permissioning).
* `429`: This occurs when hitting the rate limit for an integration. Cortex will retry 5 times before responding with this error. To prevent rate limit issues, we have built a self-throttling system that proactively throttles before hitting a rate limit from the vendor.
* `500`: This indicates that the integration itself returned an error.

## Save a query

While viewing the results of a query you ran, you can save the query to use again in the future:

1. In the upper right corner of the results page, click **Save query**.\\

   ![Click 'Save query' in the upper right.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/save-query.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=6e52f72a4a1a7d93db449f8488900acd)
2. In the side panel, configure the query details:
   * Enter a name and description for your query.
   * To allow other users in your Cortex workspace to see the query, enable the toggle next to **Share across organization**.
3. Click **Save**.

## View active, recent, and saved queries

Below the CQL search text box, you can see active queries. This section displays the ongoing process of your submitted query. When the query is complete, it will appear under **Recent**.

Along the top of the query builder, you can click into tabs to view **Saved** and **Recent** queries. Click into any of the queries in these lists to view the results of the query.

![Query builder has tabs for Search, Saved, and Recent.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/query-builder-tabs.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=059e7872f6d53c45e885a64d88913da5)

### Saved queries

Click the **Saved** tab to view a list of your saved queries, and queries that others have saved and shared across your organization.

Query results are not automatically updated, but you can refresh a query manually: While viewing the results page, click the 3 dots icon, then click **Refresh**.

![Click the 3 dots icon then click Refresh.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/refresh-query.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=e9e91a1e96e0faaa00135f2e18aec85a)

> [!TIP]
>
> When configuring a [CQL report](/standardize/cql/cql-reports#enable-auto-refresh-for-cql-reports), it is possible to enable automatic refresh.

### Recent queries

Click the **Recent** tab. This list shows all queries that have been run in the last 30 days.


# Using JQ in Cortex
Source: https://docs.cortex.io/standardize/cql/using-jq



[JQ](https://stedolan.github.io/jq/) is a lightweight, flexible command-line JSON processor that allows users to do arbitrary JSON manipulations.

Cortex leverages JQ within CQL to enable complex queries, including queries on YAML files. For instance:

```
jq(custom("foo"), ".property | length")
```

The above query would cycle through the `foo` object and retrieve the length of all `.property` components. This type of query is often used on Kubernetes resources.

### JQ and datatypes

JQ can provide additional flexibility around data types. For instance, let's say you have a string associated with a numerical value in your Custom Data.

```
x-cortex-custom-metadata:
  my-key:
    line: "100"
```

If you wanted to query on the line value as a number rather than string, the following JQ functionality could be used within CQL:

```
jq(custom("my-key"), ".line | tonumber") > 99
```

This would result in the respective entity passing this CQL check.

### JQ examples

The following examples demonstrate ways you could use JQ in Cortex:

#### Use JQ to implement conditional logic for selecting file paths dynamically

```
git.fileContents(jq(custom("git"), "if . != null then .[\"dockerfile-path\"] else \"Dockerfile\" end
```

This checks if custom git data exists, uses the custom dockerfile path if present, or falls back to the default "Dockerfile" path.

#### Accessing properties with special characters

Use bracket notation to access JSON properties containing dots, slashes, or other special characters:

```
jq(k8s.spec().firstOrNull().selector.matchLabels, ".[\"app.kubernetes.io/instance\"]")
```

#### Handling null values

Prevent errors by checking for null values before accessing properties:

```
jq(custom("data-key"), 'if .retryConfigurations != null then .retryConfigurations | map(.retryAttemptTime) else "Not Found" end')
```

For Scorecard rules, you can use a similar approach:

```
custom("retry-circuit-breaker") != null
```

#### Wildcard pattern matching

Find packages containing specific strings using the matches() function:

```
jq(custom("data-source").packages.filter((package)=>package.packageName.matches(".*<string-text-here>.*")).map((package) => package.packageVersion), ".")
```

#### Finding team members by role

Filter team members by role using JQ:

```
jq(entity.descriptor().info.`x-cortex-team`.members, "map(select(.role == \"engineering-manager\")) | .[].name")
```

#### Handling complex YAML structures

When working with complex YAML files like GitLab CI configurations:

```
jq(git.fileContents('gitlab-ci.yaml').split(' ').filter((section) => section.matchesIn('NODE_VERSION:')).firstOrNull(), '.variables.NODE_VERSION')
```

#### Extract the scheme of an AWS load balancer for resource metadata

```
jq(aws.details(), ".resources[0].Scheme")
```

Or, for nested metadata:

```
jq(aws.details(), ".resources[0].metadata.Scheme")
```

#### Extracting version from pom.xml file

This query extracts the version number from a Maven pom.xml file. You might use this to automate dependency version checks:

```
jq(jq(git.fileContents("pom.xml").split("<version>"),".[1]").split("</version>"), ".[0]")
```

#### Display a parent entity name in a CQL report

This query would allow you to display a parent entity name value, rather than an array, in a CQL report:

```
jq(entity.parents().map((parentEntity) => parentEntity.parents.map((parentEntity) => parentEntity.name)), ".[0]")
```


# Scorecards overview
Source: https://docs.cortex.io/standardize/scorecards



A Scorecard is a set of rules that Cortex measures your entities against, continuously and automatically. You write down what "good" looks like once, and Cortex tells you which entities meet that bar, which don't, and why.

Standards tend to live in wiki pages, onboarding checklists, and the heads of a few senior engineers. They drift. Scorecards move those standards into a place where they're visible, measurable, and hard to quietly ignore.

Use Scorecards to establish best practices, define maturity standards, track a migration, enforce consistency across entities, and give teams a clear picture of what they own and where it stands.

![The Scorecards list.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scorecards-generic.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=7616ec47c45cc5a8c00600b89cf40ddb)

> [!TIP]
>
> Looking to dive deeper? Check out the Cortex Academy course on [Scorecards](https://academy.cortex.io/courses/understanding-scorecards).

## The anatomy of a Scorecard

Every Scorecard is built from four pieces.

**Entities** - The things being measured. A Scorecard applies to a set of entities you define by entity type, and you can narrow that set further with groups or a [CQL expression](/standardize/cql). A production readiness Scorecard might apply only to tier 1 services; an AI maturity Scorecard might apply to every service you have.

**Rules** - A single, checkable statement about an entity: it has an owner, it has a runbook, its P50 latency is under two seconds, it has no critical vulnerabilities. Each rule either passes or fails for each entity. Rules can read an entity's metadata inside Cortex or pull live data from your [integrations](/ingesting-data-into-cortex/integrations).

**Levels or points** - How you express progress. Levels group rules into ordered tiers (Bronze, Silver, Gold) so teams know what to do first. Points assign a weight to each rule so more important work counts for more. See [Choosing levels or points](/standardize/scorecards#choosing-levels-or-points)

**An evaluation window** - How often Cortex rechecks every rule against every entity. The default is every four (4) hours. Because scores refresh on their own, a Scorecard is a live signal, not a snapshot someone needs to update.

## Understanding Scorecard rules

A rule is where a vague standard becomes a specific, testable claim. "Services should be observable" isn't a rule, but "The entity has a Datadog monitor" attached is.

Getting there is the real work of building a Scorecard, and it's usually worth doing in the open with the teams being measured. Two things make it easier:

* The form builder offers pre-configured rules for each integration you've set up, so most common checks are a couple of selections.
* The CQL editor lets you write the rule yourself in [Cortex Query Language](/standardize/cql), which is what you'll reach for when a rule spans multiple data sources or encodes something specific to your organization.

A few properties change how a rule behaves in practice:

* A failure message turns a red mark into a next step. Without one, a failing rule tells a developer they're wrong but not what to do; with one, it can link straight to a runbook or a [Workflow](/streamline/workflows) that fixes the problem.
* A scheduled start date lets you announce a rule before it counts, so teams see what's coming instead of waking up to a lower score.
* A rule filter restricts a rule to certain groups, for cases where a rule is right for most of the Scorecard's entities but not all of them. See [Scorecard rule filters](/standardize/scorecards/scorecard-filters)
* An exemption removes a rule from a specific entity. Exempted entities aren't marked passing or failing; the rule simply doesn't apply. See [Scorecard rule exemptions](/standardize/scorecards/rule-exemptions)

Filters and exemptions matter more than they sound. A standard that's obviously wrong for some entities loses credibility fast, and teams stop treating any of the score as meaningful.

## Choosing levels or points

Levels and points answer different questions.

**Levels** answer "what should this team do next?" An entity reaches a level only after passing every rule in it and below, so put non-negotiables first. Good for maturity models, onboarding, and production readiness. A rule can't repeat across levels, but the bar can rise: P50 latency under five (5) seconds at Bronze, under two (2) at Gold.

**Points** answer "how much does each of these things matter?" Every rule carries a weight, and an entity's score is the sum of what it passes. Nothing is gated behind anything else. Points suit checks that are genuinely independent, or where you want to reward going beyond the minimum: one point for a runbook, another point for more than one.

You can use both in a single Scorecard—points within levels—to signal priority order and relative weight at the same time.

## Scorecards, Initiatives, and Reports

Scorecards measure. On their own, they don't create urgency, and they don't tell a story to leadership. Three other features cover that ground.

[Initiatives](/improve/initiatives) add a deadline. A Scorecard says "services should have a runbook"; an Initiative says "every tier 1 service needs one by September 30, and Cortex will remind owners as that date approaches." If a goal is urgent or has a fixed date, that's an Initiative on top of a Scorecard, not a Scorecard on its own.

[Reports](/improve/reports) roll scores up. A Bird's eye report, Progress report, or Report card turns per-entity results into something you can bring to a review without exporting anything.

[Eng Intelligence](/improve/eng-intelligence) explains patterns. When a Scorecard shows a team consistently behind, Eng Intelligence dashboards help you see whether the cause is workload, process, or something else.

There's also a loop back to automation: a rule that a lot of teams fail the same way is usually a process problem, not a discipline problem. That's a good candidate for a [Workflow](/streamline/workflows) that makes the right thing the easy thing.

Watch how Scorecards, Initiatives, and Reports work together to drive business goals:

[YouTube video player](https://www.youtube.com/embed/oIWbMlK7Qh4)

## How teams use Scorecards

**Step 1**

**Define**

Decide which entities are in scope, write the rules, and choose levels or points. Start with a template if one is close to what you need, and keep the Scorecard in draft while you shape it.

Learn more: [**Create a Scorecard**](/standardize/scorecards/create)

**Step 2**

**Assess**

Publish it and let Cortex evaluate. The first results tell you where things actually stand. Read them for patterns as much as for individual failures, e.g. whether legacy services lag, whether one team owns more than its share, or whether a rule fails so widely that the rule itself is the problem.

Learn more: [**Review and evaluate a Scorecard**](/standardize/scorecards/evaluate)

**Step 3**

**Take action**

Fix the highest-impact failures, attach deadlines to the urgent ones with [Initiatives](/improve/initiatives), and automate the standards teams keep missing. Scores update on their own, so progress shows up without anyone reporting it.

Learn more: [**Take action on a Scorecard**](/standardize/scorecards/evaluate#taking-action-on-a-scorecard)

Scorecards work best when they're treated as living documents. Standards change, and a Scorecard nobody has edited in a year is usually measuring last year's priorities. Any time you save a change, Cortex begins reevaluating the affected entities.

## Designing a Scorecard people take seriously

A few things separate Scorecards that change behavior from Scorecards teams learn to ignore.

* **Start smaller than feels right**. A Scorecard with 40 rules on day one reads as an indictment. A first level of five rules everyone agrees with earns the credibility to add more.
* **Make every rule fixable**. If a developer can't tell what to do from the rule and its failure message, the rule is a complaint, not a standard.
* **Write rules with the teams being measured, not for them**. Standards imposed from outside get exemption requests; standards teams helped write get followed.
* **Let some things not apply**. Use filters and exemptions rather than accepting permanent failures. Rules that can never pass teach people that red is normal.
* **Recognize the wins**. Teams at the top level did real work. Saying so publicly does more for adoption than another rule.

## Building Scorecards in the UI or as code

You can build and edit Scorecards directly in the Cortex UI, which makes it easy to start, iterate, and involve teammates who don't need deep context. If you'd rather manage standards in version control, [Scorecards as code](/standardize/scorecards/scorecards-as-code) supports a GitOps approach, and you can also manage Scorecards through the Cortex API.

> [!NOTE]
>
> The two aren't exclusive. Plenty of teams draft in the UI and move to code once a Scorecard stabilizes.

## Next steps

* [Create a Scorecard](/standardize/scorecards/create) - Step-by-step instructions for building, editing, and publishing a Scorecard.
* [Review and evaluate Scorecards](/standardize/scorecards/evaluate) - How to read results, understand failures, and remediate them.
* [Scorecard examples](/standardize/scorecards/scorecard-examples) - Common use cases and how other organizations motivate their teams.
* [Scorecards as code](/standardize/scorecards/scorecards-as-code) - Manage Scorecards through GitOps.
* [Scorecard settings](/configure/settings/scorecard) - Workspace-level Scorecard settings and rule exemptions, configurable by admins under Settings > Scorecards.


# Create a Scorecard
Source: https://docs.cortex.io/standardize/scorecards/create



Use Scorecards to establish best practices, track migration, promote accountability among teams, enforce standardization across entities, or define maturity standards.

This page explains how to create a Scorecard from the Cortex UI. For instructions on creating Scorecards via GitOps, see [Scorecards as code](/standardize/scorecards/scorecards-as-code). You can also work with Scorecards via the [Cortex API](/api/rest/scorecards).

Learn about reviewing, evaluating, and taking action on failed rules in [Review and evaluate Scorecards](/standardize/scorecards/evaluate).

### Common Scorecard use cases

For information about common use cases and examples, see [Scorecard examples](/standardize/scorecards/scorecard-examples).

> [!TIP]
>
> Looking to dive deeper? Check out the [Cortex Academy course on Scorecards](https://academy.cortex.io/courses/understanding-scorecards), available to all Cortex customers and POVs.

## How to create Scorecards

### Prerequisites

* To create a Scorecard, you must have the admin or manager role, or you must have a custom role that includes the permission `Edit Scorecards`.
* Scorecards evaluate entities, so before using Scorecards, make sure you have [entities in your catalogs](/ingesting-data-into-cortex/entities-overview/entities).
* Make sure you have set up any [integrations](/ingesting-data-into-cortex/integrations) you want to write rules against.

### Step 1: Configure the basic Scorecard fields

When you create a new Scorecard, you can choose from the following options:

* **Use a Scorecard template**
* **Start from scratch**

#### Option 1: Use a template

Cortex offers the following templates:

> **Scorecard templates**
>
> * Empty Scorecard with Gold/Silver/Bronze levels pre-configured
> * Onboarding Scorecard
> * DRIVE Framework
> * DORA Operational Readiness
> * Production Readiness
> * Service Maturity
> * AI Readiness
> * AI Maturity
> * AI Governance
> * Code Quality
> * Security Scorecard
> * Vulnerability Management
> * Incident Preparedness
> * Incident Response Performance
> * SOC 2 Compliance
> * Secrets Management
> * Ownership Verification
> * Entity Verification
> * Eng Intelligence metrics
> * Velocity Scorecard
> * JavaScript Best Practices
> * Kubernetes Deployment Baseline
> * Minimum Postgres version for Aurora
> * Minimum version for ElastiCache for Redis
> * Minimum Lambda runtime versions
> * Deprecations

Expand the tile below to learn how to create a Scorecard from a template.

> **Create Scorecard from template**
>
> To create a Scorecard using a template:
>
> 1. On the Scorecards page in Cortex, click **Create Scorecard**.
> 2. Click **Scorecard template**.
> 3. Click the template you want to use, then at the bottom of the page, click **Continue**.
>    * You will be redirected to a page that shows the default configuration for your Scorecard, including the integrations used by the Scorecard and the template's levels and rules. You will be able to modify the Scorecard on the next page.
> 4. Click **Continue** at the bottom of the Scorecard default configuration page.
> 5. Configure the basic fields for your Scorecard:
>    * **Name**: Enter a descriptive name for your Scorecard.
>    * **Identifier**: Enter a unique identifier for your Scorecard.
>    * **Description**: Enter a description for your Scorecard.
>    * **Evaluation window**: By default, Scorecards are evaluated every 4 hours. If you would like to evaluate Scorecards less frequently, you can override the evaluation window and enter a new number.
>      * If a Scorecard is evaluating such a large number of entities that it cannot complete the evaluation in a 4-hour window without invoking rate limits, then a longer evaluation window is recommended.
>      * You will also be able to [manually trigger an evaluation](/standardize/scorecards/evaluate#manually-triggering-an-evaluation) when needed.
>    * **Enable notifications**: Choose whether to enable notifications.
>      * If notifications are enabled, users who own entities being evaluated by this Scorecard will receive alerts when there are relevant updates on the Scorecard and any corresponding initiatives.
>      * **Notify when scores drop**: When enabled, you will be notified any time a score drops from the last time the Scorecard was evaluated.
>    * **Enable exemptions**: Choose whether to enable Scorecard exemptions. If not set, it defaults to true.
>      * See [Scorecard rule exemptions](/standardize/scorecards/rule-exemptions) for more information.
>    * **Enable auto-approval exemptions**: Choose whether to enable auto-approving of Scorecard rule exemptions. If not set, it defaults to false.
>    * **Enable user-specific notifications:** Add a field to allow your users to notify a specific user to approve a rule exemption request rather than all Admins.
>      * If this field is enabled, Scorecard notifications will also be enabled automatically.
> 6. Select whether to apply this Scorecard to specific entities.
>    * You can choose to include or exclude specific entity types.
>    * Click **Advanced options** to see additional options for refining entity selection. You can include or exclude groups, and you can include a CQL expression to make your entity type selection.
>      * When including a CQL expression, you will have the option to [test the query](/standardize/cql/run#step-2-test-the-query) against specified entities to verify that it works as expected.
>
> If you want to use all of the default rules from the template, you can skip ahead to [Step 4: Save the Scorecard](/standardize/scorecards/create#step-4-save-the-scorecard). If you want to add any rules or levels, follow the next steps.

#### Option 2: Start from scratch

> **Create Scorecard from scratch**
>
> 1. On the Scorecards page in Cortex, click **Start from scratch**, then at the bottom of the page, click **Continue**.
> 2. Configure the basic fields for your Scorecard:
>    * **Name**: Enter a descriptive name for your Scorecard.
>    * **Identifier**: Enter a unique identifier for your Scorecard.
>    * **Description**: Enter a description for your Scorecard.
>    * **Evaluation window**: By default, Scorecards are evaluated every 4 hours. If you would like to evaluate Scorecards less frequently, you can override the evaluation window and enter a new number.
>      * If a Scorecard is evaluating such a large number of entities that it cannot complete the evaluation in a 4-hour window without invoking rate limits, then a longer evaluation window is recommended.
>    * **Enable notifications**: Choose whether to enable notifications.
>      * If notifications are enabled, users who own entities being evaluated by this Scorecard will receive alerts when there are relevant updates on the Scorecard and any corresponding initiatives.
>      * **Notify when scores drop**: When enabled, you will be notified any time a score drops from the last time the Scorecard was evaluated.
>    * **Enable exemptions**: Choose whether allow users to request rule exemptions for evaluated entities. If not set, it defaults to enabled.
>      * See [Scorecard rule exemptions](/standardize/scorecards/rule-exemptions) for more information.
>    * **Enable auto-approval exemptions**: If exemptions are allowed, choose whether to enable auto-approval of Scorecard rule exemptions. If not set, it defaults to disabled.
> 3. Next to "Apply to specific entities," select whether to apply this Scorecard to specific entities:
>    * **Selection type** and **Entity types**: Choose to include or exclude specific entity types. By default, the Scorecard will apply to all entities of the selected type(s).
>    * Click **Advanced options** to see additional options for refining entity selection. You can include or exclude groups. For example, if you're creating a services-based Scorecard, you might choose to include those that belong in a "tier 1 services" group.
>      * You can also include a CQL expression to make your entity type selection.
>
>        ![Configure whether the Scorecard applies to specific entities](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scorecard-cql.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=bdd7f3ff0a4c3dd0d993a6c98f9823d9)
>
> > [!WARNING]
> >
> > Advanced filtering only works with data that exist within Cortex, like entity groups, owners, and other custom data, but does not extend to third-party integrations.
>
> See the next section for steps on choosing a scoring type and writing rules.

### Step 2: Add levels

When you [create a Scorecard](/standardize/scorecards/create#how-to-create-scorecards), there are two options to set up your Scorecard's evaluation:

* **Level progression**
  * Establish progressive levels as you add rules to make it obvious which set of rules are the highest priority. Levels allow you to set up a gamified system to encourage developers to make progress toward goals and improve entities' performance.
    * Set your minimum requirements within the lowest level, and add increasingly higher priority rules to subsequent levels.
    * For an example demonstrating how levels work, see [Guides > Measure DORA progress](/guides/dora/scorecard#understanding-scorecard-levels).
* **Point-based rules**
  * Use points to assign weighted values to each rule you add to a Scorecard.

    * You can use point-based rules to set minimum requirements while also encouraging teams to add more metadata. For example, you could assign 1 point for adding a single runbook to an entity, and another point for adding additional runbooks:

    ![One rule checks for a single runbook, and another rule checks for more than 1 runbook.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/partial-rules.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=a11cbbc53925d45b695a3ad79051493c)

> [!TIP]
>
> If you choose to use only point-based rules in your Scorecard, then you do not need to create levels. You can skip to the next section: [Step 3: Create a rule](/standardize/scorecards/create#step-3-create-a-rule).

#### Add a level

> **To add a level to a Scorecard:**
>
> 1. While creating your Scorecard, in the "Define evaluation rules" section, click **Add level**.
>
>    ![Click Add level under the scoring type selection](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/add-level%20%281%29.jpg)
> 2. In the modal, configure your level:
>    * **Color**: Click the star icon to select a color for this level.
>    * **Name**: Enter a name that represents this level.
>      * You might choose to go with classic levels names, such as Bronze, Silver, and Gold, or you can choose something more unique to your organization.
>      * Levels are designed to inspire progress on important goals, so consider level names that will motivate your team members.
>    * **Description**: Enter a description for the level.
> 3. Click **Add level**.
>
> You can add more levels to the Scorecard, or you can move on to the next step and add rules to each level.

#### **Reorder levels**

> **To reorder levels in a Scorecard:**
>
> You can reorder levels while creating or editing your Scorecard, if the Scorecard has more than one level. Click the arrows on the right side to reorder them:
>
> ![Click the arrow on the right side of a level](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/reorder-levels.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=e20f685df5bc624047f42d86b1d877cb)

### Step 3: Create a rule

There are two methods for building a rule:

* Using the form builder
* Via the CQL editor

The form is the fastest option, as you can choose from pre-configured rules for each integration. The CQL editor is best when writing complex rules or accessing data from multiple sources.

Expand the tiles below for instructions on each option.

> **Use the form builder**
>
> 1. While creating your Scorecard, in the "Define evaluation rules" section, click **Add rule**.
>    * **Level progression scoring type**: Click **Add rule** within a level.
>
>      ![In a level titled "Level 1: Bronze" you can click "Add rule to Level 1 Bronze" in the lower left](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/add-rule-level%20%281%29.jpg)
>
>      * When using the "Level progression" scoring type, we recommend including the most essential rules in the first level so developers know to prioritize them.
>    * **Point-based rule scoring type**: Enable the toggle next to **Point-based rules**, then click **Add rule:**
>
>      ![Click Add rule under the scoring type selection](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/add-point-rule.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=da452688c1d3ac6342d6d21b4234388d)
>
> 2. The rule creation modal defaults to the **Form** type, where you can choose a pre-configured rule based on configured integrations.
>
> 3. Configure the basic fields in the form:
>    * **Integration**: Choose one of your configured integrations to apply this rule to.
>    * **Rule**: Choose a rule.
>    * The next fields vary depending on the type of rule you choose. For example, you may need to choose a boolean operation or set a file path.
>    * **Rule name**: Enter a descriptive name. Names make it easier to understand the outcome of the rule without having to read the CQL expression.
>
>      ![Configure the form to create a rule](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/form-rule%20%281%29.jpg)
>
> 4. Optionally configure the additional fields:
>    * **Description**: Enter a description for the rule.
>    * **Failure message**: Add links or instructions to tell users how they can remediate this rule if it's failing. You can reference `{{context.entity.id}}` to build a direct link to the failing entity's page in Cortex.
>    * **Restrict rule to specific groups**: Select groups to include or exclude.
>      * This option can be used when a group of entities should be evaluated by the Scorecard as a whole, but a specific rule in the Scorecard does not apply to that group.
>      * See [Scorecard rule filters](/standardize/scorecards/scorecard-filters) for more information on configuring a filter.
>    * **Points**: Enter how many points this rule is worth.
>      * You can use points to signify each rule's importance. Rules worth more points are more critical than those with fewer points.
>    * **Schedule evaluation start date**: If you want to schedule the evaluation of a rule to start on a specific date, schedule a start date here. When the field is blank, the rule will take effect immediately. If a start date is provided, the rule will take effect at the start of the specified day (UTC).
>      * This is helpful when you want users to be aware of an upcoming rule, but you do not want to evaluate the Scorecard yet based on that rule.
>      * Scheduled rules are visible to all users and will be included in the weekly team and user reports to help with socialization.
>      * Users can choose to [receive notifications](/configure/settings/notifications) when a scheduled rule is added to a Scorecard evaluating an entity they own, and they can receive reminders before a scheduled rule impacting an owned entity goes into effect.
>
> 5. Click **Save rule**.

> **Use the CQL editor**
>
> 1. While creating your Scorecard, in the "Define evaluation rules" section, click **Add rule**.
>    * **Level progression scoring type**: Click **Add rule** within a level.
>
>      ![In a level titled "Level 1: Bronze" you can click "Add rule to Level 1 Bronze" in the lower left](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/add-rule-level%20%281%29.jpg)
>
>      * When using the "Level progression" scoring type, we recommend including the most essential rules in the first level so developers know to prioritize them.
>    * **Point-based rule scoring type**: Enable the toggle next to **Point-based rules**, then click **Add rule:**
>
>      ![Click Add rule under the scoring type selection](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/add-point-rule.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=da452688c1d3ac6342d6d21b4234388d)
> 2. The rule creation modal defaults to the **Form** type, where you can choose a pre-configured rule based on configured integrations. To write a CQL expression instead, click **CQL:**
>
>    ![Choose Forms for the UI editor or CQL editor to write CQL rules](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/cql-rule.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=19f45dd6c6ea044124bb9db388140bcb)
> 3. Configure the basic fields in the form:
>    * **CQL expression**: Enter your CQL rule. On the right side of the modal, you can use CQL Explorer for help.
>      * Note: If writing an expression that references a Jira issues, Cortex will not append new filter logic to your default JQL query. See [Adding filter logic to the default JQL query in a Scorecard](/ingesting-data-into-cortex/integrations/jira#adding-filter-logic-to-the-default-jql-query-in-a-scorecard) for more information.
>    * **Rule name**: Enter a descriptive name. Names make it easier to understand the rule without having to read the CQL expression.
> 4. Optionally configure the additional fields:
>    * **Description**: Enter a description for the rule.
>    * **Failure message**: Add links or instructions to tell users how they can remediate this rule if it's failing. You can reference `{{context.entity.id}}` to build a direct link to the failing entity's page in Cortex.
>    * **Restrict rule to specific groups**: Select groups to include or exclude.
>      * This option can be used when a group of entities should be evaluated by the Scorecard as a whole, but a specific rule in the Scorecard does not apply to that group.
>      * See [Scorecard rule filters](/standardize/scorecards/scorecard-filters) for more information on configuring a filter.
>    * **Points**: Enter how many points this rule is worth.
>      * You can use points to signify each rule's importance. Rules worth more points are more critical than those with fewer points.
>    * **Schedule evaluation start date**: If you want to schedule the evaluation of a rule to start on a specific date, schedule a start date here. When the field is blank, the rule will take effect immediately. If a start date is provided, the rule will take effect at the start of the specified day (UTC).
>      * This is helpful when you want users to be aware of an upcoming rule, but you do not want to evaluate the Scorecard yet based on that rule.
>      * Scheduled rules are visible to all users and will be included in the weekly team and user reports to help with socialization.
>      * Users can choose to [receive notifications](/configure/settings/notifications) when a scheduled rule is added to a Scorecard evaluating an entity they own, and they can receive reminders before a scheduled rule impacting an owned entity goes into effect.
> 5. Click **Save rule**.

You can repeat the steps above to continue adding rules to your Scorecard. You cannot duplicate a rule across levels, since developers will have already completed that task earlier. It is common, however, to have similar rules with different thresholds if you want developers to progress in stages. For example, a base level might require that the P50 latency for API requests is under 5 seconds, while a higher level may required that the same P50 is under 2 seconds.

### Step 4: Save the Scorecard

After you have finished adding levels and rules to your Scorecard, you are ready to save it as a draft or publish it.

1. Choose whether to keep your Scorecard in draft form, visible only to users with permission to configure Scorecards. To keep it in draft form, enable the toggle next to **Save as draft**.
   * If you choose to keep your Scorecard in draft status, it will not appear in reports or send notifications.
   * If you choose to publish your Scorecard, it will be visible to all users who have the `View Scorecards` permission. Notifications, if enabled, will be triggered.
2. Click **Create Scorecard**.

After you save the Scorecard, it will automatically evaluate all the entities that apply based on the rules you have configured, and you will be redirected to the Scorecard's page in Cortex.

### **Edit a Scorecard**

If you have not [disabled UI editing](/configure/gitops/using-gitops-for-cortex#step-1-disable-ui-editing), then you can edit a Scorecard in the Cortex UI. You can edit the name, description, levels, rules, draft status, filter criteria, and the entity's being evaluated by the Scorecard. You cannot edit a Scorecard's unique identifier.

You must have the `Edit Scorecard` permission.

To edit:

1. Navigate to the Scorecard in Cortex.
2. Click **Edit** in the upper right corner of the Scorecard page:

   ![Click 'Edit' in the upper right corner.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/edit-scorecard%20%281%29.jpg)
3. Make changes to your Scorecard, then at the bottom of the page, click **Save Scorecard**.

Any time you edit and save your Scorecard, Cortex will automatically begin reevaluating the relevant entities to reflect your changes.

### **View Scorecards list**

Click [**Scorecards**](https://app.getcortexapp.com/admin/scorecards) in the main nav in Cortex.

All of your organization’s Scorecards are listed under **All**.

![At the top of the Scorecard list, there are tabs for All and Mine](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/my-scorecards.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=912fe4fbf191b3a1033d81876d59d877)

> [!NOTE]
>
> Select the **All** tab to view all published Scorecards. Select the **Mine** tab to view only Scorecards you've created and/or Scorecards that evaluate entities you own. Cortex saves your selection and restores it the next time you open this page.
>
> ![The 'All' and 'Mine' tabs located on the main Scorecards page.](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/all-mine-scorecards.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=b58460cb41e2c3d155383e127b77d7e1)

## Next steps

After you have established Scorecards, there are different steps you can take to continuously improve:

* **Evaluate progress and take action**: Review the Scorecard via reports or by using Cortex MCP, identify trends, and figure out how to take action on the issues you've identified. Learn more in [Review and evaluate Scorecards](/standardize/scorecards/evaluate).
* **Target goals with Initiatives**: If you have failing rules, or if you have rules that are a higher priority, you can start using [Initiatives](/improve/initiatives) to drive progress across the organization. Initiatives allow you to prioritize specific rules within a Scorecard and set deadlines for team members to accomplish tasks. Learn more below.

### Create Initiative from Scorecard

[Initiatives](/improve/initiatives) allow you to prioritize specific rules and set deadlines, making sure your team members complete higher priority tasks on time. In a level-based Scorecard, you can set an Initiative that asks your team to complete all rules within a level by a certain date.

You can create an Initiative while viewing a Scorecard. Note that the Scorecard must be published - i.e., not in draft mode - in order to create an Initiative for it.

1. In the upper right corner, click **+Create initiative**.

   ![Click 'Create Initiative' in the upper right.](https://mintcdn.com/cortex-290c0c42/WknxdPOUKwxfFHMJ/images/create-initiative-scorecard.jpg?fit=max\&auto=format\&n=WknxdPOUKwxfFHMJ\&q=85\&s=0d174b221345f7fb6c8c4d3b41e4921c)
2. Configure the Initiative form.
   * For detailed instructions and examples, see the [Initiatives documentation](/improve/initiatives).

You can also create an Initiative while viewing reports for the Scorecard under its [**Reports** tab](/standardize/scorecards/evaluate#reports).


# Reviewing and evaluating Scorecards
Source: https://docs.cortex.io/standardize/scorecards/evaluate



Scorecard evaluations show how your entities measure up against the standards you've defined. Reviewing the results helps you spot patterns across teams and entities, and decide where to focus improvement work.

When an entity fails a rule, Cortex shows you why, so teams can find and fix the problem quickly. As teams resolve failures, entities become healthier and more mature, and your engineering organization becomes more reliable and compliant overall.

This page covers:

* [How Scorecards are evaluated](/standardize/scorecards/evaluate#how-scorecards-are-evaluated), and how to start or cancel an evaluation.
* [Reviewing a Scorecard in the Cortex UI](/standardize/scorecards/evaluate#reviewing-a-scorecard-in-the-cortex-ui), including what each tab shows.
* [Reviewing a Scorecard with Cortex MCP](/standardize/scorecards/evaluate#reviewing-a-scorecard-with-cortex-mcp).
* [Taking action on failing rules](/standardize/scorecards/evaluate#taking-action-on-a-scorecard), for individual entities and across your organization.

## How Scorecards are evaluated

After you save a Scorecard, Cortex automatically evaluates every entity the Scorecard applies to. Cortex then re-evaluates the Scorecard on a schedule set by its evaluation window, which defaults to every 4 hours. To change the evaluation window, see [Create a Scorecard](/standardize/scorecards/create#step-1-configure-the-basic-scorecard-fields).

Cortex also starts a new evaluation whenever a change to the Scorecard definition is processed, whether the change comes through GitOps, the Cortex UI, or the API.

Cortex doesn't evaluate every entity at once. It spreads entity evaluations across the evaluation window, and each evaluation finishes before the next one is scheduled to start. Scorecards that use CQL filters can take longer, because Cortex evaluates each filter separately. To see which rules and filters add the most work, check the Scorecard's [Evaluation cost](/standardize/scorecards/evaluate#evaluation-cost) tab.

To see past evaluations and any entities that failed to evaluate, check the Scorecard's [Recent runs](/standardize/scorecards/evaluate#recent-runs) tab.

### Manually triggering an evaluation

Users with the `Run re-evaluation of Scorecards` permission can trigger an evaluation.

To evaluate a Scorecard outside its schedule, for example after you fix a failing rule:

1. From the main sidebar, expand **Scorecards**, then select **Scorecards**.
2. Select the Scorecard you want to evaluate. The Scorecard page opens.
3. In the right side panel, click **Evaluate now**.

   ![The Evaluate now button in the side panel of a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-evaluate-now-button.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=ed18b336d6bab357a951716dd2be4929)

**Evaluate now** isn't available while an evaluation is already in progress.

To re-evaluate a single entity instead of the whole Scorecard, use the [Scorecards API](/api/rest/scorecards#post-api-v1-scorecards-tag-entity-entitytag-scores).

### Canceling an evaluation

While a Scorecard is being evaluated, a progress bar appears at the top of its page. To stop the evaluation, click **Cancel** next to the progress bar.

![The Cancel button at the top of a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-cancel-eval.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=5c4698db20d97b916446496bfac7d73c)

The canceled run appears on the **Recent runs** tab with the **Cancelled** status.

## Reviewing a Scorecard in the Cortex UI

To open a Scorecard, select **Scorecards** in the main sidebar, then select the Scorecard you want to review.

![A Scorecard page in Cortex.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-page.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=a87bd18ccc043f9377849ffa02ba44c4)

The top of the page summarizes the Scorecard's results:

* **Levels** - How many entities are at each level, including entities that haven't reached a level yet.
* **% at highest level** - The percentage of entities that have reached the Scorecard's highest level.
* **% without level** - The percentage of entities that haven't reached any level.

The side panel on the right shows the Scorecard's details, including its description, the total number of entities it evaluates, which entities it applies to, scheduled rules, and evaluation status. If you can edit the Scorecard, the side panel also shows its overall [evaluation cost](/standardize/scorecards/evaluate#evaluation-cost).

### Sharing a Scorecard

To share a Scorecard (for example, to show progress to leadership), click **Share** in the upper-right corner. Cortex copies a link to your clipboard, which you can send to anyone who has access to view the Scorecard in your workspace.

![The Share button in the upper right corner of a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-share-button.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=a0f5824bacdd85f116bf5154a339cd31)

### Scorecard tabs

Each tab on a Scorecard page shows a different view of the Scorecard and its results.

![The tabs on a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-tabs.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=6da53e056401ba71eeb67731e6a01880)

> [!NOTE]
>
> The **Exemptions** and **Initiatives** tabs only appear when the Scorecard has at least one exemption or Initiative.

#### Scores

The **Scores** tab lists each entity the Scorecard evaluates, the entity's current level, and its progress in each level. Point-based Scorecards show progress as points, and level-based Scorecards show it as the number of passing rules.

![The Scores tab shows scores and levels per entity.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-scores-tab.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=3a2924a621ded0f0d39efbb3d831b311)

For example, in the screenshot above, the first two entities earned 50 out of 50 possible points in the Bronze level, and 3 out of 3 possible points in the Silver level.

**Filter and sort the list**

* Click **Filter** in the upper-right corner of the list to narrow it by domain, failing rules, groups, levels, owners, passing rules, or teams.
* Click **Level** to choose what to sort by, and whether to sort ascending or descending.

**View an entity's details**

![The side panel for an entity on the Scores tab.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-entity-details.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=78db3df517ae8872d1717a2f6f016c51)

Click an entity to open a side panel with more information:

* **Entity name** - Links to the entity's details page.
* **Summary** - At the top of the panel, the entity's current level, score, rank, percentile, and rule progress.
* **Rules** - The entity's passing and failing rules. Exemption requests awaiting review appear under **Pending exemptions**.
* **Exemptions** - Rules the entity is exempt from.
* **Progress** - A graph of the entity's progress over time.

Review the **Rules** tab closely to find failing rules you can [take action on](/standardize/scorecards/evaluate#taking-action-on-a-scorecard).

#### Overview

The **Overview** tab highlights trends across the Scorecard, including the highest-ranking entity, the most at-risk entity and rule, the most improved entity, the entity with the biggest drop, and the most-moved rule.

Below these highlights, a graph shows the progress of all rules. Click **All rules** above the graph to filter it by specific rules.

![The Overview tab on a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-overview-tab.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=d938178b702e78d068794e912dbdadf1)

By default, the **Trends and changes** section shows data from the last month. Click **Last month** to choose a different timeframe.

#### Rules

The **Rules** tab lists the Scorecard's rules by level. Expand a rule to see its CQL expression. If a rule doesn't have a name, it appears as its CQL expression.

![An expanded rule showing its CQL expression.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-rules-tab.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=33a0a9b8f49da2765cfef201d1798406)

#### Reports

The **Reports** tab links to the Scorecard's [Bird's Eye report](/improve/reports/birds-eye), [Progress report](/improve/reports/progress-report), and [Report card](/improve/reports/report-card).

![The Reports tab on a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-reports-tab.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=61924de0efc1e8c72c386aa6a1a9800f)

#### Exemptions

The **Exemptions** tab lists rule exemptions for the Scorecard, in two views:

* **Approved** - Exemptions that are currently in force, plus requests awaiting review.

  ![The Approved view of the Exemptions tab.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-exemptions-tab1.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=d2b993bc588a520c2c6c3ccacad04d18)
* **All** - The Scorecard's full exemption history, including exemptions that were rejected, revoked, or expired.

  ![The All view of the Exemptions tab.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-exemptions-tab2.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=db6d9b045b73713416d4fb118a38ae01)

Each exemption shows its current status, the entity and rule, who requested it, the reason for the request, who resolved it, and an expiration date. Click **Filter** to narrow either view by status, entity, rule, requester, or approver. For what each status means, see [Scorecard rule exemptions](/standardize/scorecards/rule-exemptions).

To review requests, you must have the `Configure Scorecard Exemptions` permission. In the **Approved** view:

* Click **Accept** to approve a pending request, or **Reject** to deny it.
* Click **Revoke exemption** to end an exemption that's already approved. A revoked exemption isn't deleted. It moves to the **All** view with the `REVOKED` status and keeps its original approval details.

#### Initiatives

The **Initiatives** tab lists the [Initiatives](/improve/initiatives) associated with the Scorecard.

![The Initiatives tab on a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-initiatives-tab.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=b4eacd6f3dcd7d4f8b1f79e5d6ed9c8b)

#### Recent runs

The **Recent runs** tab shows the Scorecard's evaluation history.

![The Recent runs tab on a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-recent-runs-tab.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=63b5ea3f18623ce286f748864c78d1f8)

Each run includes:

* **Evaluation start time** - The date, time, and timezone the evaluation started.
* **Status** - Whether the run is **Queued**, **In progress**, **Done**, **Failed**, **Timed out**, or **Cancelled**.
* **Entities** - The number of entities the run evaluated.

**Review evaluation failures**

If any entities failed to evaluate, click **Failures in last evaluation** in the upper right corner of the list. Failures are grouped by error message, with the number of entities each error affects. The list reflects the Scorecard's current state, not a specific run.

Use the error messages to find the cause, such as a missing integration or an integration that doesn't have permission to read the data a rule needs. For more help, see [Scorecard troubleshooting and FAQ](/standardize/scorecards/scorecard-troubleshooting-and-faq).

#### Evaluation cost

The **Evaluation cost** tab shows how much work each rule and filter adds when the Scorecard is evaluated. Rules that pull data in real time from third-party integrations generally cost more than rules that use data already stored in Cortex.

![The Evaluation cost tab on a Scorecard page.](https://mintcdn.com/cortex-290c0c42/HSX5yniw1QZ_-Y-H/images/scorecards-evaluation-cost-tab.png?fit=max\&auto=format\&n=HSX5yniw1QZ_-Y-H\&q=85\&s=d6354dddfcd5c877cdc4d24b49b51674)

Each row includes:

* **Rule / filter** - The rule or filter name and its CQL expression. If a rule doesn't have a name, it appears as its CQL expression.
* **Cost** - The cost level: **Low**, **Medium**, **High**, or **Very high**. If Cortex can't classify a rule, its cost is **Unknown**.
* **Integrations** - The integrations the rule reads data from. **Internal** means the rule only uses data stored in Cortex.

Rows are sorted from most to least expensive. The Scorecard's overall cost matches its most expensive rule, and appears under **Evaluation cost** in the side panel. Hover over the info icon next to it to see how cost is determined. If the overall cost is **Unknown**, it doesn't appear in the side panel.

To reduce evaluation time, review the most expensive rules first. Where possible, rewrite them to use data that's already in Cortex.

The **Evaluation cost** tab only appears for users with permission to edit Scorecards, and only when evaluation cost is enabled for your workspace.

## Reviewing a Scorecard with Cortex MCP

Use [Cortex MCP](/get-started/cortex-ai-assistant/mcp) to get quick insights into a Scorecard's performance. Ask questions in natural language, such as *What is going on with my DORA Metrics Scorecard?* or *What steps can I take to improve my Eng Intelligence Scorecard scores?*

> **Example: Assess a Scorecard with Cortex MCP**
>
> First, ask a question about a Scorecard. The MCP client shows which Cortex APIs it's using to find an answer:
>
> ![An MCP client calling Cortex APIs to answer a question about a Scorecard.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/claude-example-scorecard.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=288c4e92db4f5f6f3fd95203f1012505)
>
> Next, it gives you context to help you improve your scores:
>
> ![An MCP response listing priorities for improving a Scorecard.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/claude-scorecard-priorities.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=e92547965fe59f8d6d856a5800327ae4)
>
> In this example, after listing priorities, the response also suggests quick wins and a systematic approach:
>
> ![An MCP response suggesting quick wins and a systematic approach.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/claude-scorecard-wins.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=4cdac5ac793da5d8956660ebc2229c3c)

From there, [take action](/standardize/scorecards/evaluate#taking-action-on-a-scorecard) to fix the issues and start meeting your standards.

## Taking action on a Scorecard

Failing rules give teams concrete goals for incremental improvement. Teams can address the highest-impact failures first, track progress over time, and celebrate measurable wins, which reinforces a culture of improvement.

### Fixing failing rules

**1. Identify the failing rules**

On the Scorecard's [Scores](/standardize/scorecards/evaluate#scores) tab, view the failing rules for each entity. Group by level to see which entities have reached each level.

In this example, the entities have reached the Bronze level, but they're failing rules for Silver and Gold:

![Entities failing rules in the Silver and Gold levels.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/failed-rules.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=cee5e25b85da645339323c22b8bd4e26)

**2. Understand the cause**

Click an entity to open a side panel that shows why its rules are failing. If the rule has a failure message, it explains how to fix the rule. To add failure messages to your own rules, see [Create a Scorecard](/standardize/scorecards/create#step-3-create-a-rule).

![A failing rule with its failure message.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/failing-rule.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=e6087cc7bdf0f5c1e6d2d184d881b767)

If the failure message links to a [Workflow](/streamline/workflows) that fixes the rule, Cortex automatically passes the entity to the Workflow's entity selector (if it has one), so the entity is selected by default. To set this up manually, append the entity tag or ID to the Workflow URL, for example `?entity={{context.entity.tag}}`.

![When linking to a Workflow from a failed Scorecard rule, Cortex automatically selects the entity to use when running the Workflow.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202025-12-08%20at%201.44.28%E2%80%AFPM.png)

If a rule doesn't apply to an entity, [request an exemption](/standardize/scorecards/rule-exemptions).

**3. Track and prioritize issues**

Use the [Engineering homepage](/streamline/homepage) to see a prioritized to-do list of failing rules across the entities and Scorecards you own, so you can focus on the most impactful issues first.

![A prioritized list of failing rules on the Engineering homepage.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/homepage-actions-to-list.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=55fb37773b84ed2b9ee2703e68ebaa5a)

To set deadlines for higher-priority work, [create an Initiative](/improve/initiatives). Cortex notifies owners and team members as deadlines approach.

**4. Fix the issues**

Address the underlying issue for each failing rule. This could mean adding missing documentation, configuring an integration, or any other change the rule requires.

For example, if a rule fails because PagerDuty isn't configured for the entity, follow the [PagerDuty instructions](/ingesting-data-into-cortex/integrations/pagerduty#editing-the-entity-descriptor) to add a PagerDuty service, schedule, or escalation policy to the entity's descriptor YAML.

![PagerDuty configuration in an entity descriptor YAML file.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/pagerduty-yaml.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=1cb7412c8fcdee6b325fc10966034809)

**5. Re-evaluate the Scorecard**

The Scorecard re-evaluates on its schedule, or you can [trigger an evaluation manually](/standardize/scorecards/evaluate#manually-triggering-an-evaluation). After the evaluation finishes, review your progress and any rules that are still failing.

![A Scorecard showing improved scores after remediation.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scorecard-improved.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=26f60b379eecced80bd45a2891af9138)

### Improve standards across your organization

As you review evaluations, you might notice trends, such as teams that struggle in specific areas or entities that often miss standards. Beyond fixing individual rules, look for ways to improve the processes behind them.

#### Automate with Workflows

Look for challenges that come up across teams. For example, is a team consistently failing to add runbooks to new services? Are there failing rules related to onboarding? When a standard is often missed, it's an opportunity to automate that process with a [Workflow](/streamline/workflows).

Workflows streamline repeatable steps, reduce human error, and help your teams work faster.

![A Workflow that scaffolds a new service.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scaffold-example.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=fe007ff3197ee9072d2b326e7edcdb75)

For example, you could create a Workflow to [standardize how new services are created](/guides/production-readiness/standardize-new-service-creation), with a User Input step that asks users to confirm a runbook has been documented.

#### Analyze trends

When a group of entities is failing rules, look for organizational ways to support your teams or adjust processes.

**Team patterns**

* Are most failing entities owned by a newer team?
  * Make sure new team members aren't overwhelmed and have completed any necessary training.
  * Make sure the team understands its scope and priorities.
  * Use [Eng Intelligence](/improve/eng-intelligence) dashboards and metrics to find which parts of the software development lifecycle each team could improve.
* Does one team own more entities than others?
  * Make sure work is spread fairly across teams.
  * If one team owns more because of tribal knowledge, encourage team members to document what they know. This can also point to areas where training would help.
  * Once knowledge is documented, [link it on related entities](/ingesting-data-into-cortex/entities-overview/entities/external-docs).
* Are some teams or services successful across several areas?
  * Recognize these achievements publicly. Public recognition reinforces good practices and motivates your teams.

**Service lifecycle patterns**

* Do older, legacy services have low scores while newer ones meet standards?
  * This points to modernization opportunities.
  * To learn how to use Cortex for modernization, take the [Migrations and Modernizations course](https://academy.cortex.io/courses/migrations-and-modernizations) in Cortex Academy, available to all customers.

**Adoption over time**

* Are scores trending upward over the quarter, in line with company initiatives?
  * Scorecard trends over time show whether internal efforts, like a push for better test coverage, are working.
  * To promote specific standards, [create an Initiative from a Scorecard](/standardize/scorecards/create#create-initiative-from-scorecard) to encourage teams to fix failing rules by a deadline.


# Scorecard rule exemptions
Source: https://docs.cortex.io/standardize/scorecards/rule-exemptions



In some instances, a Scorecard rule might not apply to an entity. For example, a rule may be linked to an [Initiative](/improve/initiatives) your team is actively working on and the failure notification may be irrelevant or noisy to developers. Or, in rarer cases, the Scorecard rule may not make sense for a given component, depending on the nature of that entity. In either case, rule exemptions allow you to filter out components that shouldn’t be evaluated by a specific rule.

With rule exemptions, entities are not marked as passing or failing—the rule simply does not apply to those entities. If you use point-based rules instead of levels, the exempted rule will not be included in the average for a component’s percentage score. If you use levels, an exempt rule allows an entity to progress to the next level.

Any user can request a rule exemption, and admins or users with the `Configure Scorecard Exemptions` permission can approve, deny or revoke a rule exemption. Users with the `View Scorecard Exemptions` permission can view exemptions in Scorecards that have been requested by any user; without that permission, a user can only see their own requested exemptions.

# **Requesting a rule exemption**

Any user can request an exemption. This can be done [via the API](/api/rest/scorecards), or via the Cortex UI.

**To request a rule exemption via the Cortex UI**:

1. From the main sidebar, expand **Scorecards**, then select **Scorecards**.

2. Do one of the following:
   * Select the **All** tab to view all of your organization's published Scorecards.
   * Select the **Mine** tab to view only Scorecards you own.

3. Select the Scorecard you want to view.

4. While viewing the Scorecard, select the entity on which you want to request a rule exemption. \
   The **Scorecard details** side panel opens.

5. Locate the rule you want to request an exemption for, click the overflow menu icon next to it, then select **Request exemption**.

   ![Scorecards Request Exemption](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-request-exemption.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=1c25c50688896106ec44c858fe659659)

6. In the **Request rule exemption** side panel, do one of the following:
   1. To request a permanent exemption, toggle on **Permanent exemption**.
   2. To request a temporary exemption, enter the number of days you want to exempt the entity from this rule.
   > [!NOTE]
   >
   > It's highly recommended to include a reason when you submit an exemption request. Requests are reviewed by admins, and a clear explanation helps them determine whether an exemption makes sense.

7. Click **Submit request**.
   * If the Scorecard has user-specific notifications enabled, you'll need to select a user to notify of the rule exemption request. That user will be able to review, and approve or reject the request. If this field is not enabled, then all Admins will be notified of the request.
   * Exemptions are automatically approved only if the Scorecard has the **Enable auto-approval for exemptions** option enabled.

## Permanent or time-bound exemptions

Use a **permanent exemption** when there's no expectation that an entity will ever pass a rule. Use a **time-bound exemption** when an entity is expected to pass by a certain date.

Time-bound exemptions often relate to an ongoing Initiative. For example, if entities need an on-call rotation set up by the end of the quarter, a developer can request an exemption that ends a few weeks earlier. The failing rule won't add noise to their workflow in the meantime, and the expiration acts as a backup reminder if on-call still isn't set up.

When a time-bound exemption expires, the rule is evaluated again as usual: entities that pass display as passing, and the rest display as failing.

# **Approving, denying, or revoking a rule exemption**

To approve, deny, or revoke a Scorecard rule exemption, you need to be an admin or have a custom role that includes the `Configure Scorecard Exemptions` permission. You can do this in the Cortex UI or through the [API](/api/rest/scorecards). Admins can also view every rule exemption in **Settings**, not just on individual Scorecards.

## Auto-approval

> [!NOTE]
>
> If you're an admin in your workspace, Cortex approves your exemption requests automatically.

If your [Scorecard is configured](/standardize/scorecards) to enable auto-approval for exemptions, then you do not need to take any action to approve the exemption.

After the user submits an exemption request, the exemption appears in the Scorecard's **Exemptions** tab as `APPROVED`, with the option to revoke the exemption appearing on the right side of the rule:

![Scorecards Exemption Ask](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-exemption-ask.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=c8a15fa000fc666ab20f751cd8046180)

## Manual approval

If you have [notifications enabled](/configure/settings/notifications) for rule exemption requests, you'll get a notification each time a user requests an exemption. The notification includes:

* The requester's name
* The rule name and its Scorecard
* The entity the exemption applies to
* The reason and timeframe the requester provided
* A direct link to approve or deny the request in Cortex

If you don't have notifications enabled, you can review requests in Cortex on the Scorecard's **Exemptions** tab, or by going to **Settings** > **Scorecards** > **Rule exemptions**. Accept or reject requests from either location:

![Scorecards Manual Approval](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-manual-approval.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=f1379c4eb0d9563033b296dc617d2a5e)

# Exemption statuses

A rule exemption is always in one of five statuses. The status appears in the Cortex UI, and in the `exemptionStatus` field returned by the [Scorecard exemption endpoints](/api/rest/scorecards) and by [Retrieve Scorecard scores](/api/rest/scorecards/retrieve-scorecard-scores):

| Status | Meaning |
| - | - |
| `PENDING` | The exemption has been requested and is awaiting review. |
| `APPROVED` | The exemption is in force: the rule does not count against the entity's score. |
| `REJECTED` | The request was denied. The rule counts against the entity's score. |
| `REVOKED` | A previously approved exemption was revoked. The record is retained for auditing, including who originally approved it and when, plus who revoked it, when, and why. The rule counts against the entity's score again. |
| `EXPIRED` | The exemption was approved with an expiration date that has passed. The rule counts against the entity's score again. |

Revoking an exemption no longer deletes it or marks it as rejected; the exemption is kept with the `REVOKED` status and its full approval history. Expired exemptions are reported as `EXPIRED` rather than continuing to display as approved.

Filter by status in the Scorecard's **Exemptions** tab, in an entity's **Exemption history** tab, and in **Settings > Scorecards > Rule exemptions**.

# Viewing exempted rules

Admins and users with the `Configure Scorecard Exemptions` permission can view exemption requests, approve or deny the request, and revoke exemptions.

## Viewing exemptions in a Scorecard

1. From the main sidebar, expand **Scorecards**, then select **Scorecards**.
2. Do one of the following:
   * Select the **All** tab to view all of your organization's published Scorecards.
   * Select the **Mine** tab to view only Scorecards you own.
3. Select the Scorecard you want to view.
4. Select the **Exemptions** tab. The **Exemptions** tab has two sub-tabs: **Approved** and **All.**

   ![Scorecards All Approved](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-all-approved.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=a60440652ea00da11040a917fbfd56bd)
   * **Approved** - Exemptions that are currently in force, plus requests awaiting review. Accept or reject a pending request here, or revoke an exemption that's already approved.
   * **All (Exemption history)** - The Scorecard's full exemption history, including exemptions that were rejected, revoked, or expired.
     * The **All** view lists each exemption with the date it was requested, the entity and rule it applies to, who requested it, the reason they gave, its current status, who resolved it, and when it expires. Click a column header to sort, or click **Filter** to narrow the list by status, entity, rule, requester, or approver.

> [!NOTE]
>
> Revoking an exemption doesn't delete it. The exemption is kept with the `REVOKED` status and its original approval details, so you can see who approved it and when alongside who revoked it. An exemption that reaches its expiration date is recorded as `EXPIRED` rather than staying approved.

## **Viewing exemptions for a single entity**

On a Scorecard's **Scores** tab, select an entity to open its side panel. Select the **Exemption history** tab to see every exemption for that entity, with its status, requester, reason, and expiration date.

![Scorecards Exemption History](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-exemption-history.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=816ec1b41c465681fdb7bd9fac9e92e0)

## Viewing all exemptions

Admins can view a list of all requested exemptions.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, expand **Scorecards**, then select **Rule exemptions**.

   ![Scorecards Rule Exemptions Settings](https://mintcdn.com/cortex-290c0c42/NB69iX-cK6Jnsvqi/images/scorecards-rule-exemptions-settings.png?fit=max\&auto=format\&n=NB69iX-cK6Jnsvqi\&q=85\&s=ca5762f73295d5ea28aba04713e121a2)

Expand **Details** on a rule exemption card to see who requested the exemption and when, who approved the exemption and when, the reason for the exemption, and whether the it's temporary or permanent.

### **Searching across and filtering exemptions**

On the **Rule exemptions** page, click **Filter** in the upper-right corner of the grid to filter exemptions based on the following:

* Approver
* Entity
* Group
* Requester
* Rules
* Status

You can also sort exemptions based on expiration, rule, Scorecard, status, and timestamp (new to old OR old to new). Click **Timestamp** (default) to change the sorting option.

### Listing exemptions via the API

Use [List Scorecard rule exemptions](/api/rest/scorecards/list-scorecard-rule-exemptions) (`GET /api/v1/scorecards/exemptions`) to read rule exemptions across all Scorecards, for example to audit who requested, approved, or revoked an exemption and when it expires. Results are paginated and ordered newest first.

You can narrow the results with these optional query parameters:

* `scorecardTag`: Only exemptions on this Scorecard.
* `ruleIdentifier`: Only exemptions for this rule. Requires `scorecardTag`.
* `entityTag`: Only exemptions for this entity.
* `status`: `PENDING`, `APPROVED`, `REJECTED`, `REVOKED`, or `EXPIRED`. `APPROVED` does not include approvals past their expiration date; use `EXPIRED` for those.
* `requesterEmail` / `approverEmail`: Only exemptions requested or approved by this user.
* `onlyActive`: Only exemptions that are pending, or approved and not yet expired.

Pagination covers the first 100,000 matching exemptions; narrow the filters to reach older results.

API keys with the `View Scorecard Exemptions` permission see every exemption. A personal API key without that permission sees only exemptions its user requested in the Cortex UI; exemptions requested through the API are attributed to the API key, not the user. Exemptions on entities hidden from you by entity visibility permissions are not returned.


# Scorecard examples
Source: https://docs.cortex.io/standardize/scorecards/scorecard-examples



The Scorecard use cases and examples this is section are based on engineering teams across a wide spectrum of sizes and maturity levels. Learn [how to set goals](/standardize/scorecards/scorecard-examples#setting-goals-in-scorecards) and what [common use cases](/standardize/scorecards/scorecard-examples#common-scorecard-use-cases-and-example-rules) look like.

See additional detailed examples:

* [DRIVE Scorecard](/solutions/drive-framework/drive-scorecard-rules)
* [DORA Metrics Scorecard](/guides/dora/scorecard)
* [Using CQL Captures to surface vulnerabilities in rule failures](/guides/security/vulnerabilities-rules)
* [Using CQL Captures to surface SonarQube code coverage in rule failures](/guides/security/code-coverage-rules)

> [!TIP]
>
> **Learn about Scorecard use cases in Cortex Academy**
>
> * Learn more about leveraging Cortex to achieve operational readiness in the [Cortex Academy course, "Cortex Solutions: Production Readiness"](https://academy.cortex.io/courses/production-readiness)
> * Learn more about planning and managing migrations using Cortex in the [Cortex Academy course, "Cortex Solutions: Migrations and Modernizations"](https://academy.cortex.io/courses/migrations-and-modernizations)

## Setting goals in Scorecards

### Start with aspirational goals

Scorecards are often aspirational. For example, an SRE team may define a Production Readiness Scorecard with 20+ criteria that they think their services should meet to be considered "ready" for SRE support.

The engineering team may not be resourced to actually meet those goals, but setting objective targets helps drive organization-wide cultural shifts and sets a baseline for conversations around tech debt, infrastructure investment, and service quality.

You can add as many levels as you want to a Scorecard. You can also add as many rules to each level as makes sense for the Scorecard, but keep in mind that an entity must pass all rules in a given level in order to progress to the next one.

### Motivate developers with early wins

When creating rules, we recommend starting with smaller, achievable goals within the Scorecard's first level. Early wins help teams build confidence and momentum. Introducing too many complex rules upfront can feel overwhelming and discouraging.

Focusing on clear, incremental improvements will create a culture of steady progress. Teams will see tangible improvements in reliability, documentation, or readiness without needing a massive investment of time. Once the basic benchmarks are in place and widely adopted, you can expand to more advanced rules, ensuring the process feels supportive and achievable rather than punitive.

### Remediate failed rules

Sometimes, an entity or team will fail a rule in a Scorecard. This gives you the opportunity to identify issues and take action on them, leading to incremental improvements over time. Learn more about evaluating Scorecards and remediating failed rules in [Review and evaluate Scorecards](/standardize/scorecards/evaluate).

## Common Scorecard use cases and example rules

Cortex users commonly define Scorecards across several categories:

* **Development Maturity**: Ensure services and resources conform to basic development best practices, such as established code coverage, checking in lockfiles, READMEs, package versions, and ownership.

> **Development maturity rules**
>
> **Development Maturity**: Ensure services and resources conform to basic development best practices, such as established code coverage, checking in lockfiles, READMEs, package versions, and ownership.
>
> `git.fileExists("package-lock.json")`\\
>
> Developers should be checking in lockfiles to ensure repeatable builds.
>
> `sonarqube.metric("coverage") > 80.0`\\
>
> Set a threshold that’s achievable, so there’s an incentive to actually try. This also serves as a secondary check that the service is hooked up to Sonarqube and reporting frequently.
>
> `git.lastCommit().freshness = 1`\\
>
> Ensure that a rigorous PR process is in place for the repo, and PRs must be approved by at least one user before merging.
>
> `git.fileContents("circleci/config.yml").matches(".*npm test.*")`\\
>
> Enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline.

* **Operational Readiness**: Determine whether services and resources are ready to be deployed to production, checking for runbooks, dashboards, logs, on-call escalation policies, monitoring/alerting, and accountable owners.

> **Operational readiness rules**
>
> `ownership.allOwners().length > 0`\\
>
> Incident response requires crystal-clear accountability, so make sure there are owners defined for each service or resource.
>
> `oncall.numOfEscalations() > 1`\\
>
> Check that there are at least 2 levels in the escalation policy, so that if the first on-call does not acknowledge, there is an established backup.
>
> `links("runbooks").length >= 1`\\
>
> Create a culture of preparation by requiring runbooks to be established for the services or resources.
>
> `links("logs").length > 1`\\
>
> When there is an incident, responders should be able to find the right logs easily. Usually, this means load balancer logs and application logs.
>
> `embeds().length >= 1`\\
>
> Responders should have standard dashboards readily accessible for every service or resource in order to speed up triage.
>
> `custom("pre-prod-enabled") == true`\\
>
> Use an asynchronous process to check whether there is a live pre-production environment for the service or resource, and send a true/false flag to Cortex using the custom metadata API.
>
> `sonarqube.metric("vulnerabilities") < 3`\\
>
> Ensure that production services are not deployed with a high number of security vulnerabilities.

* **Operational Maturity**: Monitor whether services are meeting SLOs, on-call metrics look healthy, and post-mortem tickets are closed promptly, gauging if there too many customer-facing incidents.

> **Operational maturity rules**
>
> `oncall.analysis().meanSecondsToResolve < 3600`\\
>
> Make sure that issues are resolved in a reasonable amount of time. If they’re not, you can dig into the root cause.
>
> `oncall.analysis().offHourInterruptions startOfMonth(-3)")< 2`\\
>
> A reliable service or resource should not be a source of frequent customer-facing incidents.
>
> `jira.numOfIssues("labels=compliance") < 3`\\
>
> Make sure there are no outstanding compliance or legal issues affecting the service or resource.

* **Security**: Mitigate security vulnerabilities, achieve security compliance across services, measure code coverage

> **Security rules**
>
> `snyk != null`\\
>
> The first step in monitoring security is making sure each service has as associated Snyk project.
>
> `ownership.allOwners().length > 0`\\
>
> Making sure each entity has at least one owner helps ensure updates don't fall through the cracks.
>
> `git.numOfRequiredApprovals() > 0`\\
>
> Changes should be pushed through unless there is at least one approval.
>
> `sonarqube.metric("coverage") > 70`\\
>
> By monitoring code coverage, you can get a sense of how much of your code has been tested — entities with low scores are more likely to be vulnerable to attack.
>
> `git.branchProtection() != null`\\
>
> Make sure that your default branch is protected, as vulnerabilities here are critical.
>
> `sonarqube.freshness() < duration("P7D")`\\
>
> And check to make sure a SonarQube analysis has been uploaded within the last seven days, so teams are monitoring for compliance to coding rules.
>
> `snyk.issues() < 5`\\
>
> `sonarqube.metric("security_hotspots") < 5`\\
>
> `sonarqube.metric("vulnerabilities) semver("1.1.3")`\\
>
> Having every CI pipeline send a current version to Cortex on each master build lets you catch services or resources that rely on outdated versions of tooling, like CI or deploy scripts.
>
> `package("apache.commons.lang") > semver("1.2")`\\
>
> Cortex automatically parses dependency management files, so you can easily enforce library versions for platform migrations, security audits, and more.

* **Best Practices**: Define organization-wide best practices, such as infrastructure + platform, SRE, and security. For example, the Scorecard might help you ensure the correct platform library version is being used.
  * Best practices are unique to every organization and every application, so make sure to work across teams to develop a Scorecard measuring your organization's standards.

    The following example uses JavaScript best practices:

> **JavaScript best practices**
>
> Best practices are unique to every organization and every application, so make sure to work across teams to develop a Scorecard measuring your organization's standards.
>
> The following example uses JavaScript best practices:
>
> `git.fileExists("yarn.lock") or git.fileExists("package-lock.json")`\\
>
> Make sure a Lockfile is checked in to provide consistency in package installs.
>
> `git.fileExists(".prettierrc.json") or git.fileExists(".eslintrc.js")`\\
>
> Projcets should have a standard linter.
>
> `jq(git.fileContents("package.json"), ".engines.node") != null`\\
>
> Node engine version should be specified in the package.json file.
>
> `jq(git.fileContents("package.json"), ".devDependencies | with_entries(select(.key == \"typescript\")) | length") == 0 or git.fileExists("tsconfig.json")`\\
>
> Typescript projects should have a tsconfig checked in.
>
> `jq(git.fileContents("package.json"), ".engines.yarn") == null or jq(git.fileContents("package.json"), ".engine.npm") = "please-use-yarn"`\\
>
> If a project is using yarn, it should not allow NPM.
>
> `jq(git.fileContents("package.json"), ".engines.yarn") == null or !(semver("1.2.0") ~= semverRange(jq(git.fileContents("package.json"), ".engines.yarn")))`\\
>
> Finally, ensure that the yarn version being used is not deprecated.


# Scorecard rule filters
Source: https://docs.cortex.io/standardize/scorecards/scorecard-filters



Rule filters allow you to apply a Scorecard rule only to specific entities. It's helpful to use a rule filter when a rule doesn’t apply to every entity or every group.

You can apply a filter in the Cortex UI while building out your Scorecard rules, or you can write a custom CQL query to filter your rule.

## How to set up a Scorecard rule filter

1. When [setting up a rule for a Scorecard](/standardize/scorecards/scorecard-filters#step-3-create-a-rule), click and expand **Restrict rule to specific groups**.
2. Select the relevant groups to include or exclude.
   * Or, if you prefer to write a CQL query, click **Switch to CQL** under the group fields.

     ![Choose groups to exclude or include](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/restrict-rule.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=c2260561d67276f4e6ac1a9d886c7bd6)
3. Click **Save rule**.

See the [Scorecard documentation](/standardize/scorecards/scorecard-filters) for instructions on the overall process of creating a Scorecard.
You can also edit an existing Scorecard to add a filter to a rule.

### Example Scorecard rule filter

For example, let's say that entities in the "billing" group don't need to have SLOs set up properly.

* In the rule "Has SLOs set up," apply a filter to exclude the "billing" group:

  ![](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/exclude-group-rule.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=c0e5c23e75abe92e58cba479aaf1d479)
* After saving the rule with the excluded group, view the Scorecard. Any entities in the "billing" group will not be scored against the "Has SLOs set up" rule. The rule will not appear as a passing or a failing rule; it will not be included at all.

#### View the filter on the Scorecard home page

Once a rule filter has been applied, you can still see it on a Scorecard’s home page. Navigate to the **Rules** tab and expand the rule to confirm it has been exempted.


# Scorecard troubleshooting and FAQ
Source: https://docs.cortex.io/standardize/scorecards/scorecard-troubleshooting-and-faq



See common frequently asked questions and troubleshooting information below.

Cortex offers a wide variety of out-of-the-box integrations compatible with Scorecard rules. Sometimes, a Scorecard may have multiple integration queries with different endpoints, each with its own rate limits. Cortex works to stay within these rate limits, but they can still affect rule results.

> **Why does a rule show an error instead of passing or failing?**
>
> Cortex displays the error next to the failing rule on the affected entity, so you can tell a rate limit apart from a real failure.

> **Will a rate-limited rule sort itself out, or do I need to do something?**
>
> For most integrations, yes—it'll sort itself out. Cortex retries a rate-limited rule up to five (5) times, backing off between attempts.

> **Can a rate limit lower an entity's score?**
>
> If every retry hits a rate limit, Cortex falls back to the rule's last known score, so a temporary outage on a third-party API won't drop an entity's level. The same fallback applies to 5xx errors from upstream APIs and to unexpected Cortex-side errors. A brand-new rule has no previous score to fall back on, so it fails and displays a 429 error.

> **Why does my rule fail with 'Could not apply average to non-numeric and non-duration element'?**
>
> This error means an aggregation function was applied to a list of records instead of a list of numbers.
> For example, `customMetrics()` returns a list of data points that each have a `value` field and a `timestamp` field, so `average()` can't read them as numbers. Use `map()` to extract the numeric field first:
>
> `customMetrics(key="error-rate", lookback=duration("P30D")).map((m) => m.value).average()`
>
> A related error, "Cannot take average of empty list," means the lookback window in the query contains no data points. Learn more in [Querying custom metric data with CQL](/improve/eng-intelligence/custom-metrics#querying-custom-metric-data-with-cql).


# Scorecards as code
Source: https://docs.cortex.io/standardize/scorecards/scorecards-as-code



Once Scorecards are incorporated into your regular engineering workflows, they become production-grade tools. Scorecards set the benchmarks for how your organization defines “good,” which impacts everything from security standards to on-call rotations. Because Scorecards are crucial to achieving and maintaining standards, you may want to employ controlled access and version controlling.

Turn on [GitOps editing](/configure/gitops) for Scorecards to manage your standards the same way you manage the entities in your catalogs. Each Scorecard gets its own YAML file, and every change shows up in your [GitOps logs](/configure/gitops/gitops-logs).

## Setting up Scorecards as code

### Step 1: Configuring GitOps editing for Scorecards

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Select **Settings**.
3. Locate the **Workspace** section, then select **GitOps**.\


   ![](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/gitops.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=82ee9e472baed5068b15aeb36844226f)
4. On the GitOps page, select the **Scorecards** tab.\


   ![](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scorecards-tab.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=62abe64810c54183d019eeb6d6f7fd2b)
5. Toggle on **Enable GitOps for Scorecard editing**.

**When GitOps for Scorecard editing is enabled**:

* You can't edit Scorecards in the Cortex UI, including ones you originally created there. Edits happen in the Scorecard's YAML file in your Git repository.
* You can still create and delete Scorecards in the UI.

You can also [configure an allowlist](/configure/settings/gitops-settings#gitops-scorecard-settings) to control which repositories Cortex imports Scorecards from.

### Step 2: Adding Scorecards to your Git repository

You can build a Scorecard in the Cortex UI and [convert it to a YAML](/standardize/scorecards/scorecards-as-code#convert-an-existing-scorecard-to-code), or write the YAML from scratch. See [the example](/standardize/scorecards/scorecards-as-code#example-scorecard-yaml-file) below.

Keep Scorecards in their own repository, separate from your catalog entities, under `.cortex/scorecards` at the repository root. Avoid putting Scorecard definitions in a service repository. A Scorecard measures many entities, so it doesn't belong to any single one of them.

For example, a simple repository might have the following structure:

```
.
├── .cortex
│    └── scorecards
│        ├── dora.yml
│        └── performance.yml
└── src
    └── index.js
    └── ...
```

Any file found within the `.cortex/scorecards` directory, including its subdirectories, is automatically picked up and parsed as a Scorecard.

When GitOps editing is turned on for Scorecards, you can't edit any Scorecard in the Cortex UI, including Scorecards you originally created there. You can still create and delete Scorecards in the UI. For more information, refer to [Using both the UI and GitOps](/configure/gitops#using-both-ui-and-gitops).

### Converting an existing Scorecard to code

You can convert Scorecards created in the Cortex UI to code via GitOps. Keep in mind, though, that once GitOps editing is turned on and your Scorecard lives in a YAML file, you can only edit it via Git.

**To convert an existing Scorecard into code**:

1. From the main sidebar, expand **Scorecards**.
2. Select **Scorecards**.
3. On the Scorecards page, select the Scorecard you want to convert.
4. At the top of the page, click the **overflow menu icon**, then click **Export Scorecard YAML**.\


   ![](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/export-scorecard-yaml.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=e5699881801a4d5ce90fe67ac4ff2521)
5. Add the Scorecard's YAML file to your Git repository.

#### Example Scorecard YAML file

The `dora-metrics.yaml` descriptor file might look something like this:

```yaml theme={null}
name: DORA Metrics
tag: dora-metrics
description: >-
  [DORA metrics](https://www.cortex.io/post/understanding-dora-metrics) are used
  by DevOps teams to measure their performance.

  This Scorecard covers deployment frequency, change failure rate, and time to
  restore service.
draft: false
notifications:
  enabled: true
  scoreDropNotificationsEnabled: false
exemptions:
  enabled: true
  autoApprove: false
  userSpecificNotifications: false
ladder:
  levels:
    - name: Bronze
      rank: 1
      description: Baseline delivery practices are in place
      color: "#c38b5f"
    - name: Silver
      rank: 2
      description: Delivery is consistent and incidents are handled promptly
      color: "#8c9298"
    - name: Gold
      rank: 3
      description: Delivery performance meets DORA elite benchmarks
      color: "#cda400"
rules:
  - title: Deploys at least twice a month
    expression: deploys(lookback=duration("P30D"), types=["DEPLOY"]).length >= 2
    identifier: deployment-frequency-baseline
    description: Deployment frequency
    weight: 25
    failureMessage: >-
      This entity deployed fewer than 2 times in the last 30 days. Frequent,
      small deploys reduce the risk of each individual change.
    level: Bronze
  - title: Change failure rate is 30% or less
    expression: >-
      deploys(lookback=duration("P30D"), types=["ROLLBACK"]).length <=
      deploys(lookback=duration("P30D"), types=["DEPLOY"]).length * 0.3
    identifier: change-failure-rate-baseline
    description: Change failure rate
    weight: 25
    failureMessage: >-
      More than 30% of deploys in the last 30 days were rolled back. Check
      test coverage and pre-production validation for this entity.
    level: Bronze
  - title: Time to restore service is under 4 hours
    expression: oncall.analysis(lookback=duration("P30D")).meanSecondsToResolve <= 14400
    identifier: mttr-high
    description: Time to restore service
    weight: 25
    failureMessage: >-
      Incidents took longer than 4 hours to resolve on average. Confirm this
      entity has a current runbook and a working escalation policy.
    level: Silver
  - title: Deploys at least 30 times a month
    expression: deploys(lookback=duration("P30D"), types=["DEPLOY"]).length >= 30
    identifier: deployment-frequency-elite
    description: Deployment frequency
    weight: 25
    failureMessage: >-
      Elite performers deploy on demand, roughly daily or more. Look for manual
      approval steps or batched releases holding this entity back.
    level: Gold
  - title: Time to restore service is under 1 hour
    expression: oncall.analysis(lookback=duration("P30D")).meanSecondsToResolve <= 3600
    identifier: mttr-elite
    description: Time to restore service
    weight: 25
    failureMessage: >-
      Incidents took longer than 1 hour to resolve on average. Automated
      rollback is usually the fastest way to close this gap.
    level: Gold
  # Rules without a level are scored on points alone and do not gate progress
  # through the ladder. Use this for measures you want to track and reward
  # without blocking a level on them.
  - title: Incidents are acknowledged within 5 minutes
    expression: oncall.analysis(lookback=duration("P30D")).meanSecondsToFirstAck <= 300
    identifier: mtta-bonus
    description: Time to acknowledge, tracked alongside the DORA metrics
    weight: 10
    failureMessage: >-
      Incidents took longer than 5 minutes to acknowledge on average. Check
      that this entity's escalation policy has a second level.
    # Rule-level filters scope a rule to a subset of the Scorecard's entities.
    filter:
      kind: GENERIC
      groups:
        include:
          - customer-facing
    # Scheduled rules are visible to teams before they start counting.
    effectiveFrom: "2026-10-01T00:00:00Z"
filter:
  kind: GENERIC
  types:
    include:
      - service
  groups:
    include:
      - production
evaluation:
  window: 4
```

## Scorecard YAML reference

### Scorecard objects

| Name | Description |
| - | - |
| `name` | The human-readable name of the Scorecard |
| `tag` | A unique slug for the Scorecard consisting of only alphanumeric characters and dashes |
| `description` | A human-readable description of the Scorecard |
| `draft` | Whether or not the Scorecard is a draft |
| `notifications` | Notifications settings for the Scorecard |
| `ladder` | The ladder to apply to the rules |
| `rules` | A list of rules that are evaluated each time the Scorecard is evaluated |
| `filter` | Enables the ability to exclude entities from being evaluated by this Scorecard |
| `evaluation` | Enables the ability to change the evaluation window for this Scorecard |

### Notifications

| Name | Description |
| - | - |
| `enabled` | Whether or not to include the Scorecard in notifications |
| `scoreDropNotificationsEnabled` | Whether to notify about entities' scores that dropped after each evaluation of this Scorecard |

### Exemptions

| Name | Description |
| - | - |
| `enabled` | Whether or not rule exemptions are enabled for Scorecard |
| `autoApprove` | Whether or not rule exemptions are auto approved for Scorecard |
| `userSpecificNotifications` | Whether user-specific rule exemption notifications are enabled for Scorecard |

### Ladder

| Name | Description |
| - | - |
| `levels` | The levels of the ladder |

### Level

| Name | Description |
| - | - |
| `name` | The human-readable name of the level |
| `rank` | The rank of the level within the ladder. Higher rank is better. |
| `description` | A human-readable description of the level |
| `color` | The hex color of the badge that is displayed with the level |

### Rules

| Name | Description |
| - | - |
| `title` | The human-readable name of the rule |
| `expression` | The CQL expression to evaluate; must evaluate to a boolean |
| `identifier` | Identifier of the rule, unique within Scorecard scope. Can be configured to a custom value of your choice. If omitted, we will automatically generate a value. |
| `description` | A human-readable description of the rule |
| `weight` | The number of points this rule provides when successful |
| `failureMessage` | A human-readable message that will be presented when the rule is failing |
| `level` | The name of the level this rule is associated with; can be null even when a ladder is present |
| `filter` | Enables the ability to exclude entities from being evaluated for this rule |
| `effectiveFrom` | Date when the rule starts being evaluated, e.g. 2024-01-01T00:00:00Z |

### Filter

Note: One of `types`, `groups`, or `query` must be present for it to be considered a valid filter.

| Name | Description |
| - | - |
| `kind` | The kind of filter to create. Currently only supports "GENERIC". |
| `types` | Types filter (to include / exclude specific types) |
| `groups` | Groups filter (to include / exclude specific groups) |
| `query` | A CQL query; only entities matching this query will be evaluated by the Scorecard |

### TypesFilter

Note: Only one of `include` or `exclude` can be specified at a time.

| Name | Description |
| - | - |
| `include` | List of types to include in set of entities |
| `exclude` | List of types to exclude in the set of entities |

### GroupsFilter

| Name | Description |
| - | - |
| `include` | List of groups to include in set of entities |
| `exclude` | List of groups to exclude in the set of entities |

### Evaluation

| Name | Description |
| - | - |
| `window` | By default, Scorecards are evaluated every four (4) hours. This can be changed under **Settings** > **Scorecards** > **Default evaluation window**.  To evaluate Scorecards less frequently, you can override the evaluation window. This helps if you're encountering problems with rate limits. Note that Scorecards cannot be evaluated more than once per minimum set in **Settings** > **Scorecards** > **Minimum evaluation window**. |


# Engineering homepage
Source: https://docs.cortex.io/streamline/homepage



The homepage in Cortex surfaces what you own, what you have access to, and what needs your attention. It allows you to centralize your work onto one page and take action on your highest priority tasks, and it highlights Scorecard and Initiative progress for your teams with quick links to the Bird's eye report.

> [!TIP]
>
> The engineering homepage makes it easier to find the right information at the right time. It's designed for everyone — not just individual contributors.

![](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/engingeering-homepage.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=7d2b65b2c4083b012c1bc27133a2de2e)

### Homepage features

The homepage gives you visibility into your work, your catalog, your top Scorecards, and Initiative tasks with approaching due dates. The information is organized into the following sections:

* [**My work**](/streamline/homepage#my-work)
  * [Your requested PR reviews](/streamline/homepage#open-prs-and-assigned-reviews)
  * [Your open PRs or MRs](/streamline/homepage#open-prs-and-assigned-reviews)
  * [Your open issues](/streamline/homepage#issues)
  * [Your action items](/streamline/homepage#action-items) from Scorecards and Initiatives
  * [Your pending verifications](/streamline/homepage#pending-verifications)
* [**My on-calls**](/streamline/homepage#my-on-calls)
* [**Catalog quick access**](/streamline/homepage#catalog-quick-access)
  * View all of your entities, or view filtered lists of your teams, domains, or services
* [**Top Scorecards and Scorecards by team**](/streamline/homepage#top-scorecards-scorecards-by-team-and-initiatives-due-soon)
  * The top 3 Scorecards for your owned entities
* [**Initiatives due soon**](/streamline/homepage#top-scorecards-scorecards-by-team-and-initiatives-due-soon)
  * Initiative tasks that are due soon
* [**My Workflow runs**](/streamline/homepage#my-workflow-runs)
  * View your recently run [Workflows](/streamline/workflows)

You can also [pin plugins](/streamline/homepage#plugins) to your homepage.

### Understanding entity ownership

The content that appears on your homepage is based on the [entities you own](/ingesting-data-into-cortex/entities-overview/entities/ownership). You own an entity if:

* You are explicitly listed as the owner, or
* The entity is owned by a team you're a member of.

#### Child team visibility

While viewing the homepage, you can also choose whether to include child teams in your entity lists, top Scorecards, and Initiatives. This gives you visibility into the entities that your child teams own.

To include child teams, enable the **Include child teams** toggle in the upper right side of the homepage:

![Enable the toggle for 'Include child teams.'](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/homepage-include-child.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=62ff55eb7c7d0c2f29fa979208f838a3)

**Configure identity mapping for Git providers**

The Git features in Cortex use [identity mapping](/configure/settings/managing-users/identity-mapping) to connect you to your user account in your Git provider. Entities use the email address associated with your Cortex account and your Git account to connect your Cortex profile with a Git user and team.

Make sure you have properly [configured identity mapping](/configure/settings/managing-users/identity-mapping) to ensure that your Git requests appear in the dev homepage.

## My work

### Open PRs and Assigned reviews

> [!NOTE]
>
> Bitbucket data in the homepage is available in private beta. Please contact your Cortex Customer Success Manager for access.
>
> Note: Because of rate limits, Bitbucket ingestion in the homepage is limited to repositories that are mapped to an entity in Cortex.

Open PRs or MRs and Assigned reviews on the homepage come from any Git providers you have integrated with your Cortex workspace: [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops), [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket), [GitHub](/ingesting-data-into-cortex/integrations/github), and [GitLab](/ingesting-data-into-cortex/integrations/gitlab).

* Click [**Open PRs**](https://app.getcortexapp.com/admin/home/open-prs) to view a list of all pull requests or merge requests you opened.
  * The list contains the PR name, associated entity, status, date opened, and last updated date.

    ![See a list of open PRs linked from the homepage.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/open-pr-homepage.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=e2a7e5ddc2a03c07f3e90ee920f636a6)
* Click [**Requested PR reviews**](https://app.getcortexapp.com/admin/home/assigned-prs) to view all the pull requests that have been assigned to you for review.
  * The list contains the PR name, associated entity, status, reviewers, date opened, and last updated date.
  * In the "Status" column, Cortex automatically adds tags to pull requests to signify PRs that need a `Quick review` or that involve a more `Complex review` for convenience.

    ![See a list of assigned PRs linked from the homepage.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/assigned-pr-homepage.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=15afebb3f72a3851f7a8834be1702564)

These are not tied to an entity in Cortex, but are linked to a specific Cortex/Git user account.

Cortex refreshes pull requests from GitLab every 2 minutes, and from Azure DevOps and Bitbucket every 5 minutes. For GitHub, pull request syncs follow the schedule described in the [GitHub documentation](/ingesting-data-into-cortex/integrations/github#background-sync).

Pull requests that are deleted in Bitbucket are removed from the homepage once a day, at 3:30 a.m. UTC. Until that daily cleanup runs, a deleted Bitbucket pull request can still appear in your lists.

Make sure you have properly [configured identity mapping](/configure/settings/managing-users/identity-mapping) to ensure that your Git requests appear in the homepage.

#### Change the list display

While viewing the list of Git data, you can change the display:

1. At the top of the list, click **Display**.
2. Configure the filters:
   * If you want to display draft MRs or PRs, enable the toggle next to **Show drafts**.
   * If you want to display MRs or PRs older than a month, enable the toggle next to **Show older than a month**.
3. Click **Done**.

### Issues

The [Issues ](https://app.getcortexapp.com/admin/home?activeTab=Issues)section includes [Jira](/ingesting-data-into-cortex/integrations/jira) tickets, [GitHub](/ingesting-data-into-cortex/integrations/github) issues, [ClickUp](/ingesting-data-into-cortex/integrations/clickup) issues, or [Azure](/ingesting-data-into-cortex/integrations/azuredevops) work items that are associated with your email address.

![Issues from integrations are listed on the engineering homepage.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/eng-homepage-issues.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=652b1c98f18aca9600314ce4f1e06e40)

Cortex runs a JQL query against your Jira instance to populate tickets that have been assigned to your associated account.

Cortex refreshes issues from Jira, ClickUp, and Azure DevOps every 5 minutes. For GitHub, issue syncs follow the schedule described in the [GitHub documentation](/ingesting-data-into-cortex/integrations/github#background-sync).

### Action items

Click **Action items** to view a list of action items. In this section, view the entity, the rule that needs attention, the Scorecard or Initiative that contains the rule, its due date, and the priority (based on the level configured in the Scorecard):

![Action items are listed on the homepage.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/action-items-homepage%20%281%29.jpg)

Tasks with deadlines are sourced from Initiatives; those without deadlines are sourced from failing Scorecard rules.

### Pending verifications

[**Pending verifications** ](https://app.getcortexapp.com/admin/home?activeTab=Pending%20verifications)lists all [data verifications](/configure/settings/entity-settings/verification) that require your attention.

![Pending data verifications are listed on the homepage.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/pending-verif-homepage.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=ff8b230f3033ce363610cdea07459284)

## My on-calls

If your organization has an on-call integration configured ([PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty) or [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie)) you will also see that information on the homepage:

![There is a block displaying 'My on-calls' on the homepage.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/oncall-homepage.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=582996b1008be9d567ccc0c294cb240a)

Cortex uses your email address to determine your upcoming or current on-call status. If you do not see your expected on-call information, verify that your [identity mappings ](/configure/settings/managing-users/identity-mapping)are configured properly.

On-call information from PagerDuty is refreshed every 60 minutes. Information from Opsgenie is refreshed every minute.

## Catalog quick access

![From the homepage, click into your entities, teams, domains, or services.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/catalog-quick-access%20%281%29.jpg)

The catalog section is driven by [entity ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership). You can view all your owned entities, or filtered lists of your teams, services, or domains.

If you have [enabled the **Include child teams** toggle](/streamline/homepage#child-team-visibility), these lists will also include entities owned by your child teams.

## Top Scorecards, Scorecards by team, and Initiatives due soon

![Top scores for your owned entities and Scorecards for your teams are displayed.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scorecards-and-initiatives-homepage.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=0cac1acd71d7ade7538eebf7220d7065)

On your homepage, you can see:

* **Top Scorecards**: A list of your top performing [Scorecards](/standardize/scorecards), sorted by total score percentage best to worst. On the homepage, Cortex only displays scores and details for entities that you own.
  * Click **See all** to view the full list of scores for your owned entities, where you can also sort the list by name or by worst to best scores.
* **Scorecards by team**: A list of Scorecards for your teams.
* **Initiatives due soon**: If you have any [Initiative](/improve/initiatives) tasks with approaching due dates, they will be listed here.

If you have [enabled the **Include child teams** toggle](/streamline/homepage#child-team-visibility), these lists will also include entities owned by your child teams.

#### View bird's eye report for your Scorecards

From the Top Scorecards tile, click the Birds eye icon to go directly to the [Bird's eye report](/improve/reports/birds-eye) for that Scorecard:

![Click the birds eye icon to see a birds eye report for your entity.](https://mintcdn.com/cortex-290c0c42/Z-yTwwLdih7PmvB6/images/birds-eye-homepage.jpg?fit=max\&auto=format\&n=Z-yTwwLdih7PmvB6\&q=85\&s=ccb737f3a208f60ca9fa0fded8bf5c46)

#### View action items for the Scorecard

From the Top Scorecards tile or from the Initiatives tile, click the Action items icon to go directly to a filtered list of action items for that Scorecard or Initiative:

![Click the action items icon to see action items for that Scorecard.](https://mintcdn.com/cortex-290c0c42/WsEW6MxYeKygvxWi/images/action-items-homepage.jpg?fit=max\&auto=format\&n=WsEW6MxYeKygvxWi\&q=85\&s=28a0f971c844df8eb1dabccaba5d2ac1)

## My Workflow runs

![A list of Workflow runs is displayed on the homepage.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/workflows-homepage.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=1b9dc3d3dfdb1c712de9bbc9afc4b723)

View a list of all of your recently run Workflows. In the upper right corner of the tile, click **All workflow runs** to see a full list of recent runs for your workspace.

## Plugins

You can pin plugins to your homepage. Plugins will appear in the **Plugins** page linked on your homepage sidebar.

To pin plugins:

1. Navigate to [**Settings > Plugins**](https://app.getcortexapp.com/admin/settings/appearance/plugins/homepage).
2. Under the **Homepage** tab, select which plugins you want to appear on the homepage.
3. At the bottom of the page, click **Save changes**.


# Plugins
Source: https://docs.cortex.io/streamline/plugins

Overview of plugins and how to view them

Plugins are how you tailor Cortex to fit the way your organization actually works. Out of the box, Cortex covers a broad set of integrations and workflows—but every engineering org has its own internal tools, custom processes, and one-off systems that don't fit a standard mold. Plugins close that gap, letting you extend Cortex with custom functionality to support unique workflows, surface data from internal systems, or integrate with tools that Cortex doesn't natively support.

Under the hood, each plugin is a single HTML file rendered inside an iframe within Cortex, giving you full control over the UI while keeping the plugin sandboxed from the rest of the app. To make working with external APIs straightforward, Cortex provides plugin proxies that handle CORS restrictions and can enrich outbound requests with custom headers and secrets, so you can call internal services without exposing credentials in the browser. Plugins also receive contextual information about where they're running in the app, allowing them to adapt their behavior based on the entity, page, or workflow currently in view.

For a list of available plugins, see [Available plugins](/streamline/plugins/marketplace#available-plugins).

> [!TIP]
>
> Want to learn more? Check out the Cortex Academy course on [plugins](https://academy.cortex.io/courses/understanding-plugins).

## Viewing plugins

Plugins can be viewed in the following areas of Cortex:

* **Main sidebar**
* **Engineering homepage**
* **Plugins homepage** (select **Plugins** from the main sidebar)
* **Entity details page**

### Configuring plugins to appear in the main sidebar

Users with the `Configure Plugin Appearance` permission can configure which plugins appear in the main sidebar.

![The 'Plugins' section in the main sidebar.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/plugins-main-sidebar.png?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=67049bb5f47a20b1ff8b75bef27814fa)

> [!NOTE]
>
> Use the main sidebar for plugins your whole organization should see. Any plugin added to the main sidebar is visible to all users.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then select **Main sidebar**.
4. Select the **Plugins** tab.
5. From the **Select plugins** drop-down menu, select up to five (5) plugins to appear in the main sidebar.
6. Optionally, reorder a plugin by hovering over its **grip icon** and dragging it to the desired position. To remove a plugin from the main sidebar, click the **trash icon** next to it. Repeat as necessary.
7. Click **Save changes**.

### Configuring plugins to appear on the engineering homepage

Users with the `Configure Plugin Appearance` permission can configure which plugins appear on the engineering homepage.

![The 'Plugins' section on the developer homepage.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/plugins-dev-page.png?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=f185b608476e4c594687f64a7f39eb99)

> [!NOTE]
>
> Use the engineering homepage for plugins your whole organization should see. Any plugin added to the engineering homepage is visible to all users.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, scroll to the **Workspace** section, then select **Plugins**.
4. From the **Select plugins** drop-down menu, select up to five (5) plugins to appear on the engineering homepage.
5. Optionally, reorder a plugin by hovering over its **grip icon** and dragging it to the desired position. To remove a plugin from the engineering homepage, click the **trash icon** next to it. Repeat as necessary.
6. Click **Save changes**.

### Configuring plugins to appear on an entity's details page

Users with the `Edit Entities` permission can pin, reorder, and hide plugins on an entity's details page. Plugins pinned this way appear as tabs at the top of the page, either on a single entity or across all entities of the same type.

See [Customizing entity page tabs](/ingesting-data-into-cortex/entities-overview/entities/details#pinning-plugins) for more information.


# Migrating Backstage plugins to Cortex
Source: https://docs.cortex.io/streamline/plugins/backstage-migration



This guide covers how to migrate Backstage plugins to Cortex.

### Step 1: Create a Cortex plugin code repository

Follow the steps in Cortex's [Creating a plugin](/streamline/plugins/creating-plugins) documentation to create a Cortex plugin code repository.

### Step 2: Configure the repository

1. In the repository, copy/paste (and merge, when appropriate) the Backstage source code into `src/`.
   * Favor the Cortex code if you encounter any conflicts.
   * Replace the Backstage `eslint` config with the Cortex config.
     * Note: Later in this process, you will need to run `eslint src --fix` and may have to manually fix some lint settings.
2. Delete the remaining Backstage registration files, such as `plugin.ts` and `index.ts`.
   * **Do not** delete `routes.ts` as that will be removed in a later step.
3. Remove all `@backstage/` package dependencies (**except for** `@backstage/core-components`) then iterate over them by running a command similar to the following: `yarn remove @backstage/package-name @backstage/package-name-2`.

### Step 3: Switch the plugin to use `react-router`

In this step, you will switch to using `react-router` directly instead of through the Backstage abstraction.

1. Replace Backstage route usage with `react-router/react-router-dom`.
2. Use \`\` from `react-router-dom` for the provider.
3. Remove `routes.ts`.

### Step 4: Replace the Backstage entity usage with Cortex entity usage

Note that there is no complete 1:1 mapping between the two data models. You will likely need to fetch additional data from the [Cortex API](/api) as needed.

### Step 5: Replace the data fetching layer

1. Replace Backstage API refs with simple classes or objects.
2. Use `fetch()` directly instead of Backstage’s `useApi`.
3. Remove `errorApi` usage (Cortex has no equivalent).

Additional testing is recommended, as there will likely be some final clean-ups to ensure everything is working as expected.


# Calling internal service endpoints via plugin proxy
Source: https://docs.cortex.io/streamline/plugins/calling-internal-service-endpoints-via-plugin-proxy



Your organization may have services that are not publicly accessible but contain information that would be useful to manage in Cortex. You can set up a plugin proxy that works with [Cortex's Axon Relay](/ingesting-data-into-cortex/integrations/axon-relay) to call internal services without exposing the service or authentication outside of your firewall.

## How to call internal service endpoints in a plugin proxy

### Prerequisites

Before getting started:

* You should have already [set up the Cortex Axon agent](/ingesting-data-into-cortex/integrations/axon-relay) and [set your Cortex API token in the .env file](/ingesting-data-into-cortex/integrations/axon-relay#step-1.2-create-a-.env-file-and-a-docker-compose.yml-file).
* You should have already followed the steps to [create a plugin](/streamline/plugins/creating-plugins) and a [plugin proxy](/streamline/plugins/creating-plugins/plugin-proxy).

#### Considerations

* This guide describes using a Docker compose file, but note that Axon Relay can be run in Kubernetes or other container systems.
* As an example throughout this guide, assume a service in the network has the following endpoint:

`GET http://cities.internal.my-company.com/api/cities/s => ["Seattle", "Sydney", "Shanghai" ...]`

### Step 1: Create request forwarding configuration

* Create a file that defines how requests are routed.
  * The example below permits any requests, but note that the `method` and `path` can be narrowed to allow access to specific endpoints:

```json theme={null}
{
   "private": [
     {
       "method": "any", 
       "path": "/*",   
       "origin": "http://cities.internal.my-company.com"
     }
   ]
}

```

In your configuration, you will enter the root of your service URL as the value of `origin`.

### Step 2: Configure Axon Docker container

1. Create the Axon container (in this example, via Docker Compose for brevity) that defines how the container will route traffic and which routes are allowed.
   * For production employments, two replicas should be specified, and the instances should be run in Kubernetes or some other durable system.. The example below can be used to test the configuration and can be run locally.

```yaml theme={null}
services:
 relay-cities:
   image: ghcr.io/cortexapps/cortex-axon-agent:latest
   environment:
     HOSTNAME: relay-cities-${HOSTNAME:-local}
     CORTEX_API_TOKEN: $CORTEX_API_TOKEN
   volumes:
     - "./accept.cities.json:/app/accept.json"
   command: [
     "relay",
     "-a", "axon-relay-cities", # this can be any unique value
     "-f", "/app/accept.json",
   ]

```

2. Start the container, which will register it with Cortex: Run the command `docker compose up`.

### Step 3: Include the Axon call in your plugin proxy code

Your endpoints can be invoked by specifying a URL in the format: `http://[your-configuration-alias]@relay-proxy.cortex.io[/desired/url/path]`

For the example above, we could create a helper function to fetch cities by prefix:

```javascript theme={null}
import from "@cortexapps/plugin-core";

const getCitiesByLetter = async (prefix: string) => { 
  const result = await fetch(`http://axon-relay-cities@relay-proxy.cortex.io/api/cities?prefix=${prefix}`); 
  return result.json(); 
};
```


# Creating a plugin
Source: https://docs.cortex.io/streamline/plugins/creating-plugins



[Plugins](/streamline/plugins) let you pull data into Cortex from any source, expose custom metrics, and customize the UI to match your other internal tools. A plugin is an application embedded in Cortex that uses a plugin proxy to send requests to third-party services.

To quickly spin up a plugin repository, use the Scaffolder in a Workflow. The generated repository includes:

* React and TypeScript
* Linting and formatting via [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/)
* Testing via [`testing-library`](https://testing-library.com/)
* Compilation to a single HTML file via [webpack](https://webpack.js.org/)
* The Cortex React plugin package ([`@cortexapps/react-plugin-ui`](https://www.npmjs.com/package/@cortexapps/react-plugin-ui)), which provides access to context, proxy usage, CSS variables for theme-based styling, and UI components.
* The Cortex Plugin core package ([@cortexapps/plugin-core](https://www.npmjs.com/package/@cortexapps/plugin-core)).

Cortex offers a [cookiecutter template](https://github.com/cortexapps/cookiecutter-cortex-plugin) with examples using `react-plugin-ui`.

> [!WARNING]
>
> **Plugin package update (April 2025)**
>
> As of April 2025, all new plugins use the `@cortexapps/react-plugin-ui` package, which gives plugins the same look and feel as Cortex itself when rendered in an iframe.
>
> If you created your plugin before April 2025 and it uses components from `plugin-core/components`, upgrade `plugin-core` to version `3.0.0-beta.4` or later to migrate those components to the new design.

## Creating a plugin

### Prerequisites

Users with the `Configure Plugins` permission can create a plugin for use in Cortex.

### Step 1: Registering the plugin

Follow the steps below to register the plugin. Registration is a prerequisite for creating it.

> [!NOTE]
>
> By default, the plugin stays in draft mode until you manually set it live, giving you a chance to test and review before making it available.

1. From the main sidebar, select **Plugins**.
2. In the upper-right corner, click **Register plugin**.
3. Do the following:
   1. Under **Plugin name**, enter a display name for the plugin (required).
   2. Under **Identifier**, enter a unique identifier made of letters, numbers, and/or hyphens for the plugin.
   3. Under **Description**, enter a description of the plugin to help others understand its purpose.
   4. Under **Display icon**, select an icon to be used when displaying this plugin across Cortex.
   5. Under **Minimum user role**, select the minimum user role required to be able to see this plugin. You can choose default or custom roles. Note that you will not be able to delete a custom role if it is associated with a plugin.
   6. Under **Associated proxy**, if you have configured a [proxy](/streamline/plugins/creating-plugins#create-a-plugin-proxy), select the proxy to use for proxy fetches from this plugin.
   7. Under **Configure requirements**, select one of the following configuration types:
      * **Global** - Select this option if you want to configure the plugin to appear in the main sidebar or as a tab on the engineering homepage.
      * **Specific entity types** - Select this option if you want to plugin to display in the sidebar of entity pages. If selected, choose an entity type from the drop-down menu.
      * **Both options** - Select this option to have the ability to display the plugin in the main sidebar, on the engineering homepage, and on entity pages. If selected, choose an entity type from the drop-down menu.

In the next step, you'll create the plugin.

### Step 2: Creating the plugin

In the **Code** section of the registration page, choose whether to create your plugin repository from a template or from scratch.

![When creating a plugin, choose whether to use a template or start from scratch.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/plugin-code-section.png?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=003477258cde0297b340930f5d083d48)

1. Under **Create plugin**, select one of the following options:
   * **Duplicate repo with template** - Select this option to create a plugin repository from a template.
     * In the **Duplicate plugin template** side panel, do the following:
       1. Under **Project name**, enter a name for the plugin project (required).
       2. Under **License**, enter licensing information for the plugin, e.g. MIT, Apache 2.0 (required).
       3. In the **Configure output** section, select one of the following:
          1. **Create a new repo** - Select this option to generate a brand-new standalone repository to hold the duplicated plugin template code.
             1. From the **GitHub Organization** drop-down menu, select the GitHub org account under which the new plugin repository will be created (required).
             2. Under **Repo name**, enter the name of the new repository that will be created to hold this plugin's source code (required).
             3. Under **Branch**, enter the default branch (e.g. `main` or `master`) that will be initialized as the service's primary branch (required).
             4. From the **Visibility** drop-down menu, select whether the repository is public (open to everyone) or private (restricted to authorized users).
          2. **Open a pull request** - Select this option to push the duplicated template into an existing repository as a new branch and open a PR for review.
             1. From the **Repository** drop-down menu, select the existing repository where the generated plugin code will be added via pull request.
             2. Under **Branch to create**, enter the branch name (source branch) where the generated code will be pushed and from which the PR will be opened (required).
             3. Under **Subdirectory**, enter the folder path inside the existing repository where the generated plugin service will live.
       4. Optionally, toggle on **Create a corresponding Cortex entity** to automatically register a matching Cortex catalog entity alongside the plugin so the new service is tracked in Cortex. If toggle on, do the following:
          1. Under **Entity name**, enter the human-readable display name for the new Cortex entity as it appears in the catalog (required).
          2. Under **Cortex tag**, enter a unique identifier of letters, numbers, and/or hyphens to reference the entity programmatically across Cortex.
          3. Under **Description**, enter a short summary explaining what the service does and its purpose in the catalog.
       5. Click **Save**.
   * **Download template.zip** - Select this option to create a plugin from scratch. A zip file automatically downloads. You can then manually configure your repository.

In the next step, you'll generate the HTML file for your plugin.

### Step 3: Cloning the repository and installing dependencies

After you create a plugin from a template in Cortex, a link is displayed to see your created repository.

1. In GitHub, navigate to your newly-created plugin repository.
   * If you created the plugin from a template, a link is displayed to view the repository. Click **View created repository**.\


     ![The 'View created repository' button in the 'Duplicate plugin template' sidebar.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/view-created-repository.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=62fc166a999a4eb0ded252dbc72edf41)
2. [Clone the repository locally](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).
3. Install dependencies via `yarn`. You can also use `npm` commands if preferred.
4. If you need to make any changes to the plugin, modify the code before the next step.
5. Run `yarn build` to generate a single HTML file representing your plugin (output at `./dist/ui.html`).
6. In Cortex, navigate to the plugin's registration page.
   In the next step, you'll upload, preview, and save the plugin to Cortex.

### Step 4: Uploading and previewing the plugin

While still in the **Code** section of the registration page, you'll upload and preview your plugin. Once you're satisfied, the plugin can be saved and added to your Cortex tenant.

![When creating a plugin, choose whether to use a template or start from scratch.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/plugin-code-section.png?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=003477258cde0297b340930f5d083d48)

1. Under **Upload & preview** plugin, upload the HTML file generated from running `yarn build` in the previous step.
2. Optionally, toggle on **Dev mode**. Click the **down arrow** next to the toggle to open the **Plugin preview**.
   * When in dev mode, the preview for the HTML file uses code running at `http://localhost:9000/ui.html`. To run your plugin code from this location, use `yarn dev` or `npm run dev` from your plugin.
3. In the **Plugin preview**, review the plugin and make any necessary changes.
4. Click S**ave plugin**.

> [!NOTE]
>
> Looking to add theme-based styling? Refer to the [documentation](/streamline/plugins/creating-plugins/editing-a-plugin#adding-theme-based-styling).

### Creating a plugin proxy

To access authenticated external APIs, you can configure a plugin proxy to add request headers to requests matching a URL prefix. See [Creating a plugin proxy](/streamline/plugins/creating-plugins/plugin-proxy) for more information.

## Sharing a plugin

Users with the `Configure Plugins` permission can share a plugin with anyone who has access to view plugins in their Cortex workspace.

1. From the main sidebar, select **Plugins**.
2. Locate the plugin you want to share, then click the **Overflow menu**.
3. Select **Share**. A link is copied to your clipboard. \


   ![The 'Share' option is located within a plugin's 'Overflow' menu.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/plugins-share.png?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=91187c185405e07073eed64150255ff3)

## Troubleshooting and FAQ

**When developing a plugin that uses an iframe, the rendered output appears compressed. How can this be resolved?**

This issue occurs if the iframe’s height property is not set to 100%. The following example demonstrates an iframe configured to stretch to the full height of the page.

```
 <iframe 
    src="https://docs.cortex.io/" 
    width="100%" 
    height="100%"
    title="Cortex Documentation"
  ></iframe>
```


# Editing a plugin
Source: https://docs.cortex.io/streamline/plugins/creating-plugins/editing-a-plugin



As your workflows evolve and you gather feedback from users, you may want to refine what a plugin does and where it shows up. Cortex lets you edit any plugin's configuration, code, and display settings after it's been registered, so you can iterate without starting over.

## Viewing the plugin in Cortex

1. From the main sidebar, select **Plugins**.
2. Locate the plugin you want to view, then click the **Overflow menu**.
3. Select **Edit plugin**.
4. In the bottom-right corner, toggle on **Dev mode**. The **Plugin preview** uses code running at `http://localhost:9000/ui.html`.
5. Click the **down arrow** next to the toggle.
6. In the command line, navigate to your scaffolded plugin directory and run `yarn dev`.
7. Review the plugin in the **Plugin preview**.

## Editing a plugin

Users with the `Edit Plugins` permission can edit plugins.

1. In your text editor, open the cloned repository for your plugin.
2. Make any necessary changes.
3. Save and run `yarn build`.
4. Optionally, run `yarn dev` to preview your changes in Cortex.
5. Upload or drop the new HTML file into the **Upload & preview plugin** grid. Cortex automatically deletes the old HTML file and replaces it with the new one.
6. Review the plugin in the **Plugin preview**.
7. Click **Save plugin**.

## Adding theme-based styling

The `react-plugin-ui` package includes CSS variables for theme-based styling. These styles adjust to match the [brand color you have configured](/configure/settings/workspace-customization#customize-for-your-organization) and reflect the light or dark mode settings for your Cortex workspace. The styles are injected via an iframe `postMessage` request, initiated by the Cortex `CortexApi.pluginInit()` call.

If your plugin needs additional styling beyond what's available in `react-plugin-ui`, you can use the Cortex CSS API. Refer to the documentation in the [plugin template repository](https://github.com/cortexapps/cookiecutter-cortex-plugin/blob/master/%7B%7Bcookiecutter.project_name%7D%7D/src/components/ColorSwatches.tsx).


# Plugin development reference
Source: https://docs.cortex.io/streamline/plugins/creating-plugins/plugin-development-reference



This article covers the core building blocks for developing Cortex plugins using the `@cortexapps/plugin-core` and `@cortexapps/react-plugin-ui` packages.
You'll learn how to read contextual information about the user and entity your plugin is running in, call Cortex APIs, reach external (non-Cortex) APIs without running into CORS issues, verify that incoming requests originated from Cortex using signed headers, and use Cortex's prebuilt UI components so your plugin matches the look and feel of the rest of the product.

## Accessing contextual Cortex information from your plugin

The easiest way to access the plugin context is via the `usePluginContext()` hook.

```ts theme={null}
import  from "@cortexapps/plugin-core/components";
import type React from "react";

const MyComponent = React.FC => () => {
  const context = usePluginContext();

  return (
    
      Plugin context
      
    
  );
};

export default MyComponent;
```

If you need to access the plugin context outside of a React component, you can use the `CortexApi` class directly. The CortexAPI class exposed from `@cortexapps/plugin-core` provides a method for accessing the context your plugin is running in, `getContext()`.

```ts theme={null}
import  from "@cortexapps/plugin-core";
import types  from "@cortexapps/plugin-core";

// fetch information about the currently-signed-in Cortex user
const getCurrentCortexUser = async (): Promise => ;

// if the plugin is running inside of a catalog entity details page, fetch information about that entity
const getCurrentCortexEntity = async (): Promise => ;
```

## Accessing Cortex APIs from your plugin

You can access Cortex APIs using `@cortexapps/plugin-core`’s `CortexAPI`. See the [Cortex API docs](/api) for available API calls.

```ts theme={null}
import  from "@cortexapps/plugin-core";

// fetch deploys for the current entity if the plugin is running on a domain, resource, or service details page
const fetchDeploysForCurrentEntity = async () => {
  const context = await CortexApi.getContext();

  if (!context?.entity) 

  const  = context.entity;

  const response = await CortexApi.proxyFetch(`https://api.getcortexapp.com/api/v1/catalog/$/deploys`);
  return response.json();
};
```

## Accessing external APIs from your plugin

It's also possible to access non-Cortex APIs from your plugin. Because plugins are run in an iframe, typical `fetch` requests often get blocked by the browser's enforcement of CORS. However, when using the Cortex-provided template, the browser fetch is shimmed to call `CortexApi.proxyFetch`, a method for using Cortex as a proxy to make the request. For this reason, you should be able to use `fetch()` as you typically would in a web application.

If your browser fetch is not getting shimmed properly, make sure that your `@cortexapps/plugin-core` is up to date and you're using wrapping your app with `<PluginProvider>`. See the [cookiecutter template](https://github.com/cortexapps/cookiecutter-cortex-plugin/blob/master/%7B%7Bcookiecutter.project_name%7D%7D/src/components/App.tsx) for an example.

### Request signing

The following headers are added to each request made by Cortex. Use these headers to verify that the request is valid and originated from Cortex:

* `x-cortex-timestamp`
  * This header uses the current timestamp in millis, and is used to prevent replay attacks. Cortex signs the requests using the format `<timestamp>.<body>`.
* `x-cortex-timestamp-only-signature-256`
  * This header calculates the SHA256 signature using only the timestamp. Use this header in environments where the HTTP request body is unavailable due to platform limitations.
* `x-cortex-signature-256`
  * This header uses the SHA256 algorithm. For security best practices, it's recommended to use this header rather than `x-cortex-signature`.
* `x-cortex-signature`
  * This header uses the SHA1 algorithm and exists for backward compatibility. SHA1 is considered unsafe and this signature should be considered deprecated.

#### **Calculating the signature** (an [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104.html) HMAC)

1. Create a string with the value `"$timestamp.$requestBody"` if the request body is non-null OR `"$timestamp`" if the request body is null.
2. Calculate an HMAC using the SHA256 algorithm. Use the secret you provided to Cortex as the key and the string from Step 1 as the payload.
3. Verify that the `x-cortex-signature-256` matches the HMAC calculated in Step 2.

## Using Cortex UI components

Cortex UI components are available for import from `@cortexapps/react-plugin-ui`.


# Creating a plugin proxy
Source: https://docs.cortex.io/streamline/plugins/creating-plugins/plugin-proxy



To access authenticated external APIs with your plugin, you can configure a plugin proxy.

Plugin proxies try to match incoming requests against configured URL prefixes and apply rules to those requests (such as adding headers) before propagating the request to the specified downstream URL. Header rules have access to secrets via Mustache-like templating for easy authentication.

Plugin proxies must be explicitly associated with a particular plugin in the plugin configuration; once specified, all proxyFetch requests made by that plugin will use the proxy. If no proxy is defined for a plugin, no special logic will apply and requests will be propagated to downstream URLs without modification.

### Considerations

When creating a plugin proxy, consider the following:

* If there are multiple matching URL prefixes with overlapping header keys, the more specific (i.e. longer) prefix rules will be used.
* If a request from the plugin is invoked with header keys that overlap the proxy ruleset, the request-specific header values will be used.

## Creating a plugin proxy

Users with the `Edit Plugin Proxies` permission can create a plugin proxy.

> [!NOTE]
>
> If you are using a proxy with sensitive information, such as an access token, first follow the [steps to create a secret](/configure/settings/api-keys/secrets) for the proxy.

1. From the main sidebar, select **Plugins**.
2. In the upper-right corner, click **Create proxy**.
3. Do the following:
   * Under **Proxy name**, enter a human-readable name for the proxy (required).
   * Under **Path**, enter a unique identifier made of letters, numbers, and/or hyphens for the proxy (required).
   * In the **URL prefixes** section, click **Add URL** to configure URL prefixes to apply rules to requests going through this proxy (required). All requests passing through this proxy that match the URL prefix will have a set of rules applied.
     * Optionally, click **Add header** to configure a header for the URL.
       * If you are using a proxy with sensitive information, you can use mustache templating to reference a global secret by tag, e.g. `{{secrets.my_auth_token}}`.
4. Click **Create proxy**.

### Example plugin proxy configuration

```json theme={null}
{
  "id": "22",
  "tag": "github",
  "urlConfigurations": {
    "https://api.github.com": {
      "headers": [
        { "key": "X-GitHub-API-Version", "value": "2022-11-28" },
        { "key": "Authorization", "value": "Bearer {{ secrets.github_read_token }}" }
      ]
    }
  }
}
```

#### Example plugin code

```ts theme={null}
import { CortexApi } from "@cortexapps/plugin-core";

const getGithubReleases = async (ownerName: string, repoName: string) => {
  const githubReleases = await fetch(`https://api.github.com/repo/${ownerName}/${repoName}/releases`);
  return githubReleases.json();
};
```

In this scenario, the request to fetch GitHub requests will be sent with the `X-GitHub-API-Version` and `Authorization` headers, with the `Authorization` header value interpolated to include the `github_read_token` secret if it exists in your Cortex workspace.

## Managing plugin proxies

You can view your plugin proxies in **Plugins** **> Proxies**.

![The 'Proxies' tab shows all available plugin proxies.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/proxies-tab.png?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=52693f06a3fdc020a48ab8b18d4794ca)

### Editing a plugin proxy

Users with the `Edit Plugin Proxies` permission can edit a plugin proxy.

1. From the main sidebar, select **Plugins**.
2. Select the **Proxies** tab.
3. Locate the proxy you want to edit, then click the **Overflow menu**.
4. Select **Edit proxy**.
5. Make your changes, then click **Save proxy**.

### Deleting a plugin proxy

Users with the `Edit Plugin Proxies` permission can delete a plugin proxy.

Cortex does the following when a plugin proxy is deleted: checks if the proxy exists and if it's in use, deletes all headers for the proxy's URLs, flushes the header repo, deletes all URL configurations, removes any secret usages, and finally deletes the proxy entity itself.

1. From the main sidebar, select **Plugins**.
2. Select the **Proxies** tab.
3. Locate the proxy you want to delete, then click the **Overflow menu**.
4. Select **Delete proxy**.

   The **Confirm proxy deletion** window opens.
5. Click **Delete**.


# Plugin Marketplace
Source: https://docs.cortex.io/streamline/plugins/marketplace



The Cortex Plugin Marketplace allows you to discover, view, and install pre-made plugins directly into your Cortex workspace. These plugins are designed to extend platform functionality by integrating with third-party tools or surfacing custom data and dashboards. The Marketplace features Cortex-built plugins, but you can also install community-built plugins.

## Available plugins

### Cortex-built plugins

To access plugins in Cortex, select **Plugins** from the main sidebar. Select the **Marketplace** tab, then click **Details** to learn more about the plugin, including version, last updated date, and documentation.

![The 'Marketplace' tab in the Cortex UI displays all available Cortex-built plugins.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/plugins-marketplace-tab.png?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=b72d8feba237681eec70a12fed1d8e36)

The following plugins are available in the Cortex Plugin Marketplace:

* **PagerDuty Incidents** - View an entity's recent open and resolved PagerDuty incidents, escalation policies, and responders
* **Confluence** - View Confluence assets associated with an entity.
* **ServiceNow Incidents** - Display ServiceNow incidents filed against a given entity.
* **SonarQube Issues** - View and comment on SonarQube issues associated with an entity.
* **CloudForecast** - Show current highlights from CloudForecast reports in your Cortex entities, and link back to the full report in CloudForecast.

### Partner-built plugins

Partner plugins are built and supported by the partners who developed them.

The following plugins are available:

* **Spacelift** - View information from your Spacelift account, including total stacks, healthy stacks, total resources, and total runs. For each individual stack, see its repository, branch, last trigger date, status, runs, success and failure information, and resources. Click a stack to go directly to the stack in Spacelift.
  * For installation instructions, see the [Spacelift Cortex Plugin repository](https://github.com/spacelift-io/cortex-plugin).

## Installing a plugin from the Cortex Plugin Marketplace

Follow the steps below to install a Cortex-built plugin from the Marketplace.

1. From the main sidebar, select **Plugins**.
2. Select the **Marketplace** tab.
3. Locate the plugin you want to install, then click **Install**.

   The **Plugin successfully installed** window opens.
4. Click **Close**.
5. Optionally, click **Details** to view more information about the plugin.\


   ![The 'Details' link on a plugin card.](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/plugins-details-link.png?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=ccbf6c246b1e37b575f5ced43d25f7fe)


# Workflows
Source: https://docs.cortex.io/streamline/workflows

An overview of the Workflows feature

A Workflow is an automated, multi-step process that runs entirely within your Cortex workspace. It lets teams define tasks, trigger actions, collect input, and route approvals in one place, turning complex operations into a single, repeatable experience.

Workflows address the friction that comes from relying on manual checklists, Slack threads, and siloed knowledge to run critical processes. Specifically, they solve for inconsistency across teams, slow or invisible approvals, repeated manual effort on common tasks, and the risk of errors when steps are done ad hoc.

> [!TIP]
>
> Looking for a quick introduction to building and managing Workflows? Check out the Cortex Academy course on [Workflows](https://academy.cortex.io/courses/understanding-workflows).

## How workflows work

Engineering teams use workflows when they need to standardize and automate high-stakes operations like service creation, access provisioning, or incident response, especially when those processes involve multiple tools, people, or approval steps. They're also useful for onboarding, where repeatability and speed matter.

### How is a Workflow structured?

Workflows are made up of steps called blocks. Each block defines part of your workflow's logic and can collect input, trigger external systems, apply conditional logic, or interact with Cortex.

**Note:** If the initiating user doesn't have permission to perform the block's action, the block fails. To manage who can run the workflow, use access controls.

Blocks are organized into three categories:

1. **Core blocks** - Core blocks control the fundamental behavior, logic, and flow of a workflow. They include:
   * Asynchronous HTTP request - Make an asynchronous HTTP request and wait for callback
   * Branch - Create a branch based on conditional logic
   * Data transformation - Run a JQ expression
   * HTTP request -Make an HTTP request
   * JavaScript - Run a JavaScript script
   * Manual approval - Await asynchronous human approval
   * Run workflow - Run another Workflow from within the current one
   * Scaffolder - Run a scaffolder template
   * Set variable(s) - Set or update variable(s)
   * User input - Collect asynchronous input from users
2. **Cortex blocks** - Cortex blocks perform actions against your Cortex catalog or use internal platform data. They run using the permissions of the user who initiated the workflow and include:
   * Create or update an entity
   * Add custom data to an entity
   * List deployments tied to an entity
   * Get Scorecard scores or details
3. **Integration blocks** - Integration blocks connect workflows to external tools such as GitHub, PagerDuty, ServiceNow, and Slack, enabling automation across incidents, repositories, approvals, and more. Common use cases include:
   * Creating a new GitHub repository
   * Opening an incident in ServiceNow
   * Sending a message to a Slack channel
   * Updating a Jira issue
   * Triggering a Jenkins job or pipeline

> [!NOTE]
>
> Cortex supports a growing number of integrations across engineering and operations tools, including AWS, GitHub, Jenkins, PagerDuty, and Slack. For a full list of supported platforms, see [Integrations](/ingesting-data-into-cortex/integrations).

### How does a workflow manage data during a run?

When a workflow runs, Cortex generates a state object with three top-level keys: context, actions, and variables.

**Context** contains metadata about the workflow run. It's created at the start and remains unchanged throughout execution, even if the entity or its secrets change. Useful context fields include:

* `context.entity` - The workflow's entity, including tag, name, and full descriptor from `cortex.yaml`.
* `context.initiatedBy` - The user who triggered the workflow.
* `context.secrets` - Secure secrets referenced by tag. Secrets are automatically redacted in workflow runs and outputs.

You can reference context values using mustache templating, for example:

```
{{context.entity.tag}}
{{context.initiatedBy.email}}
{{context.secrets.slack-api-token}}
```

**Actions** build dynamically as the workflow runs. Each block adds a key named after its slug, storing both inputs and outputs. This allows later steps to reference outputs from earlier ones, e.g. `{{actions.get-users.outputs.result}}`. This value can be used in a JQ expression, a user input block, or an HTTP request payload.

**Variables** contain the current values of any variables declared in the workflow's settings. Unlike context, variables can change during a run, for example when a block sets a new value. You can reference them with templating, for example `{{variables.approved}}`.

To learn more, see [Referencing a Workflow state in a block](/streamline/workflows/blocks/states).

## Identifying processes to turn into Workflows

Standardizing repeatable tasks across your teams ensures consistency and improves quality. Cortex features like [Scorecards](/standardize/scorecards) and [Eng Intelligence](/improve/eng-intelligence) can help you identify good candidates for Workflow automation.

* **Scorecards** - Use Scorecards to see how teams perform against your standards over time, allowing you to identify overburdened teams and other areas for improvement. If a team has a lower score, investigate which processes are causing friction. Can any of their processes become Workflows to automate best practices and improve their efficiency?
* **Eng Intelligence** - Use Eng Intelligence to understand how teams are performing across different industry KPIs. Use this data to drive improvement via Workflows. For example, review metrics for cycle time and deployment frequency to identify where work gets stuck. Can any of these processes become Workflows to free up time and ship faster?

For a list of Workflow use case ideas, see the [Workflow guides](/guides/product-areas/workflows).

## Managing Workflows

Workflows can be managed in the [Cortex UI](/streamline/workflows/create) or via [GitOps](/streamline/workflows/workflows-as-code). You can also use the [API](/api/rest/workflows) to create, read, update, and delete Workflows. The API can also trigger Workflow runs and retrieve their status and history.

> [!NOTE]
>
> When using GitOps to manage Workflows, it's recommended to build out the Workflow in the UI first for an easier start and faster testing. Learn more in [Workflows as code](/streamline/workflows/workflows-as-code).

It's possible to configure specific users, teams, or roles to run a Workflow. See [Configuring Workflow settings](/streamline/workflows/create#step-2-configuring-workflow-settings).

It's also possible to add a "Manual approval" block to a Workflow, requiring approval from specific team members. Read more in the [Blocks documentation](/streamline/workflows/blocks).

## Workflows overview video

[YouTube video player](https://www.youtube.com/embed/AiJYYnOFAqk)


# Adding blocks to a Workflow
Source: https://docs.cortex.io/streamline/workflows/blocks



Blocks (formerly called actions) are the building components of Workflows. Each block handles a specific task, and chaining them together lets you run a sequence of operations that can reference contextual data from your workspace.

Cortex offers a searchable library of blocks that can be added to your Workflows. See [How is a Workflow structured](/streamline/workflows#how-is-a-workflow-structured) for more information. To configure blocks through the API or in Workflow YAML, see the [Workflow block configuration reference](/streamline/workflows/blocks/block-configuration-reference) for each block's fields and an example.

Blocks are organized into the following categories:

* **Core blocks** - Perform actions such as requiring a manual approval on a step within a Workflow.
* **Cortex blocks** - Perform Cortex-based actions, such as getting Scorecard scores for an entity.
* **Integration blocks** - Perform third-party integration actions such as creating a new GitHub repository or creating a new incident in ServiceNow.

## Prerequisites

1. You must have the `Edit Workflows` permission.
2. An existing Workflow. If you haven't yet created a Workflow, refer to [Creating a Workflow](/streamline/workflows/create) and [Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings).

> [!NOTE]
>
> Every block in a Workflow must have a unique slug.

## Configuring a Workflow block (basic)

1. Click the **+ icon**. The **Search for blocks** window opens.
2. Search for and select the block you want to add to the Workflow.
3. In the right pane, configure the block. Note that configuration options differ depending on the block.
4. Click **Save**.
5. Repeat Steps 1 - 4 as necessary.

## Configuring a core block

Expand the tiles below for instructions on configuring each type of block.

> **Branch**
>
> A **Branch** allows you to set up to five conditional paths for a Workflow.
>
> > [!TIP]
> >
> > See an example demonstrating how to use a Branch block in [Referencing Workflow states in a block](/streamline/workflows/blocks/states#block-and-workflow-state-reference-example).
>
> **Configuring a branch**
>
> 1. In the **Search for blocks** window, search for **Branch**, then click **Insert**.
>
> 2. In the side panel, do the following:
>    1. **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
>    2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
>    3. Click **Add path**.
>       1. **Name** - Enter a name for the conditional path.
>       2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
>       3. **Path expression** - Enter the path expression (compatible with [CEL syntax](https://cel.dev/)). The path expression does not accept dashed values; if you reference a block's slug that contains a dash, wrap the slug in quotes and square brackets.
>          1. For example, if you want to reference a block with the slug `slug-example`, the expression would begin with `actions["slug-example"]`.
>          2. Autocomplete provides correctly formatted options based on the blocks defined in your Workflow.
>       4. Click **Save**.
>    4. Click **Add fallback path**.
>       1. **Name** - Enter a name for the fallback path.
>       2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
>       3. Click **Save**.
>
> 3. Optionally, add additional paths (up to 5).
>
> 4. Click **Save**.
>
> > [!NOTE]
> >
> > To add additional blocks that occur after the paths within your branch, click **+** below the **Branch** box in the Workflow editor.
>
> **How paths work**
>
> The paths defined run sequentially. The first path that returns `true` will execute, even if subsequent paths would also return `true`. The Workflow will then continue performing blocks in that path. You can also set a fallback path that will run if all other paths fail.
>
> Primary and nested branches function the same way.
>
> **Nested branches**
>
> To nest a branch, you must have a conditional path defined.
>
> 1. In the Workflow visual, click the **+** that is branched off the original branch. The **Search for blocks** window opens.\\
>
>    ![](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflow-nested-branch.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=927494f0a94fcbf9b4e6c9370cadbd5f)
> 2. Search for **Branch**, then click **Insert**.
> 3. Follow steps 2 - 4 above in **Configuring a branch**.
>
> There are no limits on how many branches you can nest.

> **Data transformation**
>
> A **Data transformation** performs data transformations using jq. Except for the block name and slug, the only field required is the **jq expression**.
>
> > [!TIP]
> >
> > **Use cases**: Manipulate or format data between steps. For example, transform user input before sending it to an API or before using it in another Workflow block.
> >
> > **Workflow examples**: See an example demonstrating how to use a Data transformation block in [Referencing Workflow states in a block](/streamline/workflows/blocks/states#block-and-workflow-state-reference-example).
>
> **Configure a data transformation**
>
> To configure a data transformation:
>
> 1. Click **Data transformation** from the list of blocks.
> 2. Enter a name.
>    * The slug field will automatically pre-populate based on the name you enter.
> 3. Enter a [jq](https://jqlang.github.io/jq/) expression. This field can pass any sort of jq expression, as long as the variables and context are referenced differently.
>    * Although you would typically use `{}` to template the context of your Workflow, in this field you’ll need to reference such values as jq query values.
> 4. Click **Save**.

> **HTTP request**
>
> The HTTP request makes and records a request to a given URL, allowing you to integrate with external APIs or internal systems.
>
> For use cases requiring asynchronous operations (e.g. provisioning cloud resources or CI/CD pipelines), use the [Asynchronous HTTP request block](/streamline/workflows/blocks#http-action-async).
>
> > [!TIP]
> >
> > See an example demonstrating how to use an HTTP block in [Scaffolding a new service with custom data based on user input](/guides/production-readiness/standardize-new-service-creation).
>
> **Configuring an HTTP request**
>
> 1. Search for and select the **HTTP request** block.
>
> 2. In the side panel, configure the block metadata:
>    1. **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
>    2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
>    3. **Integration** - Select a configured integration from the dropdown to authenticate the request instead of manually building headers. See [Authenticating HTTP requests with an integration](#authenticating-http-requests-with-an-integration) for the list of supported integrations.
>       * The picker only lists integrations already configured for your tenant.
>       * An admin must turn on the integration for HTTP blocks before the block can run. If the integration is turned off, or the block uses an HTTP method or endpoint that an admin hasn't allowed, the block shows a warning banner. You can still save the Workflow, but the block fails when it runs. See [Controlling which integrations HTTP blocks can use](#controlling-which-integrations-http-blocks-can-use).
>       * If the integration has more than one configuration, an alias picker appears so you can choose which one to use.
>       * If a previously selected integration is no longer configured, Cortex keeps the existing value so the block stays editable, and shows a warning that the integration is missing.
>       * To go back to manually configuring the full URL and headers, clear the **Integration** field. This also resets the alias picker.
>    4. **HTTP method** - Select one of the following options from the dropdown: `DELETE`, `GET`, `PATCH`, `POST`, or `PUT` (required).
>    5. **URL** - Enter a static URL or use a template to reference other blocks (required). If you selected an integration above, enter the URL as a relative path. Cortex automatically prepends the integration's base URL to your request.
>       * When you use an integration, the path can't leave the integration's base URL. Cortex rejects paths that contain `.` or `..` segments, `//`, backslashes, or their URL-encoded forms (such as `%2e`, `%2F`, `%5C`, or `%25`).
>       * If you use `{{actions.url.outputs.result}}`, for example, you can set the URL to the output of a JQ action. In this example:
>         * `.actions` indicates a reference to a Workflow block
>         * `.url` is the slug for the referenced Workflow block
>         * `.outputs` is the location of the actual output of the JQ expression
>         * `.result` is the result field where the output is stored
>       * Because [Mustache](https://en.wikipedia.org/wiki/Mustache_\(template_system\)) performs HTML escaping by default, special characters referenced in a value with two curly braces (`{{}}`) will be converted to their associated HTML encoding. For example, `{{=}}` becomes `=`. To reference a non-escaped value, use three curly braces (`{{{=}}}`).
>    6. **Headers** - Click **Add header** to select one of the options provided, or enter your own.
>       * Include an Authorization header and use a [personal access token](/configure/settings/api-keys/personal-tokens), unless you're authenticating with a configured integration.
>       * When using a secret with a header, prefix the secret with `context.` .
>    7. **Payload** - This field only appears if you are using an HTTP request that sends a payload. The payload that you supply can also be templated and can reference an entity that the Workflow is being run with. Some additional steps are required to properly template raw JSON in the payload field:
>       * Single primitive values work as expected. To add JSON objects or arrays, create a [Data transformation block](/streamline/workflows/blocks#data-transformation) that accesses the relevant JSON and pipes it into the `tojson` built-in.
>         * For example, `.context.initiatedBy | tojson` enables a user to add the full `initiatedBy` object `()` into an HTTP request payload. When templating this value, three curly braces are needed in order to reference a non-escaped value. In this example, if the Data transformation block has the slug `transform-to-json`, then the payload would include `{{{actions.transform-to-json.outputs.result}}}`.
>
> 3. Click **Save**.
>
> > [!WARNING]
> >
> > If using special characters when templating, make sure to include three curly braces to reference a non-HTML-escaped value.

> **HTTP action (async)**
>
> The Asynchronous HTTP request makes and records a request to a given URL. This block pauses execution until a [callback API](/api/rest/workflows/update-asynchronous-http-request-workflow-block) is invoked or a timeout occurs, enabling long-running Workflows.
>
> > [!NOTE]
> >
> > You can pass the callback URL to the external service by using the template variable `{{callbackUrl}}`. This can be passed as part of the URL, in a header, or in the payload.
> >
> > For example, when passing the variable in a URL, it would look like the following format: `https://example.com/?url={{callbackUrl}}`.
> >
> > Always use exactly two curly braces for `{{callbackUrl}}`. Cortex replaces this exact text when the block runs, so `{{{callbackUrl}}}` produces a broken URL.
>
> **Configuring an Asynchronous HTTP request**
>
> 1. Search for and select the **Asynchronous HTTP request** block.
>
> 2. In the side panel, configure the block metadata:
>    1. **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
>    2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
>    3. **Integration** - Select a configured integration from the dropdown to authenticate the request instead of manually building headers. See [Authenticating HTTP requests with an integration](#authenticating-http-requests-with-an-integration) for the list of supported integrations.
>       * The picker only lists integrations already configured for your tenant.
>       * An admin must turn on the integration for HTTP blocks before the block can run. If the integration is turned off, or the block uses an HTTP method or endpoint that an admin hasn't allowed, the block shows a warning banner. You can still save the Workflow, but the block fails when it runs. See [Controlling which integrations HTTP blocks can use](#controlling-which-integrations-http-blocks-can-use).
>       * If the integration has more than one configuration, an alias picker appears so you can choose which one to use.
>       * If a previously selected integration is no longer configured, Cortex keeps the existing value so the block stays editable, and shows a warning that the integration is missing.
>       * To go back to manually configuring the full URL and headers, clear the **Integration** field. This also resets the alias picker.
>    4. **HTTP method** - Select one of the following options from the dropdown: `DELETE`, `GET`, `PATCH`, `POST`, or `PUT` (required).
>    5. **URL** - Enter a static URL or use a template to reference other blocks (required). If you selected an integration above, enter the URL as a relative path. Cortex automatically prepends the integration's base URL to your request.
>       * When you use an integration, the path can't leave the integration's base URL. Cortex rejects paths that contain `.` or `..` segments, `//`, backslashes, or their URL-encoded forms (such as `%2e`, `%2F`, `%5C`, or `%25`).
>       * If you use `{{actions.url.outputs.result}}`, for example, you can set the URL to the output of a JQ action. In this example:
>         * `.actions` indicates a reference to a Workflow block
>         * `.url` is the slug for the referenced Workflow block
>         * `.outputs` is the location of the actual output of the JQ expression
>         * `.result` is the result field where the output is stored
>       * Because [Mustache](https://en.wikipedia.org/wiki/Mustache_\(template_system\)) performs HTML escaping by default, special characters referenced in a value with two curly braces (`{{}}`) will be converted to their associated HTML encoding. For example, `{{=}}` becomes `=`. To reference a non-escaped value, use three curly braces (`{{{=}}}`).
>    6. **Headers** - Click **Add header** to select one of the options provided, or enter your own.
>       * Include an Authorization header and use a [personal access token](/configure/settings/api-keys/personal-tokens), unless you're authenticating with a configured integration.
>       * When using a secret with a header, prefix the secret with `context.` .
>    7. **Payload** - This field only appears if you are using an HTTP request that sends a payload. The payload that you supply can also be templated and can reference an entity that the Workflow is being run with. Some additional steps are required to properly template raw JSON in the payload field:
>       * Single primitive values work as expected. To add JSON objects or arrays, create a [Data transformation block](/streamline/workflows/blocks#data-transformation) that accesses the relevant JSON and pipes it into the `tojson` built-in.
>         * For example, `.context.initiatedBy | tojson` enables a user to add the full `initiatedBy` object `()` into an HTTP request payload. When templating this value, three curly braces are needed in order to reference a non-escaped value. In this example, if the Data transformation block has the slug `transform-to-json`, then the payload would include `{{{actions.transform-to-json.outputs.result}}}`.
>    8. **Timeout** - Configure a timeout for this action. The maximum is 30 days and the minimum is 1 minute.
>       * After a timeout, the block fails with the status `timed_out`. If you have [notifications](/configure/settings/notifications) enabled, you'll receive a notification if you initiate a Workflow and it times out.
>
> 3. Click **Save**.
>
> > [!WARNING]
> >
> > If using special characters when templating, make sure to include three curly braces to reference a non-HTML-escaped value. The exception is `{{callbackUrl}}`, which must always use two curly braces.
>
> **Handling the callback**
>
> Once the Asynchronous HTTP request block runs, Cortex sends the configured request and pauses the Workflow. To resume execution, the external system must call the callback URL provided by Cortex and follow the required schema.
>
> The callback request must:
>
> * Use the `POST` method
> * Include a valid Cortex API key in the `Authorization` header (`Bearer <token>`)
> * Match the expected request body shape. Below is an example:
>
> ```
> {
>   "message": "Provisioning complete – sandbox environment created.",
>   "response": {
>     "env_id": "sandbox-abc123"
>   },
>   "status": "SUCCESS"
> }
> ```
>
> Set `status` to one of the following values:
>
> * `SUCCESS` - The external work finished. The block completes and the Workflow continues.
> * `FAILURE` - The external work failed. The block fails.
> * `UPDATE` - The external work is still in progress. The block keeps waiting for another callback, and Cortex records the `message` and `response` as progress.
>
> See the full [Cortex API reference](/api/rest/workflows/update-asynchronous-http-request-workflow-block) for callback details.
>
> > [!WARNING]
> >
> > If the callback is missing required fields, improperly formatted, or lacks authentication, Cortex will not accept it, and the Workflow will remain paused or fail.

> **JavaScript**
>
> Use a JavaScript block to insert custom code or add looping and other logic to your Workflows.
>
> The JavaScript runtime supports the [ES2020](https://tc39.es/ecma262/) specification and has an implementation of [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch), allowing you to make HTTP requests directly in the script rather than needing to add an additional HTTP request block to your Workflow.
>
> > [!TIP]
> >
> > See an example demonstrating how to use a JavaScript block: [Looping in a JavaScript block and returning a specified output](/guides/operational-readiness/javascript-looping)
>
> To test your block's code locally, you can use [Cortex's JavaScript harness](https://github.com/cortexapps/js-action-harness).
>
> **Configuring a JavaScript block**
>
> 1. In the **Search for blocks** window, search for **JavaScript**, then click **Insert**.
> 2. In the side panel, do the following:
>    1. **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
>    2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
>    3. **JavaScript** - Enter the script you want to run. The script must end with a `return` statement. The value from the `return` statement is exposed via `outputs.result`.
>       * For example, in the script `return {"a": 1, "b": 2}`, the result can be referenced from subsequent blocks as `actions.<SLUG>.outputs.result`, and the value of `a` as `actions.<SLUG>.outputs.result.a`.
>       * You can reference previous blocks and run context by accessing `actions` and `context`. For example, `actions["jq"].outputs.result.`
>       * Learn more about [referencing blocks and Workflow states here](/streamline/workflows/blocks/states).
> 3. Click **Save**.
>
> If you want the block to fail, you can use the `throw` statement. For example:
>
> ```
> let previous = actions.previous.outputs.result;
> if (previous == null) {
>   throw "Some error";
> }
> ```

> **Manual approval**
>
> A **manual approval** pauses the Workflow to get approval from a member of a given Team. Like with user inputs, the Workflow proceeds to the next block once it has been approved.
>
> **Configuring a manual approval**
>
> 1. In the **Search for blocks** window, search for **Manual approval**, then click **Insert**.
> 2. In the side panel, do the following:
>    1. **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
>    2. **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.
>    3. From the **Teams allowed to approve** dropdown, select one or more teams who are allowed to approve the request from this block. Any member of a given team can approve the block.
>       * To resolve the approving team dynamically instead of picking a fixed team, click the icon next to the field (**Use value from previous step**). The field switches to a text box where you can enter the path to a value from earlier in the Workflow. Start typing to see available paths, then select one, for example `actions.user-input.outputs.team-name`. Cortex resolves this path each time the Workflow runs, so the block can route approval to a different team depending on the inputs or entity involved in that run.\\
>
>         ![](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflows-dynamic-icon.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=73123be3fc9cf604e847772b09f4a285)
>       * Enter the path on its own, without template syntax. Use `actions.action-slug.outputs.field-name`, not `{{actions.action-slug.outputs.field-name}}`.
>       * Click the icon again to switch back to selecting a fixed team.
>    4. **Context for approvers** - Optionally, enter a message to be displayed to approvers to help them make a decision. This message supports Mustache templating.
>    5. **Timeout** - Optionally, enter the callback timeout. This value can be from one (1) minute to 30 days. The default value is 30 days.
> 3. Click **Save**.
>
> **Pending approval**
>
> When a manual approval block is triggered, users that belong to teams designated as approvers will see **Pending approvals** at the top of their Workflows page.
>
> ![](https://mintcdn.com/cortex-290c0c42/wjT-J8PNs9MwpcFs/images/pending-approvals.jpg?fit=max\&auto=format\&n=wjT-J8PNs9MwpcFs\&q=85\&s=6016530bc8c36be36804205e2131c832)
>
> This section displays any blocks that are pending your approval. If manual approval actions exist within a Workflow, but do not require your approval, they will not appear here, even if you are designated to approve a different block in the same Workflow.
>
> You can open any Workflow in the pending approval list to **Approve** or **Reject** the block.
>
> Once all of your approval requests have been approved or rejected, this tab will disappear from the Workflows page.

> **Run Workflow**
>
> The **Run workflow** block calls another Workflow from inside the current one, letting you chain Workflows together. You can pass values into the child Workflow's variables, and you can have the block wait for the child Workflow to finish so later blocks can use its result.
>
> > [!NOTE]
> >
> > The embedded Workflow and the parent Workflow have a strict parent‑child relationship to prevent accidental Workflow looping.
>
> **To configure a Run Workflow block**:
>
> 1. In the **Search for blocks** window, search for **Run workflow** from the list of blocks.
> 2. Under **Block name**, enter a name. The slug field auto‑populates based on the name.
> 3. From the **Workflow** drop‑down menu, select the Workflow to run.
> 4. Optionally, from the **Entity** drop‑down menu, select an entity to run the target Workflow against. If the target Workflow is entity‑scoped and no entity is provided, it pauses for input at runtime.
> 5. Optionally, toggle on **Wait for completion** to pause this block until the child Workflow run finishes. See ***Waiting for the child Workflow*** below.
>    * When the toggle is on, you can set a **Timeout** from 1 minute to 30 days. When the timeout expires, the child Workflow run is cancelled. Without a timeout, the block waits until the child run finishes.
> 6. Under **Inputs**, optionally enter a value for each of the child Workflow's variables. See ***Passing inputs to the child Workflow*** below.
> 7. Click **Save**.
>
> **Passing inputs to the child Workflow**
>
> The **Inputs** section lists one field for each variable declared in the child Workflow's [settings](/streamline/workflows/configuring-workflow-settings). It only appears when the selected Workflow has variables.
>
> * Enter a fixed value, or a template that references earlier blocks or the run context, such as `{{actions.form.outputs.appId}}`.
>
> * The child Workflow reads each value as `{{variables.<variable-slug>}}`, the same way it reads a variable set through `initialContext` when the Workflow is run via the API.
>
> * Values keep the variable's type. For example, `5` entered for a Number variable is passed as a number, and `123` entered for a String variable stays text.
>
> * Leave a field empty to use the variable's default value.
>
> * If you select a different Workflow, the inputs are cleared.
>
> > [!WARNING]
> >
> > Cortex checks inputs when you save the block. An input the child Workflow doesn't declare, or a value of the wrong type, prevents the save. If the child Workflow's variables change later, the parent Workflow can't run until the inputs match again. Inputs the child no longer declares appear as read-only fields. Click the **Remove** icon next to each one, then save the block.
>
> **Waiting for the child Workflow**
>
> By default, the block starts the child Workflow and the parent Workflow continues right away. The block's only output is the child's run ID, `actions.<block-slug>.outputs.runId`.
>
> When **Wait for completion** is on, the parent Workflow pauses at this block until the child run ends. While it waits, the parent's run details show the child Workflow run. When the child finishes, later blocks can reference the following outputs:
>
> * `actions.<block-slug>.outputs.runId` - The child Workflow's run ID.
> * `actions.<block-slug>.outputs.status` - The final status of the child Workflow run.
> * `actions.<block-slug>.outputs.runResponse` - The child Workflow's run response.
> * `actions.<block-slug>.outputs.variables` - The child Workflow's variables when the run ended, keyed by the child's variable slugs. For example, `actions.<block-slug>.outputs.variables.approved`.
>
> Autocomplete in later blocks suggests these paths using the child Workflow's own variable names.
>
> Keep in mind:
>
> * If the child run fails, times out, or is cancelled, the Run Workflow block fails.
>
> * If the parent run ends before the child finishes (for example, it's cancelled or rejected, or another block fails or times out), Cortex cancels the child run. This keeps approvals in the child Workflow from staying open.
>
> > [!TIP]
> >
> > **Use case**: Reuse one shared approval Workflow across many parent Workflows. Each parent passes its own details into the child's variables, waits for the child to finish, then uses `actions.<block-slug>.outputs.variables` in a **Branch** block to decide what happens next.

> **Scaffolder**
>
> The **Scaffolder** uses a Cortex Scaffolder template to perform a given function. You must have the `Execute Scaffolder` permission to configure a Scaffolder block.
>
> See the docs to learn about [registering a Scaffolder template](/streamline/workflows/scaffolder).
>
> > [!TIP]
> >
> > **Use cases**: Standardize and bootstrap service creation
> >
> > **Workflow example**: See an example demonstrating how to use a Scaffolder block in [Scaffolding a new service with custom data based on user input](/guides/production-readiness/standardize-new-service-creation).
>
> To configure a Scaffolder:
>
> 1. Click **Scaffolder** from the list of blocks.
>
> 2. Enter a name.
>    * The slug field will automatically pre-populate based on the name you enter.
>
> 3. Under **Scaffolder template**, select a template from the dropdown.
>    * This dropdown pulls in all templates available from the Scaffolder page.
>
> 4. Configure the remaining fields. The fields differ depending on the template's specifications and available Git providers. The option to create a repo also may or may not be visible, depending on whether the template requires a pull request.
>
> 5. Click **Save**.
>
> > [!WARNING]
> >
> > If using the Scaffolder to create a new repo and the desired repo already exists, Cortex will surface an error and prevent the flow from continuing.
>
> **Define Scaffolder template overrides**
>
> You can also define **Scaffolder template overrides** for a block — these will override template fields with output variables from a previous Workflow step, or from the context of the Workflow.
>
> To add an override:
>
> 1. In the bottom of the block configuration, click **Add variable**.
> 2. In the override variable modal, click the **Variable** dropdown to select the Scaffolder template fields to override. Note that the options in this dropdown will be pulled from fields in the Scaffolder template you selected in the first step.
>
>    ![workflows 12](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scaffolder-variable.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=e08b93d90e9e84e4f1134a724a38c9e0)
> 3. Under **Path**, enter the path to the actual value we want in the Workflow.
>    * For example, if you wanted to override the **Project name** variable for a Scaffolder with the tag of the entity you’re running, the path would be `context.entity.tag` — that will obtain and supply the value.
> 4. If you want to override the options that are available to a user running the Workflow, toggle on **Is value override**.
>    * For example, if you wanted to restrict the project name to some set of values based on a particular HTTP fetch, you would toggle this setting on.
>    * When toggled **on**, the value being grabbed in lieu of `project_name` is the value of the variable. When toggled **off**, the value grabbed would be the option provided for that variable, i.e. the project name.
>
> **Running a workflow with a Scaffolder step**
>
> When you run a workflow with a Scaffolder block, the Scaffolder will prompt you for user input. Some fields, such as **Commit message** and **Pull request title**, only appear if your Scaffolder step creates a Pull Request rather than a repository.
>
> After the inputs are provided, the Scaffolder will run. When the run is complete, you will see a link to the newly-created repository and the entity in Cortex.
>
> > [!WARNING]
> >
> > **Note:** For GitLab, Azure DevOps, and Bitbucket, the branch name entered when running this block must match the default branch of the target repository in your Git provider.

> **User input**
>
> The **User input** block pauses the Workflow and prompts the user for specific inputs. Once inputs are entered, the Workflow proceeds to the next block.
>
> > [!TIP]
> >
> > **Use cases**: Collect new developer details (name, email, GitHub username) during onboarding, or gather IAM policy requirements before creating a policy in AWS.
> >
> > **Workflow example**: Onboard a new developer > Collect user information in User input block > Subsequent actions use this data to create accounts and send notifications.
> >
> > See examples demonstrating how to use a User Input block in [Looping in a JavaScript block and returning specified output](/guides/operational-readiness/javascript-looping) and [Scaffolding a new service with custom data based on user input](/guides/production-readiness/standardize-new-service-creation).
>
> > [!WARNING]
> >
> > Note that users with the `Edit Workflows` permission are inherently able to obtain secret values using complex data transformation on secrets or echoing services.
>
> **To configure a user input block**:
>
> 1. In the Workflow, click the **User input** block.
> 2. In the **User input** side panel, do the following:
>    1. Under **Block name**, enter a name for the block.
>    2. The **Slug** field automatically pre-populates based on the block name.
>    3. Click **Add user input**.\\
>
>       ![](https://mintcdn.com/cortex-290c0c42/pbVnLtaKpBTlBN5p/images/add-user-input.png?fit=max\&auto=format\&n=pbVnLtaKpBTlBN5p\&q=85\&s=c7d8237f898b2701a8f9e109ab63097c)
> 3. In the **Add input** side panel, do the following:
>    * Under **Name**, enter a name for the input field (required).
>    * The **Key** field automatically pre-populates based on the name (required). This must be unique across fields in a given user input block.
>    * Under **Description**, enter a description of the input field.
>      * You can use templating to reference previous block outputs in the description. For example, if a previous step creates a Pull Request and outputs the URL of the PR, you might want to reference it in the description of a subsequent user input step using a template: `Confirm that you have merged the Pull Request created here: {{ actions.<block-slug>.outputs.response.gitURL }}`
>    * From the **Type** drop-down menu, select an input type:
>      * **Date** - Date in `YYYY-MM-DD` format. If you select this option, configure the fields that appear:
>        * **Date format** - Select **Date** or **Date and time**
>        * **Default value** - Enter the default date value
>      * **Number** - A numerical value. If you select this option, configure the fields that appear:
>        * **Number format** - Select **Integer** or **Decimal**
>        * **Minimum value** - Set the minimum number value
>        * **Maximum value** - Set the maximum number value
>      * **Paragraph** - Multi-line, freeform text
>      * **Secret** - Capture a secret value
>      * **Select** - Manually configured or predefined data selection. If you select this option, configure the fields that appear:
>        * **Data source** - Select one of the following:
>          * **Cortex entity** - Filter which entities users can select. If you don't set filters, all entities are available. You can set filters under the **Filtering options** section. Optionally, toggle on the following:
>            * **Allow multiple** - If enabled, multiple selections are accepted.
>            * **Limit to workflow runner's entities** - If enabled, the user running the Workflow will only see their owned entities as options during this user input step.
>              * To only show teams the user belongs to, enable this toggle *and* select `team` from the **Entity type** drop-down menu.
>          * **Cortex user** - Filter by teams and users to set the available options. Without filters, all Cortex users and teams are available. You can set filters under the **Filtering options** section. Optionally, toggle on the following:
>            * **Allow multiple** - If enabled, multiple selections are accepted.
>          * **Manual** - Manually define each option for the input. You can select any of these defined options as the default value. Optionally, toggle on **Allow multiple** to allow multiple selections.
>            * Click **Add option** to add values and labels. If a label is not defined, the value is used as the label.
>          * **Slack channels** - Choose to include or exclude one or more Slack channels from the available options. The default values include all Slack channels registered in Cortex. Optionally, toggle on **Allow multiple** to allow multiple selections.
>            * Select the channels you want to include from the **Slack channels** drop-down menu.
>      * **Text** - Short, freeform text
>      * **Toggle** - Boolean value
>      * **Nested form** - Users can enter data multiple times for the inputs you configure. If you select this option, configure the fields that appear. See ***Additional steps for the 'Nested form'  type*** below for more information.
>        * **Data type** - Select one of the following:
>          * **Object** (default) - Each item is a structured record made up of the sub-fields you define below. Use this when every entry needs more than one property, such as a list of database instances that each have a name and a size.
>          * **Single value** - Each item is a single value of one type. Use this to collect a simple list, such as admin emails, allowed IP addresses, or port numbers. When you select **Single value**, configure the **Value type** that appears:
>            * **Text** - A single line of text
>            * **Paragraph** - Multi-line, freeform text
>            * **Number** - A numeric value. Choose **Integer** (whole numbers) or **Decimal** (allows decimals), and optionally set a minimum and maximum value.
>            * **Toggle** - A true or false value
>            * **Date** - A date in YYYY-MM-DD format
>        * **Set the number of elements** - Toggle on to to let the user add or remove entries when running the Workflow. Set a minimum and maximum count; the minimum also serves as the default number of elements.
> 4. Depending on the input type you selected in the previous step, you may need to configure the following:
>    1. Under **Placeholder**, enter text to display when a field is empty.
>    2. Under **Default value**, enter a value that automatically populates the field.
>    3. Under **Validation regex**, set validation options for the input field. If you chose the **secret type**, enter the secret value needed to run this action.
>    4. Under **Path to override value**, enter the previous block output path to override the value of a given input.
>       * For example, if the key is `name`, entering `actions.name-action.outputs.name` in the previous block output path field will use the output from a previous step as the name.
>    5. Optionally, toggle on **Is override value editable**. If enabled, users can edit the override value before continuing to execute the Workflow.
> 5. Click **Add input**. After clicking **Add input**, you're directed back to the **User input** side panel.
> 6. Optionally, toggle on **Validation logic**. See ***Adding validation logic*** below for more information.
> 7. Click **Save**.
>
> **Additional steps for the 'Nested form' type**
>
> A nested form lets users provide an arbitrary number of responses. Each response can either be a sub‑form with multiple fields (one or more inputs per row) or a single value (one string per row), depending on the Data type you choose. For example, a data warehouse form might collect a name and size for each database instance (`Object`), while an allow‑list form might collect a flat list of email addresses (`String`).
>
> Cortex supports up to 5 layers of nesting in `Object` nested forms using the `Nested form` input. `String` nested forms cannot be nested further, as each row is a leaf string.
>
> 'Nested form' type output:
>
> * When the data type is **Single value**, the block output is a flat JSON array of the chosen type, referenced as `actions.<slug>.outputs.<key>` . For example, `["jenny", "luis"]` for Text or `[8080, 8443]` for an Integer.
> * When the data type is **Object**, the output is an array of objects, for example `[{ "name": "db-1", "size": 100 }, { "name": "db-2", "size": 200 }]`.
>
> **Adding validation logic**
>
> Define custom JavaScript validations on Workflow input fields to ensure users complete required fields and meet your standards. For example, you might validate that a new repository follows your naming conventions, or that the chosen name is unique.
>
> **To add validation**:
>
> 1. In the **User input** side panel, toggle on **Validation logic**.
> 2. Enter a JavaScript expression.
>    * Call `validator.addInputViolation` to display an error on a specific input, and `validator.addGlobalViolation` to display an error at the top of the form.
>      * If you call `validator.addInputViolation` with an invalid input key, an error displays at the top of the form.
>
> **Example JavaScript expression**
>
> This expression requires the role value to be at least three characters and the selected date to be in the future. It displays input-specific errors for the u`ser role` and t`arget date` inputs, and a global error if any field is invalid:
>
> ```javascript theme={null}
> let currentOutputs = actions['user-input'].outputs;
> let isAnyFieldInvalid = false;
>
> if(currentOutputs['user-role'].length < 3) {
>     validator.addInputViolation('user-role', "Role must have at least 3 characters")
>     isAnyFieldInvalid = true;
> }
>
> let selectedDate = Date.parse(currentOutputs['target-date'])
> let currentDate = Date.now()
> if(selectedDate < currentDate) {
>     validator.addInputViolation('target-date', "Selected date must be in the future")
>     isAnyFieldInvalid = true;
> }
>
> if(isAnyFieldInvalid) {
>     validator.addGlobalViolation("Not all fields are valid, please fix before continuing");
> }
> ```
>
> The validation logic runs when you submit your response to the user input, flagging any issues immediately. With the example above, errors appear if the `user role` value is under three characters or the `target date` is not in the future.
>
> ![](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/validation-input.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=618db8db04c62e5b70fa1e713f54a77a)

> **Set variable(s)**
>
> This block allows you to set or update specific variables during a Workflow. The variables must be declared in the [Workflow's basic settings](/streamline/workflows/configuring-workflow-settings).
>
> To configure a Set variable(s) block:
>
> 1. Click **Set variable(s)** from the list of blocks.
> 2. Enter a slug for the block.
>    * The slug field will automatically pre-populate based on the name you enter.
> 3. In the **Variable** dropdown, select the variable you want to set/update.
> 4. Define how you want to set the variable's value. You can use a direct reference or use JavaScript.
> 5. Optionally, set additional variables.
> 6. Click **Save**.

## Authenticating HTTP requests with an integration

In the [HTTP request](#http-request) and [Asynchronous HTTP request](#http-action-async) blocks, you can authenticate a request with an integration that's already configured in your Cortex workspace. You don't need to build an Authorization header yourself. Cortex uses the integration's credentials and prepends its base URL to the relative path you enter in the **URL** field.

The **Integration** dropdown only shows integrations that are configured in your workspace. Before a block can run with an integration, an admin must also turn that integration on for HTTP blocks. See [Controlling which integrations HTTP blocks can use](#controlling-which-integrations-http-blocks-can-use).

You can authenticate HTTP requests with the following integrations:

> **Expand to see a list of supported integrations**
>
> * [Apiiro](/ingesting-data-into-cortex/integrations/apiiro)
> * [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops)
> * [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr)
> * [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket)
> * [BugSnag](/ingesting-data-into-cortex/integrations/bugsnag)
> * [Buildkite](/ingesting-data-into-cortex/integrations/buildkite)
> * [CircleCI](/ingesting-data-into-cortex/integrations/circleci)
> * [ClickUp](/ingesting-data-into-cortex/integrations/clickup)
> * [Codecov](/ingesting-data-into-cortex/integrations/codecov)
> * [Coralogix](/ingesting-data-into-cortex/integrations/coralogix)
> * [Cortex](/api)
> * [FireHydrant](/ingesting-data-into-cortex/integrations/firehydrant)
> * [GitHub](/ingesting-data-into-cortex/integrations/github)
> * [GitLab](/ingesting-data-into-cortex/integrations/gitlab)
> * [Google Cloud](/ingesting-data-into-cortex/integrations/google)
> * [Harness](/ingesting-data-into-cortex/integrations/harness)
> * [Instana](/ingesting-data-into-cortex/integrations/instana)
> * [Jenkins](/ingesting-data-into-cortex/integrations/jenkins)
> * [Jira](/ingesting-data-into-cortex/integrations/jira)
> * [LaunchDarkly](/ingesting-data-into-cortex/integrations/launchdarkly)
> * [Mend](/ingesting-data-into-cortex/integrations/mend)
> * [New Relic](/ingesting-data-into-cortex/integrations/newrelic)
> * [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie)
> * [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty)
> * [Prometheus](/ingesting-data-into-cortex/integrations/prometheus)
> * [Rollbar](/ingesting-data-into-cortex/integrations/rollbar)
> * [Rootly](/ingesting-data-into-cortex/integrations/rootly)
> * [Semgrep](/ingesting-data-into-cortex/integrations/semgrep)
> * [Sentry](/ingesting-data-into-cortex/integrations/sentry)
> * [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow)
> * [ServiceNow Cloud Observability (Lightstep)](/ingesting-data-into-cortex/integrations/lightstep)
> * [Slack](/ingesting-data-into-cortex/integrations/slack)
> * [Snyk](/ingesting-data-into-cortex/integrations/snyk)
> * [SonarQube](/ingesting-data-into-cortex/integrations/sonarqube)
> * [Splunk Observability Cloud (SignalFx)](/ingesting-data-into-cortex/integrations/splunk-observability)
> * [Splunk On-Call (VictorOps)](/ingesting-data-into-cortex/integrations/splunk-oncall)
> * [Sumo Logic](/ingesting-data-into-cortex/integrations/sumologic)
> * [xMatters](/ingesting-data-into-cortex/integrations/xmatters)

> [!NOTE]
>
> The block authenticates with the integration's API token, so it has the same permissions as that token. Check the token's scopes before you let Workflow editors call an integration's API. To limit what HTTP blocks can do with an integration, see [Controlling which integrations HTTP blocks can use](#controlling-which-integrations-http-blocks-can-use).

### Controlling which integrations HTTP blocks can use

Admins control which integrations HTTP blocks can authenticate with, which actions they can take, and which API endpoints they can't call. Cortex checks these settings each time an HTTP request or Asynchronous HTTP request block runs, before it fetches the integration's credentials or sends the request.

**Prerequisites**

* You must have the `Edit Settings` permission.
* The integration must be configured in your Cortex workspace.

**Default settings**

* An integration that hasn't been turned on is off, so new integrations start off.
* Workspaces created before these settings were added have the following integrations turned on: Azure DevOps, Bitbucket, Cortex, GitHub, GitLab, Google Cloud, Harness, Jenkins, LaunchDarkly, PagerDuty, ServiceNow, and Slack. Turn on any other integration before you use it in an HTTP block.
* When an integration is turned on, all actions are allowed and no endpoints are blocked.

#### Turning integrations on or off

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, expand **Workflows**, then select **HTTP block**.

   ![The 'HTTP block' tab in the settings sidebar.](https://mintcdn.com/cortex-290c0c42/7CB_Y98t5_vB09nW/images/settings-http-block.png?fit=max\&auto=format\&n=7CB_Y98t5_vB09nW\&q=85\&s=67e15a95493d595a67bc4f172253cff0)
   * The page lists every supported integration in alphabetical order. Integrations that aren't installed in your workspace are locked. Click **Install** next to one to set it up.
   * To hide integrations you haven't installed, select **Show only installed**.
4. Use the toggle next to an integration to turn it on or off for HTTP blocks.

If a Workflow uses an integration that's turned off, the block shows a banner in the Workflow editor, and the run fails with the message "`<Integration>` integration is disabled for HTTP blocks. Integrations can be enabled in settings."

#### Limiting allowed actions

By default, HTTP blocks can send any HTTP method to an integration that's turned on. To limit them, for example to read-only access:

1. On the **HTTP block settings** page, click **Configure** next to an integration that's turned on.
2. In the side panel, under **Allowed actions**, toggle each action on or off:
   * **Create** - `POST` requests
   * **Read** - `GET` requests
   * **Update** - `PUT` and `PATCH` requests
   * **Delete** - `DELETE` requests
3. Click **Save**.

The settings page shows the allowed actions for each integration as badges. If a block uses a method that isn't allowed, the block shows a banner in the Workflow editor, and the run fails with a message such as "DELETE requests to Jira are not allowed for HTTP blocks. Allowed actions can be changed in settings."

#### Blocking specific endpoints

Block a single endpoint when an action is fine in general but one call is hard to undo, such as deleting a Scorecard.

1. On the **HTTP block settings** page, click **Configure** next to an integration that's turned on.
2. In the side panel, under **Blocked endpoints**, click **Add rule**.
3. Do the following::
   * Select a method from the dropdown.
   * Enter the path to block, starting with `/`. Use a placeholder such as `{tag}` for a variable part of the path, for example `/api/v1/scorecards/{tag}`. The path can't contain `?` or `..`.
   * Optionally, select the **Include sub-paths** checkbox to also block every path under the one you entered.
   * Optionally, but highly recommended, explain why the endpoint is blocked. Cortex shows the reason when a run is blocked.
   * Click **Add rule**.
4. Optionally, use **Test a request** to check whether a method and path would be blocked or allowed.
5. Click **Save**.

Endpoint rules match the path relative to the integration's base URL, so one rule covers both cloud and self-hosted instances (for example, GitHub and GitHub Enterprise). If a block with a fixed path matches a rule, it shows a banner in the Workflow editor. Cortex also checks paths built from templates when the block runs, and fails the run if the path matches a rule.

## Configuring an integration block

**Prerequisites**

1. Ensure the integration is installed in your Cortex workspace.
2. Ensure the integration is configured with the correct permissions. Refer to [Integrations](/ingesting-data-into-cortex/integrations#third-party-integrations) for more information.

> [!NOTE]
>
> If an integration supports multiple configurations, you'll be prompted to select the **configuration alias** to use with the block. The block authenticates using the selected configuration, so ensure that you select the configuration with the appropriate permissions.

Cortex provides prebuilt blocks to perform a variety of actions for the following integrations. Expand an integration below to view available blocks.

> **AWS**
>
> * Attach role policy
> * Create EC2 security group
> * Create IAM group
> * Create IAM role
> * Create S3 bucket
> * Describe EC2 instances
> * List buckets
> * Put role policy
> * Run EC2 instances

> **Azure DevOps**
>
> * Create a branch
> * Create branch policies
> * Create file
> * Create repository
> * Delete a branch
> * Delete branch policy
> * Delete file
> * Delete repository
> * Fetch latest commit ID
> * Get a branch
> * Get all branches
> * Get branch policy
> * Get file
> * Get pipeline
> * Get pipeline run details
> * Get repository
> * List branch policies
> * List pipeline runs
> * List pipelines
> * List repositories
> * Rename a branch
> * Run pipeline
> * Update branch policies
> * Update file

> **Bitbucket**
>
> * Create repository
> * Get file
> * Update branch protection

> **GitHub**
>
> * Add label to pull request
> * Add user to org
> * Add user to team
> * Create a branch
> * Create deployment
> * Create or update custom property values
> * Create or update a file
> * Create a pull request
> * Create a pull request comment
> * Create reference (or branch)
> * Create release
> * Create repository
> * Create team
> * Delete a branch
> * Delete branch protection rules
> * Delete file
> * Delete team
> * Find files
> * Get a branch
> * Get branch protection rules
> * Get commit
> * Get deployment
> * Get file
> * Get release by tag
> * Get team
> * Get team membership
> * List branches
> * List commits
> * List deployments
> * List organization members
> * List releases
> * List repositories
> * List team members
> * List teams
> * Merge a branch
> * Remove user from organization
> * Remove user from team
> * Rename a branch
> * Trigger workflow (see additional note below)
> * Update branch protection rules
> * Update repository
>
> **When using the Trigger workflow block**:
>
> The block triggers a run of a GitHub Actions workflow in a given repository. The `response` output includes fields that identify the triggered run:
>
> * `workflow_run_id` - The ID of the GitHub Actions run that was triggered.
> * `run_url` - The GitHub API URL for the run.
> * `html_url` - The link to the run in the GitHub UI.
>
> You can reference these fields from later blocks, for example `{{actions.<block-slug>.outputs.response.workflow_run_id}}`. This is useful for monitoring the triggered run, such as polling the GitHub API from a JavaScript block until the run completes before the Cortex Workflow continues.
>
> Some GitHub instances, such as older GitHub Enterprise Server versions, don't return run details when a workflow is dispatched. In that case the block still succeeds, but `response` and its run detail fields are null.

> **GitLab**
>
> * Archive project
> * Create approval rule
> * Create branch protection
> * Create file
> * Create pipeline schedule
> * Create project
> * Create project access token
> * Create project variable
> * Create push rule
> * Delete approval rule
> * Delete branch protection
> * Delete file
> * Delete pipeline schedule
> * Delete project
> * Delete project variable
> * Delete push rule
> * Get approval configuration
> * Get approval rule
> * Get file
> * Get pipeline schedule
> * Get project
> * Get project variable Get protected branch
> * Get push rule
> * List approval rules
> * List pipeline schedules
> * List project access tokens
> * List project variables
> * List protected branches
> * Revoke project access token
> * Rotate project access token
> * Run pipeline
> * Unarchive project
> * Update approval configuration
> * Update approval rule
> * Update branch protection
> * Update file
> * Update pipeline schedule
> * Update project
> * Update project variable

> **Google Cloud**
>
> * Create project
> * Delete project
> * Get project
> * List projects
> * Update project

> **Harness**
>
> * Execute pipeline
>
> **When using the Execute pipeline block**:
>
> The block runs a Harness pipeline in a given organization and project. It requires an **Organization identifier**, a **Project identifier**, and a **Pipeline identifier**, and optionally accepts **Runtime inputs** as YAML and **Notes** describing the run.
>
> The block's output includes:
>
> * `execution_id` - The identifier of the Harness pipeline execution that was started.
> * `status` - The execution status Harness reported at trigger time.
> * `response` - The full response object from Harness.
>
> The block is synchronous, so it returns Harness's acknowledgment of the run rather than the pipeline's final result. The pipeline runs as the owner of the API key in the selected Harness configuration, not as the person who started the Workflow.
>
> For more detail, including guidance for internally hosted instances, see [Using the integration for Harness](/ingesting-data-into-cortex/integrations/harness/using-the-integration-for-harness).

> **incident.io**
>
> * Create incident
>
> **When using the Create incident block**:
>
> The block creates a new incident in incident.io and maps it to the Cortex entity you specify. The incident's custom fields come from that entity's incident.io registrations. For more information, see [Connecting entities to incident.io](/ingesting-data-into-cortex/integrations/incidentio/connecting-entities-to-incident.io).
>
> The block accepts the following inputs:
>
> * **Entity tag** (required) - The tag of the Cortex entity to associate with the incident.
> * **Name** (required) - The name of the incident.
> * **Summary** (optional) - Additional information about the incident.
> * **Severity** (required) - The name of an incident.io severity, e.g. `Minor`.
> * **Status** (optional) - The name of an incident.io status. Leave it empty to use your incident.io default status.
> * **Incident type** (optional) - The name of an incident.io incident type. Leave it empty to use your incident.io default incident type.
> * **Mode** (optional) - The incident mode: **Standard**, **Retrospective**, **Test**, or **Tutorial**. Defaults to **Standard**.
>
> Severity, status, and incident type are customized in each incident.io account, so Cortex can't list their values in a dropdown. Enter each value as text. It must match a name that's permitted in your incident.io configuration, but it isn't case-sensitive. When the Workflow runs, Cortex validates these values against the incident.io configuration you selected. If a value isn't valid, the block and the Workflow run fail, and no incident is created.
>
> To create incidents, your incident.io API key needs the `Create incidents` scope. See [Configuring incident.io](/ingesting-data-into-cortex/integrations/incidentio#prerequisites).

> **Jenkins**
>
> * Run a build
> * Run a build with parameters

> **LaunchDarkly**
>
> * Create a feature flag
> * Delete a feature flag
> * Get feature flag
> * List feature flags
> * List projects
> * Toggle feature flags
> * Update a feature flag

> **Microsoft Teams**
>
> * Send message

> **PagerDuty**
>
> * Create escalation policy
> * Create incident
> * Create schedule
> * Create service
> * Create team
> * Delete escalation policy
> * Delete schedule
> * Delete service
> * Delete team
> * Get escalation policy
> * Get schedule
> * Get service
> * Get team
> * List escalation policies
> * List incidents
> * List schedules
> * List services
> * List teams
> * List users
> * Schedule override
> * Update escalation policy
> * Update schedule
> * Update service
> * Update team

> **ServiceNow**
>
> * Create incident
> * Create record
> * Delete incident
> * Delete record
> * Get incident
> * Get record
> * Get user by email
> * Get user information
> * List groups
> * List incident categories
> * List incident subcategories
> * List incidents
> * List records
> * List users
> * Update record

> **Slack**
>
> * Get channel info
> * Get user by email
> * List channels
> * List members in channel
> * List users
> * Send message
>
> When using a Slack block:
>
> 1. Ensure the [Cortex AI assistant](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant#using-the-ai-assistant) is added to the appropriate Slack channel.
>    * If the AI assistant isn't in the channel, you'll receive the following error: `Cannot send message to Slack channel without invitation`. To resolve the error, do one of the following:
>      * Invite the AI assistant to the specific channel OR
>      * Reinstall the Slack integration to get the latest scopes, which allows posting to public channels without the AI assistant needing to be a member
> 2. Ensure the AI assistant has the correct permission(s) scoped:
>    * If the channel is public and the install is up to date (has `chat:write.public`), the bot can post without being a member.
>    * If the channel is private, the bot needs `chat:write` and must be invited to the channel.

**To configure an integration block**:

1. Click the **+ icon**.
   The **Search for blocks** window opens.
2. Search for the block you want to add to the Workflow.
3. Select a block to view its details, including any permissions required for it to run correctly.
4. Click **Configure**.
   The block is inserted into your Workflow, and a configuration form appears in the side panel.
5. In the side panel, configure the block metadata:

   * **Block name** - Optionally, change the name of the block. The name auto-populates based on the block name.
   * **Slug** - Optionally, change the slug. The slug auto-populates based on the block name and is made up of letters, digits, and hyphens.

   Metadata differs depending on the block. Any of these inputs can accept dynamic values using Mustache syntax (`{{ ... }}`). For fields that aren't text-based, click the **path icon** on the right of the input to switch into templating mode.\


   ![Mustache templating displayed when configuring a Workflow block.](https://mintlify.s3.us-west-1.amazonaws.com/cortex-290c0c42/images/Screenshot%202025-05-19%20at%2011.08.28%E2%80%AFAM.png)
6. Click **Save**.

## Duplicating a block

There may be an instance where you want to repeat a task within your Workflow. Follow the steps below to duplicate a block.

1. Locate the block you want to duplicate.
2. Click the **Overflow icon** on the right side of the block.\


   ![The 'Overflow menu' icon on a block.](https://mintcdn.com/cortex-290c0c42/kiI3HgqRloEyGGgk/images/duplicate-block.jpg?fit=max\&auto=format\&n=kiI3HgqRloEyGGgk\&q=85\&s=2ad77a0802b0393cb9e6532249ce0580)
3. Click **Duplicate block**. A copy of the block is placed in the Workflow.
4. Optionally, hover over the block and use the **grip icon** to drag it to a new position in the Workflow.

## Using request signing with Workflow blocks

Refer to the documentation for [using request signing with Workflow blocks](/streamline/workflows/blocks/using-request-signing-with-workflow-blocks).

## Referencing a Workflow state in a block

Refer to the documentation for [referencing a Workflow state in a block](/streamline/workflows/blocks/states).

[Next step: Running a Workflow](/streamline/workflows/run)


# Workflow block configuration reference
Source: https://docs.cortex.io/streamline/workflows/blocks/block-configuration-reference

Fields, types, and examples for each Workflow block as it appears in the Workflows API and in Workflow YAML

This page lists the configuration fields for each Workflow block as they appear in a Workflow definition. Use it when you create or update Workflows with the [Workflows API](/api/rest/workflows) or manage them as YAML with [Workflows as code](/streamline/workflows/workflows-as-code). The API and YAML use the same structure, so every example on this page works in both. In JSON, use the same keys.

For instructions on configuring blocks in the Workflow editor, see [Adding blocks to a Workflow](/streamline/workflows/blocks).

> [!NOTE]
>
> The fastest way to get a correct definition is to build the Workflow in the UI first, then click **Export Workflow YAML** (see [Workflows as code](/streamline/workflows/workflows-as-code#step-2-creating-a-yaml-file-for-the-workflow)). The export shows the exact values Cortex expects, including IDs that are specific to your workspace.

## How a block appears in a Workflow definition

In a definition, blocks are listed under `actions`. Each entry has the same outer fields, and the block-specific configuration sits under `schema`. The `schema.type` value sets which other fields the block takes.

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | The display name of the block. |
| `slug` | string | Yes | A unique identifier for the block within the Workflow. Use lowercase letters, digits, and hyphens, 2 to 255 characters, not starting or ending with a hyphen. |
| `isRootAction` | boolean | Yes | Whether this is the first block in the Workflow. A Workflow has exactly one root block. |
| `outgoingActions` | array of strings | Yes | The slugs of the blocks that run after this one. Use `[]` for the last block. For a Branch block, list the `outgoingAction` of every path, including the fallback path. |
| `schema` | object | Yes | The block's configuration. Always includes `type`. See the sections below. |

```yaml theme={null}
actions:
- name: Get user email
  slug: get-user-email
  isRootAction: true
  outgoingActions:
  - notify-team
  schema:
    type: JQ
    expression: .context.initiatedBy.email
- name: Notify team
  slug: notify-team
  isRootAction: false
  outgoingActions: []
  schema:
    type: SLACK
    channel: platform-team
    message: "Workflow started by {{actions.get-user-email.outputs.result}}"
```

### Referencing run data in block fields

Blocks can read the Workflow run state through three top-level keys: `context`, `actions`, and `variables`. Each block writes its result to `actions.<slug>.outputs`. How you reference a value depends on the field:

* **Text fields** (URLs, headers, payloads, messages, descriptions) - Use Mustache templates, such as `{{variables.app-name}}` or `{{actions.get-user-email.outputs.result}}`. Use three curly braces to avoid HTML escaping.
* **JQ expressions** - Start with a dot, such as `.variables.app-name`.
* **CEL expressions, JavaScript, and path fields** - Use dot paths without a leading dot, such as `variables.app-name`.
* **Slugs that contain a hyphen** - In CEL, JavaScript, and JQ, quote them: `actions["get-user-email"]` (or `.actions["get-user-email"]` in JQ).

For the full state object, see [Referencing a Workflow state in a block](/streamline/workflows/blocks/states).

## Core blocks

### Branch (`CONDITIONAL_BRANCH`)

Cortex evaluates the paths in order and takes the first one whose expression returns `true`. If none do, it takes the fallback path. See [Branch](/streamline/workflows/blocks#branch) for how paths work.

| Field | Type | Required | Description |
| - | - | - | - |
| `branches` | array of objects | Yes | The conditional paths, evaluated in order. See the path fields below. |
| `fallbackBranch` | object | No | The path to take if no other path returns `true`. |
| `joiningAction` | string | No | The slug of the block where the paths join again. Leave it out if the paths don't join. When set, the slug must also be in this block's `outgoingActions`. |

Each path in `branches` takes the following fields. `fallbackBranch` takes the same fields except `expression`, and its `type` is `FALLBACK`.

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | `CONDITIONAL` for paths in `branches`, `FALLBACK` for `fallbackBranch`. |
| `name` | string | Yes | The display name of the path. |
| `slug` | string | Yes | The path's identifier. It must be unique within the block. |
| `expression` | string | Yes (`CONDITIONAL` only) | A [CEL](https://cel.dev/) expression that can read `context`, `actions`, and `variables`, such as `variables.count > 0`. |
| `outgoingAction` | string | No | The slug of the first block in this path. |

**Outputs:** `actions.<slug>.outputs.conditions.<path-slug>.result`

```yaml theme={null}
- name: Check environment
  slug: check-environment
  isRootAction: false
  outgoingActions:
  - deploy-production
  - deploy-staging
  schema:
    type: CONDITIONAL_BRANCH
    branches:
    - type: CONDITIONAL
      name: Production
      slug: production
      expression: actions["user-input"].outputs.environment == "prod"
      outgoingAction: deploy-production
    fallbackBranch:
      type: FALLBACK
      name: Everything else
      slug: everything-else
      outgoingAction: deploy-staging
```

### Data transformation (`JQ`)

| Field | Type | Required | Description |
| - | - | - | - |
| `expression` | string | Yes | A [jq](https://jqlang.github.io/jq/) expression. Its input has the keys `context`, `actions`, and `variables`, such as `.context.initiatedBy.email`. |

**Outputs:** `actions.<slug>.outputs.result`

```yaml theme={null}
schema:
  type: JQ
  expression: .context.initiatedBy | tojson
```

### HTTP request (`HTTP_REQUEST`)

| Field | Type | Required | Description |
| - | - | - | - |
| `httpMethod` | string | Yes | One of `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. |
| `url` | string | Yes | The request URL. Supports templates. When `integration` is set, enter a path relative to the integration's base URL. |
| `headers` | object | Yes | A map of header names to values. Use `{}` for no headers. Supports templates. |
| `payload` | string | No | The request body. Supports templates. |
| `integration` | string | No | A configured integration to authenticate the request with, such as `GitHub`, `Jira`, or `Cortex`. See [Authenticating HTTP requests with an integration](/streamline/workflows/blocks#authenticating-http-requests-with-an-integration). |
| `integrationAlias` | string | No | The integration configuration to use when the integration has more than one. |
| `targetHost` | string | No | Only for the `Google` integration: the `*.googleapis.com` host to call. Defaults to `cloudresourcemanager.googleapis.com`. Cortex rejects this field with any other integration. |

**Outputs:** `actions.<slug>.outputs.status`, `actions.<slug>.outputs.headers`, `actions.<slug>.outputs.body`

```yaml theme={null}
schema:
  type: HTTP_REQUEST
  httpMethod: POST
  url: https://api.example.com/v1/environments
  headers:
    Content-Type: application/json
    Authorization: "Bearer {{context.secrets.example-token}}"
  payload: '{"name": "{{actions.user-input.outputs.env-name}}"}'
```

### Asynchronous HTTP request (`HTTP_REQUEST_ASYNC`)

This block takes all of the [HTTP request](#http-request-http_request) fields, plus a timeout. The Workflow pauses until the external system calls the callback URL (available as `{{callbackUrl}}`) or the timeout expires. See [Asynchronous HTTP request](/streamline/workflows/blocks#http-action-async) for the callback format.

| Field | Type | Required | Description |
| - | - | - | - |
| `timeoutInSeconds` | integer | No | How long to wait for the callback, in seconds. |

```yaml theme={null}
schema:
  type: HTTP_REQUEST_ASYNC
  httpMethod: POST
  url: https://ci.example.com/pipelines/provision
  headers:
    Content-Type: application/json
  payload: '{"callback": "{{callbackUrl}}"}'
  timeoutInSeconds: 3600
```

### JavaScript (`JAVASCRIPT`)

| Field | Type | Required | Description |
| - | - | - | - |
| `script` | string | Yes | The script to run. It runs as the body of `run(actions, context, variables)` and must end with a `return` statement. |

**Outputs:** `actions.<slug>.outputs.result`, plus any top-level keys of the returned object.

```yaml theme={null}
schema:
  type: JAVASCRIPT
  script: |
    const email = context.initiatedBy.email;
    return { username: email.split("@")[0] };
```

### Manual approval (`MANUAL_APPROVAL`)

| Field | Type | Required | Description |
| - | - | - | - |
| `approvingTeamIds` | array of strings | Yes | The Cortex IDs (CIDs) of the teams whose members can approve, not team tags. Can be `[]` when `approvingTeamIdsOverride` is set. |
| `approvingTeamIdsOverride` | string | No | A dot path that resolves the approving teams at run time, such as `variables.approvers` or `actions.user-input.outputs.team`. The value at the path must be an array of team Cortex IDs or team tags. Don't wrap it in template braces. |
| `approverDescription` | string | No | A message shown to approvers. Supports templates. |

```yaml theme={null}
schema:
  type: MANUAL_APPROVAL
  approvingTeamIds: []
  approvingTeamIdsOverride: variables.approvers
  approverDescription: "Approve the new environment for {{actions.user-input.outputs.env-name}}"
```

### Run Workflow (`RUN_WORKFLOW`)

| Field | Type | Required | Description |
| - | - | - | - |
| `workflowId` | string | Yes | The child Workflow to run. |
| `entityId` | string | No | The entity to run the child Workflow against. |
| `inputs` | object | Yes | Values for the child Workflow's variables, keyed by variable slug. The child reads each value as `{{variables.<slug>}}`. Values keep the variable's type and can use templates. Use `{}` if there are no inputs. |
| `waitForCompletion` | boolean | Yes | Whether to wait for the child run to finish before continuing. Cortex uses `false` if you leave it out. |
| `timeoutInSeconds` | integer | No | How long to wait for the child run, in seconds. When it expires, Cortex cancels the child run. Only used with `waitForCompletion`. |

**Outputs:** `actions.<slug>.outputs.runId`. With `waitForCompletion: true`, also `status`, `runResponse`, and `variables`. See [Run Workflow](/streamline/workflows/blocks#run-workflow).

```yaml theme={null}
schema:
  type: RUN_WORKFLOW
  workflowId: approval-workflow
  waitForCompletion: true
  timeoutInSeconds: 86400
  inputs:
    app-id: "{{actions.form.outputs.appId}}"
    count: 5
```

### Scaffolder (`SCAFFOLDER`)

| Field | Type | Required | Description |
| - | - | - | - |
| `scaffolderTemplateTag` | string | One of these two | The tag of the Scaffolder template. If both fields are set, Cortex uses this one, which keeps definitions portable across workspaces. |
| `scaffolderTemplateId` | string | One of these two | The template's tag or Cortex ID. In responses, this is always the Cortex ID, or `null` if the template was deleted. |
| `createNewRepository` | boolean | No | Whether to create a new repository. Defaults to `true`. Set it to `false` to open a pull request against an existing repository. |
| `createService` | boolean | No | Whether to create the entity in Cortex. |
| `inputOverrides` | array of objects | Yes | Values that override template fields. See [Input overrides](#input-overrides). Use `[]` for none. |

```yaml theme={null}
schema:
  type: SCAFFOLDER
  scaffolderTemplateTag: java-service
  createNewRepository: true
  createService: true
  inputOverrides:
  - type: VALUE
    inputKey: project_name
    outputVariable: context.entity.tag
    editable: false
```

### Set variable(s) (`SET_VARIABLES`)

The variables must be declared in the Workflow's `variables` list (see [Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings)).

| Field | Type | Required | Description |
| - | - | - | - |
| `variables` | array of objects | Yes | The variables to set. Each item has a `slug` (the variable's slug) and a `source`. |
| `variables[].source.type` | string | Yes | `REFERENCE` to read a value from a path, or `JAVASCRIPT` to compute it with a script. |
| `variables[].source.path` | string | For `REFERENCE` | A dot path into the run data, such as `actions.fetch.outputs.body`. |
| `variables[].source.script` | string | For `JAVASCRIPT` | A script that returns the value. It runs as the body of `run(actions, context, variables)`. |

```yaml theme={null}
schema:
  type: SET_VARIABLES
  variables:
  - slug: approved
    source:
      type: REFERENCE
      path: actions.run-approval.outputs.variables.approved
  - slug: retry-count
    source:
      type: JAVASCRIPT
      script: return (variables["retry-count"] ?? 0) + 1;
```

### User input (`USER_INPUT`)

| Field | Type | Required | Description |
| - | - | - | - |
| `inputs` | array of objects | Yes | The fields to show the user. See [User input field types](#user-input-field-types). |
| `inputOverrides` | array of objects | Yes | Values that override or prefill fields. See [Input overrides](#input-overrides). Use `[]` for none. |
| `jsValidatorScript` | string | No | JavaScript that validates the response. See [Adding validation logic](/streamline/workflows/blocks#user-input). |

**Outputs:** `actions.<slug>.outputs.<key>` for each field.

```yaml theme={null}
schema:
  type: USER_INPUT
  inputs:
  - type: INPUT_FIELD
    name: Service name
    key: service-name
    required: true
    validationRegex: ^[a-z][a-z0-9-]+$
  - type: SELECT_FIELD
    name: Environment
    key: environment
    required: true
    options: [dev, staging, prod]
    optionsLabels: [Development, Staging, Production]
    allowAdditionalOptions: false
  inputOverrides: []
  jsValidatorScript: ""
```

#### User input field types

Every field takes these common keys:

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | The field type. See the table below. |
| `name` | string | Yes | The label shown to the user. |
| `key` | string | Yes | The output key. It must be unique within the block. |
| `required` | boolean | Yes | Whether the user must provide a value. |
| `description` | string | No | Help text shown with the field. Supports templates. |

Each type also takes the keys below. Keys in **bold** are required.

| UI type | `type` | Additional keys |
| - | - | - |
| Text | `INPUT_FIELD` | `defaultValue` (string), `placeholder`, `validationRegex` |
| Paragraph | `TEXTAREA_FIELD` | `defaultValue` (string), `placeholder`, `validationRegex` |
| Secret | `SECRET_FIELD` | **`disabled`**, `placeholder`, `validationRegex` |
| Toggle | `TOGGLE_FIELD` | `defaultValue` (boolean) |
| Number | `NUMBER_FIELD` | **`format`** (`INTEGER` or `DECIMAL`), **`disabled`**, `min`, `max`, `defaultValue` (number), `placeholder` |
| Date | `DATE_FIELD` | **`format`** (`DATE` or `DATETIME`), **`disabled`**, `defaultValue` (string), `placeholder` |
| Select, manual options | `SELECT_FIELD` | **`options`** (array of strings), **`allowAdditionalOptions`**, `optionsLabels`, `defaultValue` (string), `placeholder` |
| Select, manual options with **Allow multiple** | `MULTISELECT_FIELD` | **`options`** (array of strings), **`allowAdditionalOptions`**, `optionsLabels`, `defaultValue` (array of strings), `placeholder` |
| Select, Cortex entity | `CORTEX_ENTITY_FIELD` | **`entityFilter`**, **`allowMultiple`**, **`limitEntitiesToRunnerUserScope`**, **`shouldDisplayOptionsAsHierarchy`**, `defaultValue` (array of strings), `placeholder` |
| Select, Cortex user | `CORTEX_USER_FIELD` | **`filter`**, **`allowMultiple`**, `defaultValue` (array of `{name, email}` objects), `placeholder` |
| Select, Slack channels | `SLACK_FIELD` | **`filter`** (object with `channels`), **`allowMultiple`**, `defaultValue` (array of strings), `placeholder` |
| Nested form | `NESTED_FORM_FIELD` | See [Nested form fields](#nested-form-fields). |

Notes on these keys:

* If you leave out a required boolean (`disabled`, `allowMultiple`, `allowAdditionalOptions`, `limitEntitiesToRunnerUserScope`, or `shouldDisplayOptionsAsHierarchy`), Cortex uses `false`. If you leave out `format`, Cortex uses `DECIMAL` for numbers and `DATE` for dates.
* `optionsLabels` sets display labels in the same order as `options`. If you leave it out, Cortex shows the option values.
* `entityFilter` accepts `typeFilter` (`{types: [service, team]}`), `groupTags`, `excludedGroupTags`, `teamIds`, `domainIds`, and `emailOwners`. Use `{}` to allow all entities.
* For `CORTEX_USER_FIELD`, `filter` accepts `teamCids` and `userEmails`. Use `{}` to allow all users.

```yaml theme={null}
- type: CORTEX_ENTITY_FIELD
  name: Service
  key: service
  required: true
  allowMultiple: false
  limitEntitiesToRunnerUserScope: true
  shouldDisplayOptionsAsHierarchy: false
  entityFilter:
    typeFilter:
      types: [service]
```

#### Nested form fields

A `NESTED_FORM_FIELD` lets the user enter a list of items. It takes the common keys, plus:

| Field | Type | Required | Description |
| - | - | - | - |
| `itemType` | string | No | `OBJECT` (the default) for items with several sub-fields, or `STRING`, `INTEGER`, `DECIMAL`, or `BOOLEAN` for single values. For single values, Cortex derives this from `element`. |
| `inputs` | array of objects | For `OBJECT` | The sub-fields for each item. Uses the same field types as `inputs` on the block, up to five levels of nesting. |
| `inputOverrides` | array of objects | For `OBJECT` | Overrides for the sub-fields. Use `[]` for none. |
| `element` | object | For single values | One field definition that describes every item. Its `type` must be `INPUT_FIELD`, `TEXTAREA_FIELD`, `DATE_FIELD`, `NUMBER_FIELD`, or `TOGGLE_FIELD`. |
| `min` | number | No | The minimum number of items. It also sets how many items appear by default. Defaults to 1. |
| `max` | number | No | The maximum number of items. |
| `disabled` | boolean | No | Whether the field is disabled. |

**Outputs:** an array of objects for `OBJECT` (for example, `[{"name": "db-1", "size": 100}]`), or a flat array for single values (for example, `[8080, 8443]`).

```yaml theme={null}
- type: NESTED_FORM_FIELD
  name: Databases
  key: databases
  required: true
  itemType: OBJECT
  min: 1
  max: 5
  inputs:
  - type: INPUT_FIELD
    name: Name
    key: name
    required: true
  - type: NUMBER_FIELD
    name: Size (GB)
    key: size
    required: true
    format: INTEGER
    disabled: false
  inputOverrides: []
```

For a single-value example, see [Workflows as code](/streamline/workflows/workflows-as-code#example-workflow-yaml).

#### Input overrides

`inputOverrides` on User input and Scaffolder blocks fill a field from a value earlier in the run.

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | `VALUE` sets the field's value. `OPTION` sets the options the user can choose from. |
| `inputKey` | string | Yes | The key of the field to override. |
| `outputVariable` | string | Yes | A dot path to the value, such as `actions.lookup.outputs.result` or `variables.team-tags`. |
| `editable` | boolean | Yes (`VALUE` only) | Whether the user can edit the value before continuing. When `true`, the Workflow pauses for the user. Cortex uses `false` if you leave it out. |

## Integration blocks

Most prebuilt integration blocks use the `ADVANCED_HTTP_REQUEST` type and identify the action with `actionIdentifier`. Each action has its own set of `inputs`, so the easiest way to get the identifier and input keys is to add the block in the UI and export the Workflow YAML.

| `type` | Fields |
| - | - |
| `ADVANCED_HTTP_REQUEST` | `actionIdentifier` (string, required, such as `googleCloud.getProject`), `inputs` (object, required, keyed by input), `integrationAlias` (required when the integration has more than one configuration) |
| `AWS` | `actionIdentifier` (string, required, such as `aws.ec2.describeInstances`), `inputs` (object, required), `accountId` (string, required, supports templates), `region` (string, required, such as `us-east-1`, supports templates) |
| `SLACK` | `channel` (required, the channel name without `#`), `message` (required) |
| `MS_TEAMS_SEND_MESSAGE` | `teamId`, `channelId`, `message` (all required) |
| `PAGERDUTY_CREATE_INCIDENT` | `serviceId`, `title`, `body`, `fromEmail`, `urgency` (`HIGH` or `LOW`), all required; `incidentTypeName` |
| `GITHUB_CREATE_OR_UPDATE_FILE` | `alias`, `repositoryName`, `path`, `content` (not base64-encoded), `commitMessage`, all required; `branch` (defaults to the default branch), `committer` and `author` (each `{name, email}`) |
| `JIRA_CREATE_ISSUE` | `alias`, `projectKey`, `issueSummary`, `issueType`, `description`, `labels`, `components`, and `fields`, all required (use `[]` or `{}` for none); `assignee`, `reporter`, `priority` |

```yaml theme={null}
schema:
  type: ADVANCED_HTTP_REQUEST
  actionIdentifier: googleCloud.getProject
  integrationAlias: production
  inputs:
    projectId: "{{actions.user-input.outputs.project-id}}"
```

## Validating a definition

Before you save, you can check a definition with the [Validates YAML descriptor](/api/rest/workflows/validates-yaml-descriptor) endpoint. It reports missing required fields, slugs that aren't unique, and broken references between blocks.


# Referencing a Workflow state in a block
Source: https://docs.cortex.io/streamline/workflows/blocks/states



Every Workflow run produces a state object that grows as the Workflow executes. Blocks can read from this state at any point, giving them access to both top-level context (such as who initiated the run) and the output of any preceding block. This is what makes blocks composable: each one can build on what came before.

The Workflow state object includes top-level `context`, `actions`, and `variables` keys:

* `context` is immutable, set at the beginning, and available to all blocks.
  * If an entity changes during Workflow execution, those changes will **not** be represented in `context.entity`.
  * If secrets change during a Workflow, those changes will **not** be represented in `context.secrets`.
  * You can examine the context object via the **Run context** tab when viewing a Workflow run.
  * [Learn more](/streamline/workflows/blocks/states#the-workflow-state-context-key) about the `context` key.
* `actions` is built up as actions execute via blocks.
  * Each block will have an `inputs` and `outputs` key, but their format differs based on the block type.
* `variables` contains the current values of any variables declared on the workflow. If a variable does not have a default value and hasn't been set yet, its value will be `null`.
  * **Note**: since variables are mutable, the variable values can change over time. Depending on the ordering of blocks in your workflow, different blocks may have access to different variable values.
  * If the Workflow was started by a [Run Workflow block](/streamline/workflows/blocks#run-workflow) in another Workflow, `variables` starts with the values that block passed in. Any variable without a passed-in value uses its default.

The state object looks similar to the following:

```json theme={null}
{
  "context": {
    "initiatedBy": {
      "name": "Henry Hippocampus",
      "email": "henry.hippocampus@cortex.io",
      "identityMappings": {
        "github": "hhippocampus"
      },
      "identityMappingsByAlias": {
        "github": {
          "cortex": "hhippocampus",
          "other-config": "hippo"
        }
      }
    },
    "workflowRunId":"a607c73f-b8e2-44b7-aa20-e23de7cf7af7",
    "initiatedAtIso8601Timestamp": "2025-05-16T21:42:37.642+00:00", // ISO8601 timestamp
    "secrets": {
      "secret-tag": "********"
    },
    "entity": { // only present for entity-scoped workflows
      "id": "en0123456789abcdef",
      "tag": "test-entity",
      "name": "Test Entity",
      "descriptor": { 
        "info": { ... }
      }
    }
  },
  "actions": {
    "action-slug-1": {
      "inputs": {},
      "outputs": {}
    }, 
    "action-slug-2": {
      "inputs": {},
      "outputs": {}
    }
    ...
  },
  "variables": {
    "variable1": true,
    "variable2": null,
    "variable3": { 
      "isObject": true
    }
  }
}
```

## The Workflow state `context` key

The context object always has the following keys:

* `{{context.workflowRunId}}` - The Workflow run ID
* `{{context.initiatedAtIso8601Timestamp}}` - The timestamp at which this block was initiated
* `{{context.initiatedBy}}` - The user object of the initiator
  * `email` - The user's email
  * `name` - The initiator's name
  * `identityMappings` - A mapping of the identity providers listed below to the initiating user's corresponding external ID. The external ID is pulled from identity provider's default configuration when there is more than one configuration.
    * `azure_devops`
    * `bitbucket`
    * `clickup`
    * `github`
    * `gitlab`
    * `jira`
    * `microsoft_teams`
    * `opsgenie`
    * `pagerduty`
    * `service_now`
    * `slack`
  * `identityMappingsByAlias` - Similar to `identityMappings`, but each provider maps to an object of configuration `alias` to external ID. This field is useful when users have different external IDs across an integration's configurations.
* `{{context.secrets}}` - An object of Cortex secret tags to their values

### **Accessing configured secrets**

You can access your configured secrets by tag: `{{context.secrets.SECRET_TAG}}`.

Note that Mustache syntax performs HTML escaping by default, so if your configured secret contains a reserved HTML character, use triple braces to use raw content: `{{{context.secrets.SECRET_TAG}}}`.

Secret values are redacted in inputs and outputs of the workflow state.

> [!NOTE]
>
> Accessing a secret in the `context` object is not supported for Slack blocks.

### **Accessing entity data**

When the block runs in the context of a catalog entity, the template context includes data about that entity under the `{{context.entity}}` key:

* `id`
* `tag`
* `name`
* `descriptor` (this is the `cortex.yaml`, as an object)

These can be accessed under the `{{context.entity}}` key, for example `{{context.entity.tag}}` or `{{context.entity.descriptor.info.x-cortex-git.github.repository}}` .

## Referencing a block or workflow state

You can reference a previous block or a workflow state in several ways:

* Templated into block schemas via [Mustache](https://github.com/spullara/mustache.java) (`{{}}`)
* Accessed directly from JQ actions
* Referenced to define **User input** block overrides
* Referenced in **Branch** block path expressions using CEL syntax
* Accessed via JavaScript
  * For example, in a [JavaScript block](/streamline/workflows/blocks#javascript) you can reference Workflow variables using the syntax `const selected = variables['variable-slug']`.

### **Block and workflow state reference example**

Assume a Workflow was created where you gather names from an "HTTP request" block, a "data transformation" block parses the array of names, the names are surfaced to users in a "user input" block where they can select a name, then a "branch" block runs a different path based on which name was selected during the previous "user input" block. In one of the branch paths, there is a "Slack" block that sends a templated message based on the output of previous blocks.

The workflow contains the following blocks:

* HTTP request block called `users`
  * In this example, the block sends a `GET` request to gather user names from a URL containing sample data.
* Data transformation block called `names`
  * It contains a JQ query referencing the output of the `users` block:

    `[.actions.users.outputs.body[] | .name]`
* User input block called `pick-name`
  * It contains an override that references the output of the `names` block:

    `actions.names.outputs.result`
* Branch block called `create-services`
  * There are multiple paths in this branch, depending on which name you chose in the previous block. One of the name options is `Ervin`, and there is a conditional path called `Ervin` within this block that contains the following path expression. It references `Ervin` as the output of the `pick-names` block:

    `actions['pick-name'].outputs.name == 'Ervin' && context.entity.descriptor.info['x-cortex-type'] == 'team'`.
  * The `Ervin` path contains a Slack block to send a templated message via Slack, referencing the output of the `pick-name` block and referencing the workflow state by including the email address of the user who initiated the workflow:

    `We created a service for {{actions.pick-name.outputs.name}}. [message from workflow triggered by {{context.initiatedBy.email}}]`

When you run the workflow, the following chain of events occurs:

1. The HTTP request block gathers user names.
   * In the "Inputs" tab of this block, you can see where the data was pulled from.
   * In the "Outputs" tab of this block, you can see the list of names under the body.
2. The data transformation block parses an array of names from the HTTP request block.
   * In the "Outputs" tab of this block, you can see the list of names.
3. The Workflow is paused while awaiting user input. The user input block surfaces a `name` field where the user can select a name from the list. The names are from the array parsed in the previous block.
4. The user selects the name `Ervin`, and the Workflow continues to the next block.
5. The branch block runs a path depending on which name you chose in the previous block. In this example, the `Ervin` path runs because the CEL expression for that conditional path was configured to run when the `pick-name` block's output is `Ervin`.
   * In the "Outputs" tab of this block, you can see the conditions that were checked to verify which path to run.
6. The `Ervin` path contains a Slack block that sends a templated message referencing the output the previous block and the user who initiated the Workflow. The message is sent to the user with the templated references translated:

   `We created a service for Ervin. [message from workflow triggered by jdoe@example.com]`


# Using request signing with Workflow blocks
Source: https://docs.cortex.io/streamline/workflows/blocks/using-request-signing-with-workflow-blocks



If you're using a Workflow as a way to trigger hooks into internal tooling, it's recommended to validate that the request is actually originating from Cortex using request signing. Signing secrets are added to requests coming from Workflow blocks.

The following headers are added to each request made by Cortex. Use these headers to verify that the request is valid and originated from Cortex:

* `x-cortex-timestamp`- This header uses the current timestamp in millis, and is used to prevent replay attacks. Cortex signs the requests using the format `<timestamp>.<body>`.
* `x-cortex-timestamp-only-signature-256` - This header calculates the SHA256 signature using only the timestamp. Use this header in environments where the HTTP request body is unavailable due to platform limitations.
* `x-cortex-signature-256` - This header uses the SHA256 algorithm. For security best practices, use this header rather than `x-cortex-signature`.
* `x-cortex-signature` - This header uses the SHA1 algorithm and exists for backward compatibility. SHA1 is considered unsafe and this signature should be considered deprecated.

**To configure a signing secret**:

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Security and access** section, then click **Secrets**.
4. Under **Request signing secret**, enter a secret into the text field. The secret can be made up of letters, digits, special characters, and hyphens.
5. Copy and store the secret. Once the secret is saved, there's no way to view it in the Cortex UI.
6. Click **Save secret**.
7. Calculate the signature (an [RFC2104](https://datatracker.ietf.org/doc/html/rfc2104.html) HMAC):
   1. Create a string with the value `$timestamp.$requestBody` if the request body is non-null OR `$timestamp` if the request body is null.
   2. Calculate an HMAC using the SHA256 algorithm. Use the secret you provided to Cortex as the key and the string from Step A above as the payload.
   3. Verify that the `x-cortex-signature-256` matches the HMAC calculated in Step B above.


# Configuring Workflow settings
Source: https://docs.cortex.io/streamline/workflows/configuring-workflow-settings



After [creating a Workflow](/streamline/workflows/create), you need to configure it. Follow the steps below to configure a Workflow.

## Prerequisites

1. You must have the `Edit Workflows` permission.
2. An existing Workflow. If you haven't yet created a Workflow, refer to [Creating a Workflow](/streamline/workflows/create).

## Configuring Workflow settings

1. In the **Workflow information** pane, do the following:
   1. Optionally, edit the Workflow name.
   2. Optionally, change the slug. The slug auto-populates based on the Workflow name and is made up of letters, digits, and hyphens. If you previously used a template, be sure to update the prepopulated slug when you use the template again.
   3. Under **Description**, enter a brief description of the workflow.
   4. Click **Edit** to change the display icon. This makes the workflow easier to identify.
   5. Under **Run response template**, enter a message to be displayed to the user upon run completion. This message can reference values from the run using Cortex's templating syntax. Refer to the [Blocks documentation](/streamline/workflows/blocks/states) for more information.
   6. Under **Failed run response template**, enter a message to be displayed to the user upon run failure. This message can reference values from the run using Cortex's templating syntax. Refer to the [Blocks documentation](/streamline/workflows/blocks/states) for more information.
   7. From the **Scope** drop-down menu, select one of the following:
      * **Entity** - The Workflow is tied to a specific entity type such as Services or Teams. If selected, configure the following:
        * **Entity type** - Select a built-in or custom entity. Entities must be already defined to appear in the list.
        * **Include groups** - Select a group or groups. Groups must be already defined to appear in the list.
        * **Exclude groups** - Exclude a group or groups. Groups must be already defined to appear in the list.
        * **User relation to entities** - Under **User relation to entities**, optionally toggle on the following:
          * **Require entity ownership** - Only owners of the target entity can run the Workflow. Leave this off to allow any user in your organization to run it.
          * **Require edit permission** - Available once **Require entity ownership** is on. The owner must also have edit access to the entity.
          * **Require team member role** - Available once **Require entity ownership** is on. Select one or more team roles from the list. The owner must hold at least one of the selected roles on the entity's owning team to run the Workflow.
      * **Global** - The Workflow is not tied to a specific entity and can be run from the main Workflows page.
   8. Optionally, toggle on **Restrict to initiator** to ensure that only the user who initiated the workflow can provide required input during the run.
   9. Optionally, declare variables that can be referenced from each block. Variable slugs declared here can be set at runtime by callers of the [Workflow Runs API](/api/rest/workflows) using the `initialContext` field, or by a parent Workflow through the **Inputs** section of a [Run Workflow block](/streamline/workflows/blocks#run-workflow). In the **Variables** section, click **Add variable**. Enter the following:
      * **Slug** - Enter a unique slug for the variable. It must be unique and can only contain letters, numbers, or hyphens.
      * **Description** - Enter a description of the variable.
      * **Variable type** - Select the variable type.
        * **Boolean** - A true or false value.
        * **Number** - A numeric value, such as an integer or decimal.
        * **Object** - A structured value containing one or more key-value pairs.
        * **String** - A sequence of characters, such as a word or phrase.
        * **… is array** - If toggled on, the variable is treated as a list of values of the selected type.
      * **Default value** - Enter a default value. This must be a valid JSON.
      * Click **Add**.
   10. Click **Save**.

[Next step: Adding blocks to the Workflow](/streamline/workflows/blocks)


# Creating a Workflow
Source: https://docs.cortex.io/streamline/workflows/create



This article describes how to create a Workflow in the Cortex UI. For information on creating Workflows via GitOps, see [Workflows as code](/streamline/workflows/workflows-as-code).

> [!TIP]
>
> Looking for a quick introduction to building and managing Workflows? Check out the Cortex Academy course on [Workflows](https://academy.cortex.io/courses/understanding-workflows).

## Prerequisites

1. You must have the `Edit Workflows` permission.
2. If you want to manage Workflows in the Cortex UI, ensure that GitOps editing is disabled in settings:
   1. From the main sidebar, click your avatar in the bottom-left corner.
   2. Click **Settings**.
   3. From the **Settings** menu, locate the **Workspace** section, then click **GitOps**.
   4. Select the **Workflows** tab.
   5. Ensure that **Enable GitOps for Workflows editing** is toggled off.

## Creating a Workflow

You can choose to create a Workflow from a template or you can choose to create one from scratch.

1. From the main sidebar, select **Workflows**.
2. In the upper-right corner, click **Create Workflow**. The **Create Workflow** page opens.
3. Choose whether to start with a template or from scratch:
   * **Blank Workflow (Start from scratch)** - Use this option for a blank canvas with no predefined blocks.
   * **Template** - Use a template when your task matches one of the predefined options. Each tile displays the requirements for secrets you must define before using the template; be sure to follow the requirements before you proceed. Click **Use** in the bottom-right of a template's tile to select that template.
   > **Expand to see the list of templates**
   >
   > * Creating an AWS S3 bucket
   > * Creating an AWS EC2 instance
   > * Creating an Azure function
   > * Triggering Humanitec pipeline with callback
   > * Dev onboarding: User access
   > * Requesting access to GitHub Copilot
   > * Creating a ServiceNow incident
   > * Creating a work item
   > * Creating a Cortex domain
   > * Creating a Cortex service
   > * Creating a Cortex team
   > * Deleting a Cortex entity
   > * Retrieving Cortex entity details
   > * Updating entity description
   > * Linking SOC2 documents to an entity
   > * Updating a JSON file in GitHub
4. In the **Create workflow** window, enter a **Workflow name**.
5. Optionally, to add the Workflow to a folder, select the **Add to folder** checkbox.

   > [!NOTE]
   >
   > The **Add to folder** checkbox only appears if your workspace has at least one [Workflow folder](/streamline/workflows/viewing-workflows#organizing-workflows-into-folders).
6. Click **Create**.

   If you selected **Add to folder**, choose where to add the Workflow:

   * **Existing folder** - Select this option to add the Workflow to a folder that already exists in your workspace.
   * **New folder** - Select this option to create a new folder. Enter the following:
     1. **Folder name** - The name of the folder (required).
     2. **Description** - A brief overview of the folder.
     3. **Parent folder** - The folder that contains the new folder.
     4. **Display icon** - The icon that represents the folder.
     5. Click **Add to folder**.

   If you cancel this step, Cortex still creates the Workflow without adding it to a folder. You can [move it into a folder](/streamline/workflows/viewing-workflows#moving-a-workflow-into-a-folder) later.

[Next step: Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings)


# Publishing a Workflow
Source: https://docs.cortex.io/streamline/workflows/publishing-a-workflow



This article covers how to restrict access to a Workflow and how to publish one.

You may want to restrict access to limit who can run Workflows that touch production systems, modify infrastructure, or should only be available to specific teams, for example, an SRE team's incident response Workflow or a platform team's provisioning Workflow.

Publishing controls visibility in the Cortex UI: draft Workflows are hidden and only accessible to their authors and collaborators, while published Workflows appear throughout Cortex where any user with access can discover and run them. A Workflow can be run in either state, so you can test and iterate in draft mode, then publish once it's ready for broader use.

## Restricting access to a Workflow

By default, published workflows are visible to anyone in your organization who has permission to view them. To restrict access, follow the steps below.

> [!NOTE]
>
> When a Workflow is saved as a draft, it's only visible to users with the `Edit Workflow` permission.

1. From the main sidebar, select **Workflows**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's Workflows.
   * Select the **Mine** tab to search and filter only the Workflows you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow, then click the **overflow menu icon** next to it.\


   ![The 'Overflow menu' icon next to a Workflow.](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflows-overflow.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=86698867dbd3391ff36ee5119662b38c)
4. Select **Edit Workflow**.
5. In the upper-right corner, click Access.
6. Toggle off **Organization run access**.
7. To set access for specific users, teams, or roles, do any the following:
   1. From the **Select users** drop-down menu, select the users who should have access to view the workflow. Note that users must have the `Execute Workflow Runs` permission *and* they must match at least one of the users, teams, or roles specified.
   2. From the **Select teams** drop-down menu, select the teams who should have access to view the workflow.
   3. From the **Roles** drop-down menu, select the roles who should have access to view the workflow.
8. Click **Apply**.

## Enabling API access

Users with a [personal access token](/configure/settings/api-keys/personal-tokens) or a [global API key](/configure/settings/api-keys), with the `Execute Workflow Runs` permission, can run a [Workflow via the API](/api/rest/workflows) or the [Cortex MCP](/get-started/cortex-ai-assistant/mcp/using-cortex-mcp#creating-and-running-workflows-with-the-cortex-mcp).

Follow the steps below to allow a Workflow to be triggered through the Workflow Runs API.

1. From the main sidebar, select **Workflows**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's Workflows.
   * Select the **Mine** tab to search and filter only the Workflows you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow, then click the **overflow menu icon** next to it.\


   ![The 'Overflow menu' icon next to a Workflow.](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflows-overflow.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=86698867dbd3391ff36ee5119662b38c)
4. Select **Edit Workflow**.
5. In the upper‑right corner, click **Access**.
6. Toggle on **Runnable via API**.
7. Click **Apply**.

   The Workflow can now be run via the API.
8. Repeat these steps for each Workflow you want to run via the API.\


## **Publishing a Workflow**

A workflow remains in draft mode until it's published. Drafts are only visible to users who have permission to edit workflows.

To set a workflow to public, toggle off the **Draft** option in the upper-right corner of the Workflow:

![The 'Draft' option toggled off indicates that the Workflow is viewable and discoverable.](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflow-draft.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=7b603763d662c711a5792715f55790e8)


# Running a Workflow
Source: https://docs.cortex.io/streamline/workflows/run



After you've [created a Workflow](/streamline/workflows/create), [configured its basic settings](/streamline/workflows/configuring-workflow-settings), and [added blocks](/streamline/workflows/blocks), you're ready to run it.

You can run a Workflow in the following ways:

* [Directly after configuration](/streamline/workflows/run#running-a-workflow-directly-after-configuration)
* [From the Workflows page](/streamline/workflows/run#running-a-workflow-from-the-workflows-page-via-the-main-sidebar) (via the main sidebar)
* [From an entity](/streamline/workflows/run#running-a-workflow-from-an-entity)
* [Via the API](/streamline/workflows/run#running-a-workflow-via-the-api)

> [!NOTE]
>
> To run a Workflow with Cortex-based blocks, you need the appropriate [permissions](/configure/settings/managing-users/permissioning) for each block. For example, a block that adds Eng Intelligence custom metrics to an entity requires the `Configure Eng Intelligence Custom Metrics` permission to run successfully.

## Prerequisites

1. You must have the `Execute Workflow Runs` permission.
2. An existing Workflow. If you haven't yet created a Workflow, refer to [Creating a Workflow](/streamline/workflows/create), [Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings), and [Adding blocks to a Workflow](/streamline/workflows/blocks).
3. The Workflow must have no validation errors or warnings. You can save a Workflow that has warnings, such as `Invalid templating reference`, but you can't run it until you resolve them. This applies to runs started from the UI, the API, the Cortex MCP, and Run Workflow blocks.

## Running a Workflow directly after configuration

1. In the upper-right corner of the page, click **Run**.\


   ![The 'Run' icon in the upper-right corner of the Workflow page.](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflow-run-icon.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=44e2a29f6951be035e9a7fe4227b4253)
2. Click **Run workflow**.

## Running a Workflow from the Workflows page (via the main sidebar)

1. From the main sidebar, select **Workflows**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's Workflows.
   * Select the **Mine** tab to search and filter only the Workflows you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow you want to run, then click **Run**. Note that if the Workflow is scoped to an entity, the **Select an entity** window opens. Select an entity from the drop-down menu, then click **Run workflow**.

> [!NOTE]
>
> Workflows that require user input or manual approval pause until the configured input or approval is completed.

Nested form inputs configured with **Data type: String** render as a simple list of text fields, one per row, with an **Add** button and a **Remove** button (trash icon). **Data type: Object** nested forms render the configured sub‑form per row.

![Nested form String input at runtime: one text field per row with Add and remove buttons.](https://mintcdn.com/cortex-290c0c42/LuvRb_WdTtJiOHK_/images/array-example.png?fit=max\&auto=format\&n=LuvRb_WdTtJiOHK_\&q=85\&s=0ad3ba7b1293212d952d3ebcde00cd5e)

## Running a Workflow from an entity

Follow the steps below to run a Workflow from an entity.

> [!NOTE]
>
> Workflows are linked to entities only if specified during configuration. To link an existing Workflow to an entity, edit the Workflow first.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's entities.
   * Select the **Mine** tab to search and filter only the entities you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Search for and select the entity from which you want to run the Workflow.
4. From the entity details sidebar, select **Workflows**.\


   ![](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflows-entity-menu.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=f35e61b907fc90be777d6dbcb86a3f0a)
5. Locate the Workflow you want to run, then click **Run**.
   The **Confirm** window opens.
6. Click **Run workflow**.
7. Click the tile to view the recent run.\


   ![The run tile.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/run-tile.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=c68eb5a84ba5a0364cb85412f0c143e1)

## Running a Workflow via the API

You can trigger Workflows programmatically using the [Workflow Runs API](/api/rest/workflows). This is useful for integrating Cortex Workflows into CI/CD pipelines, scripts, and other automation.

**Prerequisites**

1. The Workflow must have **Runnable via API** enabled. See [Enabling API access](/streamline/workflows/publishing-a-workflow#enabling-api-access).
2. The caller must authenticate with a [personal access token](/configure/settings/api-keys/personal-tokens) or a [global API key](/configure/settings/api-keys) that has the `Execute Workflow Runs` permission.

**What you can do via the API**

* Trigger a Workflow run for a global or entity‑scoped Workflow.
* Pass runtime values into Workflow variables using `initialContext`. See step 1-i in [Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings#configuring-workflow-settings).
* Specify the initiating user with `runAs` —required when the Workflow restricts inputs to the initiator, when authenticating with a workspace or global API key, or when the Workflow contains a Scaffolder block. If `runAs` is omitted and an initiator is required, the run pauses and prompts for user selection.
* Notify additional users of run events with `notificationRecipients`.
* Prevent duplicate runs from accidental retries by sending an `Idempotency-Key` header.
* Retrieve a specific run or list runs with filters.

For full request and response details, see the [Workflow Runs API](/api/rest/workflows) reference.

> [!NOTE]
>
> When you check a run's progress through the API, note that the two statuses spell "canceled" differently. A run's `status` is `CANCELLED`, but an individual block's state is `CANCELED`. Match on the right spelling for each.

API‑initiated runs appear on the **Runs** tab alongside UI runs. See [Tracking API‑initiated runs](/streamline/workflows/viewing-workflows#tracking-api-initiated-runs).

## **Running a Workflow with secret user input**

When a Workflow includes a secret user input block, Cortex prompts the user to enter a value and redacts it in the **Outputs** tab. If the block has regex validation configured, the user's input must match the Validation regex set for that block.

The **Outputs** tab shows the secret fields after the Workflow runs, but Cortex redacts the values themselves.

> [!WARNING]
>
> It's possible for users with the `Edit Workflows` permission to obtain secret values using complex data transformation on secrets or echoing services.

## Running a Workflow with list inputs

When a user input collects a list (nested form with the single value data type), the runner can add or remove entries within the configured element count. Number items are validated against the Integer/Decimal format and any minimum or maximum you set, and toggle items are entered as true/false switches.

## Viewing a Workflow run

See the documentation for [viewing a Workflow run](/streamline/workflows/viewing-workflows).

## Canceling a run

Follow the steps below to cancel a run.

> [!NOTE]
>
> Canceling a partially complete run does not impact any blocks that have been successfully completed.

1. On the Workflows page, select the **Runs** tab.
2. Select the run you want to cancel.
3. In the upper-right corner of the page, click **Cancel run**. The run is terminated.\


   ![](https://mintcdn.com/cortex-290c0c42/ZnXiYA63E8Z5w17x/images/cancel-run.png?fit=max\&auto=format\&n=ZnXiYA63E8Z5w17x\&q=85\&s=9c6114c992e4cb54f322bf41c3e489e5)

[Next step: Publishing a Workflow](/streamline/workflows/publishing-a-workflow)

## Troubleshooting and FAQ

> **When trying to run a Workflow, why might I get the 404 error could not find workflow with id: xyz?**
>
> This happens when you have multiple tenants and use an API key from the wrong tenant. Ensure that you are using the correct API key, or create a new API key and try again.

> **Why do I see a 403 Forbidden IP address error when running a Workflow?**
>
> Workflow steps that call the Cortex API fail if the request originates from an IP that isn't on your allowlist. Send a message to [help@cortex.io](mailto:help@cortex.io) if you need further assistance.

> **Why does a Workflow run fail with a message about ownership or team role?**
>
> This happens when the Workflow requires **Require entity ownership**. Only the entity's owner can run it. If **Require team member role** is also on, the owner must additionally hold one of the configured roles on the owning team—holding the role alone, without being the owner, isn't enough. Runs triggered via the API always fail this check if Cortex can't identify the calling user.


# Registering a Scaffolder template
Source: https://docs.cortex.io/streamline/workflows/scaffolder



Cortex's Scaffolder lets you automate project setup through reusable Workflows, creating new repositories and libraries, or adding functionality like CI scripts and infrastructure modules to existing services. Templates handle the boilerplate and plumbing, so new projects follow your team's best practices from day one.

Templating is powered by [Cookiecutter](https://cookiecutter.io), an open-source, industry-standard tool for generating project boilerplate. If you're using GitHub templates and want to convert them to Cookiecutter templates to use within a Cortex Workflow, see [Converting a repo to a Cookiecutter template](/streamline/workflows/scaffolder/convert-template).

> [!TIP]
>
> Looking for a quick introduction to Scaffolder? Check out the Cortex Academy course, [Intro to Scaffolder](https://academy.cortex.io/courses/introduction-to-scaffolder).

This article walks through adding the Scaffolder as a block in a [Workflow](/streamline/workflows). For advanced usage, see [Scaffolder advanced usage](/streamline/workflows/scaffolder/advanced-usage).

![](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scaffolder-page.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=84c5ba86c56f2ffddcc0e2d7da029e23)

## Creating a Scaffolder template

**Prerequisites**

1. A Git integration with `write` access. The following integrations are available:
   1. [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops) - Configure the Azure DevOps token with `Code read, write & manage` access.
   2. [Bitbucket](/ingesting-data-into-cortex/integrations/bitbucket)
      1. Cloud - Configure the Bitbucket token with `Repositories - admin and delete` scopes.
      2. Data Center - Bitbucket Data Center uses `OAuth` for authentication rather than workspace tokens. The configured OAuth credentials must have permissions to:

         1. Read the source repository being cloned
         2. Create a new repository

         These permissions can be granted in several ways, including repository-level permissions or global read/write permissions. Choose the approach that best fits your organization's access policies.
   3. [GitHub](/ingesting-data-into-cortex/integrations/github) - Cortex's GitHub app is pre-configured with permissions for the Scaffolder.
   4. [GitLab](/ingesting-data-into-cortex/integrations/gitlab) - Configure the GitLab access token with `write` permissions.
2. Configure your username's [identity mappings](/configure/settings/managing-users/identity-mapping) for your Git provider.

### Step 1: Creating a Cookiecutter template

Before you can use the Scaffolder, you'll need a [Cookiecutter](https://cookiecutter.io) template. You can use an existing template or create a new one.

#### Using a Cookiecutter template

To get started quickly, you can use an [existing open source template](https://www.cookiecutter.io/templates).

1. Find an open source template and clone the repo.
2. Open your `cookiecutter.json` file, located in the root of the template repository.
3. In the file, add a `version` key and enter the version number. This lets Cortex record the template version used for each project in the Catalog, so you can track which projects are running outdated templates.\


   ```json theme={null}
   {
   "project_name": "My Project",
   "database": ["postgres", "mysql"],
   "version": "0.1.2"
   }
   ```
4. Follow the Cookiecutter instructions to [generate the project](https://cookiecutter.readthedocs.io/en/stable/usage.html#keeping-your-cookiecutters-organized).

> [!WARNING]
>
> **Security restrictions for templates**
>
> On Cortex Cloud, templates run in a restricted environment—network access and syscalls are disabled for security. If your template throws an exception, check that it isn't relying on either of these.
>
> Cortex Server (self-hosted) has no such restrictions.
>
> Python post-generation hooks are supported on Cortex Cloud and Cortex Server. They run in an isolated sandbox with their own restrictions. For details, see [Running Cookiecutter hooks](/streamline/workflows/scaffolder/advanced-usage#running-cookiecutter-hooks).

#### Creating a new Cookiecutter template

To create your own template, follow the [Cookiecutter tutorial](https://cookiecutter.readthedocs.io/en/stable/tutorials/tutorial2.html). Once your template is ready, use the [Cookiecutter documentation](https://cookiecutter.readthedocs.io/en/stable/usage.html#keeping-your-cookiecutters-organized) to generate a project from it.

### Step 2: Adding the template to Cortex

Users with the `Configure Scaffolder Templates` permission can add the Cookiecutter template to Cortex.

1. From the main sidebar, select **Workflows**.
2. In the upper-right corner of the **Workflows** page, click **Register Scaffolder template**.

   ![The 'Register Scaffolder template' button is located in the upper-right corner of the page.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/register-scaffolder-template.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=44e389f7bde575911079891d36974d1e)
3. Configure the template:
   * **Provider** - Select which Git provider you are using.
   * **Name** - Enter a name for the template. This will be seen by developers when they create a service using the template.
   * **Description** - Add a description to help others understand the template's purpose.
   * **Tags** - Optionally, add tags to describe the template. For example, these could help developers understand whether the template is meant to be used for a specific service type, what language it uses, and more.
4. Below **Configuration**, fill in the fields:
   * **Git provider configuration** - Enter the configuration, e.g., `default`
     * By default, the option **Use this configuration for all git operations** is **enabled**. When enabled, Cortex uses the selected configuration for **all** Git operations (e.g., fetching the template details, populating the form options, and creating the new repo or Pull Request). The form options will be filtered to only those organizations or repositories that the selected configuration has access to.
     * With this setting **disabled**, you can use a single Scaffolder template with multiple organizations/configurations. While the selected configuration must still have to access the template's repository, the remaining Git operations will be run dynamically based on the user's form selections. The Scaffolder form options will be populated using data from all configurations. Then, Cortex will automatically use a configuration with access to the selected organization (if scaffolding a new repository) or repository (if scaffolding a new PR) for all remaining Git operations.
   * **Git URL** - Enter the git URL where your template lives, e.g. `https://github.com/cortexapps/cookiecutter-employee`
   * **Git ref** (optional) - Enter a git ref (branch name, tag, or commit SHA) to pin the template to a specific version of the repository. For example, entering v1.0.0 will always pull the template as it existed at that tag, regardless of subsequent changes to the default branch. If left blank, the template will pull from the default branch.
   * **Subdirectory for Cookiecutter template** (optional) - If your Cookiecutter template is not stored at the root of your repository, enter the subdirectory URL here.
   * **Configuration requirements** - Select one of the following:
     * **New service**. Cortex service descriptor will be generated for the service and it will be automatically added to relevant catalogs.
       * If you don't select this option, you will still have the option to create a service entity when running the Scaffolder.
     * **New pull request**. When enabled, the template can only be used to open pull requests against existing repositories.
     * **Both**. Enable both "New service" and "New pull request" configurations.
     * **Neither**. Disable both "New service" and "New pull request" configurations.
   * **Visibility** - When creating a new repository choose the default visibility of the repository. If you do not specify, the template defaults to setting a new repository as private.
     * The available options depend on the Git provider. The `Public` setting only works if the org containing the repository allows it. The `Internal` setting only works for GitHub Enterprise accounts.
     * When running a Workflow that contains a Scaffolder block, you can configure an override to change the repo visibility.
   * **Create cortex.yaml in git when creating a new service** - When enabled, a cortex.yaml will be created in git when the Scaffolder creates a new service.
     * If you don't enable this setting, the entity descriptor will be added via the API.
   * **Show README.md during Scaffolding** - When enabled, the project's README.md will be displayed when inputting the variables to use while rendering the template. If there is no README.md, nothing will be shown.
5. Click **Register Scaffolder template**.

If you see a "Failed to save template" error, ensure that you have provided a valid Git URL.

### Step 3: Create a Workflow with a Scaffolder step

After you have added a template to Cortex, you can start using the Scaffolder in a [Workflow](/streamline/workflows).

Follow the instructions in the [Workflows documentation](/streamline/workflows) for creating a Workflow and adding a Scaffolder block.

> [!TIP]
>
> If your Scaffolder template requires input variables, you can configure overrides in your [Workflow's Scaffolder block](/streamline/workflows/blocks#scaffolder). This allows you to use output from previous Workflow steps as the responses to the template. To streamline the process and avoid extra prompts, you can add a [User Input block](/streamline/workflows/blocks#user-input) before the Scaffolder to collect responses that will be used in the Scaffolder template.
>
> See an end-to-end Scaffolder Workflow example in [Scaffolding a new service with custom data based on user input](/guides/production-readiness/standardize-new-service-creation).

## View Scaffolder templates

View all templates available to your organization under [**Workflows > Scaffolders**](https://app.getcortexapp.com/admin/workflows?activeTab=scaffolders).

The template's [Cortex ID (CID)](/ingesting-data-into-cortex/entities-overview/entities#cortex-id) can be found at the top of the page while editing the Scaffolder template:

![The CID is at the top of the Scaffolder template editing page.](https://mintcdn.com/cortex-290c0c42/TKBM5XkYAo_gc56V/images/scaffolder-cid.jpg?fit=max\&auto=format\&n=TKBM5XkYAo_gc56V\&q=85\&s=6fddc6bdcc78cc5e67e486a7b2284e77)

## Troubleshooting and FAQ

See frequently asked questions below.

> **When running a Scaffolder and choosing from my list of Azure DevOps projects, some projects aren't appearing as expected**
>
> This can happen if you have enabled the option **Use this configuration for all git operations** when [configuring your template in Cortex](/streamline/workflows/scaffolder#step-2-adding-the-template-to-cortex). Disable this setting for the ability to choose from all configurations.

> **My Scaffolder block fails after I added a hook to my template**
>
> Hooks run in a sandbox that can't access the network, run shell commands, read environment variables, or reach files outside the generated project. A hook that relies on any of these, creates a symbolic link, or exits with an error fails the block. See [Running Cookiecutter hooks](/streamline/workflows/scaffolder/advanced-usage#running-cookiecutter-hooks) for what's supported.

> **When running a Scaffolder Workflow that pushes template files to a newly created repository, the Workflow completes successfully, but no files appear in the repository**
>
> This occurs when the branch name entered during the Scaffolder run does not match the default branch configured in your Git provider. For GitLab, Azure DevOps, and Bitbucket, the branch specified must match the repository's default branch (typically `main` or `master`). If it does not match, the Workflow will report successful completion but template files will not be pushed to the new repository.

> **Scaffolding Workflow appears stuck with no error**
>
> Scaffolder runs might hang without surfacing an error when cloning large repositories or monorepos to open a pull request. Enabling sparse checkout can resolve this by cloning the repository without retrieving all of its git object data. This option is effective when a Scaffolder run only creates new files; if it needs to modify or delete existing files, use the standard clone path instead.
>
> How to recognize the issue:
>
> * The scaffolding step runs for around 5 minutes and then terminates. This is the clone timeout — if the operation doesn't complete within that window, it's cancelled.
> * The run fails with exit code 137, which indicates the process was killed by the system (typically due to memory pressure).
> * The target repository is large. You can measure it with `git count-objects -v`.
>
> If you run into any of these issues, it's recommended that you toggle on the sparse checkout option in your Scaffolder template:
>
> 1. From the main sidebar, select **Workflows**.
> 2. Select the **Scaffolders** tab.
> 3. On the **Scaffolders** page, locate the template, then click the **pencil icon** next it.
> 4. Toggle on **Enable sparse checkout**.
> 5. Click **Update Scaffolder**.


# Scaffolder advanced usage
Source: https://docs.cortex.io/streamline/workflows/scaffolder/advanced-usage



This article describes advanced features you can use with a Scaffolder block in a [Workflow](/streamline/workflows): Customizing the autogenerated `cortex.yaml`, running Cookiecutter hooks, building complex templates that use inputs collected by Cortex, building templates that add to existing services, and more.

## Repository cloning behavior

When running a Cookiecutter template, Cortex performs a shallow clone of the template's source repository. A shallow clone fetches the entire repository tree, but only at the current `HEAD` commit— not the full history.

Behavior on the target side depends on the run type. When a Scaffolder run creates a new repository, Cortex provisions it directly—no clone of an existing target is involved. When a run opens a pull request against an existing repository, Cortex clones that target repository with a shallow clone of the entire repository. Sparse checkout on the target can be used when the run produces only additive changes, i.e. new files only, with no updates or deletions to existing files, since only the paths being added need to be materialized.

## Templates that add to existing services

A powerful workflow that the Scaffolder unlocks is the ability to templatize code to be added to *existing* services – for example, you may want templates that developers can use to add Terraform modules, CI pipelines, or build/deploy scripts to a service that's already been built.

To do so, you'll want to create a template that generates the file or directory you'd like to add to your existing service, and enable the PR-only toggle when adding the template to your workspace.

Keep in mind that your template *always* needs to generate a directory as expected by cookiecutter.

> [!NOTE]
>
> The Scaffolder merges files with a recursive copy. If your template generates files or directories that already exist in the target repo, Cortex will *not* attempt to merge the content of the files. Instead, we do a recursive copy, replacing any files that exist in the target.

### Root-level files

If you're trying to add files to the root of an existing service, your template should generate the files at the root of the generated directory. Keep in mind that you can use template variables for the filenames as well.

The expected file structure of your template would be:

```
(template-folder)$ ls -l
cookiecutter.json
{}/
    {}-generated-file.js
    my-file-to-generate.yml
```

Note that the files live under a nested, templated directory. When we open a PR, the PR will still only contain the two nested files at the *root of the PR*. Essentially, the PR will be:

```
{}-generated-file.js
my-file-to-generate.yml
```

### Directories

If you're looking to generate a directory, the template should *generate* the desired directory as the output. Although `cookiecutter` by default generates the output of the entire template into a directory, the PR feature copies output of the template out of the generated directory into the root (recursively).

For example, if you want your template to generate the directory `infra-files-{}` (or generate a file into this directory), your structure should look like:

```
(template folder)$ ls -l
cookiecutter.json
{}/
    infra-files-{}/
        my-generated-file.json
```

Note that you can use templated variables when generating the directory name or files in the directory.

## Overriding the autogenerated Service Descriptor

By default, the Scaffolder generates an [entity descriptor file](/ingesting-data-into-cortex/entities-overview/entities#defining-entities-via-yaml-file) named `cortex.yaml` in the root of the repository when used to create a service. This file contains some basic information which the user inputs during the flow such as [entity ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership), [groups](/ingesting-data-into-cortex/entities-overview/entities/groups), and [external docs](/ingesting-data-into-cortex/entities-overview/entities/external-docs).

In some cases, you may want to generate your own Service Descriptor. This may because you want to add [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data), auto-generate groups based on the template they've selected, add placeholder links, or other such advanced use cases.

To override the Service Descriptor generated by Cortex, just include a `cortex.yaml` or `cortex.yml` file in the template. If Cortex detects that the template has generated either one of these files, the Scaffolder will skip the Service Descriptor generation step.

## Running Cookiecutter hooks

[Cookiecutter hooks](https://cookiecutter.readthedocs.io/en/stable/advanced/hooks.html) are scripts that run as part of generating a project. The Scaffolder supports Python post-generation hooks, so you can clean up or adjust the generated project before Cortex creates the repository or opens the pull request. For example, a hook can remove files and directories that don't apply to the options a user selected.

Hooks run when a template is used in a Scaffolder block in a Workflow, for templates that create a new repository and templates that open a pull request. Templates without hooks aren't affected.

### Adding a post-generation hook

1. In the root of your template repository, next to `cookiecutter.json`, create a `hooks` directory.
2. In the `hooks` directory, add a file named `post_gen_project.py`.
3. Write the hook in Python. The hook runs from the root of the generated project, and you can reference template variables with Cookiecutter's `{{ cookiecutter.<variable> }}` syntax.

Your template structure should look like this:

```
(template-folder)$ tree
cookiecutter.json
hooks/
    post_gen_project.py
{{cookiecutter.project_slug}}/
    Dockerfile
    docker/
    ...
```

For example, this hook removes the Docker files when the user doesn't need them:

```python theme={null}
import os
import shutil

if "{{ cookiecutter.use_docker }}" != "yes":
    os.remove("Dockerfile")
    shutil.rmtree("docker")
```

### Supported hooks

* **Supported** - `post_gen_project.py` hooks written in Python.
* **Skipped** - `pre_prompt` and `pre_gen_project` hooks, and hooks that aren't Python files (for example, `post_gen_project.sh`). The Scaffolder ignores these hooks, and the run continues without them.

### Hook restrictions

Hooks run in an isolated sandbox that can only read and write files inside the generated project. A hook can't:

* Access files outside the generated project.
* Make network requests.
* Run shell commands or start other processes, for example with `subprocess` or `os.system`.
* Read environment variables.
* Install packages. Use the Python standard library instead.

### When a hook fails

If a hook exits with an error, creates a symbolic link, or exceeds its time or memory limit, the Scaffolder block fails. Cortex doesn't create the repository or open the pull request, so no partial output is published. Fix the hook in your template repository, then run the Workflow again.

## Hiding template variables in the UI

As the complexity of your template grows, you may have variables in your `cookiecutter.json` that you want to hide from the UI, for example if they're autogenerated using Python or they're not something you want users to override at all.

To hide fields, just add a `@cortex_hidden_keys` field containing a list of variables you want to hide.

```json theme={null}
{
    "project_name": "My Project",
    "project_slug": "{}",
    "@cortex_hidden_keys": ["project_slug"],
    "version": "0.0.1"
}
```

We hide the `version` key by default, so you don't need to add that to the list!

If you have "private variables" (variables starting with `_`, such as `"_my_secret_variable"`), they will automatically be hidden from the UI.

## Consuming Cortex fields in a template

The Cortex Scaffolder flow requires users to input additional information aside from the fields defined in the `cookiecutter.json` file when creating a service. This includes:

* Git repository details
* Ownership
* [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag)
* [Groups](/ingesting-data-into-cortex/entities-overview/entities/groups)
* Dependencies
* Template details

You may want your template to use this information, without duplicating these fields in your `cookiecutter.json` and having developers fill out the information twice! For example, you may want to use the name of the git repo that's created while generating a deployment script in the template.

These fields are available to your template in a magic `_@cortex_inputs` variable.

### The `_@cortex_inputs` variable

The structure of `_@cortex_inputs` is a dictionary that will always contain the following:

```json theme={null}
{
  "git": , // varies based on git provider, see below
  "user": ,
  "template_details": 
}
```

See below for details on the `git` object, which contains information on the repository that Cortex is creating for the new project.

> [!NOTE]
>
> You can access this variable in your template the same way you do for any of your own variables: `{}`.

If your template has the **"Requires a new service"** flag enabled, `_@cortex_inputs` will additionally contain the following:

```json theme={null}
{
  "service_details": {
    "tag": "my-service",
    "name": "My Service",
    "description": "Optional description if defined",
    "owners": [
      ,
      ,
      
    ],
    "serviceGroups": ["list", "of", "groups"],
    "dependencies": [
        ,
        ,
        
    ]
  }
}
```

**Git details**

The git object shown above is different based on the provider you're using. The structure is shown below.

**GitHub**

```json theme={null}
{
  "git": {
    "repository": 
  }
}
```

**GitLab**

```json theme={null}
{
  "git": {
    "repository": 
  }
}
```

**Bitbucket**

```json theme={null}
{
  "git": {
    "repository": 
  }
}
```

**Azure DevOps**

```json theme={null}
{
  "git": {
    "repository": 
  }
}
```

## Extending Cookiecutter: Cortex field configurations

You can add metadata to each variable that Cortex will display during the scaffolding process.

### Adding descriptions and placeholders to inputs

To help guide users during scaffolding, you can configure input fields with:

* a description (appears beneath the input field)
* a placeholder (appears inside the input box before the user types anything)

These are defined in the `_cortex_field_configurations` object in your `cookiecutter.json`.

Here's an example `cookiecutter.json`, where `full_name` is an input consumed by the template. We've defined `_cortex_field_configurations` to add a description and a placeholder to the UI field for `full_name`.

```json theme={null}
{
  "full_name": "Albert Einstein",
  "_cortex_field_configurations": {
    "full_name": {
      "description": "Enter the full name of the new team member",
      "placeholder": "e.g., Jane Doe"
    }
  }
}
```

> [!NOTE]
>
> The `use_default` key is no longer supported. While default values (like `"Albert Einstein"`) can still be defined in your template, they will not be surfaced in the UI unless manually entered by the user.


# Convert a GitHub repo to a Cookiecutter template
Source: https://docs.cortex.io/streamline/workflows/scaffolder/convert-template



If you are using GitHub templates to standardize your service creation, it is possible to convert the templates for use within a [Cortex Workflow](/streamline/workflows).
This guide explains how to convert a GitHub repository template into a [Cookiecutter](https://www.cookiecutter.io/) template, enabling a more efficient process when you scaffold the repository from a Workflow.

In this guide, assume the repository has the following structure:

```json theme={null}
Dockerfile
ReadMe
pipeline.yaml
/App
   |- App.py
```

## How to convert a GitHub template to a Cookiecutter template

1. Clone the existing GitHub repository locally.
2. Create a cookiecutter.json file, including the basic inputs needed from the user, other fields that will be used in the template, and the version (required). For example:

```json theme={null}
{
	"project_name":"my project",
	"author":"author@example.com",
	"version": 0.1.0
}
```

3. Create a base folder with a name similar to:

   `{{ cookiecutter.project_name }}`
4. Move the contents of the repo into to folder you created in Step 3. For example:

```json theme={null}
/{{cookiecutter.project_name}}
    |- Dockerfile
    |- ReadMe
    |- pipeline.yaml
    |- App
         |- App.py
cookiecutter.json
```

5. In each of the files and folders, replace existing fields with the corresponding Cookiecutter fields.
   * For example, a Dockerfile may include the line `MAINTAINER  author@example.com`. This can be changed to the following:

```json theme={null}
MAINTAINER  {{cookiecutter.author}}
```

6. Optionally, add content to the README in the repository to document what the Cookiecutter template does.
   * When [registering a Scaffolder template](/streamline/workflows/scaffolder/convert-template), you can choose whether to display the README in Cortex when running a Scaffolder block in a Workflow.

### Handling existing mustache templating in a repository file

You may have files that already contain mustache templating. In an instance where you do not want these interpreted as Cookiecutter fields, you can escape the curly braces, as described in [Cookiecutter's troubleshooting docs here](https://cookiecutter.readthedocs.io/en/stable/troubleshooting.html?utm_source=chatgpt.com).


# Viewing Workflows
Source: https://docs.cortex.io/streamline/workflows/viewing-workflows



Workflows let you automate sequential actions and development processes using contextual data from your workspace. Workflows can be simple, like granting database permissions, or sophisticated, like creating a Jira ticket for an incident detected in Cortex.

## Viewing the Workflows page

Users with the `View Workflows` permission can view existing Workflows.

The Workflows page can be accessed from the main sidebar.

In the **Workflows** tab, view existing Workflows, including each Workflow's name and description. Use the tabs at the top of the list to filter what you see. Each tab shows a count of the Workflows in it:

* **All** - All Workflows in your workspace.
* **Mine** - Workflows you can edit, including ones you created, ones created by a team you're on, and ones you've been given edit access to.
* **Pinned** - All pinned Workflows in a single list, regardless of folder. Each Workflow's folder path appears under its name.

From this page, you can create, edit, run, duplicate, share, or delete a Workflow. You can also move a Workflow into a folder.

![The 'Overflow' icon on the Workflows page.](https://mintcdn.com/cortex-290c0c42/-1_HUDGuJeASw2vp/images/workflows-overflow-icon.png?fit=max\&auto=format\&n=-1_HUDGuJeASw2vp\&q=85\&s=6a5a86dd4a2a16a0ee5e90bf3c06c06c)

> [!NOTE]
>
> The options in the overflow menu depend on whether you open it for a Workflow or a folder. For folder options, see [Managing a folder](/streamline/workflows/viewing-workflows#managing-a-folder).

If a Workflow is in draft mode, a **draft icon** appears next to its name:

![The 'Draft' icon next to a Workflow's name.](https://mintcdn.com/cortex-290c0c42/-1_HUDGuJeASw2vp/images/workflows-draft-icon.png?fit=max\&auto=format\&n=-1_HUDGuJeASw2vp\&q=85\&s=92d5d13c84f10c0866d59f2e1566f4c2)

If a Workflow is managed via [GitOps](/streamline/workflows/workflows-as-code), a **Git icon** appears next to its name:

![The 'Gitt' icon next to a Workflow's name.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/gitops-managed-workflow.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=26842e94c52b96264b1a8e75fd69c403)

Click the **pin icon** next to a Workflow to pin it. Pinned Workflows appear at the top of the **All** and **Mine** tabs, and in the **Pinned** tab:

![The 'Pin' icon.](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflows-pin-icon.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=f0777647c1c40e3b0fb93913487d0154)

### Linking directly to a Workflow

You can link directly to any Workflow using its tag. This is useful when you share a Workflow in docs, runbooks, or Slack, or when you build links in scripts and other tooling.

Use the following URL format, replacing `<WORKFLOW_TAG>` with the Workflow's tag:

```text theme={null}
https://app.getcortexapp.com/admin/workflows/<WORKFLOW_TAG>
```

For example, a Workflow with the tag `provision-replicas` opens at `https://app.getcortexapp.com/admin/workflows/provision-replicas`.

A Workflow's tag is the **Slug** in its [Workflow settings](/streamline/workflows/configuring-workflow-settings) and the `tag` field in its [Workflow YAML](/streamline/workflows/workflows-as-code). The [Workflows API](/api/rest/workflows) also returns each Workflow's `tag`, so scripts can build links without an extra lookup.

> [!NOTE]
>
> If your Cortex workspace is in the EU region, or you're using a self-managed Cortex instance, replace `app.getcortexapp.com` with your Cortex domain. For example:
>
> * **EU region** - `https://app.eu.cortex.io/admin/workflows/provision-replicas`
> * **Self-managed** - `https://app.cortex.your-org-name.com/admin/workflows/provision-replicas`

## Organizing Workflows into folders

Users with the `Edit Workflows` permission can create and organize Workflow folders.

Folders let you group related Workflows so the Workflows page stays organized as your library grows. You can create folders, nest subfolders inside them, and move Workflows between folders. You can also add a Workflow to a folder when you [create it](/streamline/workflows/create#creating-a-workflow).

Folders appear at the top of the Workflows list. Click a folder to expand it and view the Workflows and subfolders inside. To open or close every folder at once, click **Expand all** or **Collapse all** in the list header:

![Folders at the top of the Workflows list.](https://mintcdn.com/cortex-290c0c42/-1_HUDGuJeASw2vp/images/workflows-folders.png?fit=max\&auto=format\&n=-1_HUDGuJeASw2vp\&q=85\&s=b77b640550ba6654114c47a9977737db)

### Creating a folder

1. From the main sidebar, select **Workflows**.
2. On the Workflows page, click **New folder**. The **New folder** window opens.\

3. Do the following:
   1. Under **Folder name**, enter a descriptive name for the folder (required).
   2. Under **Description**, add an overview of the folder.
   3. From the **Parent folder** drop-down, select **Root** to create a top-level folder, or select an existing folder to nest the new folder inside it.
   4. Under **Display icon**, click **Edit** to choose an icon that visually represents the folder.
4. Click **Create**.

### Moving a Workflow into a folder

1. From the main sidebar, select **Workflows**.
2. On the Workflows page, locate the Workflow you want to move.
3. Click the **overflow menu icon** next to it, then select **Move to folder**. The **Move workflow** window opens.
4. From the **Destination** dropdown, select the destination folder.
5. Click **Move**.

### Managing a folder

1. From the main sidebar, select **Workflows**.
2. On the Workflows page, locate the folder you want to manage.
3. Click the **overflow menu icon** next to it.
4. Select any of the following:
   * **Add subfolder here** - Create a subfolder inside the selected folder
   * **Edit** - Change the folder's name, icon, description, or parent folder
   * **Move to folder** - Move the folder and its contents into another folder
   * **Delete** - Delete the folder

## Viewing Workflow runs

Users with the `View Workflow Runs` permission can view past Workflow runs.

On the Workflows page, select the **Runs** tab to view runs for each Workflow.

![The 'Runs' tab shows a list of recently run Workflows.](https://mintcdn.com/cortex-290c0c42/-1_HUDGuJeASw2vp/images/workflows-runs-tab.png?fit=max\&auto=format\&n=-1_HUDGuJeASw2vp\&q=85\&s=b6d8ed652c657bc2fac84332427f473a)

Select a run to see more information about it, including its status: `In Progress`, `Paused`, `Successful`, `Canceled`, or `Error`. While in the run, click **View flowchart** in the upper-right corner to view the entire Workflow step-by-step.

**Filtering and sharing**

On the Workflows page, click the **Filter icon** to narrow your results, or the **Share icon** to copy a link to the **Runs** page that you can send to your team.

**Approvals**

On the Workflows page, select the **Waiting for approval** tab to view runs that are awaiting your approval. Note that this tab is only visible if a run is waiting for your approval.

**Run history and retention**

For auditing and debugging, Cortex stores run history, including the initiator, run context, and the inputs and outputs of each action, for 30 days. Runs from deleted Workflows are not displayed.

### **Inspecting a workflow run**

Run history is available from the Workflows page or the entity page where the workflow was run. Click a specific run to open the view, which shows:

* **Run context** - The static context values used during execution, such as `context.entity`, `context.secrets`, and `context.initiatedBy`.
* **Inputs and outputs** - The data passed into each block and the results returned.

To inspect a specific step, click any block in the visual to view its input and output payloads and execution status.

### **Tracking API‑initiated runs**

Runs triggered through the [Workflow Runs API](/api/rest/workflows) appear on the **Runs** tab alongside runs started from the UI, marked with a **key icon** next to the initiator's name.

Runs that failed to initiate via the API appear on the **Failures** tab. Click **View details** on a failed entry to see the error. Note that the **Failures** tab only appears when there are failed runs.

## Viewing Scaffolder templates

Users with the `View Workflows` permission can view Scaffolder templates on the Workflows page.

On the Workflows page, select the **Scaffolders** tab to view, edit, or delete registered Scaffolder templates.

![The 'Scaffolders' tab shows a list of Scaffolder templates used in your Workflows.](https://mintcdn.com/cortex-290c0c42/-1_HUDGuJeASw2vp/images/workflows-scaffolder-tab.png?fit=max\&auto=format\&n=-1_HUDGuJeASw2vp\&q=85\&s=954d4736c328fa4bfd9fccdcc28f4d65)

To preview a Scaffolder template, click the **preview icon** next to it:

![The 'Preview' icon next to a Scaffolder template.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scaffolder-preview-icon.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=10c699e18e99b467d9e63101a3fdab92)

To edit a template, click the **pencil icon** next to it:

![The 'Pencil' icon next to a Scaffolder template.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scaffolder-pencil-icon.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=5f5f4be8bc5789b51c771d3317c2fa6c)

To create a Workflow that contains a Scaffolder step with a particular template, click the **rocket ship icon** next to it:

![The 'Rocket ship' icon next to a Scaffolder template.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scaffolder-rocket-ship.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=c1482dac3bad763e1e0e409b22d6a407)

To delete a Scaffolder template, click the **trash icon** next to it:

![The 'Trash' icon next to a Scaffolder template.](https://mintcdn.com/cortex-290c0c42/GZStB8YvzgOc1dXn/images/scaffolder-trash-icon.png?fit=max\&auto=format\&n=GZStB8YvzgOc1dXn\&q=85\&s=d607f2a184c2256a07a50ac522180f10)


# Workflows as code
Source: https://docs.cortex.io/streamline/workflows/workflows-as-code



Workflows allow you to run sequential actions and increase efficiency across development workflows. With Workflows as code, you can treat Workflows like other production asset; this feature allows you to manage Workflows through [GitOps](/configure/gitops). Each Workflow has its own YAML file.

When GitOps is enabled, changes made to Workflows will appear in [GitOps logs](/configure/gitops/gitops-logs).

## Managing Workflows in both GitOps and the Cortex UI

When you enable GitOps editing for Workflows, it only affects Workflows that are backed by a YAML file. You can still create and delete Workflows via the Cortex UI, and you can still edit a Workflow via the UI if it's not managed via GitOps.

### Step 1: Configuring GitOps editing for Workflows

Users with the `Edit Workflows` permission can configure GitOps editing in Cortex.

> [!WARNING]
>
> Enabling GitOps editing for Workflows only affects Workflows backed by a YAML file. You can still create and delete Workflows via the Cortex UI.

1. From the main sidebar, click your avatar in the bottom-left corner.
2. Click **Settings**.
3. From the **Settings** menu, locate the **Workspace** section, then click **GitOps**.
4. Select the **Workflows** tab.
5. Toggle on **Enable GitOps for Workflows editing**.
6. Optionally, under **Workflow GitOps repository allowlist**, specify which repositories to import Workflows from. See [configuring an allowlist](/configure/settings/gitops-settings#gitops-workflow-settings) for more information.
7. Select the the **Entities** tab.
8. Under **Processing**, toggle on **Cortex YAML processing**.

### Step 2: Creating a YAML file for the Workflow

**Prerequisites**

1. You must have the `Edit Workflows` permission.
2. An existing Workflow. If you haven't yet created a Workflow, refer to [Creating a Workflow](/streamline/workflows/create) and [Configuring Workflow settings](/streamline/workflows/configuring-workflow-settings).

Workflow YAML files must be stored in their own repository, separate from catalog entities, under `.cortex/workflows` at the repository root. You can organize the files into subdirectories, which Cortex searches recursively.

The Workflow YAML uses the same data structure as [Cortex's Workflow API](/api/rest/workflows). For the fields each block takes, see the [Workflow block configuration reference](/streamline/workflows/blocks/block-configuration-reference).

You can create a Workflow configuration from scratch, or you can start in the Cortex UI and export the Workflow to a YAML file.

GitOps editing applies only to Workflows that are backed by a YAML file, so you can continue to create, edit, and delete other Workflows in the Cortex UI. For more information, refer to [Using both the UI and GitOps](/configure/gitops#using-both-ui-and-gitops).

**To export a Workflow to a YAML file in Cortex**:

1. From the main sidebar, select **Workflows**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's Workflows.
   * Select the **Mine** tab to search and filter only the Workflows you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow, then click the **overflow menu icon** next to it.\


   ![The 'Overflow menu' icon next to a Workflow.](https://mintcdn.com/cortex-290c0c42/JcmXgfdiEzZzqS2M/images/workflows-overflow.png?fit=max\&auto=format\&n=JcmXgfdiEzZzqS2M\&q=85\&s=86698867dbd3391ff36ee5119662b38c)
4. Select **Edit Workflow**.
5. At the top of the Workflow, click the **Overflow menu.**
6. Select **Export Workflow YAML**.\


   ![The 'Export Workflow YAML' option.](https://mintcdn.com/cortex-290c0c42/kB9I5hpwwMkz0yx1/images/export-workflow-yaml.png?fit=max\&auto=format\&n=kB9I5hpwwMkz0yx1\&q=85\&s=12ae55c63f3b8e98116b6c416fa9250c)
7. The YAML is downloaded and saved to your computer.
8. Add the YAML file to your Git repository within `.cortex/workflows`.

#### Example Workflow YAML

A **nested form** input is a `NESTED_FORM_FIELD` on a `USER_INPUT` action under `schema.inputs`. When the data type is a single value, the item is described by a nested `element` object: set its `type` (for example, `NUMBER_FIELD`) and, for numbers, a `format` of `INTEGER` or `DECIMAL`, along with optional per-item `min`, `max`, `placeholder`, and `defaultValue`. The field's top-level `itemType` summarizes the item type. The outer `min` and `max` set the number of items the runner can enter ( `min` defaults to 1 and also serves as the default count) while `element.min` and `element.max` bound each individual value.

Other item types use the same structure with a different `element.type` and `itemType`.

**Example YAML (single value, number / integer)**

```yaml theme={null}
name: Provision replicas
tag: provision-replicas
description: null
isDraft: true
filter:
  type: GLOBAL
isRunnableViaApi: false
actions:
- name: Get deployments
  slug: get-deployments
  schema:
    inputs:
    - name: Replica counts
      description: null
      key: replica-counts
      required: false
      disabled: false
      element:                 # describes each item (present for "Single value")
        name: Replica counts
        description: null
        key: replica-counts
        required: false
        disabled: false
        defaultValue: null
        placeholder: null
        format: INTEGER        # INTEGER or DECIMAL (NUMBER_FIELD only)
        min: null              # per-item minimum value
        max: null              # per-item maximum value
        type: NUMBER_FIELD     # item value type
      min: 1                   # min number of items (element count); also the default count
      max: null                # max number of items (element count)
      itemType: INTEGER        # summary of the item type
      type: NESTED_FORM_FIELD
    inputOverrides: []
    jsValidatorScript: ""
    type: USER_INPUT
  outgoingActions: []
  isRootAction: true
runRestrictionPolicies: []
iconTag: null
variables: []
```

**A note about the example Workflow YAML**

* `itemType` sets the item type. It defaults to `OBJECT`; other values (for example `STRING` or `INTEGER`) make each item a single value.
* With `itemType: OBJECT`, the nested form is a sub-form. Define one or more sub-inputs per row.
* With a single-value `itemType`, the item is described by the nested `element` object—its `type` and type-specific options such as `format` for numbers or `validationRegex` for text. There is no separate `inputs` list on the field.
* `min` and `max` are optional element-count limits and apply to every `itemType`. `min` defaults to 1 and also acts as the default number of rows.
* `name`, `description`, `key`, and `required` apply to the field for every `itemType`. `inputOverrides` and `jsValidatorScript` are set at the `schema` level, not on the field.

**Item type reference**

| Value type | element.type | itemType |
| - | - | - |
| Text | `INPUT_FIELD` | `STRING` |
| Paragraph | `TEXTAREA_FIELD` | `STRING` |
| Number (Integer) | `NUMBER_FIELD` + `format: INTEGER` | `INTEGER` |
| Number (Decimal) | `NUMBER_FIELD` + `format: DECIMAL` | `DECIMAL` |
| Toggle | `TOGGLE_FIELD` | `BOOLEAN` |
| Date | `DATE_FIELD` | `STRING` |

`element` also carries type-specific keys, i.e. `NUMBER_FIELD` adds format (`INTEGER`/`DECIMAL`) plus min/max; text types add `validationRegex`. For the default Object data type, the field uses a list of sub-field definitions instead of a single element.

#### Example Run Workflow block YAML

A **Run Workflow** block uses `type: RUN_WORKFLOW` under `schema`. `inputs` maps each of the child Workflow's variable slugs to a value or a template, and `waitForCompletion` makes the block wait for the child run to finish.

```yaml theme={null}
- name: Run approval
  slug: run-approval
  schema:
    type: RUN_WORKFLOW
    workflowId: approval-workflow
    waitForCompletion: true
    inputs:
      app-id: "{{actions.form.outputs.appId}}"
      count: 5
```

Values keep the child variable's type, so `count: 5` is passed as a number. If the child Workflow has no variables, set `inputs: {}`.

## Editing GitOps-managed Workflows in Cortex

Users with the `Edit Workflows` permission can duplicate and edit Workflows in Cortex.

GitOps-managed Workflows are read-only in the Cortex UI. To modify one, create a duplicate, edit the copy, and use it as your primary Workflow going forward.

The UI displays a link to the Workflow's YAML file in your repository:

![The 'Repo' icon in the upper-right corner of a Workflow.](https://mintcdn.com/cortex-290c0c42/GdCQ7wvPeVXdjHh5/images/workflow-repo-link.jpg?fit=max\&auto=format\&n=GdCQ7wvPeVXdjHh5\&q=85\&s=4c10553e634d403e41f6168355d86213)

1. From the main sidebar, select **Workflows**.
2. Do one of the following:
   * Select the **All** tab to search and filter across all of your organization's Workflows.
   * Select the **Mine** tab to search and filter only the Workflows you own.
   * Note that Cortex saves your selection and restores it the next time you open this page.
3. Locate the Workflow, then click the **overflow menu icon** next to it.
4. Select **Duplicate Workflow**.
5. Click **Duplicate workflow**.

   The Workflow is duplicated and a copy is added to the main Workflows page.
6. To edit the new Workflow, do one of the following:
   1. Click **Edit Workflow** in the toast notification that appears in the bottom-right corner.
   2. Locate the Workflow, click the **Overflow menu** next to it, then select **Edit Workflow**.
7. Make any necessary changes.
8. Save the Workflow.

A **Git icon** next to a Workflow's name indicates that it's managed via GitOps:

![The 'Git' icon next to a Workflow's name.](https://mintcdn.com/cortex-290c0c42/OnaYqLHqq-U_XM2R/images/gitops-managed-workflow.jpg?fit=max\&auto=format\&n=OnaYqLHqq-U_XM2R\&q=85\&s=26842e94c52b96264b1a8e75fd69c403)


# Styling plugins with theme tokens
Source: https://docs.cortex.io/styling-plugins-with-theme-tokens



This article covers styling your plugin with theme tokens, the CSS variables Cortex passes to plugins so they match the look and feel of the rest of the product. Tokens reflect the current user's theme, including custom brand colors and light or dark mode.

## Setting up theming in your plugin

> Plugins created from the [plugin template](https://github.com/cortexapps/cookiecutter-cortex-plugin) are already set up for theming. Skip to [Using theme tokens](#using-theme-tokens).

To set up theming in a plugin:

1. Install `@cortexapps/plugin-core` and `@cortexapps/react-plugin-ui`.
2. Import `@cortexapps/react-plugin-ui/index.css` in your entry file.
3. Call `CortexApi.pluginInit()` before rendering your app, so the theme arrives before your plugin renders.
4. Wrap your app in `<PluginProvider>` from `@cortexapps/plugin-core/components`. See the template's [App.tsx](https://github.com/cortexapps/cookiecutter-cortex-plugin/blob/master/%7B%7Bcookiecutter.project_name%7D%7D/src/components/App.tsx) for an example.

```tsx theme={null}
import { createRoot } from "react-dom/client";
import { CortexApi } from "@cortexapps/plugin-core";
import "@cortexapps/react-plugin-ui/index.css";
import App from "./components/App";

document.addEventListener("DOMContentLoaded", () => {
  // request the theme from Cortex and subscribe to theme changes
  CortexApi.pluginInit();

  createRoot(document.getElementById("cortex-plugin-root")!).render(<App />);
});
```

If the tokens aren't applied, make sure `@cortexapps/plugin-core` is up to date, `CortexApi.pluginInit()` is called before your app renders and your app is wrapped in `<PluginProvider>`.

## Theme token reference

The following tokens are available to your plugin.

| Token | Use |
| :- | :- |
| `--cortex-plugin-background` | Page background |
| `--cortex-plugin-foreground` | Default text |
| `--cortex-plugin-primary` | Primary actions and highlights |
| `--cortex-plugin-secondary` | Secondary buttons and surfaces |
| `--cortex-plugin-muted` | Subdued backgrounds and secondary text |
| `--cortex-plugin-accent` | Hover and highlight states |
| `--cortex-plugin-accent-foreground` | Text on accent backgrounds |
| `--cortex-plugin-destructive` | Error backgrounds |
| `--cortex-plugin-destructive-foreground` | Text on error backgrounds |
| `--cortex-plugin-border` | Borders and dividers |
| `--cortex-plugin-input` | Input fields |
| `--cortex-plugin-ring` | Focus rings |

## Using theme tokens

Reference a token anywhere you would use a color value. For example, in CSS:

```css theme={null}
.panel {
  background-color: var(--cortex-plugin-background);
  color: var(--cortex-plugin-foreground);
  border: 1px solid var(--cortex-plugin-border);
}
```

If you use Tailwind, reference tokens with arbitrary values:

```tsx theme={null}
<div className="bg-[var(--cortex-plugin-muted)] border-[var(--cortex-plugin-border)]" />
```

### Adding fallback values

Add a fallback value so your plugin still renders correctly if the theme hasn't loaded yet:

```css theme={null}
background-color: var(--cortex-plugin-background, #fff);
```

> **Note:** Fallbacks are fixed values, so they don't follow brand colors or dark mode.

## Supporting light and dark mode

You don't need to define separate colors for light and dark mode. Token values change with the user's setting, so anything styled with tokens switches automatically.

`<PluginProvider>` also adds a `light` or `dark` class to the `<html>` element. Use this class for anything the tokens don't cover, such as swapping an image:

```css theme={null}
.dark .logo {
  content: url("logo-dark.svg");
}
```

## Using the component library

The quickest way to match Cortex is to build your plugin with `@cortexapps/react-plugin-ui`. Its components already use the theme tokens, so they follow the user's theme with no extra styling.

The library includes the following components:

* Badge
* Breadcrumb
* Button
* Card
* Checkbox
* Dialog
* Input
* Label
* Loader
* Progress
* Select
* Tabs
* Typeahead

### Component examples

Import components from `@cortexapps/react-plugin-ui`. For example, a card with a badge and a button:

```tsx theme={null}
import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@cortexapps/react-plugin-ui";

<Card>
  <CardHeader>
    <CardTitle>payments-service</CardTitle>
  </CardHeader>
  <CardContent>
    <Badge variant="success">Passing</Badge>
    <Button variant="outline">View details</Button>
  </CardContent>
</Card>
```

Tabs:

```tsx theme={null}
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@cortexapps/react-plugin-ui";

<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">...</TabsContent>
  <TabsContent value="settings">...</TabsContent>
</Tabs>
```

An input with a label:

```tsx theme={null}
import { Input, Label } from "@cortexapps/react-plugin-ui";

<Label htmlFor="service-name">Service name</Label>
<Input id="service-name" placeholder="Enter a service name" />
```