# Add services

Services are a default entity type in Cortex, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module.

## View services

To view services, click **Catalogs > Services** from the main nav.

When you open the Services page, you'll see tabs labeled **Mine** and **All**, which denote services you own and all services visible to you in your Cortex workspace.

<figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-18880358cfbc7f4776f1c3575c9b92c8bec77d87%2Fview-services.jpg?alt=media" alt=""><figcaption><p>The services list has tabs for All and Mine.</p></figcaption></figure>

### Configure the view of your service list

At the top of your services list, you can choose how the list is displayed:

* **Name**: Click **Name**, then choose whether to sort by name or identifier ([Cortex tag](https://docs.cortex.io/ingesting-data-into-cortex/entities/..#cortex-tag)), and whether the sort order should be ascending or descending.
* **Display**: Click **Display**, then choose whether to display hierarchies, whether to show archived, and which columns to display.
* **Filter**: To narrow the scope of your list, click **Filter** then select criteria you'd like to filter by.\
  ![](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-100dfb2b4e76c6a591e484eb175992e673ec2db0%2Ffilter-entities-list.jpg?alt=media)

## Creating services

You can create services:

* By importing them from a connected integration
* Manually in the Cortex UI
* Via the entity descriptor YAML through [GitOps](https://docs.cortex.io/configure/gitops)
* Via the [API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities#post-api-v1-open-api)

{% tabs %}
{% tab title="Import" %}
You can import services directly from third-party integrations:

1. In Cortex, navigate to **Catalogs > All entities**, then click **Import entities**.
2. Choose **Import discovered entities**.\
   ![](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-86aac8a010fadb3aadf7dcd370514e54650a9c48%2Fimport-method.jpg?alt=media)
3. Select the integration to import from.
4. On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.\
   ![](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-f93c5c6c1e4af4fe0eff65ccbf66db8d481291c9%2Fimport-services.jpg?alt=media)
   * If you have a large volume of entites, click **Filter** in the upper right corner of the results list to select and apply entity type filters.
5. At the bottom of the page, click **Next step**.
6. Edit the details for the entity:
   1. **Type**: Select **Service**.
   2. **Entity name**: Enter a human readable name.
   3. **Identifier**: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the `x-cortex-tag`.
   4. **Description**: Enter a description of the entity to help others understand its purpose.
   5. **Groups**: Select [groups to segment](https://docs.cortex.io/ingesting-data-into-cortex/entities/groups) your entity.
   6. **Owners**: Define [ownership](https://docs.cortex.io/ingesting-data-into-cortex/entities/ownership) for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
      * You may see owners that Cortex [recommends based on repository activity](https://docs.cortex.io/ingesting-data-into-cortex/ownership#recommendation). You can accept or reject the recommendations.
   7. **Links**: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
   8. **Parents**: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the [relationship graph](https://docs.cortex.io/ingesting-data-into-cortex/entities/relationship-graph).
   9. **Dependencies**: Select entities that this entity depends on. These can be visualized in the [relationship graph](https://docs.cortex.io/ingesting-data-into-cortex/entities/relationship-graph).
   10. **On-call**: Configure on-call information.
   11. **Repository**: Select the repository associated with this entity.
7. If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.\
   ![](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-0c0884e54daaaca121dcaae62306ed9a6d0beac7%2Feach-entity.jpg?alt=media)
8. Click **Confirm import**.
   {% endtab %}

{% tab title="Manual" %}
To create a service:

1. In the main nav of Cortex, click **Catalogs > Services**.
2. At the top of the Services page, click **+Import entities**.
3. Choose **Create entities manually**.\
   ![](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-86aac8a010fadb3aadf7dcd370514e54650a9c48%2Fimport-method.jpg?alt=media)
4. Configure the form:
   * **Type**: Select **Service**.
   * **Entity name**: Enter a human readable name.
   * **Identifier**: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the `x-cortex-tag`.
   * **Description**: Enter a description of the entity to help others understand its purpose.
   * **Groups**: Select [groups to segment](https://docs.cortex.io/ingesting-data-into-cortex/entities/groups) your entity.
   * **Owners**: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
   * **Links**: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
   * **Parents**: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the [relationship graph](https://docs.cortex.io/ingesting-data-into-cortex/entities/relationship-graph).
   * **Dependencies**: Select entities that this entity depends on. These can be visualized in the [relationship graph](https://docs.cortex.io/ingesting-data-into-cortex/entities/relationship-graph).
   * **On-call**: Configure on-call information.
   * **Repository**: Select the repository associated with this entity.
5. When you are finished, click **Confirm import** at the bottom of the page.
   {% endtab %}

{% tab title="Entity descriptor" %}
**Service entity descriptor**

A barebones spec file has the OpenAPI version, along with an `info` section that contains some basic details.

```yaml
openapi: 3.0.1
info:
  title: My Service
  description: This is my cool service.
  x-cortex-tag: my-service
  x-cortex-type: service
```

**Required fields**

The only required fields under `info` are the `title`, `x-cortex-tag`, and `x-cortex-type`. The description is optional, but we highly recommend adding descriptions to all of your entities.

**Example cortex.yaml for a service**

```yaml
openapi: 3.0.1
info:
  title: Chat Service
  description: Chat service is responsible for handling 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
```

{% endtab %}

{% tab title="API" %}
You can create, update, and delete services using the [Cortex API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities).
{% endtab %}
{% endtabs %}

## Edit services

It is possible to edit entities after creating them:

1. Navigate to the entity's page.
2. In the upper right corner, click **Configure entity**.
3. Make any desired changes.
   * Note: The only field you cannot edit is the identifier.
4. At the bottom of the screen, click **Save changes**.