# Add teams
**Teams** serve as both an entity representing your organization in Cortex and as [owners](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) for different entities in the catalogs. Teams offers a centralized place for the most important information about each group, making it easier for everyone to find what they need.
Teams can be assessed via [Scorecards](/standardize/scorecards.md), interact with integrations, and leverage [custom data](/ingesting-data-into-cortex/entities-overview/entities/custom-data.md). They can also be configured in a hierarchy.
## View teams
To view your teams, navigate to **Catalogs > Teams**.
When you open the [Teams catalog page](https://app.getcortexapp.com/admin/catalogs/teams), you'll see **Mine** and **All**, which denote teams you belong to and all teams at your organization, respectively. The teams that appear under "All" will automatically display as a [hierarchy](#understanding-hierarchies), whereas those under "Mine" will be listed individually.
### View the teams leaderboard
On the right side of the Teams catalog page, see the Scorecard Leaderboard, which highlights the ten best-performing teams within your organization.
The leaderboard is calculated from the average of [Scorecard](/standardize/scorecards.md) 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 dropdown to select a different Scorecard, allowing you to view the leaderboard based on specific Scorecards.
{% hint style="success" %}
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.
{% endhint %}
### View an individual team's page
Each team has its own details page, where you can view key details about the team. Click a team from the Teams catalog page to view its details.
At the top of a team details page, you’ll find on-call information, Slack channels, and parent and children teams.
Additional information appears in tabs on the team's details page:
A team's details page includes an overview, team members, owned entities, and dependencies.
* The **Overview** tab includes:
* Vulnerabilities and issues from linked integrations.
* How the team is performing across Scorecards. By default, this will show the level that the team’s entities have reached in each Scorecard.
* On the right, enable the toggle next to **Aggregate children scores** to include child entities in the Scorecard overview.
* A list of recent events associated with this team, such as alerts from [PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty.md).
* The **Dependencies** tab shows any incoming or outgoing dependencies associated with this team.
* The **Team members** tab includes a list of all team members and their roles. When available, Cortex will also pull in profile photos from your Git provider.
* The **Entities** tab shows a list of all entities that the team owns.
Learn more about the sidebar links in the [Entity details page](/ingesting-data-into-cortex/entities-overview/entities/details.md) documentation.
### Ownership
Teams not only allow you to collect vital information in a single place, but are also crucial for ownership. 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.
Read more in the [Ownership documentation](/ingesting-data-into-cortex/entities-overview/entities/ownership.md).
## Creating a team
You can create teams:
* By importing them from a connected integration (e.g., Workday, GitHub)
* Manually in the Cortex UI
* Via the entity descriptor YAML through [GitOps](/configure/gitops.md)
* Via the [API](/api/readme/teams.md)
### Understanding hierarchies
You can configure teams to reflect the actual hierarchy at your organization while creating or importing teams in Cortex. A team can be defined as the parent of one or more teams while also being the child of another team.
When you access the [Teams catalog](https://app.getcortexapp.com/admin/catalogs/teams), individual teams and parent teams are displayed by default. Parent teams have an arrow next to their name, indicating that you can expand to view children teams.
In the above example, `My Company` is a parent team with 7 child teams nested under it.
### Create a team
See the tabs below for instructions on each method.
{% tabs %}
{% tab title="Import" %}
**Importing a team from an integration**
If you have an existing source of truth for your teams and team members, we recommend importing teams. By integrating with your identity provider at this stage, Cortex will automatically sync team pages with your source of truth so you don't have to update information in more than one place when people join or leave teams.
Each integration syncs teams daily.
{% hint style="warning" %}
You can only import entities from integrations that have already been configured.
{% endhint %}
**Supported integrations**
Teams from the following integrations can be imported:
* [Azure DevOps](/ingesting-data-into-cortex/integrations/azuredevops.md)
* [BambooHR](/ingesting-data-into-cortex/integrations/bamboohr.md)
* [Entra ID (formerly Azure Active Directory)](/ingesting-data-into-cortex/integrations/entraid.md)
* [GitHub](/ingesting-data-into-cortex/integrations/github.md)
* [GitLab](/ingesting-data-into-cortex/integrations/gitlab.md)
* [Google](/ingesting-data-into-cortex/integrations/google.md)
* [Okta](/ingesting-data-into-cortex/integrations/okta.md)
* [Opsgenie](/ingesting-data-into-cortex/integrations/opsgenie.md)
* [ServiceNow](/ingesting-data-into-cortex/integrations/servicenow.md)
* Before following the import process, you must [configure table mappings](/ingesting-data-into-cortex/integrations/servicenow.md#step-2-configure-table-mappings).
* [Workday](/ingesting-data-into-cortex/integrations/workday.md)
* For the Workday integration, you can enable [automatic import of discovered teams](#auto-import-teams).
**Importing teams**
After configuring an integration that includes teams, follow these steps to import teams:
1. In Cortex, navigate to **Catalogs > All entities**, then click **Import entities**.
2. Choose **Import discovered entities**.\
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.\
* 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:
* **Type**: Select `Team`.
* **Name**: Enter a human readable name for your team.
* **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 team to help others understand its purpose.
* **Groups**: Select [groups to segment](/ingesting-data-into-cortex/entities-overview/entities/groups.md) your entity.
* **Members**: Select members of your team. Team members will be marked as owners of entities and receive notifications about entities owned by the team if notifications are enabled.
* **Links**: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
* **Slack channels**: Link the team's associated Slack channel. If [notifications are configured](/configure/settings/notifications.md), the team will receive notifications here.
* You must have the [Slack integration](/ingesting-data-into-cortex/integrations/slack.md) configured before linking a channel.
* **Parents** and **Children**: Define parent and children teams. This is where you configure the hierarchy for your entity. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
* **On-call**: Configure the on-call service associated with this team. When selected, you will see the latest on-call information displayed on the team's details page.
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.\
8. Click **Confirm import**.
{% endtab %}
{% tab title="Manual" %}
**Manually creating teams**
If you don’t have an identity provider with updated team information, you can create a team manually within Cortex. Because teams are important for effective ownership, it's recommended that you create teams in Cortex even if you don't have a single source of truth for team information.
1. In Cortex, navigate to **Catalogs > Teams**, then click **Import teams**.
2. Choose **Create entities manually**.\
3. Configure the form:
4. Configure the team details:
* **Type**: Select `Team`.
* **Name**: Enter a human readable name for your team.
* **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 team to help others understand its purpose.
* **Groups**: Select [groups to segment](/ingesting-data-into-cortex/entities-overview/entities/groups.md) your entity.
* **Members**: Select members of your team. Team members will be marked as owners of entities and receive notifications about entities owned by the team if notifications are enabled.
* **Links**: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
* **Slack channels**: Link the team's associated Slack channel. If [notifications are configured](/configure/settings/notifications.md), the team will receive notifications here.
* You must have the [Slack integration](/ingesting-data-into-cortex/integrations/slack.md) configured before linking a channel.
* **Parents** and **Children**: Define parent and children teams. This is where you configure the hierarchy for your entity. These can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
* **On-call**: Configure the on-call service associated with this team. When selected, you will see the latest on-call information displayed on the team's details page.
5. Click **Confirm import**.
Once you've created a team, you can view it on the **Teams** page within the hierarchy. If you haven't added parents or children, you can disable **View as hierarchy** to see the list of all teams.
{% endtab %}
{% tab title="Entity descriptor" %}
**Adding Cortex-managed teams**
You can manually create teams in Cortex and define them in the entity descriptor.
You can also define teams as owners via entity descriptors. See the [Ownership documentation](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) for more information.
**Team entity descriptor**
If your entity is a team, you must specify `x-cortex-type` as `team`.
```yaml
openapi: 3.0.1
info:
title: Payments Team
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
```
The `x-cortex-team` tag has two main sections: `groups` and `members`.
**Adding groups to the team entity descriptor**
Use `groups` to link your team entity with a team on a different platform that you have integrated with Cortex. You can only link one group to a team entity.
For example, you can specify:
```
openapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
groups:
- name: okta-security-team
provider: OKTA
```
Under `groups`, when you specify `okta-security-team`, your team will contain all the members from your `okta-security-team`.
Now, if you specify the `okta-security-team` in your [`x-cortex-owners`](#ownership) on any of your other entities, they will automatically recognize `example-team` as a team that owns their entity.
**Adding team members to the team entity descriptor**
`members` can be used to add individual members to your team when you have a use case for a team entity that doesn't correspond exactly to a team on one of your integrations. Members support `roles`. For example, the following entity includes a member who has the `product-manager` role and a member who has both the `engineering-manager` role and `manager` role:
```
openapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
members:
- name: Product Manager
email: product-manager@cortex.io
notificationsEnabled: true
roles:
- tag: product-manager
- name: Engineering Manager
email: engineering-manager@cortex.io
notificationsEnabled: true
roles:
- tag: engineering-manager
- tag: manager
```
After specifying the YAML example above, your team now will contain `Product Manager` and `Engineering Manager`. If `product-manager@cortex.io` or `engineering-manager@cortex.io` were to correspond with the email of an actual account in Cortex, they would start seeing `example-team` being displayed as a team that they're a part of (i.e., it would start showing up in their `Mine` tab in catalogs that contain teams).
[Roles](#adding-team-member-roles) must be defined for your workspace in your [Entity Settings page](https://app.getcortexapp.com/admin/settings/entities), under the "Teams" tab.
{% hint style="info" %}
The `role` field in member is optional. In order to be considered valid, a team must have a non-empty group.
{% endhint %}
**Team children**
You can define a list of other teams as children, allowing you to represent a hierarchy of how your teams are modeled across your workspace, using the `x-cortex-children` tag.
```yaml
openapi: 3.0.1
info:
title: Payments
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-children:
- tag: child-team-1
- tag: child-team-2
```
This hierarchy is available to look at in the Teams catalog page.
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.
**Team parents**
Team children allow you to define the team relationship from the top-down, but in some cases it may be easier to define the team hierarchy from the bottom-up. For these cases, `x-cortex-parents` can be added to any entity's YAML to define its parents.
```yaml
openapi: 3.0.1
info:
title: Payments
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-parents:
- tag: parent-team-1
- tag: parent-team-2
```
**Example cortex.yaml**
Note: the YAML definition for a team entity can take file names other than `cortex.yaml` or `cortex.yml`; see the [GitOps example repository structure](/configure/gitops.md#how-gitops-works-in-cortex).
```yaml
openapi: 3.0.1
info:
title: Chat Team
description: Chat team.
x-cortex-tag: chat-team
x-cortex-type: team
x-cortex-team:
groups:
- name: okta-chat-team
provider: OKTA
members:
- name: Product Manager
email: product-manager@cortex.io
notificationsEnabled: true
- name: Engineering Manager
email: engineering-manager@cortex.io
notificationsEnabled: true
x-cortex-children: # children can be of type team
- tag: chat-infra-team
- tag: chat-sre-team
x-cortex-slack:
channels:
- name: chat-team
notificationsEnabled: true
description: This is a description for the chat-team Slack channel # optional
x-cortex-oncall:
pagerduty:
id: ASDF2345
type: SCHEDULE
```
{% endtab %}
{% tab title="API" %}
**Creating teams via the API**
You can create, update, and delete teams using the [Cortex API](/api/readme/teams.md).
{% endtab %}
{% endtabs %}
### Edit teams
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**.
## Adding team member roles
You can manually create a team member role:
1. In Cortex, navigate to [**Settings > Entities > Teams**](https://app.getcortexapp.com/admin/settings/entities/teams?activeTab=TeamMemberRoles).
2. Click **Add role**.
3. In the "Add role" modal, configure the role:
* **Role name**: Enter the role's name.
* **Tag**: The tag - a unique identifier for the role - automatically populates based on the role name.
* **Role description**: Enter a description of the role.
* **Enable notifications by default**: If notifications are enabled, members with this role will receive relevant updates on Scorecards, Initiatives, and more.
4. Click **Save**.
#### Apply role to team members
You can apply a role only to manually-created team members. Team members who were imported from an identity integration will retain the role that was imported.
To apply a role:
1. In Cortex, navigate to **Catalogs > Teams**.
2. Click into a team.
3. In the upper right corner, click **Configure entity**.
4. Click **Members**.
5. Next to a team member, click the edit icon.
6. In the side panel, add a new team role.
7. Click **Update**.
## Adjusting team settings
Under [**Settings > Entities > Teams**](https://app.getcortexapp.com/admin/settings/entities/teams), there are several settings relating to teams. You can select which identity providers to use to sync teams and team memberships, configure automatic import from Workday, configure entity editing access, and sync or create roles. Learn more in [Entity settings](/configure/settings/entity-settings.md).
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.