Jira

Each note raised becomes a Bug (or a Task) in one Jira project, on your sprint board if you use one. Moving the issue to any done status marks the note done; moving it back opens the note again.

This works with Jira Cloud, the kind at an atlassian.net address. Jira Server and Data Center are not supported yet.

Before starting, do steps 1 and 2 of How connections work: data-issues="queue" on the tag, and a secret on the store.

1Make an API token

Open id.atlassian.com/manage-profile/security/api-tokens, signed in as the account Notefix should file issues as.
Press Create API token. Not Create API token with scopes.
Name it Notefix, choose when it expires, and press Create.
Press Copy. Atlassian will not show it again.

Tip

Issues are filed as whoever owns the token. Many teams make a separate account for this, with access to just the one project, so issues show Notefix as the reporter and the token cannot reach anything else.

2Find your site and project

Site: the address you open Jira at, like https://acme.atlassian.net.
Project key: the letters before the number in the project's issues. In WEB-12, the key is WEB.

3Write the settings file

On the server where the store runs:

sudo mkdir -p /etc/notefix
sudo install -m 600 -o "$USER" /dev/null /etc/notefix/jira.env
nano /etc/notefix/jira.env

NOTEFIX_API=http://127.0.0.1:8097
NOTEFIX_BOARD=staging
NOTEFIX_SECRET=the-secret-you-gave-the-store
NOTEFIX_SITE=https://staging.acme.com
JIRA_SITE=https://acme.atlassian.net
[email protected]
JIRA_TOKEN=paste-your-token
JIRA_PROJECT=WEB
JIRA_SPRINT=active

Setting
`JIRA_EMAIL`	The email of the account the token belongs to
`JIRA_SPRINT`	`active` puts new issues in the current sprint, so they show on a Scrum board. Leave it out on a Kanban board
`JIRA_ISSUE_TYPE`	Optional. By default a Bug, or a Task if the project has no Bug
`JIRA_LABELS`	Optional. Extra labels, separated by commas. Every issue is also labelled `notefix`

4Try it

set -a; . /etc/notefix/jira.env; set +a
python3 connectors/runner.py jira

It checks the token, the project and its issue types first, then says:

jira connector on board 'staging' via http://127.0.0.1:8097

On your page, open a note and press Create an issue. Within about 15 seconds the note shows WEB-1, and the issue is on your board. Move it to Done, and within a minute the note turns green.

In Settings, under Connected tools, Jira now shows your site and project and Working.

Then run it as a service, with jira.env and runner.py jira.

What the issue looks like#

Summary: the first line of the note.
Description: the note's words, who wrote it, the screen, the device and the element, and a link back to the page. Under a line, For developers: the selector, route and build.
Screenshots from the note are attached.
Label notefix, so you can filter for them.

When a note counts as done#

Every Jira workflow names its columns differently: Done, Shipped, Won't do. But every status belongs to one of three categories, and Notefix reads the category. Any status in the green Done category closes the note, whatever it is called, with nothing to set up.

If it does not work#

The connector says	What to do
`Jira rejected the email and token`	Check `JIRA_EMAIL` is the token owner's, and the token has not expired
`JIRA_SITE must be the https address`	Use the full address, starting `https://`
`Jira 404 on /rest/api/3/project/…`	Check `JIRA_PROJECT`, and that the account can see that project
`No issue type 'X' in WEB. It has: …`	Use one of the types it lists in `JIRA_ISSUE_TYPE`
`… is in the backlog: WEB has no active sprint`	Not an error. Start a sprint, or leave out `JIRA_SPRINT`