Getting started

Linker adds a field to your Jira work items where people pick related work items from a search box. Behind the scenes, Linker turns each pick into a real Jira work item link (the same kind you get from "Link work item") and keeps field and links matching in both directions. This page walks you through the setup, which takes about five minutes.

Set up Linker in 6 steps

1. Install the app Install Linker from the Atlassian Marketplace (or via your admin's installation link). A Jira admin approves what the app is allowed to do: read and write work items and links, read user display names, store its own settings, and read field configurations. Linker sends no data outside Atlassian.
2. Create the custom field Go to Settings → Work items → Custom fields → Create custom field, switch the category to Advanced (or use the search) and choose the field type Linker Work Item Picker. Whether the field holds a list of related work items or exactly one is not a type question: it is the per-context Selection setting, explained in the Configuration reference. Give the field a name your teams will recognize, e.g. Linker or Related work. Shortcut: the Create custom field button on Linker's own Fields page (Jira Settings (gear) → Apps → Linker → Fields) creates the field in one step. See The Fields page.
3. Put it on your screens Add the field to the screens of the spaces that should use it; Jira asks right after creation. For team-managed spaces, add the field to the work-type layout instead: see Team-managed spaces.
4. Configure the context Open Custom fields → your field → Contexts and configuration → Edit custom field config. Here you decide which work items the search offers, which link type Linker creates, and how linked work items are shown. Every setting has an ⓘ icon with a detailed explanation; the full list is in the Configuration reference.
5. Link your first work items Open a work item, click into the Linker field, type to search and pick one or more work items, then press Save. The links appear immediately under Linked work items.
6. Add the panel (optional) Open Jira Settings (gear) → Apps → Linker → Fields and choose Create a panel for this field in the field's ⋯ menu (or build one from scratch on the Global panels page next to it), then press the Apps button on the work item and choose Linker to get a table of the linked work items: see Work item panels. A team that only wants a panel in its own space does not need you for it: see Space panels.

What Linker gives you

• Real links, not text: everything works with boards, filters, dashboards and search, because the links are Jira's own.
• Two-way sync: links made by hand flow back into the field, and field edits create links. How it works.
• Safe by default: Linker only deletes links it created itself, never links people made by hand (you can change this).
• Configurable everywhere: search suggestions, field table and CSV exports are all built from drag-and-drop building blocks, separately for each field context; panel columns work the same way on the Global panels page.
• Dynamic JQL: picker and panel filters can reference the current work item's own values with currentIssue(), e.g. to offer only the contracts of this very customer.
• Bulk paste: paste a whole list of work item keys into the picker and add them all with one click.
• Create and link: where the admin allows it, the picker creates a brand-new work item from the text somebody typed and takes it straight into the field. Create and link.
• Searchable from anywhere: three JQL functions let boards, saved filters, dashboards and automation rules ask about Linker relationships, without naming the field. Linker JQL functions.
• Panels without a bottleneck: whoever administers a space builds that space's panels in the space's own settings, with Jira's Administer Projects permission and nothing else. Jira administrators keep the overview, and one switch decides whether it is allowed at all. Space panels.
• Status changes where you read them: a panel can turn its status column into Jira's own status button, so work moves on without leaving the page. Work item panels.
• Edit a value where you read it: where the admin allows it, a panel lets viewers change plain cells in place, text, number, date, assignee or priority, written in their own name so Jira's permissions decide. Work item panels.
• A workflow that waits for the links: the validator Linker: no open linked work items blocks a transition while a work item linked the configured way is not done yet. It runs as a Jira expression, so it costs nothing at transition time. Workflow validator.
• Customer portal ready: in Jira Service Management the field can show a customer-safe line on the request, built from the details you pick, and the picker works on the request form. It needs a JQL filter to show anything there, because that filter is the customer's boundary. Service desk portal.
• Move a setup between sites: the Fields page exports every field configuration and every global panel as one JSON document and imports it again elsewhere, by names and keys rather than ids, with a preview of what each entry would do. Configuration reference.
• Light and dark: every Linker screen follows Jira's light or dark theme automatically.
• Six languages: English, German, French, Spanish, Portuguese and Japanese, following each user's Jira language.

Next steps

• Configuration reference: every setting, with diagrams
• How linking works: the four mechanisms that keep field and links matching, and how fast each one is
• JQL guide: filter the picker, and the three Linker functions for the rest of Jira
• Create and link: new work items straight from the picker, including the required-field case
• Resync & migration: fill fields from existing links (read the warnings!)
• Space panels: let a space build its own panels, and what stays with the Jira administrator
• Troubleshooting & FAQ