Atlassian Jira

This guide was written specifically for integrating the Atlassian Jira Cloud product with FOSSA, although this will likely work if you are using a Jira Server/on-premises version as well.

There are two main features of FOSSA's Jira integration:
1) The ability to export FOSSA issues as new tickets in Jira.
2) The ability to resolve issues within Jira and have the linked FOSSA issue resolved automatically.

Setup and Configuration

In order to configure these two features, you will need to first obtain/create some permissions within Jira:

• To export issues: Jira "Product Access" is required.
• To resolve issues: Jira "Administration Access" is required (to create the webhook).

A permission group can be created to inherit both Product and Administration permission to give the user of that group access to both.

To integrate Jira with FOSSA, head over to the Jira integration settings page (/account/settings/integrations/jira). This page allows you to configure your Jira site integration(s). Start by clicking Add Site if you have not set it up previously.

Name and Site URL

Give your Jira site a unique name (only relevant if setting configuring multiple Jira integrations), and then input your Jira site URL. Note that this should just be the base URL, for example if using Jira cloud it might be something like your-org.atlassian.com.

Project Key(s)

Every Jira project has a key, usually a 3-4 character unique identifier. You'd be able to see this in the URL of the project, and it is used as the prefix for all issue IDs within that project. You can also find it in the right-hand details panel of each project summary, under Key.

You can include multiple projects (for example, if your frontend and backend teams use different Jira projects to track issues), but you must include at least one project key.

Issue Types and Labels

Issue types map directly to the types of issues you have configured in Jira, so type them exactly as they appear there. Examples of default issue types include "Bug" and "Task". Labels don't need to be predefined in Jira, so you can input anything you wish to label FOSSA-exported issues with.

📘

Tip:

Users often like all FOSSA exported issues to use the same label or issue type for easier tracking, so perhaps create a new "FOSSA" label or issue type within your Jira site.

Credentials

You'll need to authenticate with Jira in order to integrate successfully. Enter the email of a user who has permission to create and resolve issues (consider creating a new "FOSSA user" within your Jira instance).

API Token: Jira Cloud

Jira Cloud allows users to create API tokens that integrations such as FOSSA can use to communicate with Jira on the user's behalf. FOSSA requires that a Jira user with permission to create, resolve, and modify users create the API token.

You can follow this guide for creating a new API token.

When configuring your Jira site in FOSSA, use the username of the Jira user that created the API token, and use the API token as the user's password.

API Token: Jira Server/On-prem

For Jira Server/on-prem users, you will need to create a new user for FOSSA within your Jira instance.

1. Create a new user:

Specify whatever username/password you'd like in the screen above. By default, we keep the combination fossabot/fossa123.

2. Add user as an admin

Custom Fields

❗️

IMPORTANT

FOSSA supports exporting issues with simple text-based custom fields. To configure a custom field in Jira, follow this guide.

You can integrate custom fields with FOSSA by doing the following on the Jira settings page:

1. In the Jira integration settings page, click Add Field under the custom fields section.
2. Enter the Field ID of the custom field. You can find this ID in your Jira site by clicking on:
   • Project Settings

- In the sidebar: Issues > Fields

- Clicking on the Edit button at the top right of the table (the pencil).

- Click Edit on the field you wish to add.
- In the URL, you will find something like `orderableFieldId=customfield_10031`

- All you need is the numeric portion a the end of the ID (eg: `10031`)

3. Add a display name (usually the same name the field has in Jira).
4. Optionally include a default value for the field.
5. If you want all issues to include this field when exported from FOSSA, ensure that "required" is selected.

Headers

If your Jira configuration requires additional request headers (perhaps for authentication), you can set them at the bottom of the Jira settings page. This is an advanced feature and you probably don't need to worry about it if you are integrating with Jira cloud.

Webhooks

Once you save your Jira site settings, a webhook URL will be generated for you. FOSSA requires webhooks to sync issue status with Jira. This means that when a user closes an issue in Jira, the corresponding issue will be resolved in FOSSA.

In order to tell Jira about this webhook, follow these steps:

1. In Jira, navigate to Admin > System > Advanced > WebHooks.

2. Create a new webhook.

3. Enter in your FOSSA IP/Port with the path specified below. Note that the webhook URL is different for each Jira site that you configure in FOSSA.

4. Define events for updating/deleting issues:

5.Then click the Create on the bottom of the form. The created webhook should look something like:

Troubleshooting

If issues aren't getting exported, please check your logs for common errors:

• "The issue type selected is invalid."

When FOSSA generates a ticket, by default it sets the Jira issueType to be Task. This is one of the default issue types for new Jira installations, but your admin may have deleted/configured out this issue type or your installation could just be missing it. Check on the existing issue types in Jira and create the Task type if it is missing.

See the Jira help doc for more instructions.