Connecting Jira

The tracker integration connects OTB Works to a Jira Cloud project. Works keeps the plan, change control, money and assurance. Jira keeps the delivery team’s tickets. The integration links the two without making either a second source of truth for the same fact.

This page covers Jira. For Azure DevOps see Connecting Azure DevOps.

What it does

Reads the tickets on your chosen boards into a copy held in Works, on a schedule you control. The copy holds plain fields: key, type, title, status, assignee’s display name, parent, story points, created and updated times and link.
Links a Works plan item to a Jira issue, one at a time.
Shows the gap on Deliver, Board vs plan: board items the plan does not know about, and plan work with no ticket.
Raises a proposal when a linked step’s Jira status moves to a status you have said means done. A person approves it through change control, unless you have set an auto-approval rule.
Moves a linked Jira issue to a status you choose when a linked step changes state in Works.
Posts a comment on a linked issue, when a person chooses to send one.

What it does not do

It never writes a plan item, a link or a governed field from the board by itself. Importing is not automatic.
A governed Works field, such as a step’s state, can never be set directly from Jira. A Jira status change can only raise a proposal.
It does not create or rename anything in Jira. The setup wizard only reads from Jira.
It does not send money, rates, budgets, benefit values, effort in days, or names, emails and assignees to Jira.
Jira’s status, assignee, summary and last-updated time stay Jira’s. Works shows them labelled as external, with when they were last fetched. It never overwrites its own value with them.

Who owns each field

Field	Owner
Step state, effort, dates, percent complete	Works
Which Jira issue a plan item is linked to	Works
Issue status	Jira
Issue assignee	Jira
Issue summary	Jira
Issue last updated	Jira
Connection credentials	Works, stored encrypted

Which Works level maps to which Jira issue type, and the direction of each ungoverned field, are configurable per connection. A field Works governs through change control can never flow inbound, and sending one outward is not built.

Prerequisites

Licence. Tracker integration is included from the Enterprise edition. Without it, Admin users see the screens with the edition that would unlock them. Other people see nothing.
Permission. Setting up and changing a connection needs the administration permission (the Admin role). Linking an item, and sending a comment, needs permission to edit Deliver, within reach of that item.
A Jira Cloud credential. You need the Jira site URL, the email of the account the token belongs to, an API token, and the project key. The account can only see the boards and projects it has access to. See What the token must be allowed to do.
Encryption key. The credential is stored encrypted. The instance generates its own key on first boot and keeps it in instance-keys.json on the data volume, so nothing needs configuring. You can set OTB_INTEGRATIONS_ENC_KEY yourself; if you do, back it up, because a lost key makes stored credentials unreadable and you must enter them again. Back up instance-keys.json with the database.
Network. The server must be able to reach your Jira site over HTTPS.

What the token must be allowed to do

Works signs in as the account that owns the token, with its email and API token, and does only what that account may do in Jira. Read from the client’s calls (jiraClient.ts), it uses these:

Works does	Jira call	The account needs
Test the connection	Read the account’s own details	Nothing beyond a valid token
List boards, their columns, epics and statuses	Agile board, board configuration, epics and status list	Access to the board and its project (Browse projects)
Pull issues	Board issue list; one issue’s summary, status, assignee, updated	Browse projects on those projects
Send a comment	Add a comment to an issue	Add comments, in the issue’s project
Move a status	Read the issue’s transitions, then transition it	Transition issues, in the issue’s project

A connection that only pulls needs read access. The comment and status rows matter only if you use outbound push; without those permissions Jira answers “forbidden” and Works records the attempt as failed.

Permission names are Jira’s own project permissions; the mapping from call to permission is Atlassian’s, not Works’. A “forbidden” failure is the signal that the account lacks one.

Connect and set up boards

You need the Admin role.

Open the account menu, then Admin, then Integrations.
Select New connection.
On Connect, choose Jira Cloud and fill in:
- Name, for example “Delivery Jira”.
- Site URL, for example https://your-domain.atlassian.net.
- Account email: the email the API token belongs to.
- API token. It is stored encrypted and never shown again.
- Project: the Jira project key.
Select Test connection. A “Connection works” mark appears when it succeeds. Testing reads from Jira and changes nothing there.
Select Continue.
On Boards, tick the boards that should feed the programme. You can choose more than one. The list shows only boards the connecting account can open. If it is empty, ask the board owner to add that account, then select Refresh from Jira Cloud.
On Scope, choose how the boards map onto the programme:
- One set of boards for the whole programme. Only one connection can be set up this way.
- One board per workstream. Choose a workstream for each board. You can have several connections.
For a programme-wide set, choose what a workstream is: an Epic, or “Not an Epic: I will link by hand”.
On Statuses, give each status Jira reports a meaning: Not started, In progress, Done, Blocked (stays In progress), or Not mapped. The list is pre-filled from Jira’s own categories. Correct any that are wrong. A status named Blocked, On hold, Impeded or Impediment is pre-selected as Blocked.
On Preview, read the list of what will change. Nothing is saved yet.
Select Save.

A status you leave Not mapped does not block saving. An item in it shows on the board as a disagreement, and Works never guesses.

The wizard writes only the connection’s own settings. It links nothing. Link plan items to Jira issues afterwards.

Link a plan item

Open Deliver, then Linked tickets. The page is titled Linked issues.
Under Link an item, choose the Connection, search for the Plan item, and enter the Jira issue key, such as OTB-123.
Link it.

A step can have one ticket. A deliverable, work package or workstream can have more than one. From a linked row you can Refresh, Push a message, Map person and Unlink.

Mapping

Open the connection in Admin, then its Mapping section.

Level mapping: the Jira issue type each level of your plan is held as, and its depth. Depth 0 is the top.
Field mapping: the Jira field for each Works field, and the direction. A governed field shows “Not synced (governed)”.

A mapping is saved whole or not at all. A saved mapping is versioned. If it cannot be saved, the message lists what is wrong.

Under Statuses, set which Jira statuses mean done, and add auto-approval rules. There are two rule types: any status marked done, or a named external status.

Under Status moves (the Outbound section), set which Jira statuses a step’s move is sent as:

Done: the first done status the issue’s workflow offers.
In progress: if you leave it empty, Works tries Jira’s usual “In Progress”.
Not started: if you leave it empty, nothing is sent when a step goes back to Not started.

Anything not named is left as it is. A change that came from Jira is never sent back to Jira.

People

Open the connection, then People. Every Jira account seen as an assignee on a pulled issue is listed. Map it to a Works person, or leave it unmapped. A mapped person’s day rate is what a linked step is costed against. An unmapped assignee is never costed at zero.

Pull schedule

Works pulls the board into its copy on a schedule per connection.

Setting	Value
Default interval	15 minutes
Minimum	5 minutes
Maximum	1 day
Full resync	Every 24 hours

After the first full read, only changed items are read. The full daily resync is what finds items deleted or moved off the board. Such items are marked missing, never deleted.

On the connection’s page you can turn Scheduled pulling on or off, change How often, and select Pull now. After a failure the schedule backs off. After five failures in a row it pauses itself, names the reason, and waits. Select Resume pulling when fixed. A person is notified of the pause. A lapsed licence stops the schedule.

Outbound status push and governance

Works sends only three things to Jira: a status a linked item moves to, comment text a person chooses to send, and a plan reference such as WP-3.2. Nothing else can leave. This list cannot be edited.

Never sent: day rates and what anyone is paid, costs, budgets and forecasts, benefit values, effort in days, and names, emails and assignees.

Controls:

Comment check. Before a comment is sent, it is checked for money. A currency amount, a rate or a figure Works holds is blocked, with no override. A word such as “budget” asks the sender to confirm the text holds no financial information. The confirmation is recorded. The check cannot catch money written in words.
Preview. The comment composer shows the exact request, minus the credential, as you type.
Ledger. Every attempt is recorded in an append-only ledger: sent, unchanged, failed, blocked, paused, superseded or skipped. The connection’s Outbound section shows it, with counts of sent and blocked.
Pause. On a connection’s Outbound section, select Pause pushing and give a reason. On the Connections overview, Pause all pushing stops every connection. While paused, a comment is accepted and held, and a status move is held, not sent. Held items are listed.
Resume. Resuming processes the held items once, in order. A status move is not sent if Jira has since changed or been updated: the tracker wins, and the ledger says superseded. Comments are checked again before sending. Items since unlinked or deleted are skipped. You see a summary, for example “5 sent, 2 skipped because Jira is newer”.

A failed status push does not undo the Works decision. It is recorded with a plain reason and can be retried. A transient failure is retried once automatically.

Remove a connection

Removing a connection deletes it. You choose what happens to the work items it brought into Works. The push ledger is kept. The removal dialog asks “What to do with the work items from this tool” and offers Keep them or Delete them, says what goes with the connection either way and what stays, and offers to delete any steps Works created from the tool’s items.

Troubleshooting

Every failure from Jira is named. A pull failure never overwrites the last good copy: you see the last known value, when it was fetched, and that the latest refresh failed.

Named failure	Meaning
unauthorized	Jira rejected the credential. Replace the token.
forbidden	The account lacks permission.
not_found	The issue or project was not found.
rate_limited	Jira asked Works to slow down. The wait is respected.
timeout	No answer within 10 seconds.
network_error	The server could not reach Jira (DNS or connection).
unexpected_status	Another non-success response.
unexpected_response_shape	Jira replied in a form Works does not expect. The API may have changed.

Reading calls are retried up to three attempts for gateway errors, timeouts and network failures. A comment is never retried automatically, so it cannot be posted twice.

Common questions:

Test connection fails. Check the site URL, email, token and project key. Select Replace credential on the connection to enter a new token.
No boards listed. The account cannot open any board. Ask the board owner to add it.
“Jira offers no transition to …” The issue’s workflow has no step to the status you chose. Check the issue’s workflow, or change the status you mapped.
A status shows as a disagreement. It is Not mapped. Map it under Statuses.
Nothing pulls. Check the Pull schedule card. It may be paused after five failures, or the licence may have lapsed.
Cannot save a mapping. The message names the problem. A mapping that sends a financial field outward is refused.
Blocked items. A Blocked status keeps the step In progress. Works can offer to raise an issue for it on the Steer gaps view. A blocked item is noticed when its link is next pulled.

Jira Server and Data Center are not supported: the client calls Jira Cloud’s REST API version 3 and its agile API.