Jira issues#
OakCore lets you link specification nodes (requirements, tests, risks) to Jira Cloud issues. After setup, OakCore keeps a read-only snapshot of each linked issue and writes an OakCore landing URL to a configured custom field on the Jira issue.
Connection setup (site URL, project key, API token, backlink field, webhooks) is described in Jira Cloud connection.
Bind an issue to a node#
- Open a node whose type supports issue binding (requirement, test, or risk).
- In the sidebar, open the Info tab and scroll to Bindings → Issues.
- Choose the connection (by label), paste an issue reference, and link.
Requires a Jira Cloud connection for the target project.
Accepted references:
| Format | Example |
|---|---|
| Issue key | PROJ-42 |
| Browse URL | https://acme.atlassian.net/browse/PROJ-42 |
The key or URL must belong to the connection's project. GitHub-style references (#42) are not accepted for Jira connections.
After linking, OakCore:
- Pulls the current issue data (summary, status, assignee, priority, labels, …).
- Writes the landing URL to the configured URL custom field on the Jira issue — the backlink.
If the custom field cannot be updated (wrong screen, field type, or permissions), OakCore falls back to an issue comment with the same link — similar to GitHub Issues.
Example landing URL:
{your-oakcore-url}/integration-issue?projectId={project_id}&artifactId={artifact_id}
When you unlink the last node from an issue, OakCore clears the backlink field value.
Status display#
Jira workflow status names appear as-is in the snapshot. For open/closed counts and badges, OakCore maps Jira status categories:
| Jira status category | OakCore state_category |
|---|---|
| To Do, In Progress | open |
| Done | closed |
Webhook events#
On the Jira webhook, subscribe to Issue updated and Issue deleted. OakCore re-fetches the issue snapshot when Jira sends these events.
Troubleshooting#
| Symptom | What to check |
|---|---|
| Bind rejected — wrong project | Issue key prefix must match the connection's project key |
| Snapshot stays pending | Run Test on the connection; wait for background sync |
| No backlink on issue | Backlink field display name; field visible on issue; token can edit issues |
| Status badge wrong | Unusual workflow — open count uses status category, not status name |
See also Jira Cloud connection → Troubleshooting.