Skip to main content
Contact Support

Jira Cloud and self-hosted setup

Tags:

Last updated

Learn how to connect your Jira Cloud or Jira self-hosted account to Flow.

When Jira and Flow are connected, Flow receives data from Jira, including:

  • Ticket data such as keys, titles, bodies, and comments
  • User information such as name and email
  • Project names
  • Ticket states, labels, and sprints

Note: The terminology used in Jira and Flow differs slightly. Use this mapping to understand how concepts in Jira map to Flow:

  • A Jira issue is called a ticket in Flow
  • A Jira project is called a ticket project in Flow

Important: Use a service account to create this integration. Learn more about creating a service account.

Permissions

To connect your Jira account to Flow, the service account must have the following permissions to receive project ticket data and metadata:

  • Permission to access Jira.
  • Browse users and groups global permission.
  • Browse projects project permission for each project.
  • Create issues permission for each project.
  • Issue-level security permission to view affected issues, if issue-level security is configured.

Learn more about Global permissions (external site, opens in new tab), Project permissions (external site, opens in new tab), and Issue security schemes (external site, opens in new tab).

Jira permissions are complex, and your instance may have different permissions setups depending on the product and version. Learn more about the API endpoints Flow uses to collect information from Jira to check which other permissions you may need.

Note: By default, on the integration details page and the Ticket projects page, the last updated date is set from the timezone of the Jira user profile associated with the service account. If Flow does not have access to the /rest/api/2/myself endpoint, this time will be listed in UTC.

Troubleshooting Create issues permissions

Most permissions issues with Jira are due to missing Create issues permissions. Missing this permission results in tickets appearing incorrectly in Flow, or not at all.

To verify that your service account has the correct permissions, there are a few options:

  • Check the permission using the Jira Admin Helper (external site, opens in new tab)

  • In your company-managed Jira project, navigate to the Permissions section of Project settings.

    Then scroll down to see the Issue permissions and confirm that the service account is a member of a group or project role with the Create issues permission. Alternatively, the service account might be listed as a user with that permission if you aren't using groups or project roles to manage permissions.

Team-managed Jira projects may require additional permissions and setup due to the differences in team-managed project permissions structures (external site, opens in new tab) versus company-managed Jira projects. The service account needs the same permissions in a team-managed project as in all other projects, and specifically needs the Create issues permission. In many cases, this requires adding the service account as a Member or Administrator to each team-managed project you wish to see data for in Flow.

The most common signal of a missing Create issues permission is the inability to set ticket type assignments during the ticket project configuration.

Tip: If you cannot set ticket type assignments on any project in your Jira integration, the issue is likely a globally missing Create issues permission for the service account. If there are only specific projects experiencing the issue, those projects are likely team-managed projects and the service account should be added as a Member or Administrator to them.

Once the permissions are updated and Flow reprocesses your data, continue to configure your ticket projects as normal.

Version requirements

Jira version 7.13 or higher

Flow integrates with Jira Cloud, Jira Data Center, and Jira Server. Project data is available from Jira Software and Jira Work Management products. While projects from Jira Service Management will appear on the Ticket projects page, they can't be processed by Flow.

back to top

Connecting to Jira

To connect Flow to Jira:

  1. Click Settings in the top navigation of Flow.
  2. In the left navigation under Integrations, click Integrations.
  3. Click the Add integration button in the top right corner of the Integrations page.
  4. Click Jira Cloud & Self-Managed on the Integration Provider page.

Important: If you migrate your Jira instance from Jira self-hosted to Jira Cloud, you must create a new integration. Updating your Base URL for your existing integration doesn't update your connection and Flow can't ingest data If you previously had a connection using OAuth 1.0a or username/password authentication, learn more about migrating to OAuth 2.0.

Note: OAuth 2.0 authentication is not available for Jira Server. Use Access token authentication instead.

OAuth 2.0 is the recommended authentication method for Jira Cloud and Jira Data Center integrations.

Integrations using OAuth 2.0 require the same user permissions for your service account as for access token authentication. However, Flow requests access to a more specific list of read-only scopes as part of our connection to gather the data we require. If you're connecting with Jira Cloud, you'll see a full list of these scopes when you accept the connection between Flow and Jira.

Note: While the service account user must have the Create issues permission, Flow only requests read-only scopes during the OAuth flow. This means Flow does not have the ability to write to your Jira.

The Create issues permission is required for Flow to ingest issue type metadata. While this is a read/write permission, the granular scopes requested during OAuth ensure Flow does not actually have write access to your Jira system in any capacity. If Flow adds functionality in the future that requires more scopes, you will need to specifically authorize those additional scopes during OAuth. They cannot be increased without your direct acceptance.

If you have a Jira Data Center integration, you must configure an application link (external site, opens in new tab) in Jira before taking any steps in Flow. When configuring this link, ensure:

  • The callback/redirect URL is set to https://flow.pluralsight.com/accounts/complete/jira-data-center
  • The application permissions are set to write

Once your application link is created, copy the Client ID and Client secret to input in Flow later.

Tip: Make sure to label your application link so you can easily tell which one is for Flow. If you ever need to reauthenticate, you’ll need to find the Client ID and Client secret again.

On the Jira integration setup page:

  1. Select OAuth.
  2. Enter your Base URL, starting with https and excluding any trailing slashes.
    1. If Flow detects that your base URL is not a Jira Cloud URL, Flow will open additional fields for Client ID and Client secret. Enter the values from your application link in Jira Data Center.
  3. Click Connect with OAuth.
  4. In the resulting window, log in to the Atlassian account for the service account, if prompted.
  5. Select which Jira organization to authenticate with.
  6. Review the requested scopes, then click Accept. This will close the new window.
  7. In Flow, click Next.

Once your authentication is complete, enable or disable services, then name your integration to complete your integration setup.

Tip: Sometimes browser add-ons can interfere with the OAuth connection. Ensure you’ve allowed popups in your browser, and if you’re experiencing issues, make the connection in an Incognito window.

  1. First, create an API token (external site, opens in new tab).
  2. Once you have your token, return to Flow and fill in the following fields to complete your integration:
    1. Email—Enter your email address.
    2. Personal access token—Paste your API token here.
    3. Base URL—Enter your Jira URL, excluding any trailing slashes.
  3. Click Test connection.
  4. Click Next to finalize your integration.

back to top

Final steps

  1. Choose the services you want to integrate from Jira. The only option here is tickets. Leave that status toggle set to on. If you disable tickets, Flow doesn't show any data from Jira.
  2. Click Next.
  3. Enter the name you want to give the Jira integration.
  4. Click Create.
  5. A Successfully Created banner displays once the connection is established.

Once the connection is established, you'll land on the details page for this integration. On this page, toggle the Import button On for each project to import the projects you want to track in Flow. By default, importing for all projects is set Off.

In addition to importing your projects, you can also perform the following actions on this integration:

  • Auto Import all projects—Turning this On auto imports all projects and continues to import new projects if applicable.
  • Pause all imports—This keeps new data from being imported. This does not remove existing data.
  • Refresh—This refreshes all ticket projects and discovers any new projects not already displayed in your Project list.
  • Settings—Click Settings to pause or turn off ticket ingestion. Toggle Ticket Services Off to remove all data associated with this Integration. Pausing this service will pause ingestion of new data.

To learn more about managing your Projects, see Managing ticket projects. To learn more about managing your new integration settings, see Managing integrations.

back to top

Troubleshooting

If you receive an error message when testing your connection during the setup process, check the following and try again:

  • Confirm that your base URL is correct. 
  • Confirm that your permissions are correct. 

OAuth authentication method:

  • Ensure that all fields are left blank except Application name.
  • Confirm that you checked the box next to Create incoming link.

Access token authentication method:

  • Confirm that you pasted your access token without additional characters or spaces before or after the token.
  • Confirm that the email address you provided is the same email address associated with your Jira account.
  • Confirm that you're connecting to Jira Cloud, not Jira Data Center or Jira Server. If you need to connect to Jira Data Center or Jira Server, use an alternate authentication method.

Jira self-hosted

  • Ensure you are using Jira 7.13 or higher.

Epic association

  • If you have multiple Jira integrations and tickets are not being associated with their epics, ensure the ticket projects of both the epic ticket and the child ticket are ingested under the same integration.

Related articles