Introducing the revamped Team Catalog

Introduction

In order to be the engineering system of record, Cortex needs to be able to surface information about teams beyond the services/resources they own. We’re pleased to announce that as of this week, we’ve promoted the Team catalog to top-line entity type, enabling users to associate data from any integration the same way they might for other catalogs like Services, Resources, and Domains. This enables users to not only provide more context on teams, but also aggregate integration data at the team level, write complex queries about aggregate team data, and soon, create scorecards specific to team performance.

What’s new

1. Team relationships to other entities and integration data is now managed by a YAML file, where users can add all the same sort of information you might for services, resources, and domains—like relevant custom data, links, and integrations.
2. Each team’s landing page experience has been upgraded to show a menu for new data types listed above, as well as on-call information and hierarchy (previously embedded in a tab view. Tab menu for scorecards, members, links, and services, resources & domains persists).
3. The Teams landing page leadership board has been upgraded to show whether each team is moving up or down on the board
   

What’s staying the same

1. We’ll still automatically populate each team’s membership based on your IdP (with further customization now possible!), and automatically populate services, resources, domains, and events associated with each team.
2. We’ll still automatically associate relevant Scorecards for your team, and will display a leaderboard representing progress against all or specific scorecards.
3. You can still link relevant documentation and Slack channels for each team, and edit that information via UI (and now via YAML file if preferred).

How it works

Relationships between your team and other entities, including data from integrations, are now managed (and editable) in a YAML file for each team. Associate teams to other top-line entities in the Cortex platform with the x-cortex-’fill-in-the-blank’ syntax in your YAML file. Example, x-cortex-customdata in your team YAML will enable you to link a custom datasource to your team. Leverage any of the same tags you might already have in your other catalog YAML files, with two new additions—the x-cortex-team tag, and x-cortex-children tag.

The x-cortex team tag comprises two sections, groups and members. Groups can be used to link your team entity with a group already defined in one of your integrations, like Okta, for example, to ensure any members of that group are persisted in your Cortex team. Members can be used to add individual members to your team when you have a use case for a Cortex team that does not correspond exactly to a group defined elsewhere across your integrations. This can be particularly useful if you want to add a manager, PM, designer, front-end resource, etc.  

The x-cortex-children tag enables you to define “child” teams that belong to a given team. This enables you to replicate (or edit for Cortex-specific-use cases) the hierarchy of how teams are modeled across your workspace. See our docs for more details and sample code for these examples!

Top use cases

While you could always view information about teams as they related to services, resources, or domains (like who owns each, which scorecards they’re associated with, etc), this update to the Teams catalog means you can now reverse this flow, to view or query team-related information independent of those other entity types. Check out some examples below.

1. Aggregate data by team: While users have always been able to view information pertaining to their own work in the Developer Homepage—like JIRA issues, and open PRs, now teams can carry their own relationships to those data sources, making this information viewable in aggregate for the whole team.
2. Multi-group membership: Team membership isn’t always mutually exclusive. There’s lots of reasons why a developer will belong to multiple groups. For example, someone might belong to the Front-end group and the Payments product group, which both belong to the Experiences team. The new Teams catalog enables users to accommodate multi-group membership.
3. GitOps support: Like any other top-line entity in Cortex, you’ll soon have the option to define your teams via GitOps. This helps keep the source-of-truth closer to your team or service owners, and reduces dependency on humans making edits via the UI. 
4. Scorecards & Initiatives on teams: Create scorecards for teams based on stand-alone or integration-sourced data. Hold entire teams to standards of excellence, or simply ask questions like, “Which Teams have more than 5 open issues in the last year?” or, “Which teams have the highest number of closed PRs?”
   

Your information architecture

The data model in your IDP needs to be both consistent with the rest of your stack, and efficiently structured for easy navigation. But sometimes, those two things can feel mutually exclusive. If the rest of your development ecosystem lacks consistency in entity definitions and relations, or if you have new use cases you’d like to enable in your IDP, you might need help thinking through the best structure.

The truth is that defining your IDP information architecture is hard—for every organization. This space is still new, still evolving, and we’re still learning the right way to do this work. Cortex can help. While we enable users to design their own data model, we also simplify the process with logical defaults for entities and data types introduced via 40+ supported integrations. Hands-on support is also part of every customer onboarding to ensure your data is modeled exactly as you require. Check out this blog for more information, or get in touch with our team to learn how Cortex can help support your journey to engineering excellence.