Link components to Jira issues

This feature is for company-managed Jira Software projects on the same site. We're working on adding it to team-managed projects. Find out if you’re in a company-managed or team-managed project

If you use Jira Software, you can track work on components by linking them to Jira issues.

A Jira admin needs to turn on the Compass custom field for a Jira Software project. Then anybody in that project can link components to Jira issues.

Once components are linked to Jira issues, you can view, sort, and filter those issues from the components' Jira issues page.

Before you begin

Turn on the Compass custom field for a Jira Software project

A Jira admin needs to turn on the Compass custom field for a Jira Software project. The project has to be company-managed, and on the same Jira site.

In Jira, select Settings > Issues.
Under Fields, select Custom fields.
Find the Compass custom field, and select More actions > Associate to screens.
Add the custom field to the screens you want by ticking the corresponding box.
Select Update.

Add the Jira Software project to a component

In Compass, go to a component’s Jira issues page.
Select the URL field, and choose the same project you turned the Compass custom field on for.
Select Add.

Link a component to a Jira issue

Turn on the Compass custom field for a Jira Software project.
Add the same Jira Software project to a component.
Find the Jira issue you want to link a component to.
On the Jira issue, select the Compass custom field.
Choose a component.
Select Link. The Jira issue will appear on the component’s Jira issues page.

Change the component linked to a Jira issue

Find the Jira issue you want to change.
On the Jira issue, select the Compass custom field.
Choose a different component.
Select Link. The Jira issue will appear on the component’s Jira issues page.

Unlink a component from a Jira issue

Find the Jira issue you want to unlink a component from.
On the Jira issue, select the Compass custom field.
Select Remove .
Select OK. The Jira issue will disappear from the Compass component's Jira issues page.

View a component's Jira issues

In Compass, find the component that you want to see Jira issues for.
In the side navigation, select Jira issues.
In the table, filter Jira issues by type or status, or sort them from the table columns. By default, Jira issues are sorted by most recently updated.

Link a component to multiple Jira issues

In December 2022, we improved how you link components to Jira issues

If you used the Jira issues Components field to link Compass components, you now need to use the Compass custom field.

Learn how to bulk change your Jira issues by reading the steps below.

Turn on the Compass custom field for a Jira Software project.
Add the Jira Software project to a component's Overview page.
Go to your Jira Software project’s Issues page.
Select the JQL search mode.
In the query field, type component = compass-component-name. This shows Jira issues that have their Components field set to the name of the Compass component you specify in the query.
Select More actions > Bulk change issues.
In the new tab that opens, select all the issues, then select Next.
Select Edit issues, then select Next.
Select Change Compass, then copy and paste the Compass component ID into the field.

To copy the Compass component ID:
1. In Compass, go to the component’s Overview page.
2. Select More actions > Copy component ID.
Select Next.
Select Confirm.
Let your changes take effect, then select Done. You’ll see your component in the Jira issues' Compass custom field, and the Jira issues will appear in Compass.

Known issues

We're working to fix the following issues:

When bulk editing Jira issues that have components linked to them, the Compass custom field doesn’t show the component name
When viewing advanced search results in Jira Software, the Compass custom field shows the component ID instead of the component name
In Jira Software email notifications, the Compass custom field shows the component ID instead of the component name