Jira - Spotify for Backstage

The Jira integration plugin for Soundcheck supports the extraction of the following facts:

Issues Search
Issues Count

Prerequisites

Configure Jira integration in Backstage

Integrations are configured at the root level of app-config.yaml. Here’s an example configuration for Jira:

Basic authentication option:

soundcheck:
  collectors:
    jira:
      baseUrl: https://jira-instance.atlassian.net
      username: username # This could be your email or username that you use to log in to jira
      apiToken: token # Generate new token https://id.atlassian.com/manage-profile/security/api-tokens

Personal Access token (bearer token) authentication option:

soundcheck:
  collectors:
    jira:
      baseUrl: https://jira-instance.atlassian.net
      personalAccessToken: token # Generate new token https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html

Add the JiraFactCollector to Soundcheck

First, add the @spotify/backstage-plugin-soundcheck-backend-module-jira package:

yarn workspace backend add @spotify/backstage-plugin-soundcheck-backend-module-jira

Then add the following to your packages/backend/src/index.ts file:

packages/backend/src/index.ts

const backend = createBackend();

backend.add(import('@spotify/backstage-plugin-soundcheck-backend'));
backend.add(import('@spotify/backstage-plugin-soundcheck-backend-module-jira'));
// ...

backend.start();

Consult the Soundcheck Backend documentation for additional details on setting up the Soundcheck backend.

Plugin Configuration

The collection of Jira facts is driven by configuration. To learn more about the configuration, consult the Defining Jira Fact Collectors section. Jira Fact Collector can be configured via YAML or No-Code UI. If you configure it via both YAML and No-Code UI, the configurations will be merged. It’s preferable to choose a single source for the Fact Collectors configuration (either No-Code UI or YAML) to avoid confusing merge results.

No-Code UI Configuration Option

Make sure the prerequisite Configure Jira integration in Backstage is completed and Jira instance details are configured.
To enable the Jira Integration, go to Soundcheck > Integrations > Jira and click the Configure button. To learn more about the No-Code UI config, see the Configuring a fact collector (integration) via the no-code UI.

YAML Configuration Option

Create a jira-facts-collectors.yaml file in the root of your Backstage repository and fill in all your Jira Fact Collectors. A simple example Jira fact collector is listed below.

---
baseUrl: https://jira-instance.atlassian.net
username: username # This could be your email or username that you use to log in to jira
apiToken: token # Generate new token https://id.atlassian.com/manage-profile/security/api-tokens
collects:
  - type: issues-search
    filter:
      - spec.lifecycle: 'production'
        spec.type: 'website'
    cache: false
    jql: status="To Do"
  - type: issues-count
    filter:
      - spec.lifecycle: 'production'
        spec.type: 'website'
    cache: false
    jql: status="To Do"

Note: this file will be loaded at runtime along with the rest of your Backstage configuration files, so make sure it’s available in deployed environments in the same way as your app-config.yaml files.

Add a Soundcheck collectors field to the app-config.yaml and reference the newly created jira-facts-collectors.yaml file.

# app-config.yaml
soundcheck:
  collectors:
    jira:
      $include: ./jira-facts-collectors.yaml

Defining Jira Fact Collectors

This section describes the data shape and semantics of Jira Fact Collectors.

Overall Shape Of A Jira Fact Collector

The following is an example of a descriptor file for a Jira Fact Collector:

---
baseUrl: https://jira-instance.atlassian.net
username: username # This could be your email or username that you use to log in to jira
apiToken: token # Generate new token https://id.atlassian.com/manage-profile/security/api-tokens
collects:
  - type: issues-search
    filter:
      - spec.lifecycle: 'production'
        spec.type: 'website'
    cache: false
    jql: status="To Do"
  - type: issues-count
    filter:
      - spec.lifecycle: 'production'
        spec.type: 'website'
    cache: false
    jql: status="To Do"

Below are the details for each field.

`baseUrl` [required]

The base URL of the Jira instance to use.

`apiToken` [optional]

Jira API token to use for basic authentication (together with username). If not provided, the plugin will attempt to use personalAccessToken as bearer token for authentication.

`username` [optional]

Jira username or email to use for basic authentication (together with apiToken). If not provided, the plugin will attempt to use personalAccessToken as bearer token for authentication.

`personalAccessToken` [optional]

Jira Personal Access token to use for authentication as bearer token. If not provided, the plugin will attempt to use username and apiToken for basic authentication.

`collects` [required]

An array describing which facts to collect.

Overall Shape Of A Fact Collector

Each collector supports the fields described below.

`type` [required]

The type of the extractor (e.g. issues-search, issues-count).

`frequency` [optional]

The frequency at which the fact collection should be executed. Possible values are either a cron expression { cron: ... } or HumanDuration. If provided, it overrides the default frequency provided at the top level. If not provided, it defaults to the frequency provided at the top level. If neither extractor’s frequency nor default frequency is provided, the fact will only be collected on demand. Example:

frequency:
  minutes: 10

`initialDelay` [optional]

The amount of time that should pass before the first invocation happens. Possible values are either a cron expression { cron: ... } or HumanDuration. Example:

initialDelay:
  seconds: 30

`batchSize` [optional]

The number of entities to collect facts for at once. Optional, the default value is 1. Note: Fact collection for a batch of entities is still considered as one hit towards the rate limits by the Soundcheck Rate Limiting engine, while the actual number of hits will be equal to the batchSize. Example:

batchSize: 100

`filter` [optional]

A filter specifying which entities to collect the specified facts for. Matches the filter format used by the Catalog API. If provided, it overrides the default filter provided at the top level. If not provided, it defaults to the filter provided at the top level. If neither extractor’s filter nor default filter is provided, the fact will be collected for all entities. See filters for more details.

`exclude` [optional]

Entities matching this filter will be skipped during the fact collection process. Can be used in combination with filter. Matches the filter format used by the Catalog API.

filter:
  - kind: component
exclude:
  - spec.type: documentation

`cache` [optional]

If the collected facts should be cached, and if so for how long. Possible values are either true or false or a nested { duration: HumanDuration } field. If provided it, overrides the default cache config provided at the top level. If not provided, it defaults to the cache config provided at the top level. If neither extractor’s cache nor default cache config is provided, the fact will not be cached. Example:

cache:
  duration:
    hours: 24

`jql` [optional]

You can use the Jira Query Language (JQL) to specify criteria to search for issues in Jira. Check out JQL docs for more examples.

Rate Limiting (Optional)

This fact collector can be rate limited in Soundcheck using the following configuration:

soundcheck:
  job:
    workers:
      jira:
        limiter:
          max: 400
          duration: 60000

Jira API has a rate limiting policy in place. We recommend setting your rate limit to something that will avoid exceeding your quota, i.e. in the example above, we set the rate limit to 400 executions every minute. This fact collector handles 429 rate limit errors from Jira. Soundcheck will automatically wait and retry requests that are rate limited.

Entity configuration

In your catalog-info.yaml file, add the following metadata annotation to allow the plugin to map an entity to a project in Jira.

metadata:
  annotations:
    atlassian.net/jql: project = <project-id>

Check out JQL docs for more examples.

Collecting Issues Search Fact

An Issues Search Fact contains information about issues from:

Get issues using JQL API for Jira Server (hosted) instances.
Search for issues using JQL enhanced search API for Jira Cloud instances.

Jira has recently deprecated and removed their Get issues using JQL API for Jira Cloud instances. If you are using Jira Cloud, Soundcheck will detect it automatically and the fact will be collected from Jira’s new Search for issues using JQL enhanced search API. Please be mindful of the minor differences in the output schemas of these two APIs. You may need to update the checks that depend on this fact.

If JQL is defined in both places: soundcheck.collectors.jira.collects[?(@.type === 'issues-search')].jql and metadata.annotations["atlassian.net/jql"], the plugin will concatenate them with an AND. Plugin will not remove any duplicate params. This is useful if you want to create reusable facts, for example you can create fact that will look at issues with the status To Do like this:

soundcheck:
  collectors:
    jira:
      collects:
        - factName: todoIssues
          type: issues-search
          jql: status="To Do"

In the next step you may want to restrict the jql to only look for issues with status To Do AND where project key is PROJECT. In your entity you would add following annotation:

metadata:
  annotations:
    atlassian.net/jql: project = "PROJECT"

The next step is to create a check that could look like this:

soundcheck:
  checks:
    - id: has_no_todo_tickets
      rule:
        factRef: jira:default/todoIssues
        path: $.issues
        operator: hasLengthOf
        value: 0

And finally add it to a track:

soundcheck:
  tracks:
    - id: product-certified
      name: Product certified
      ownerEntityRef: group:default/example-owner
      description: >
        Improve quality of product backlog
      documentationURL: https://www.backstage.io
      filter:
        catalog:
          metadata.tags: someTagValue
      levels:
        - ordinal: 1
          checks:
            - id: has_no_todo_tickets
              name: checks if there are any todo tickets
              description: >
                This checks if there are any todo tickets for the project

The plugin will call the JIRA endpoint with following jql value (status="To Do") AND (project = "PROJECT") for all entities with tag someTagValue. If there are 0 issues with status To Do for project PROJECT the check will be green, otherwise it will fail. The following is an example response from Jira Issues Search API:

{
  "issues": [
    {
      "expand": "html",
      "id": "10230",
      "self": "http://localhost:7007/api/soundcheck/issue/BULK-62",
      "key": "BULK-62",
      "fields": {
        "summary": "testing",
        "timetracking": null,
        "issuetype": {
          "self": "http://localhost:7007/api/soundcheck/issuetype/5",
          "id": "5",
          "description": "The sub-task of the issue",
          "iconUrl": "http://localhost:7007/images/icons/issue_subtask.gif",
          "name": "Sub-task",
          "subtask": true
        },
        "transitions": "http://localhost:7007/api/soundcheck/issue/BULK-62/transitions"
      },
      "customfield_10071": null
    },
    {
      "expand": "html",
      "id": "10004",
      "self": "http://localhost:7007/api/soundcheck/issue/BULK-47",
      "key": "BULK-47",
      "fields": {
        "summary": "Cheese v1 2.0 issue",
        "timetracking": null,
        "issuetype": {
          "self": "http://localhost:7007/api/soundcheck/issuetype/3",
          "id": "3",
          "description": "A task that needs to be done.",
          "iconUrl": "http://localhost:7007/images/icons/task.gif",
          "name": "Task",
          "subtask": false
        },
        "transitions": "http://localhost:7007/api/soundcheck/issue/BULK-47/transitions"
      }
    }
  ]
}

Collecting Issues Count Fact

An Issues Count Fact contains information about issues from:

Get issues using JQL API for Jira Server (hosted) instances.
Count issues using JQL API for Jira Cloud instances.

If JQL is defined in both places: soundcheck.collectors.jira.collects[?(@.type === 'issues-count')].jql and metadata.annotations["atlassian.net/jql"], the plugin will concatenate them with an AND. Plugin will not remove any duplicate params. This is useful if you want to create reusable facts, for example you can create fact that will look at issues with the status To Do like this:

soundcheck:
  collectors:
    jira:
      collects:
        - factName: todoIssues
          type: issues-count
          jql: status="To Do"

In the next step you may want to restrict the jql to only look for issues with status To Do AND where project key is PROJECT. In your entity you would add following annotation:

metadata:
  annotations:
    atlassian.net/jql: project = "PROJECT"

The next step is to create a check that could look like this:

soundcheck:
  checks:
    - id: has_no_todo_tickets
      rule:
        factRef: jira:default/todoIssues
        path: $.total
        operator: equal
        value: 0

And finally add it to a track:

soundcheck:
  tracks:
    - id: product-certified
      name: Product certified
      ownerEntityRef: group:default/example-owner
      description: >
        Improve quality of product backlog
      documentationURL: https://www.backstage.io
      filter:
        catalog:
          metadata.tags: someTagValue
      levels:
        - ordinal: 1
          checks:
            - id: has_no_todo_tickets
              name: checks if there are any todo tickets
              description: >
                This checks if there are any todo tickets for the project

{
  "total": 10
}

​Prerequisites

​Configure Jira integration in Backstage

​Add the JiraFactCollector to Soundcheck

​Plugin Configuration

​No-Code UI Configuration Option

​YAML Configuration Option

​Defining Jira Fact Collectors

​Overall Shape Of A Jira Fact Collector

​baseUrl [required]

​apiToken [optional]

​username [optional]

​personalAccessToken [optional]

​collects [required]

​Overall Shape Of A Fact Collector

​type [required]

​frequency [optional]

​initialDelay [optional]

​batchSize [optional]

​filter [optional]

​exclude [optional]

​cache [optional]

​jql [optional]

​Rate Limiting (Optional)

​Entity configuration

​Collecting Issues Search Fact

​Collecting Issues Count Fact

Prerequisites

Configure Jira integration in Backstage

Add the JiraFactCollector to Soundcheck

Plugin Configuration

No-Code UI Configuration Option

YAML Configuration Option

Defining Jira Fact Collectors

Overall Shape Of A Jira Fact Collector

`baseUrl` [required]

`apiToken` [optional]

`username` [optional]

`personalAccessToken` [optional]

`collects` [required]

Overall Shape Of A Fact Collector

`type` [required]

`frequency` [optional]

`initialDelay` [optional]

`batchSize` [optional]

`filter` [optional]

`exclude` [optional]

`cache` [optional]

`jql` [optional]

Rate Limiting (Optional)

Entity configuration

Collecting Issues Search Fact

Collecting Issues Count Fact