This article is part of Managing bug report in issue tracker series.

See managing bug reports in issue tracker for common information. Please, read it first. For common information and setup of Jira itself - please see this article. The text below assumes that you already completed Jira installation.

Important Note: This article refers to Jira bug tracker, which was initially (historically) known as "just Jira". Later it was renamed to "Jira Software", and now it is "Jira Cloud". This article does not reference "Jira Core", "Jira Service Management", "Jira Service Desk", "Jira Align", "Jira Work Management" or any other product from Atlassian Jira family. Jira bug tracker can be integrated with BitBucket. If you are looking for a way to submit bug reports to Jira Service Desk instead ("Jira Service Management") - you can use Jira issue collectors. Additionally, exact location of options and their UI are different in various Jira versions. Please, refer to your Jira documentation when in doubt.

Important Note: While EurekaLog supports any type of project and workflow in Jira (see supported workflow), we highly recommend what you use "Bug Tracking" project type in Jira (i.e. not "Scrum", not "Kanban") for automated crash reporting with EurekaLog. Additionally, we recommend that you use "Classic" workflow, "Jira" workflow, or "Build" workflow in your "Bug Tracking" project type. Avoid using "Simplified" workflow when possible. Please note that you can assign "Classic"/"Jira"/"Build" workflow to "Bug" type issues (tickets) only, and use "Simplified" for everything else ("Task", "Epic", "New Feature", etc.).

This article will tell you how to prepare Jira to work with EurekaLog accessing Jira via API. Alternatively, you may use HTTP send method to post bugs to Jira issue collector without using the API.

Below are detailed steps for recommended Jira setup for automatic bug report submission. Before going through setup - make sure to upgrade your Jira to the latest version (if using self-hosted or standalone server).

Some steps below are optional, some steps must be executed only once (like custom fields creation), other are executed from time to time (like creating new projects for your new products) and the rest are executed regularly (like creating product versions).

Full list of necessary actions contains:

Please note that all actions below are just examples. It's recommendation, but it's not necessary to be absolutely like that. You may use another configuration.

Notes:

Creating custom fields

1. (Administration/Issues/Custom Fields) https://your-account.atlassian.net/secure/admin/ViewCustomFields.jspa Create custom field to improve usefulness of EurekaLog.

Open settings for Custom Fields

Most important field is "Count" - to store number of sent/occurred problems. Its type should be "Number" (integer); field name can be arbitrary, like "Occurrences", "Bug count", "Popularity", "Incidents", "Hit Count", etc. Other suggested custom fields are: "BugID" (to store BugID and search issues) and "e-mail" ("user e-mail", which is typically entered in MS Classic error dialog). Both fields should be text fields. Again, field names can be anything.

We strongly recommend to create at least "Count" and "BugID" fields.

Example: two new custom fields

2. Create any other additional fields as you need/like (you can submit values for custom fields at run-time via OnCustomWebFieldsRequest event). Note that you can use "|" symbol (vertical bar) to separate individual values for multi-select custom fields.

Important: Be sure that custom fields are present on issue submission page. Otherwise EurekaLog will not be able to fill them. If some fields are missing - you has to configure your screens.

Verifying fields on "Create Issue" page

Configuring fields depends on your version of Jira. You may need to create/change/adjust Field Configuration, Screen(s), Context(s), Field Layout(s). Please, refer to your Jira guide on custom fields.

Creating user accounts

1. (Administration/User management) https://admin.atlassian.com/yourID/users Create new non-admin user account for bug report submission. Create it with disabled e-mail notification:

Creating new user

Important Note: If your Jira version uses usernames - please remember username of new account. You will be using it later - when entering login credentials into EurekaLog. Do not use e-mail or full name.

Note: Some versions of Jira do not allow you to create users. You are supposed to invite new users via e-mail invitation. Do that to create new user account.

2. Log in as bug report reporting account. Click on your profile icon -> "Account settings". Or use "Settings" -> "Atlassian account settings". Then go do "Security" -> "Create and manage API tokens". This will open https://id.atlassian.com/manage-profile/security/api-tokens page when using cloud / hosted Jira.

Creating a new access token

Create a new access token with any name. Copy/save the created token, you will need it later (see below).

Log off from the account and log back in as admin.

3. Configure new user to have access to Jira.

Important Note: Exact steps depend on your specific Jira version. Please, refer to your Jira guide to learn more about configuring users. Basically, you want to give new user account a read-write access to Jira and your project(s).

Click on "Edit groups" link and add user into developers group (users group have read-only access; developers group have read-write access; administrators group have full control access):

Including account into groups

Some versions of Jira have group like "jira-software-users" - you can use that group.

Double-check that the user account has access to the Jira bug tracker: use "Product Access" link near users/group menu items, and ensure that the user or its group are listed under "Jira Software":

4. Repeat these steps for each bug submitter user account which you want to create.

5. (Optional) You can also create a new group and/or role and include all bug-reporting user accounts into that group (Administration/Groups and Administration/Roles):

Creating new user group for bug reporting

Creating new role for bug reporting

Associating role with group

6. (Optional) Open bug reporting user account and include it into a bug reporting group:

Suggested group setup for bug reporting user accounts

Repeat this for all bug reporting accounts.

Creating projects

1. (Administration/Projects) https://your-account.atlassian.net/jira/settings/projects/manage Create Bug Tracking project for your software product. You may create several projects - one for each of your software products.

Creating new project for bug reports

Important Note: While EurekaLog can work with any project (such as Kanban or Scrum) - we highly recommend that you use Bug Tracking type of project. If you are not using Bug Tracking type of project - be sure to specify/edit names of project statuses in EurekaLog options for Jira.

2. (Optional) (Project Settings / Workflows) https://your-account.atlassian.net/plugins/servlet/project-config/project-key/workflows Assign a workflow for bugs.

Setting up workflows for the project

Some versions of Jira supports customizing workflow(s) for the project. Open your new project, open its settings and go to "Workflows".

Important Note: We do not recommend that you use "Simplified" workflow with EurekaLog. Please, consider using "Jira", "Classic", or "Build" workflows with EurekaLog. If you use any other workflow - ensure your workflow supports transitions required by EurekaLog.

Adding a workflow and assigning issue types to it

Click on the "Add Workflow" button to add workflow to the project. Assign issue type(s) to the selected workflow. We recommend to assign "Bug" type to "Jira"/"Classic"/"Build" workflow.

3. (Optional) Create components for the projects. Typically component is used for identification of the part of your software product.

Creating component(s) for the project

4. (Project Settings / Summary / Versions) https://your-account.atlassian.net/plugins/servlet/project-config/project-key/administer-versions Create versions (called "Releases" in Jira) for the project. If you don't use versioning (highly unrecommended) - you can skip this step.

Managing versions in a project

You should create new version for each release of your software. I.e. when you release (publish on site, send to custom, etc) "YourSoftware 1.0.0.0" - you need to create "1.0.0.0" version. When you release update: "YourSoftware 1.0.1.0" - you need to add "1.0.1.0" version.

Version strings can be arbitrary like "1", "1.0", "1.0.1", "1.0.1.0" or even "1.0.1.0 beta 3". However, it's recommended to use four-number versions with optional textual description, for example: "1.0.1.0" and "1.0.1.0 beta 3".

Note: if you don't want to edit project each time you release new version - you can create versions for the future use. I.e. when you release "YourSoftware 1.0.0.0" - you can create "1.0.0.0", "1.0.1.0", "1.0.2.0", "1.0.3.0"..."1.0.10.0" versions.

For example:

Versions

When reporting - version are taken from file's version information, so you must supply the corresponding version in description of your .exe or .dll files.

Note: EurekaLog will use closest match.

Important Note: EurekaLog will only for "Released" versions, if a corresponding option is enabled. Be sure to mark versions of your compiled .exe as "Released" in Jira.

5. Setup project access rights: permissions and roles.

Enabling external access to bug tracker

1. (Administration/General Configuration) Enable access to bug tracker via API calls:

Enable "Accept remote API calls" option

Note: this option is enabled by default on Jira cloud accounts. It is also may be unavailable in some Jira server installations. Please, refer to documentation for your Jira version for more information.

Integrating Jira and BitBucket

1. You can use Jira as a bug tracker for your BitBucket projects. Please, refer to Atlassian documentation.

EurekaLog setup

1. Enter Jira details into EurekaLog settings of your projects:

Jira settings filled into EurekaLog options

Important Note: some older versions of Jira require you to use your username as login. Do not use e-mail of full name. You are specifying username when creating account for reporting:

Username when creating new account

If you forgot your username, you can always find it in your profile or user management:

Locating username of already created accounts

Notes:

2. Set any additional/common send options.

3. Set/fill custom fields. EurekaLog has support for automatic managing of "Count", "BugID" and "E-Mail" fields. You just need to enter field names in EurekaLog options. For other custom fields you have to fill them manually, for example:

uses

  EEvents, ESysInfo;

procedure SetCustomFields(const ACustom: Pointer; AExceptionInfo: TEurekaExceptionInfo; 

  ASender: TObject; AWebFields: TStrings; var ACallNextHandler: Boolean);

begin

  AWebFields.Values['License'] := GetYourApplicationLicense;

  AWebFields.Values['Tags'] := 'EXE|CRASH|AUTOREPORT';

end;

initialization

  RegisterEventCustomWebFieldsRequest(nil, SetCustomFields);

end.

Note that you can use "|" symbol (vertical bar) to separate individual values for multi-select custom fields.

4. Add any custom data, additional attached files, write necessary event handlers, set exception filters, etc, etc.

Testing

1. Test sending. You can do this right in the EurekaLog send options dialog - by clicking on "Test..." button. This will send test bug report.

Suggested actions are:

These actions should test that sending is actually working.

2. Now it's time to test your application-specific sending.

Now your application is ready for deployment.

Maintaining projects

1. You need to create or update project versions when you ship new release of your software. If you've created a batch of versions in Jira for future use - you may skip it until you've run out of versions.

See also: