*If you have an on-premise Jira implementation, please contact us for help with your integration with CoLab.

Integration capabilities

CoLab's Jira integration enables the following capabilities for users:

• Automatically create Jira issues from CoLab feedback using a flexible rules system.
• Provide direct context about the origin of issues or tasks from the source.
• Use two-way syncing to keep your task backlog organized in both CoLab and Jira.

Setting up the integration

When setting up your first integration between CoLab and Jira, designate a specific user to authenticate the integration. CoLab can only perform actions in Jira that the designated user has permissions for, so it’s important to choose the right person for this role.

In Jira, the admin user who authenticated the integration will always appear as the issue creator in the history tab. We recommend creating an artificial “CoLab” user in Jira with the necessary permissions and using this user for authentication. This approach makes it easy to identify which issues originated in CoLab, rather than showing the name of a specific admin.

Required Jira permissions to properly integrate CoLab

1. From the Jira project you’d like to connect to CoLab, click Project settings on the left side menu.
2. In the Project settings, click Permissions on the left side menu.
3. Review the permissions in this project and make sure that the user who authenticates the CoLab integration has the following permissions:
   • Browse projects - this will allow CoLab to ask users which Jira project to push feedback into.
   • Create issues - this will allow CoLab to create Jira issues when a CoLab feedback is pushed into Jira.
   • Edit issues - this will allow CoLab to update fields when syncing CoLab feedback status & Jira issue status.

Simply put, if CoLab needs the ability to perform an action in a Jira project, the user who is authenticating the connection needs the ability to perform the same action in a Jira project.

Authorizing a Jira connection for the first time

To start adding Jira integrations to CoLab, follow these steps:

1. As a CoLab company admin, head to the Admin settings and click on the Integrations tab
2. Connecting CoLab to Jira starts here by clicking on “Connect”
3. Before filling out all the required fields, you will need to create an API token so CoLab can access your Jira instance
   a. Follow the instructions on the Manage API tokens for your Atlassian account support page to login to the API tokens page
   b. On the API tokens page in Jira, click on Create API Token
   c. Add a token label (ie. CoLab)
   d. Create your API token
4. Fill out the 3 required fields for authenticating the connection:
   a. Add the user’s email who will authenticate the connection
   b. Enter the API token for your Atlassian account (see Step 3 on how to create an API token)
   c. Add your Jira workspace URL (ie. https://example.atlassian.net)
5. After successful authentication, you should see a new prompt to create an integration!

Creating and Configuring Integrations

Once you’ve authenticated the connection between CoLab and Jira, the next step is to create and configure one or more integrations. Each integration represents a connection between a CoLab workspace and a Jira project.

Creating a new Jira integration

To add a Jira integration to CoLab, follow these steps:

1. Click create new integration
   a. Name your integration
   b. Choose the Jira project you want to integrate
   c. Choose the CoLab workspace you want to integrate
   ‍
2. Select a rule to determine when to send feedback to Jira
   a. Send all feedback: This will automatically create Jira issues for every piece of feedback created
   b. Send feedback by feedback type: This will automatically create Jira issues for every piece of feedback created of a specified type
   c. Send feedback by tag: This will automatically create Jira issues for every piece of feedback that gets tagged with a specified feedback tag
   ‍
3. Map CoLab feedback to Jira issues
   a. Select the Jira issue type you would like to be auto-created from CoLab feedback
   b. Select the Jira issue status you would like to sync with the “Closed” feedback status so that “closing” feedback in CoLab will close its corresponding Jira issue & vice versa
   ‍
4. After finishing all of the steps to configure your integration, you will need to complete the integration setup using an auto-generated webhook URL
   a. CoLab Feedback Status <> Jira Issue Status Mapping is as follows:
   ‍
   "Open" <> "To Do"
   "In progress" <> "In Progress"
   “For review” <> “In Progress”
   "Accepted (closed)" <> "Done"
   “Rejected (closed)” <> “Done”
   “Informational” <> “Done”
   
   b. Jira Issue Status <> CoLab Feedback Status is as follows:
   
   "To do" <> "Open"
   "In progress" <> "In progress"
   "Done" <> "Closed Accepted"
   
   c. To support bi-directional syncing, you will need to create a webhook under system settings in Jira
   d. When the webhook is created, copy the webhook URL from CoLab and paste it into the webhook URL field in Jira
   e. Finally, select the issue “created” and “updated” events so that issues & feedback can sync properly

CoLab <> Jira integrations in action

After creating an integration, you’re all set! Jira issues will be automatically created in your specified Jira projects based on the rules you defined in your integrations.

On the CoLab side, you’ll notice a couple of things in-app:

1. For CoLab feedback that trigger the Jira integration, you’ll see a “Linked Jira Issue” field added to the feedback in the Feedback Details section
2. In Track, you’ll also see a “Linked Jira Issue” column in the feedback table
3. For linked CoLab feedback & Jira issues, closing one will result in closing the other
4. If the CoLab <> Jira connection disconnects for any reason, you’ll find a warning banner on the Integrations page in Admin settings with a prompt to reconnect
5. Reconnecting will require filling out the credentials used to authenticate the connection
   a. The user’s email who will authenticate the connection
   b. The API token for your Atlassian account
   c. Your Jira workspace URL

Ready to connect your engineering collaboration and project management processes in one seamless workflow using CoLab’s Jira integration?