Select JIRA as a data source

1. On the main menu, click Perf, and then open the required unit.

2. On the right of the toolbar, click the Configure Data Sources icon. The data sources configuration opens.

Open

3. In the Data Sources Configuration window, in the Data Sources tab, select JIRA. The Step 2. Configure Source pane opens.

Open

4. On the Step 2 pane configure JIRA Data Source.

1. Configure credentials

There are 4 options of Jira integration:

• Basic - authentification flow, which supports default credentional setting.

• OIDC - Open ID Connect authentication protocol for Jira based on OAuth 2.0.

• OAuth 1.0 - is an authentication protocol, which allows to integrate Perf with Jira that support OAuth 1.0 or if you have security concerns around sharing login credentials with third-party applications.

• Personal Access Token - is an API token generated by Jira (server version) and linked to particular user profile. This API token provide access to Jira API. Token can has expiration and can be revoked any time by user.

1.1 Basic authentication

The following information must be provided:

• URL - JIRA instance URL (without a project key);

• Login (or e-mail);

• Password or API token;

• Project key: it allows you entering more than one project key but overall number of tickets from all projects should not exceed 120.000 otherwise data load will take too long and may fail;

• Optional. Issue filter ID or JQL. Filter should be public (see Obtaining Jira Filter ID );

• Optional. Advanced Settings to tune data load from JIRA;

• Optional. Requests per second - how many requests to do in a second to get tickets from Jira, expected value is from 1 to 1000;

• Optional. Tickets per request - how many tickets to get from JIRA during a request, expected value is from 1 to 100, by default it is 50.

1.2 OAuth1 authentication

The following information must be provided:

• Access token - In order to use OAuth 1.0 with Jira in Perf, you will need to obtain an Access Token from Jira and provide it to Perf as part of the data source configuration settings. Click “Get Token” and follow instriction.

• Private Key - generated a public-private key pair (see Jira guidline).

• Consumer Key - is a unique identifier assigned to a client application by Jira during the registration process.

1.3 OIDC authentication

The following information must be provided:

• Token URL - URL of your Jira instance's authorization server. This is typically in the format of https://<your-jira-instance-url>/oauth/token.

• Client ID - unique identifier assigned to your client application by the Jira instance.

• Login - login/Jira username

• Password - Jira passwor

1.4 Personal Access Token (PAT)

1. Go to your Project, Configure Data Source

2. Click on the "Add Data Source" button and select "Jira" from the list of available datasources.

3. Choose Basic Auth as Type of Integration

4. Put jira-api-token as a Login and your PAT as Password/API token

5. Press 'Check Connection'

Check connection

Once you completed credentials configuration, check the connection. PERF will check connectivity to your Jira and get some metadata from it.

To check connection:

1. Click Check Connection. If the connection is successful, the Next button appears.

2. Click Next.

2. Workflows Interpretation

Workflows represent processes on your project and give you control over the project's progress. PERF simplifies workflows by distributing each of them into three different buckets.
At this step issue statuses pulled from a JIRA project are to be distributed into 3 buckets: To Do, In Progress, and Done.

• To Do: for statuses meaning the item is not ready for development.

• In Progress: for statuses meaning the item is in development.

• Done: for statuses meaning the item satisfies the "Definition of Done" criterion in a project.

To distribute statuses across buckets click status and drag it to the respective bucket. This mapping will directly affect charts in PERF, e.g. "Done" statuses will influence the calculation of a team velocity.

To distribute unused item types drag the item types which are not used for tracking, to the Ignored Issue Types bucket. Click the X icon in the item to deactivate the item.

Include sub-items 

Checkbox "Include sub-items into metrics calculation" works as follows: 

• If the checkbox is checked all sub-items estimates and their quantity will be taken into account while calculating metrics (it mostly affects Productivity  & Scope and Backlog metrics).

• If the checkbox is unchecked sub-items are not included in the calculation in items at all but estimates are summarized in most of the Productivity metrics.

Change is applied immediately, data load is unnecessary.

For more details, see Include Sub-Items into Metrics Calculation.

Workflow updates type

Jira workflows could be changed and then a new status could be added or removed the existing one. To manage changes in the configuration you can choose between automatic and manual workflows update.

3. Configure fields mapping

Custom fields in Jira enable collecting additional information not available in the default system fields. 

PERF allows using custom fields: 

• to calculate metrics with custom fields (e.g., story points estimations, person-hours estimations, severity, priority, etc.);

• to build custom metrics over the data collected in the custom fields;

• to use custom fields in PERF and make accurate calculations, defining where the project saves the required data.

To map metrics attribute with custom fields, select the needed attribute in the table and choose the corresponding custom field. Otherwise, PERF will use a standard system field for the parameter.

If you plan to build custom metrics over data with custom fields, we recommend adding required custom fields to the table to be available in the "Fields" tab of advanced custom metrics.

Using criteria builder for configuring settings

While using the Add new rule or ADD CRITERION buttons, pay attention to multiple conditions and how they logically interact with each other.

4. Configure scope management

This section describes how to configure scope management for Jira data source.

Definition of ready

Is used to configure what work items are considered to be ready for development for the project, so the affected metrics are calculated correctly.

Definition of work buckets

Configure what issues are considered as features, defects and debts on the project.

Defects work bucket affects all quality-related metrics based on data from release and task tracking data sources (defines work items used for defects tracking).

Track changes in requirements

Define issue types and fields that must remain unchangeable after a work item (requirement) is marked as ready for development. This setting is used in metric.

Criteria can include issue type and a field, also a custom field.

Sprint grace periods

Grace periods are used to adjust sprints lengths to the project’s specifics. See the affected metrics section to learn more.

Estimation & tracking hygiene

These settings define what work items should be estimated in story points or person-hours on the project, to manage estimation & tracking discipline on the project.

Filter and group sprints expressions

Some projects might have overlapping or parallel sprints that may need to be filtered out from the metrics or grouped to show combined values. See the affected metrics section to learn how to filter or group the sprints.

Blocking dependencies identification

Use this setting to define what dependencies are considered blocking on the project, for example when one issue can't be resolved before another one. So if such 'blocking' link types are provided here, they will allow showing improperly sequenced dependencies. For example, if a Story A depends on another Story B scheduled for a later release, this case will be reflected as an improper dependency which requires a re-planning: Story B should come before story A in this example.

Discovered blocking dependencies will be displayed on metric.

5. Set quality management rules

Invalid defects

This setting is used to mark defects that are IN-valid (thus actually NOT considered) by the team as the defects. This setting affect metric.

Top-priority defects

Define the attributes you use to label defects to be fixed in the first place

Escaped defects

Configure parameters of the defects discovered by the Customers or end users.

6. Configure on-time delivery targets

This step is necessary of you wish to use metrics to monitor commitments fulfillment, e.g. all critical bugs are fixed within 24h after reporting. 

PERF uses information provided at this step to properly calculate metrics related to the productivity area such as follows: 

7. Complete configuration process 

To complete JIRA configuration:

1. Click Save. The Run Data Load button appears.

2. Click Run Data Load to start data loading from JIRA.