1. Workpath Help Center
  2. Account Administration
  3. 💻 Integrations

Setting up the Jira Integration

There are a few important steps to complete in order to set up the Workpath - Jira Integration:

  1. Make sure your Jira instance can be reached from outside your network
  2. Install the integration
  3. Enter your Jira authentication information in Workpath
  4. Set the Jira permission for the integration
  5. Link Workpath Teams to Jira Projects

Let's get started!

 

Step 1: Make sure your Jira instance can be reached from outside your network

This step is not necessary for Jira Cloud.

Firewall

If you are on Jira Data Center (formerly called Server), please make sure that Workpath can reach the Jira API of your Jira instance. You might need to whitelist the following IP address: 3.122.149.234.

Rate limiting

If possible, exclude Workpath from any rate limiting configured in your Jira Data Center instance. Workpath will handle rate limit errors by retrying the request, but the wait times will lead to a degraded experience for users interacting with the Workpath Jira app.

Step 2: Install the integration from the Atlassian Marketplace

  1. Log in to the Jira instance where you want to install the integration as an admin
  2. Go to "Manage Apps" in the Jira admin preferences
  3. Click on "Find new apps" and search for "Workpath"
  4. Click on "Install" next to the Workpath extension for your product, either "Workpath OKRs for Jira Cloud" or "Workpath OKRs for Jira Data Center".

Step 3: Enter your Jira authentication information in Workpath

mceclip0.png

  1. As an admin user, navigate in Workpath to Settings -> Integrations -> Jira
  2. Click on "Add a new connection"
  3. Select your Jira Product: Jira Cloud or Jira Data Center
    1. For Jira Data Center, you have 2 options for for adding information:
      1. You can provide the credentials of a user (username and password)
      2. You can provide authorization via OAuth 2.0
  4. Enter the required information:

Jira Cloud

  • The Jira Cloud URL, i.e. the URL where the Jira instance can be found. In most cases, this is something like https://your-company.atlassian.net/
  • The email address and API token of a user that has at least read permissions in the Jira projects that you want to link to Workpath. Please create an API token as described here.

Jira Data Center (Method 1: Basic Auth)

  • The URL at which your Jira Data Center instance can be reached, e.g. https://your-jira-url.com. Workpath will look for the Jira API in /rest/api/2 of the URL you entered.
  • The username and password for Jira of a user that has at least read permissions in the Jira projects that you want to link to Workpath.
  • The Public and Secret Key. After installing the integration in Jira Data Center, this information can be found when navigating in Jira to Manage Apps -> Manage tokens.

mceclip2.png

Once you entered this information, Workpath will test the connection. In case you receive the error "We could not access any Jira Projects with these credentials.", the credentials (email address/username and/or password/token) are not accepted by the Jira API, please double-check these.

Jira Data Center (Method 2: OAuth)

  • The URL at which your Jira Data Center instance can be reached, e.g. https://your-jira-url.com. Workpath will look for the Jira API in /rest/api/2 of the URL you entered.
  • The Client ID and Client Secret are obtained from the Application Link in Jira.
    • Go to Jira settings -> Applications -> Application links 
    • mceclip1.png
    • Click Create link to create a new link for Workpath.
    • In the popup, select External application and Incoming
    • mceclip3.png
    • In the next screen, provide:
      • Name
        • Can be any name, the following
      • Redirect URL
        • Must be 
          https://connect.workpath.com/jira/v1/server/oauth/callback
      • Permission
        • Must be Write.
      • mceclip4.png 
    • After clicking Save, copy the Client ID and Client secret.
    • mceclip5.png
  • The Public and Secret Key. After installing the integration in Jira Data Center, this information can be found when navigating in Jira to Manage Apps -> Manage tokens.
    • mceclip2.png
  • Now that all fields have been added, just click on Add.
  • After that, click on Sign in with Jira to start the permission flow. This will redirect you to Jira where you need to allow Workpath to access projects and issues.
    • mceclip6.png

Step 4: Set the Jira permission for the integration

After installing the integration in Jira, there is a new permission "View and Link Workpath Goals“ available in your Jira instance.

By default, only Jira admins have this permission and can thereby use the Jira integration. Users without this permission cannot see or use the integration.

Assign this new permission to any user or group that should be able to use the integration:

  1. As an admin user, in Jira go to Settings > System > Global permissions
  2. In the lower section "Grant Permission", select the permission "View and Link Workpath Goals" and assign it to an additional user group.

 

Jira_Permission.gif

 

More information on how to manage permissions can be found in this Atlassian documentation for Jira Cloud and Jira Data Center.

⚠️ If a Jira Project has not been linked to a Workpath team (see step 5 below) then no user will see the Workpath section in a Jira issue. This means that you can provide permissions to a wider audience and they will only see the Workpath section in a Jira issue if that project is connected to a Workpath team.

Step 5: Link Workpath Teams to Jira Projects

The Jira integration can be enabled for any team in Workpath by linking the Jira projects that this team works in, which can be done in the Team settings in Workpath. You can learn more here.

 

Done!

You should now be able to use the integration. Please reach out to us if there are any additional questions. 

More information about the integration and how it can be used can be found here.

 

 

FAQ

Is it possible to link several Jira instances with Workpath?
Absolutely, our platform supports integration with multiple Jira instances to streamline your workflow and enhance productivity.

 

Is it possible to link the same Jira instance to multiple Workpath accounts?

Yes, projects from the same Jira instance can be shared and connected through multiple Workpath accounts.

 

Atlassian has limited the number of automations. Are Workpath synchronizations affected by this limitation?
Workpath's synchronizations are not impacted by Atlassian's automation limits. For the most accurate and detailed information, please reach out to us.


What kind of data is synchronized with Workpath? (Date, Description, etc.)
The data synchronized with Workpath includes several key elements such as the issue title, current status, a direct URL to access the Jira issue from within Workpath, the description, and the issue type (e.g., Story, Bug, etc.), ensuring a comprehensive overview and seamless tracking of your projects.

 

Since when has the Workpath integration been established?
Our integration with Jira has been successfully operational since 2020, continuously facilitating and enhancing our client's project management capabilities.

 

What about data security & data protection related parameters. Is the data stored in Europe?
Data security and protection are paramount at Workpath. Rest assured, all data, without exception, is securely stored in Germany, leveraging the same robust systems used for all other data associated with your Workpath account. This ensures compliance with the strictest data protection regulations and provides peace of mind regarding the security of your information.

 

Was this article helpful?
5 out of 8 found this helpful

Related articles