Fetcher Background Information

Fetcher Background Information#

A fetcher to get issues from Jira Tracker via the Jira Rest API. It can be configured by a configuration file that contains a query and other filtering criteria.

Prerequisites#

The user id that is set for the fetcher in JIRA_USERNAME (or the owner of the JIRA_PAT) must have access to the project in Jira tracker in order for the fetcher to work.

Environment variables#

JIRA_URL#

The Jira tracker server url. An example would be https://intran.net/some/path/to/jira. If your full URL is https://intran.net/some/path/to/jira/browse/ABC-123, you need to remove the last part starting with /browse/ so that you obtain the URL in the correct format.

JIRA_USERNAME#

A valid user NT-ID.

JIRA_USER_PORTAL_PASSWORD#

The user WAM/Portal password. For technical users it might be different from ldap password.

JIRA_PAT#

The personal access token. For more information on how to create a PAT check the JIRA documentation. This may be used instead of the Basic authentication via username and password.

JIRA_CONFIG_FILE_PATH#

The path to the fetcher’s and evaluator’s config file. More details about the config file can be found right below.

The fetcher’s config file#

The definition of which issues to be fetched, is given by a yaml file. The location of this file is then referenced by the JIRA_CONFIG_FILE_PATH environment variable.

Note

This config files is used to configure the Jira fetcher and evaluator. For having a better understanding of the config, check out: Evaluator Background Information.

This config file should have the following structure:

query: '<jql-query>'  # A jql query
neededFields: # List of issue fields to fetch.
  - field1
  - field2
evaluate: # Used by the evaluator
  fields:
    fieldTag1:
      fieldName:  # A field from neededFields
      conditions:
        expected: # List of possible required values of the field
          - "a"
          - "b"
    fieldTag2:
      fieldName:  # A field from neededFields
      conditions:
        illegal: # List of possible rejected values of the field
          - "x"
          - "y"

The values of the “query” and “neededFields” properties is what the fetcher will send inside the request in order to filter the data. For more details about the query language and possible fields, check the official docs:

In Jira UI, if you go to Issues -> Search for issues, you can find an advanced search bar, which accepts jql. This could help to construct and validate your query.

Example Output#

The Jira fetcher creates a file in the evidence path called data.json. It has the following structure and contains all of the fetched issues:

[
  {
    "id": "123456",
    "url": "https://tracker.server.com/tracker111/browse/PROJECT-4",
    "summary": "Example task",
    "issuetype": {
      "self": "https://tracker.server.com/tracker111/rest/api/2/issuetype/3",
      "id": "3",
      "description": "A task that needs to be done."
    },
    "assignee": {
      "self": "https://tracker.server.com/tracker111/rest/api/2/user?username=USER",
      "name": "USER",
      "key": "JIRAUSERID",
      "emailAddress": "User Email",
      "displayName": "User Display Name",
      "active": true,
      "timeZone": "Europe/Berlin"
    },
    "status": {
      "self": "https://tracker.server.com/tracker111/rest/api/2/status/10158",
      "description": "This status is managed internally by JIRA Software",
      "iconUrl": "https://tracker.server.com/tracker111/images/icons/subtask.gif",
      "name": "To Do",
      "id": "111"
    }
  },
  {
    "id": "12345",
    "url": "https://tracker.server.com/tracker111/browse/PROJECT-2",
    "summary": "Example task",
    "issuetype": {
      "self": "https://tracker.server.com/tracker111/rest/api/2/issuetype/3",
      "id": "3",
      "description": "A task that has been done."
    },
    "assignee": {
      "self": "https://tracker.server.com/tracker111/rest/api/2/user?username=USER",
      "name": "USER",
      "key": "JIRAUSERID",
      "emailAddress": "User Email",
      "displayName": "User Display Name",
      "active": true,
      "timeZone": "Europe/Berlin"
    },
    "status": {
      "self": "https://tracker.server.com/tracker111/rest/api/2/status/10158",
      "description": "This status is managed internally by JIRA Software",
      "iconUrl": "https://tracker.server.com/tracker111/images/icons/subtask.gif",
      "name": "Done",
      "id": "222"
    }
  }
]

Example config#

Below is an example jira fetcher configuration file. It runs a query to fetch all issues of type TASK from PROJECT1 Jira project. The fetched fields that will be evaluated and saved in the data.json fetcher output file are defined under neededFields

query: "project = PROJECT1 and issuetype in ('Task')"
neededFields:
  - "summary"
  - "status"
  - "assignee"
evaluate:
  fields:
    assignee:
      fieldName: "assignee"
      conditions:
        expected:
          - "USER1"
    status:
      fieldName: "status"
      conditions:
        expected:
          - "Done"

The example configuration file below runs Jira fetcher. The autopilot is configured in lines: 7-15. Required environment variables are read from provided run environment Then the autopilot is used by the check 1.1 in line 30 which is part of requirement 2.6.

 1metadata:
 2  version: v1
 3header:
 4  name: MACMA
 5  version: 1.16.0
 6autopilots:
 7  jira-autopilot:
 8    run: |
 9      jira-fetcher
10      jira-evaluator
11    env:
12      JIRA_CONFIG_FILE_PATH: ./jira-config.yaml
13      JIRA_URL: ${{ vars.JIRA_URL }}
14      JIRA_USER_PORTAL_PASSWORD: ${{ secrets.JIRA_USER_PORTAL_PASSWORD }}
15      JIRA_USERNAME: ${{ secrets.JIRA_USERNAME }}
16finalize:
17  run: |
18    html-finalizer
19chapters:
20  "1":
21    title: Project management
22    requirements:
23      "2.6":
24        title: Release Jira issues are all done and closed
25        text: Release Jira issues are all done and closed
26        checks:
27          "1.1":
28            title: Evaluate Jira issues
29            automation:
30              autopilot: jira-autopilot