The Jira Cloud block facilitates a one-way import from projects in Jira into Airtable. Users can now collaborate with greater flexibility and visibility when working with engineering teams.
As a popular bug tracking system for engineers, Jira contains a vast amount of project-related data that other teams may need. However, the interface is not always suitable for cross department workflows. Many teams are overwhelmed by Jira and only need a subset of the information that is relevant to their work. The Jira Cloud block allows teams to import only what they need and the flexibility to organize the data to suit their process.
To use the integration, you must be on Jira Cloud (not Jira Server) - easy instructions on how to check which version you’re on here.
Before you add the Jira Cloud block to your base, you will want to check the following:
1. Confirm you have implemented Jira Cloud.
If your access URL is
jira.<domain>.com, you have a locally hosted Jira Server implementation 🚫
2. Create an API Key within your Jira Cloud Implementation - instructions on how to do this are here.
- Store the API Key value securely in a password vault. Anyone with access to this key could gain access to your Jira Cloud information.
- If this value is lost, a new key must be generated. It cannot be viewed again
- The account tied to the Jira Cloud API Key must have an appropriate level of access to read each mapped value
Enabling Assignee Fields
To fully utilize the Assignee field, additional configuration in Jira Cloud is needed.
Due to privacy limitations of the Jira API, users can only import assignee information after they enable user email visibility in Jira. This change only alters who within your project can view the user email on the user profile page. It does not change any project-specific privacy settings, like who can view or access your project.
You can either have an admin change these settings globally or ask each of your project members to change their personal settings. It should take less than a minute to adjust these settings.
If you’re an admin, you can click on “Jira System settings” and enable the ability to pull in assignees by changing the user email visibility from “Hidden” to “Public” inside your organization. NOTE: “Public" is the only supported option at this time.
If you’d prefer each individual to change their settings, you can update your profile information by going to your Profile and visibility page and changing your email visibility (see image below). You can follow the instructions here.
- Have each member of your project click on their Profile Icon → Account Settings
- On the Profile and Visibility page → Scroll to the bottom Contact section
- Change “Only you and admins” to “Anyone”
Getting started with the Jira Cloud block
When you first add the block to your dashboard, the block prompts you to connect to a Jira account. Follow the on-screen instructions to allow Airtable connect to Jira Cloud.
Enter your email: Use the email address linked to the API Key created under the Getting Started Section
Enter your Jira Workspace name: This is the name of your Jira implementation - do not include .atlassian.net
Save your API token: This is the code saved when creating the API Key under the Getting Started Section
Importing issue types
To import issues of any type (tasks, sub-tasks, new features, bugs, epics, and improvements) from a project, you can either configure the options in the Issues tab or use custom JQL (Jira Query Language) for more complex selections.
Select Issues tab
Select Project: Select the Project from Jira Cloud that you would like to import into Airtable. (All Projects or a specific project)
Issue Type: Select issue type to import. All available issue types can be selected.
Select Table: Table will default to the active Table. This can be changed to any available table in the base.
Merge with existing records:
- If you choose to merge records, each time the import is executed, only new records will be added to the table.
- If you choose not to merge records, each time the import is executed, a new record will be added to the table.
- If a Jira record no longer meets the criteria configured in the import block, it will not be removed or updated from the table.
The configuration is set to import only issues with the type “Bug”. Upon execution, the Jira record is added to the table. In Jira Cloud, the Jira ISSUE TYPE is CHANGED FROM "BUG" TO "IMPROVEMENT". HOWEVER, YOUR SETTINGS of the Jira block MEANS THAT IT only imports "BUG" ISSUE TYPES from Jira and does not sync THIS NEW information. Since the block is only returning Jiras tagged as "Bug", this record will remain UNCHANGED in your Airtable.
Custom JQL Tab
The Jira Cloud block supports JQL (Jira Query Language). Therefore, if you have any custom searches in Jira, you can copy these advanced queries from Jira and add them to this tab.
- If you choose to use JQL, be aware that if a Jira no longer falls within the JQL results, the block does not remove or update the record.
issuetype = Bug AND project = MW AND resolution = Unresolved AND status = "In Progress" AND assignee in (currentUser()) ORDER BY priority DESC
The query shown says to only return all “Bugs” in the “MW” Project that are “Unresolved” and “In Progress” and assigned to the “Current User”**. In Jira, the status changes to “In Review” and assigned to another user, upon the next block execution this record will no longer be returned as part of the JQL query. Since the Jira Cloud block only imports information from Jira and does not sync information this record will remain untouched in the Airtable Table.
**JQL currentUser refers to the account tied to the API Key and not the user executing the import
When a Jira ticket is deleted (but has already been pulled into Airtable), the Airtable record will not be deleted and will no longer be updated.
The list below outlines Jira to Airtable supported field type configuration. Field types in BLUE are configured based on Airtable's recommended best practice.
- Issue Key - Single Line, Long Text
- Status - Single Line, Long Text, Single Select
- Assignee - Single Line, Long Text, Collaborator
- Summary - Single Line, Long Text
- Created Date - Single Line, Long Text, Date
- Due Date - Single Line, Long Text, Date
- Labels - Single Line, Long Text, Multiple Select
- Description - Single Line, Long Text
- URL - Single Line, Long Text, URL, Link to another record
- Priority - Single Line, Long Text, Single Select
- Issue Type - Single Line, Long Text, Single Select
- Formatted text, code, emojis, embedded attachments and tagged users will appear as unformatted plain text
- If you’re importing Jira fields into Airtable Multiple Select and Single Select fields, the options need to be declared within Airtable prior to the initial import
- Airtable is case sensitive, so make sure Multiple Select and Single Select values match Jira exactly (i.e. Sub-Task is not the same as Sub-task)
- Assignees will appear blank if User Email Visibility is not set to Public within Jira Cloud settings
Updating your project
Records can be updated within Airtable by manually running the Jira Cloud block from the blocks dashboard. In addition to updating records, you are able to clearly the last time records were imported from Jira.
- Multiple Select and Single Select fields need to be manually updated to add any new selections to match Jira prior to any subsequent imports
Recommended Best Practice
- Configure a separate table for each project using the Select Issues Tab
- Create a separate Jira Cloud block for each Jira project. You can add more block dashboards and re-name them to stay organized. Just refer to the dropdown below the blocks icon, which is named "Dashboard 1" by default.
- Select All Issue Types and Merge Records so imported records update successfully
- Configure all Multi-Select, Single Select and Collaborators within Airtable prior to import
- Update choices to any Multi-Select or Single Select Field in the table prior to making changes in Jira Cloud
- Confirm Date Field formatting matches Jira Cloud date formatting to avoid
- Include a Last Modified Time field to the table to identify the last time the record was updated
Updating your Jira API Credentials
If you need to change your Jira API credentials, click the settings wheel in the top right hand corner of your block to insert new credentials.
Why are my date fields blank?
Confirm the date configuration within Airtable matches the Jira Cloud date configuration
Why are my Assignees all blank? Why are only some of my Assignees blank?
This will happen if the User Email Visibility on the Jira Cloud Implementation has not been set to Public or if an individual has concealed their individual setting to Hidden.
Why are my Statuses / Priorities / Labels blank?
If you’ve are importing to a Multi-Select or Single Select field and the selections being imported from Jira are not available as configured selections, the field will not update. Make sure all selections are configured correctly and matches text formatting exactly.