Jira Integration

Create Jira issues directly from Brightidea submissions! Transfer ideas for project management and implementation, or link ideas to existing issues for improved cross-system tracking. To get started, follow the guide below.

Table of Contents

• Connecting Brightidea to Jira
  • Within Brightidea
  • Within Jira
• Enabling the Jira Integration in Your Activity
• Using the Integration to Create and Link Jira Issues
  • Connecting Jira through Pipeline Steps/List View 
  • Connecting Jira through View Idea
  • General Behavior
• Important Notes

In order to use the Jira integration, a couple levels of configuration are required:

1. Connect your Brightidea system to a Jira instance (requires admin in both)
2. Enable the Jira integration in any number of Activities
3. Authorize individual user accounts between Brightidea & Jira to use all available functionality

Connecting Brightidea to Jira

Once the feature is enabled in your system, you will see a Jira Integration setup panel in System Setup > Ideas > Jira Integration. Make sure you have administrator access in both Brightidea and Jira before continuing (or work together with someone who does).

Within Brightidea

A System Admin will need to open the Jira Integration tab to complete the following steps:

1. Input your company's Jira URL (e.g. https://company.jira.com) into the Jira URL field. Make sure to include the https prefix and hit Save URL after it has been entered. 
   • Note: for on-premise Jira installations, the URL must be externally accessible to Brightidea. If the URL is only visible from within your network or VPN, Brightidea will not be able to connect.
   • The status indicator will not connect properly until the Jira-side setup below is completed
2. The necessary parameters should be auto-generated. If not, or if you are reconfiguring a connection, click Generate new OAuth Key Pair. You will copy these to Jira in the next steps.
   • OAuth Consumer Key is unique to your system
   • Jira Public Key is a unique key used to connect Brightidea to your Jira instance
   • Note: Generate new OAuth Key Pair will invalidate any existing connections, and all users will be required to reauthorize their accounts

Within Jira

A Jira admin will establish the system-to-system connection by:

1. Navigate to Settings > Products > Application Link
   • 
2. From here you will need to create a new Application Link by entering the URL of your Brightidea system (e.g. https://company.brightidea.com) and clicking Create new link
   • 
   • If you see a warning, simply click Continue
     • 
3. We recommend labeling this link "Brightidea" so that it can easily be identified, but you can use any name you'd like. Keep Generic Application selected, then click Continue.
   • 
4. Once the link is created, find it in the Application Link list and click the edit button. Click over to the Incoming Authentication tab. 
   • Paste the OAuth Consumer Key from Brightidea into the Consumer Key field in Jira.
   • Enter "Brightidea" for Consumer Name
   • Description is optional
   • Paste the Public Key from Brightidea to Jira
   • Click Save then Close
   • 
5. Switch back to Brightidea and you should see the connection status change to Connected (may take several seconds)

Your Brightidea and Jira should now be fully connected!

Enabling the Jira Integration in Your Activity

Once the systems are connected, the Jira integration can be enabled in any Activity.

As a System or Activity Admin, navigate in the desired Activity to Site Setup > Ideas > Integrations.

• To enable the Jira integration, click Enable Jira Integration for This Activity and save
• By default the integration will be made available to admins in the Activity. To also allow end-user participants to use the integration, select End-user Access to Jira Integration and save

Using the Integration to Create and Link Jira Issues

After Jira has been successfully connected and enabled in an Activity, Admins will have two different approaches to creating or linking issues from submissions:

1. Admin-only workflow from pipeline Steps or List views
2. Admin or end-user workflow from the View Idea page, which requires additional configuration below

From either approach, the first time creating an issue or link, each user will be prompted to authorize with their Jira accounts:

Connecting to Jira through Pipeline Steps/List View 

From the Actions menu, admins will see two new options in List and Steps views: (a) Create a new Jira issue from a submission or (b) Link a submission to an existing Jira issue.

Simply select a Submission, choose Create or Link from the Actions menu, and follow the dialogs:

Note:

• Existing links and issues that have been created from a submission cannot be viewed from Steps or Lists views
• Issues cannot be unlinked from Steps or List views -- see the View Idea section below for this.

Connecting Jira through View Idea

Using the Jira integration on View Idea requires setting up a widget. Visibility of the widget will be determined by your configuration in the prior step: Enabling the Jira Integration in Your Activity.

1. Navigate to View Idea for any idea in the activity
2. Enable widget editor mode from the floating gear button
3. Select the Jira Issues widget and click the "+" button to add to the page
   • 
4. Move and configure the widget as desired
5. Refresh the page, you should now see the widget load properly:
   • 

Again, authorization is required to Create or Link:

If a user has not authorized, they will see a plain HTML link in the widget to any existing issues by their Jira key.

Authorized users will see a rich view of Jira issues with the issue type, title, and status displayed in line:

Issues can be unlinked by hovering over the issue icon and clicking "unlink."

We also recommend enabling the option "Add Right Column On View Idea 2.0" within the Site Setup > Beta section to display the Jira widget on the right-side of the View Idea page, as seen above.

General Behavior

• Idea Title will be transferred for the Issue Summary
• Idea Description will be transferred to the Issue Description
• Issues will be created and linked on behalf of the acting user, and the account they have authorized
• Access & visibility to Jira projects, issue types, and issues will adhere to that user's Jira permissions

Important Notes

• The Jira instance must be visible to Brightidea for the two systems to communicate; firewalls and [virtual] networks may prevent this for on-premise installations. Check with your IT or Jira admins for more info.
• At this time, Title/Subject and Description are the fields that are transferred to Jira
  • Required fields with no defaults in the Jira project may block submission from Brightidea
  • Additional fields will need to be manually copied as desired, once the issue is created
• Not all rich text formatting can be transferred to Jira at this time. Brightidea uses underlying HTML formatting, and Jira has a specific markdown language that does not map 1:1
  

  • For example, certain formatting styles such as underline, strikethrough and ordered lists may not be parsed over correctly

• Sub-task issue types are not currently supported