Setting up Teams in Catalog

A step-by-step guide on how to build a powerful Teams catalog type, along with multiple example use cases for Teams.

incident.io Engineering Team avatar
Written by incident.io Engineering Team
Updated yesterday

Understanding the teams within your organization is a key part of driving successful incident response. Teams allow you to create powerful automations, such as:

  • Show or require different information when a user is declaring an incident, depending on what team they’re in

  • Auto-subscribe managers to incidents that their team members are participating in

  • Restrict accepting a security incident to only members of the infrastructure & security group

  • Automatically set custom fields based on who is assigned to a role in an incident

We know that every organization is different, so we allow you to model teams flexibly using Catalog. This allows you to model your specific organization structure, without having to fit into someone else's box. For example, you could have:

  • A Catalog type Team that has Members, a Manager, and a Tech Lead

  • A Catalog type Division, which contains a list of the Teams that it includes

  • A Catalog type Function which has Members so you know whether someone is an Engineer, a Product Manager or a Customer Success Manager

Setting up Teams

If you already have a Team catalog type that has an attribute (e.g. Team Members) with the SlackUser resource type, please read this article to learn how to migrate your Team catalog type.

Once you've completed the migration for your existing type, read on from the Going from User → Team section to supercharge your User-based workflows.

To get set up with Teams in Catalog, you have two options:

  1. Create Teams via the dashboard, and manage them with a point-and-click interface

    1. Head to Catalog

    2. Click "Add a custom type"

    3. Populate the catalog type with the relevant attributes, including an attribute called Members (or equivalent) which has the type User

  2. Use the Catalog Importer to create Teams from your own data source (e.g. manage them in Github or Gitlab)

    1. Follow the Catalog Importer installation instructions

    2. Ensure that all user attributes, e.g. Team Members, use the User type rather than SlackUser (see example)

Note: You can also get started with the point-and-click interface, and then export them to Github once you’re happy with the setup.

For example, here’s our Post Incident engineering team represented in our Catalog:

Once you've connected Teams → Users, you can answer questions like: "Who are the Members of the Post Incident engineering team".

Going from User → Team

To unlock the real power of Teams, you'll want to be able to navigate from a User to the Team they’re in, across incident.io features like Forms, Workflows, and more.

To do this, we need to create a Backlink.

A Backlink enables you to create powerful automations that start with "for this user... I want to do this thing". If we don't create a Backlink, you'll only be able to build automations that start with "for this team... I want to do this thing".

Head over to your User catalog type (in the Users section), open it, and hit "Edit type". Then, create an attribute called Team, and choose from the relevant Backlink:

We can then specify whether we expect users to be a member of multiple teams, or just one. In our case, we expect users to be part of a single team, so we can choose ‘Just one’

We now have a new attribute Team which represents ‘the Team which this user is a member of’.

Another Backlink Configuration Example

Let's assume you have a Features catalog type, and a Feature Areas catalog type (e.g. the higher-level category that a set of features are part of). When setting up Catalog, you map all Features to a Feature Area.

It would be extremely repetitive, difficult to maintain, if you then needed to also map all Feature Areas to Features. This means your Feature Area catalog type ends up looking like this (note: the lack of "link" back to Features):

So, in order to "go the other way", you'll want to set up a Backlink such that you can access Features from the Feature Area catalog type.

Which results in a Feature Area catalog type that has a Backlink to Features.

Configuring Backlinks via Catalog Importer

If you'd like to add Backlinks to a catalog type that you're managing via Catalog Importer, no problem!

In your Catalog Importer config, you'll need to add backlink_attribute: id, where id = the ID of the attribute that defines the link between your source and target catalog types. Note: You'll also want to drop the source property from the Backlinked attribute.

In our Features and Feature Areas example, your Catalog Importer config would look something like this:

// Feature
attributes: [
{
id: 'feature_area',
name: 'Feature Area',
type: 'Custom["Feature Area"]',
array: true,
source: '$.feature_area',
}
]

// Feature Area
attributes: [
{
id: 'features',
name: 'Features',
type: 'Custom["Feature"]',
backlink_attribute: feature_area
}
]

Examples

There are many examples of how you can use your new Teams catalog type, especially the User → Teams link.

Example Usage: Incident Forms

You can now customise your declare incident form based on the user’s team, like defaulting the affected team to the current user’s team or showing / requiring fields based on the user. Check it out in Settings → Forms.

Example Usage: Workflows

You can now use a user’s team to build out workflows. In this example, we’ll auto-subscribe Engineering Managers to every incident that someone in their team is participating in. This helps keep managers aware of where members of their team might be unexpectedly spending time, and who might need support.

Example Usage: Restricted Incident Types

You can now restrict an incident type by rule - here, we’re saying that only users in the Infrastructure team can accept security incidents.

Example Usage: Automatically Set Custom Fields based on Roles

You can now automatically set custom fields based on who is assigned to a role in an incident, for example "set 'affected team' based on which team the incident lead is a member of".

Did this answer your question?