Twinwell for Jira: documentation

Twinwell keeps a work item in one project and its "twin" in another project on the same Jira site in step: fields, status, comments and attachments, in the directions you choose.

Where to find it

• Jira settings > Apps > Twinwell: Issue Sync (Jira admins): sync pairs, Health, Log, Settings.
• Issue Sync panel on a work item: its twin, the last sync result, Sync now, Unlink, and Create twin for pairs its project belongs to.

Set up a sync pair in five minutes

1. Open Sync pairs > New sync pair. Name it ("Support to Dev") and pick project A and project B.
2. Start from a preset if one fits:
   • Service request to dev work item: summary and description from the request, priority and labels both ways, status both ways, comments both ways with synced comments internal on the request, attachments from the request to the dev work item.
   • Team to team: the common fields both ways, newest change wins.
   • Read-only mirror: everything from A to B, A is the source of truth.
3. When does a work item get a twin? Manual only (the Create button on the work item), every new work item, new or updated work items matching JQL, or when a work item enters one of the statuses you pick. Choose which project's work items get twins automatically.
4. Work types and statuses. Press Auto-map types and statuses by name, then adjust. Each status in A moves the twin in B to the status you map, and back.
5. Fields. Add a row per field: the field in A, the field in B, the direction, and who wins if both change. Save. Twinwell checks everything (JQL, field types, statuses) before saving and tells you exactly what to fix.

How fields are matched

You can map different fields to each other when the types fit, for example a select list to a text field, or a single select to a multi-select. If a value doesn't exist on the other side (an option, a component or a version), Twinwell skips that field, keeps syncing the rest, and shows a warning on the work item and the Health page. Once you add the value, press Retry.

Directions and conflicts

• Direction per field: both ways, A to B only, B to A only, or off. Status and comments have their own direction.
• If both change before a sync runs: Newest change wins compares when each field last changed on each side (from the work item history), not when the work item was last updated. A (or B) is the source of truth pushes that side's value and overwrites edits made on the other side. Every conflict is written to the Log.

Status

Twinwell moves the twin with the transitions in its own workflow, so conditions, validators and post functions still apply. If the twin's workflow has no transition from its current status to the mapped one, Twinwell leaves it and shows a warning with the reason. Unmapped statuses are left alone.

Comments and service projects

• Comments are copied with the author's name and the source key at the top ("Ana Park on SUP-12:"). Edits to a synced comment are copied too.
• Comments landing on a service request are internal notes by default. You can choose "Public only if it was a public comment on a request" or "Public unless the source comment was internal". An internal note is never made public, whatever you choose.
• Internal notes from the service project go to the dev side unless you turn that off.
• Comments restricted to a group or role are never copied.
• Comments that existed before the twin was created are copied only if you tick "also copy the comments that already exist".

Attachments

Choose a direction and a size limit (default 20 MB). New attachments are copied once; files over the limit are listed on the work item instead.

Health, retries and the log

• A failed sync retries automatically after 30 seconds, 2 minutes, 10 minutes, 30 minutes, then 1, 2, 4 and 8 hours. After the last try (8 by default) it is stalled.
• Permission errors (the app can't edit the twin) stall at once, because retrying can't fix them.
• If a queued sync hasn't run within 15 minutes, Twinwell queues it again and logs it.
• Health lists stalled, retrying, broken and needs-attention work items with Jira's exact message. Press Retry or Retry all stalled after fixing the cause, or Unlink.
• On a work item, the Issue Sync panel shows the same state and a Sync now button.
• Log: every change, conflict, retry and error, filterable by kind and pair.

Find synced work with JQL

• issueSyncTwin = "SUP-12": the twin of SUP-12.
• issueSyncState = stalled (or retrying, attention, broken, ok).
• issueSyncPair = "Support to Dev".

How Twinwell avoids loops

A change Twinwell makes is never synced back. Jira tells apps which events they caused, and Twinwell also remembers a fingerprint of each field on both sides after every sync, so even a duplicated or replayed event finds nothing new to copy. Twins and synced comments are marked so a twin never gets a twin of its own.

Permissions

• The Twinwell app needs, in both projects: Browse projects, Create, Edit and Transition work items, Add comments, Create attachments and Link work items. The app normally has these through Jira's app role; if a project's permission scheme removes them, syncs stall with a permission message that says so.
• People can create a twin only if they can create work items in the target project, and they see a twin's key only if they can see the twin.

Limits

• Same Jira site only.
• Jira Product Discovery projects are not supported (Jira's API can't write their fields yet).
• Up to 50 sync pairs, 40 field mappings per pair.
• Each sync checks the newest 100 comments of each work item and copies up to 50 new comments and 10 attachments; the next sync continues.
• Jira sends no event when a comment is edited, so comment edits go across on the next change to either work item, or with Sync now.
• Deleting a comment or attachment does not delete its copy.
• Edits and synced comments are made by the Twinwell app user.