Skip to main content

2. Importing entities

You can start importing entities right away for any of Cortex's built-in entity types and you can import entities for custom entity types once you’ve added at least one type.

To import one or more entities, open the All Entities page and select Import Entities next to the search bar.

import entity 1

The first step is selecting the entity type that you want to import. The options available to you at this stage are the same ones on the Entity types page. If you don’t see an entity type that corresponds to the type you’re trying to import, make sure that you’ve created the corresponding entity type first.

import entity 2

The 24 options available in the above example are the same 24 that we’ll find in our Entity types tab.

import entity 3

Select the entity type that you want to import to move onto the next step.

import entity 4

If you have permissions to edit settings, any integrations that are already set up in Cortex will appear with a grayed out Ready next to them, while integrations that aren’t set up appear with an Install option. When you select any of the installed integrations, all of the entities available for import will appear below.

For other users, only the integrations that are ready for import will be displayed.

import entity 5

You can import as few or as many entities as you want from the list of discovered entities. In this case, because we’re importing services as our entity type, and because we selected the GitHub integration, Cortex will discover and display all entities in GitHub.

If an entity does not appear for import, you can use the Sync button under Import entities to prompt a sync.

import entity 6

Cortex will display any newly discovered entities in the list once the sync is finished.


The sync may take a few minutes the first few times because Cortex is fetching data directly from integrations.

Especially in the beginning, the list of discovered entities may be pretty long. You can use the search bar at the top to narrow down the results.

Any entities you choose for import will appear under Selected entities (in this case, services – the language here will reflect the entity type you’re importing).

import entity 8

Cortex will automatically pull the entity’s name and identifier from the source, but you can edit the name, identifier, and description for any entity by selecting the pencil icon.

You can select as few or as many entities for import at this stage as you like. However, you can only import entities from a single source at a time. For example, since we’re importing from GitHub right now, we cannot add any New Relic entities to the import.


The first time you import entities, stick with a handful of the most important ones, so you can get familiar with the process.

import entity 10

The interface will only display six entities at a time, but you can select and # more entities to see and/or edit the entities you’ve selected for import.

import entity 11

Once you’ve chosen all the entities you want to import and you’re satisfied with their names and tags, select Add # entities. All of these entities will then appear in the All entities catalog.


There is no limit to the number of entities you can import at a given time, but you can only import entities from a single integration at a time.

Create an entity manually

While it’s recommended that you import entities from established integrations, you can also create an entity manually. If you don’t have integrations set up, you’ll be able to create a few essential entities — services, domains, teams, and certain others. You’d also create an entity manually if you wanted to create a special type, like an API, and model things differently than Cortex’s out-of-the-box setup.

To do so, select Create entities manually under Select an integration or create your own entity.

import entity 12

You’ll then be able to directly enter the entity’s name, identifier, and description. Once you’re done, select Add # Entity.

If you're only creating one entity, you'll be taken to another page to define owners and add parent domains, groups, links, dependencies, and on-call information. Depending on the entity type you're creating, you can add an associated repo.

import entity 14

Other entity types will also include a schema field where you can fill out the entity descriptor.

import entity 15

Once you select Create entity, the manually created entity will appear in the All Entities page alongside any entities imported from integrations. You’ll also be able to find the new entity in any catalog page that has filters that include the entity.

Importing from a catalog page

It’s also possible to import an entity directly into a specific catalog. First, navigate to the catalog the new entity will belong to, and then select + Import entities at the top of the page.

import entity 13

This will take you through the exact same import flow. Generally when you complete the import flow through this method, the entities will be added to the catalog selected (in this case, Domains), in addition to the All entities page and other catalogs that include the entity. However, this is not the case if the entity you’re importing/creating does not qualify under the catalog’s criteria.

For example, we can import an s3 bucket using the import function from the Domains catalog, but because an s3 bucket doesn’t apply under the Domains catalog filter criteria, it will not appear in the Domains catalog.