In order to create metrics per team, Faros needs to be able to attribute each commit, task, deployment, incident, or event to the correct teams. This page will explain how we connect these objects to teams via the team association tables.

Team association tables

Employees, boards, repositories, and applications are directly associated with teams either implicitly or manually via the UI. (Please see Managing your Organization and Managing Apps, Repos and Boards to understand how to associate teams to these objects.) Those team associations are stored in the following tables:

• Employees → Team Membership
• Applications → Application Ownership
• Task boards → Board Ownership
• Repositories → Repository Ownership

❗️

Project Ownership is deprecated. Whether you are using projects or boards, the ownership is tracked through the "Board Ownership" table.

When creating your own custom dashboards and charts, you can use these intermediate tables to connect your objects (commits, tasks, pull requests, deployments, etc) to teams.

Examples

Say you are creating a dashboard around the number of pull requests associated with a team. You might want to consider the number of pull requests authored by a member of that team, or perhaps you are more interested in the number of pull requests in the repositories owned by that team. Let's create both of these metrics through Faros.

Number of pull requests associated to repositories owned by a team

Let’s start with calculating the number of pull requests in the repositories owned by a particular team.

Take a look at the columns in the Pull Request object

Note that we can use the Repository ID field to join with the Repository Ownership table. This will join pull requests to the pull request's repository's team.

Once you have set up this join, you can then filter by team and create the metric you want to track.

Number of pull requests associated to employee within a team

Now let’s calculate the number of pull requests authored by members of a team. Again, we start with the Pull Request table.

Notice all the Author fields. In particular, there are two ID fields, Author ID and Author Identity ID. The Author ID is associated with the underlying GitHub (or other source) user id, and the Author Identity ID represents the unified Faros Employee ID. To join this table with other objects in Faros via the pull release author, we will need to use the Author Identity ID field.

📘

An employee in Faros represents an individual developer or manager within your organization.

Engineering organizations use multiple tools and services in order to build and maintain their product, and each developer has an account on each of these systems. The employee record in Faros ties all those accounts together so there is a unified representation for each person across all the systems represented in Faros.
For each record that is associated with a person, such as a task or a pull request, the Faros table will include both the original account id and an “Identity ID”, which refers to the unified Faros employee id.

The table that associates employees to their teams is “Team Membership”, so that is what we will use to join our PRs to our teams.

Just like the first example, we can now filter by team and measure the count of PRs. However, instead of including PRs within a team's repositories, this time the count will include the PRs authored by someone in the team.

Attributions in Faros standard reports

Faros uses the following attributions in the Faros standard reports.

• Incidents are attributed to teams based on which team owns the affected application.
• Tasks are attributed to teams based on which board they are assigned to or based on the employee they are assigned to. (A task might belong to one board, but be assigned to an employee in a different board.)
• Pull requests, commits and merge requests derive their team from the assigned employee.
• Deployments are attributed to teams via the employees that authored the underlying commits. Note that multiple commits can be part of one deployment, so the same deployment can be attributed to multiple teams.
• Flows derive their team from their type. Examples are tasks, incidents or commits.

In Faros standard charts, the info bubble should give information about how Faros determines the attribution for that chart. However, you can always open the underlying query to see exact how a chart attributes its data to a team.

Understanding the team association tables

In the examples in the previous section, we created the filter "Parent Team is all_teams". "all_teams" is the top level team in every org's team hierarchy.

When filtering by team, the charts will include data attributed not just to the "all_teams" teams but to all the sub-teams as well. Likewise, if filtering to the data-science team, it would include the data associated not just to the data-science team but to the apps and modeling teams as well.

This happens automatically when using the team association tables (Team Membership, Application Ownership, Board Ownership, Project Ownership, Repository Ownership, Pipeline Ownership). When a board, application, etc is assigned to a team, a record is added for not just the assigned team, but for all parent teams.

When you are constructing your charts or dashboards and join records to a team association table, there will be a row for each team in the hierarchy.

That way, a record will be counted when filtering by its original team and when filtering by the other teams higher in its hierarchy.

❗️

You should only ever filter by one team at a time. If you add both a team and its subteams to a filter, records will potentially be counted multiple times.