Integrate airfocus with Jira

Benefits

Connect your product management workflows, prioritization frameworks, and roadmaps with day-to-day development by syncing your data seamlessly between airfocus and Jira. The integration is compatible with Jira Cloud, Jira Server, and Jira Data Center.

• Import Jira issues (as items) into airfocus.
• Push airfocus items into Jira (as any issue type).
• Two-way sync & flexible filtering (custom JQL).
• Flexible field mapping.
• Display your airfocus priority scores in Jira for context around business value and priorities.
• Ability to see the parent-child relationships directly in airfocus.

Requirements

• On airfocus: User needs to have “Full” permissions to the workspace they want to configure the Jira integration for.
• On Jira: "Administrator" permissions are required to establish the application link between your Jira instance and airfocus team.
• If the application link between the Jira instance and the airfocus team has been established already, any Jira user with at least "Create_Issue" permission to a project can set up new integrations to that instance.
• Our Jira integration is compatible with Jira Cloud, Jira Server, and Jira Data Center. We support all Jira Server versions listed on the Atlassian Support End of Life Policy. Versions earlier than those listed there have reached End of Life (EOL) and may function but are not supported.

Set up the Jira integration

1. Sign up for airfocus or log into your existing account. 
2. Create a new workspace in airfocus or select the one you want to integrate Jira with.
   • You have to authorize your Jira instance only once per airfocus team.
   • You can add multiple Jira integrations to a given workspace (for example, from different Jira projects or instances).
3. Click Extensions from the top-right corner of your workspace.
4. Select Manage integrations.
5. Click Connect on the "Jira" tile.
6. Select Connect a new Jira instance from the dropdown that appears.
7. Enter your Jira instance base URL (e.g. https://airfocustest.atlassian.net/ or https://jira.mycompany.com).
8. Click Proceed.
9. Copy the “Application URL”. You’ll need this for the next steps in Jira.
10. Click Jira application link center to open the Jira Application Link Center.
    • You need to be an administrator in Jira to access this page. 

The next steps vary for Jira Cloud and Jira Server/Data Center. Check out the section below for your instance to continue.

Create an application link in Jira Cloud

1. In Jira Cloud, click the Settings icon in the top right corner
2. Select Jira apps. 
3. Under the “Integrations” section on the left side, click Application links.
4. Click the Create link button in the top-right of the page.
5. Select the option for “Direct application link”.
6. Paste your airfocus URL as “Application URL”.
7. Click Next.
8. Type a name for the application and ensure the application type is set as “Generic Application”.
9. Using the information provided in airfocus, copy and paste the Service Provider Name, Consumer key, Shared secret, Request Token URL, Access token URL, and Authorize URL into Jira.
10. Check the box next to “Create incoming link”.
11. Click Continue.
12. Using the information provided in airfocus, copy and paste the Consumer Key, Consumer Name, and, Public Key into Jira.
13. Click Continue.
14. Go back to airfocus and click Finish setup.

We'll redirect you to the oAuth authorization step which lets airfocus use your Jira user to synchronize items between the two. Click Allow to authorize airfocus to sync with your account.

Create an application link in Jira Server or Jira Data Center

1. Click Create link at the top right,
2. Select Atlassian product.
3. Paste your airfocus URL as “Application URL”.
4. Click Continue to confirm.
   
5. Fill in the values provided in the airfocus interface.
6. Click Continue.
7. Copy over the values from Step 3. 
8. Click Continue. 
   • You should now see a confirmation in Jira.
9. Go back to airfocus and click Finish setup.

We'll redirect you to the oAuth authorization step which lets airfocus use your Jira user to synchronize items between the two. Click Allow to authorize airfocus to sync with your account.

Configure integration filtering

1. Select the project you want to sync. You can type to filter the list of projects.
   • Projects that you can see but lack the CREATE_ISSUES permissions for are marked as such (only available for Jira Cloud).
   • The name of your integration is created automatically based on the project. You can also change it later.
2. Select the issue type you want to sync. 
   • Since the fields can differ between issue types (depending on your Jira version and the type of project, i.e. team-managed or company-managed), this filters down the fields you can map to those that are actually available on the selected issue type.
   • If you want to sync multiple issue types, we recommend to set up one integration each, either in the same workspace or across several workspaces. You can connect integrations from other workspaces (e.g. for Epics or Sub-Tasks) via airfocus hierarchy.
   • You can also filter the synced issues even further by providing a JQL query in the issue filter (read more about JQL here).

Map airfocus and Jira fields

Use mapping to define how information in Jira should be mapped to information in airfocus. If you change an issue or item in one system, the other system will be adjusted accordingly.

You can, for example, define how Jira statuses should be mapped to airfocus single-select fields and/or how Jira labels should be mapped to airfocus multi-select fields.

There are also many more options to map different Jira custom and system fields to your airfocus fields.

When you take a look at the field mapping options, you'll see that two fields are always mapped by default: item names and item descriptions.

You can define for each of your fields whether you want to have a one-way synchronization or a two-way synchronization between the field in Jira and airfocus.

You can set the mapping directions for all fields at once (as far as technically possible) with the “Set direction” button.

By default, the mapping direction is set from Jira to airfocus only and can be changed by the user to whatever is available for mapping.

When setting up a new mapping for one of your fields you’ll find you’re only able to map Jira field to airfocus fields if both ends have the same field type.

When selecting a field in the dropdown, only fields that match the field type will be displayed in the dropdown on the other end.

After selecting two fields you want to map you can select the field options and how they should be mapped.

Overview of all mappable fields types

Mappable Jira system fields:

⚠️ Warning regarding two-way sync for the description field: The two-way syncing process might result in slight changes in your Jira descriptions' content and formatting. This is due to not all Jira's stylings being natively supported in airfocus yet.

⚠️ Warnings regarding people field mapping: The mapping logic is based on display names. Therefore "Kirsten" in Jira does NOT map to "Kirst" in airfocus, even though both accounts use the same email address.

In the instance of Jira only allowing one value on a people field (e.g. they can only have 1 assignee), a sync to airfocus favors the first value for the mapped airfocus people field. For example, a ticket in Jira assigned to "Julian" will overwrite an item in airfocus that is assigned to "Julian and Nikita". Nikita will be removed and only Julian will remain assigned.

Mappable Jira custom fields:

Troubleshoot: Find your date range field

We need at least two date fields (apart from fix versions) to be able to map them to an airfocus date range field.

Our integration can only detects date fields if they are visible on the synced issue type (screen). You need to ensure at least two date fields are on the issue type (screen) on Jira and at least one date range field is available for mapping on your airfocus workspace.

What that looks like in Jira:

• for Jira Cloud team-managed, go to project settings > issue types and drag the field from the right sidebar to the list of fields in the middle.
• for Jira Cloud company-managed (and Jira Server), go to project settings > issues > screens and edit the screen of the issue type you're syncing. You can add additional date fields at the bottom.

Auto-mapping fields

When mapping fields with many options, toggle on "Auto-map field options" to save time. This automatically maps fields with the same values in both airfocus and Jira.

Auto-create field value generation

Toggle on "Auto-create field options" to automatically add new fields created in Jira to airfocus when they are added to an item. 

Note: The auto-create field generator is not case sensitive.

How to map the focus score with Jira

With airfocus' Jira integration, you can use airfocus for prioritization and roadmapping while developers (and others) use Jira for day-to-day development planning.

By default, we already show airfocus data like priority scores, lanes, and timelines in Jira. This help article describes how you can map the airfocus focus score with a Jira custom field (which you can also filter for in Jira).

By mapping the airfocus focus score with your Jira project, you’ll be able to show your number one priority metric right where people work – on each synchronized Jira issue card and the issue card cover. This way you'll get your whole team aligned and focused on which tasks matter.

In order to display the airfocus focus score in Jira, you need to map it with a Jira custom field. The custom field must have the field type "Number field". Setting this up takes around 3 minutes.

Here's how:

1. Inside Jira, click the gear icon in the top-right corner to open the settings.
2. Click Issues.
3. Select Custom fields from the navigation menu on the left side.
4. Click Create custom field from the top-right corner.
5. Select Number field as the field type.
6. Type a name and description (optional).
7. Click Create.
8. Associate the new custom field to screens (of your synced project)
   
9. Go back to your Jira integration settings in airfocus and select the newly created custom field from the dropdown
   

The airfocus focus score will now show up for your Jira issues
 

If you also want to show the focus score on your card covers, follow these steps:

1. Click the three-dot icon in the top-right corner of your board.
2. Select Board settings.
3. Click Card layout from the navigation menu on the left side.
4. Select your focus score custom field from the dropdown.
5. Click Add.
6. You will now also find the focus score on the board.
   

Configure additional settings

• When "Archive unknown issues" is enabled, then previously imported items will be archived in airfocus if they are not present in Jira anymore (or just do not match the JQL filter anymore).
• When "Automatic syncing" is enabled, your integration will automatically sync every 10 minutes and every time you access the workspace.
• Click View logs to view your Jira integration activity logs and see what changes were made before the last sync.

Map item link types

You can sync item link types—such as "Blocks," "Duplicates," and "Relates to"—between Jira and airfocus using either bidirectional or one-way syncing. When bidirectional (two-way) syncing is configured for a link type, any update in one platform automatically reflects in the other, allowing you to visualize dependencies on timelines and roadmaps without manual duplication. For more specific workflows, you can set up one-way syncs or consolidate your data by mapping multiple Jira link types to a single airfocus link type.

To map item link types, follow these steps:

1. Click Extensions from the top-right corner of any airfocus page.
2. Select Manage integrations.
3. Under “Active integrations”, select Jira.
4. Under “Item link type mapping”, click + Add link type mapping.
5. Using the dropdowns, select a link type for Jira on the left and a link type for airfocus on the right.
6. Click the arrow icon under “Direction” to change whether the sync is bidirectional or one-way.
7. Optionally, click + Add link type to add an additional Jira link type to map to a single airfocus link type.
   • If you add an additional link type, when airfocus syncs to Jira, it will sync to the primary link type only.
8. Click Update and synchronize from the bottom of the page.

Item relationships and dependencies will now sync across Jira and airfocus according to the settings you configured.
 

Hierarchy sync

Hierarchy sync for Jira allows you to sync the parent-child relations automatically from your Jira project to airfocus. This allows you to do product management work on airfocus while having the latest Jira hierarchy in sight without needing to switch between airfocus and Jira.

To set up/enable the Hierarchy sync for Jira, you’ll need:

• Two or more workspaces with airfocus hierarchy enabled between them OR a workspace that allows hierarchy relations within the same workspace.
• Two or more Jira issue types synced to airfocus.
• If you have two integrations in two workspaces, sync a single item type for each workspace.
• If you have two integrations in one workspace, sync a single item type for each of the integrations in that one workspace.

A user needs full access to the workspace in order to change anything in the integration.

To set up hierarchy sync, follow these steps:

1. In the workspace settings in airfocus, make sure the airfocus product hierarchy is enabled with another or within your current workspace.
   
2. At the bottom of the Jira integration settings page, toggle on the “Automatic item linking” widget.
3. You can choose any workspace that fulfills the following:
   • The other workspace has a hierarchy relation to the current one.
   • The other workspace has Jira integration to the same Jira instance.
   • The user has full access to the other workspace.
   • The other workspace is in the same airfocus team.

Once you have the Hierarchy sync enabled, you can see the parent-child relationships directly in airfocus.

Note the following when enabling Hierarchy sync for Jira:

• The integration only adds the relations between synced items, not additional items. This means items have to be synchronized by their respective integration already before hierarchy links will be synced.
• The Jira API does not reveal the children of an epic which means it prevents airfocus from detecting whether a Jira epic has any children issues. In order to see the child relationships on airfocus, the epic already has to be synced to airfocus when you sync the children level issues in order for all relationships to be reflected correctly on airfocus.

Hierarchy sync for Jira can also be configured within the same workspace, if multiple Jira issue types are synced to the same airfocus workspace (either through a single or multiple integrations) and has enabled 'Allow hierarchy relations within this workspace' within the Hierarchy tab in the Workspace settings.

A user requires at least read access to the connected Jira project in order to enable Hierarchy sync for Jira.

Note regarding the hierarchy sync for Jira data center/on-prem users:

• The airfocus hierarchy does not sync with Jira on-prem initiatives. Only epics, stories, tasks, and sub-tasks.
• The airfocus hierarchy does sync with all Jira Cloud levels, including initiatives, epics, stories, tasks and sub-tasks.

Additional information

Connect multiple Jira projects

To connect another Jira project from the same Jira instance with your workspace, you don't have to go through the authentication process again. You can add another Jira project integration on the integrations page from now on. The setup will only require selecting the instance and starting the mapping right away.

Static IP addresses to white-list for your Jira Server integration

If you are integrating with an on-premise deployment system like Jira Server, your IT team may need to allow list airfocus in your firewall so airfocus can make connections to your server to create records. You can make the connection through port 443.

Teams on https://app.airfocus.com or https://app.us.airfocus.com use these IP addresses:

• 46.101.71.101
• 46.101.69.142

Teams on https://airfocus.app  use these IP addresses:

• 100.24.176.163
• 34.204.246.112
• 54.227.154.184
• 35.156.253.227
• 18.159.159.136
• 18.199.183.125

Troubleshooting

• Check that the permissions of the user trying to connect airfocus to Jira match the requirements.
• Check for any warnings or missing fields in the field mapping section.
• Click the "Debug" button at the bottom of the integration settings. During the synchronization, several API endpoints are called. If one of them fails, it is difficult to tell which one. The debug dialog shows all calls and their results, to make it easier for you to find a misconfiguration.
• Delete and re-install the integration. Hint: The app link setup to connect airfocus to Jira remains.
• Reach out to our lovely customer success team for additional support.

Give feedback on this article