Work item panels

The Linker panel is an extra section on a work item that shows linked work items (or the results of a JQL query) as a proper table, with status colors, priority and type icons, and assignee photos. What the panel shows is defined by panel definitions: every one of them that covers the work item appears as its own titled section. Jira administrators build them on the Global panels page, and whoever administers a space can build panels for that space in the space's own settings, see Space panels.

Where the panel appears

1. Open a work item and press the Apps button (the hexagon next to +) in the toolbar, then choose Linker.
2. Make it permanent: open the panel's ⋯ menu and choose Show for all work items: from then on the panel appears on every work item automatically.

The ⋯ menu also offers Collapse and Remove. Which sections the panel shows on a given work item is decided by your panel definitions' scopes.

The Global panels page

Site-wide panels are managed in one place: open Jira Settings (gear) → Apps → Linker → Global panels. Linker's admin area has three pages next to each other, Fields, Global panels and Space panels; the app's entry in the settings sidebar switches between them. A panel definition has four parts:

The list itself uses the same table pattern as the Fields page: a search box and filters (by content kind and by space) above it, and columns for Name, Source, Spaces, Work types and Display. The Display column sums up a panel's presentation in one line: how many columns, how many rows per page, plus tags such as read-only, viewer columns or Inline edit; JQL panels carry a JQL badge. Clicking the Name header sorts the view. Drag a row to reorder the panels: the list order is the order of the sections on the work items (reordering pauses while a filter or the sort is active). Each row ends in a ⋯ menu with Edit, Move up, Move down and Delete, which asks for confirmation first. And a collapsible Recent app activity section lists the app's latest actions: links created or removed, sync updates and resync runs.

Two combinations are easy to configure and awkward to live with, so the editor says so in place, as a quiet note under the setting rather than as a warning:

• Hidden headers plus viewer columns. When viewers assemble their own columns while the header row is hidden, they are choosing columns they cannot identify in the table. Show the headers, or set the columns centrally.
• A single-selection context that never deletes links. Every earlier pick keeps its link, so the links pile up on the work item over time while the field value itself stays correct. The note appears on the contexts the panel actually renders for.

Creating a panel

There are three ways:

1. From the Fields page: each field's ⋯ menu offers Create a panel for this field. One click creates a panel named after the field, with its columns prefilled, bound to one of the field's contexts, so it follows that context's space and work-type coverage live. A field with several contexts asks which one the panel should follow, and a context that already has its panel simply gets that one back rather than a second copy. See The Fields page.
2. Directly on the Global panels page: create a panel from scratch. Link-type panels, which show native links, and JQL panels, which show a query's results, are built here; neither needs a Linker field at all.
3. In a space's own settings: whoever administers a space builds link-type and query panels for that space themselves, under Space settings → Apps → Linker Panels, without a Jira administrator. See Space panels and the summary below.

Panels a space builds for itself

A panel is not always a site-wide affair. Whoever holds Jira's Administer Projects permission on a space finds a Linker Panels page in that space's settings and builds the panels of that space there. Linker asks Jira for that permission on every write, so the page is not the gate, the permission is.

• The panel is bound to its space. The space is decided by the server from where the call came, never taken from the form, so nobody can build a panel for a space they do not administer. It cannot be moved to another space afterwards, by anybody.
• Link types and queries only. A field panel is not offered in a space, because it hangs on a field context, and a context is global configuration a space administrator does not own. A Jira administrator builds those as global panels instead. The reasoning is spelled out under Why a field panel is not offered here.
• Global panels come first on the work item, then the panels of the space it lives in; panels of other spaces do not appear at all. Each list is ordered on its own, so a space cannot reorder anything but its own sections.
• A Jira administrator keeps the overview. The Space panels page in the admin area lists every space panel of the site and can repair or delete any of them. One toggle there decides whether space administrators may create panels at all. See The Space panels page.

What the panel shows

The work item's single Linker panel shows every panel definition whose scope covers that work item, each as its own section headed by the panel's name. The global panels come first, in their configured order, then the panels bound to the space the work item lives in, in theirs; panels bound to another space never render here. See Space panels. A panel with several link types shows one list, each work item once, however many of the configured kinds connect it. Which link put a row there is the Link type column: the phrase as seen from the open work item, e.g. is client of, and several phrases on one row when the work item is linked more than once. There are no sub-headings per kind; they showed the same work items twice when two kinds overlapped and counted them twice. A JQL panel section lists every work item matching its query, with the same columns, lazy loading and counts as any other section, just without links behind it. A column that shows a Linker field is not a piece of text either: it renders the work items that field holds the way the field itself does on a work item, one line per referenced work item, with the built-in columns the field's context configured under Display. See Linker fields as columns below. A section that has no entries on this work item simply says “No linked work items.”

Each section heading shows a count of its entries, and clicking the heading collapses the section; your browser remembers which sections you keep collapsed. Long sections load lazily: they start with the section's configured Work items per page (10 unless changed) and a Show N more button; the count in the heading is always the real total.

A panel definition can also switch on Show a progress bar (share of work items in the Done category): a slim bar above the section that shows how much of the listed work has reached a status in Jira's Done status category. It goes by the status category, not by a resolution, so a work item counts as soon as its status is a Done one. The share is counted across all matching work items, not only the rows currently visible.

The section menu and sorting

Every section carries a More actions menu (⋯) in its heading, with five entries that work on what the section holds:

• Copy keys puts every key the section holds on the clipboard, as a comma separated list. That includes the rows behind Show more, as far as the section has loaded them.
• Open in Jira search opens Jira's own search in a new tab: with key in (…) over the section's keys for a field or link-type section, and with the section's resolved JQL for a query section.
• Only open work items is a checkbox that hides every row whose status is in Jira's Done category. Your browser remembers the choice per viewer and per section, so a section you keep narrowed stays narrowed on the next work item.
• Export as CSV writes the rows the section holds into a CSV file: the section's own columns as the header line, RFC 4180 quoting for anything containing a comma, a quote or a line break, and UTF-8 with a byte order mark, so a spreadsheet opens the file with the right characters. Every loaded row is in it, the ones behind Show more included. Your browser saves the file to its downloads, and the same text goes on the clipboard as well, so you still have it if the browser did not save anything.
• Show sums is a checkbox that adds a line under the table, for example “Sum of the rows shown: Column 12 · Other 7”. A custom column is summed when every loaded cell in it is a number; empty cells are ignored, and one non-numeric cell in a column means that column gets no sum at all. The line follows Only open work items, so it always sums exactly the rows in front of you. Your browser remembers the choice per viewer and per section.

The column headers of a section sort as well: a click sorts the loaded rows by that column, keys by their number, text columns alphabetically, empty cells last, and a second click reverses it. The sort lives as long as the page does; a reload starts from the configured order again.

None of this asks Jira for anything. The menu, the sorting, the filter, the export and the sums all run in the browser on the rows the section already has, so they cost no request and are instant.

Viewers choose their own columns

Normally everyone sees the columns configured in the panel definition. When a definition switches on Viewers choose their own columns, every viewer can assemble their own columns directly in the panel: a customize button appears in the section header and opens an inline editor. The current columns show as chips; the arrow buttons reorder them and the × removes one. An Add field select offers the built-in columns and any Jira field. Save stores the pick, and Reset to default returns to the configured columns.

The pick is personal: it is stored per person, so everyone else keeps their own view. The columns the admin configured are only the starting set for people who have not customized yet.

Linking from the panel

Each section has a + button that opens the familiar Linker search, so people can link work items without leaving the panel:

• Field panels add the picked work items to the Linker field. The person needs permission to edit the work item, which is Jira's Edit Issues permission; the panel asks Jira whether they have it and says so plainly if they do not.
• Link-type panels create a native Jira link of the panel's first configured link type, in the person's own name, so Jira's Link Issues permission applies and Jira's own refusal is what you see.

The search respects the panel's optional JQL filter, on field panels in addition to the field's own picker filter. Any currentIssue("…") placeholders in those filters resolve against the work item the panel is on. And on a panel bound to a field whose context uses the single selection mode (One work item (new pick replaces)), picking a work item replaces the current value, just like in the field itself. A JQL panel has no linking actions at all: there are no links to manage, so its sections show neither the + nor the ×.

Removing works the same way: hover a row and click the ×; the panel always asks for confirmation before anything is deleted. Field panels then behave exactly like deselecting in the picker, so the configured delete behavior applies: a link someone created by hand is protected under Only delete links created by the app, and the panel says so if the entry may come back through sync. Link-type panels delete the native link itself, again in the person's name and so again requiring Link Issues. Which links a field panel may delete is a longer story, and a clone is the surprising case: see Which links the app will delete.

Status changes in the panel

A panel is often the place where somebody notices that a piece of work has moved on. With Allow status changes in this panel, they can say so right there instead of opening the work item.

The status column then stops being a label and becomes a button, coloured by status category exactly like Jira's own status control. Clicking it opens a menu of transitions, each written as the transition name followed by the status it leads to, in the same reading order Jira uses. Clicking the status does not open the row's work item, so the two actions never get in each other's way.

The column becomes a button only on the rows that person may actually move. Linker asks Jira for the Transition Issues permission per row, in one request for the whole panel, because the rows of a link-type panel routinely live in other spaces under other permission schemes. Where the permission is missing, the status stays the plain label it always was, so nobody is invited to click something that would only refuse them.

What the menu offers

The transitions are asked from Jira live, in the viewer's name, at the moment the menu is opened. So the menu shows exactly what that person would see on the work item itself: workflow conditions, validators and permissions all apply, and nothing has to be configured twice.

• A workflow that offers nothing right now gives an empty menu saying “No transitions available for you here.” Somebody without the permission does not get that far: their rows carry no button at all.

Running a transition

Choosing an entry runs the transition in the viewer's name, right there. A flag confirms it (“<KEY> is now <status>”), and the panel reloads completely afterwards, so the counts, the progress bar and any JQL filter that depends on the status are correct again immediately. A Linker field on the same page refreshes with it.

If Jira refuses, the panel says so and keeps Jira's own message, as “Transitions could not be loaded” or “The status could not be changed”. Those flags stay until they are dismissed, because a failed status change should not scroll away unseen.

Transitions that need a form

Some transitions ask for something on the way: a resolution, a comment, an assignee. Those cannot run silently, and the panel does not pretend otherwise. The entry says “Needs more information: opens Jira's form for this transition.”, and choosing it opens Jira's own transition screen in a new tab, already on the right transition. The person fills the form there and confirms, exactly as they would from the work item.

The panel does not learn when that happened, so it does not update on the spot: it picks the new status up on its next refresh, which happens when you come back to the tab, or automatically after a short while. See Limitations & timing.

Editing cells in the panel

A panel is often the place where somebody notices that a value is wrong, and correcting it should not mean opening the work item. Let viewers edit cells in place is a setting per panel, in the panel editor on the Global panels page and in a space's own Linker Panels page alike, so the decision belongs to whoever administers the panel, not to the viewer. It is off by default, and a panel that has it on carries an Inline edit badge in the admin list, so the list says at a glance where editing is allowed.

When it is on, clicking a cell of a plain field opens an editor right in the table:

• Text and paragraph custom fields.
• Number, date and date with time.
• The summary and the due date, the two system fields people correct most often in a list.
• The assignee, with the same people search Jira offers for that work item (its assignable users), plus Unassigned. Everybody is offered with their avatar and their name, as in Jira's own assignee field.
• The priority.
• A Linker field, through Linker's own picker, see Linker fields as columns below.

Everything else stays the label it was. Selects, option fields, cascading fields and multi-value fields are read only, and so are the work type, the parent, the description and other rich text; the status has its own transition menu rather than an editor, because a status is not a value you type. Fields of other apps are read only too: an app cannot render another app's editor, and a guess at one would write the wrong thing.

Saving writes that one field, in the viewer's name. So Jira decides, exactly as it would on the work item itself, whether that person may edit it and whether the field is on that work item's edit screen; if Jira refuses, the panel shows Jira's own message rather than a message of its own. After a successful save the row is read again, so what you see afterwards is what Jira stored, not what you typed.

One thing changes for the whole panel once editing is on: clicking a row no longer opens its work item. Navigating away in the middle of a correction is exactly what nobody wants, so the row click steps aside and lets the cells have the click. The key column still links, so the work item stays one click away wherever you want it, and panels without inline editing keep the row click exactly as it was.

Linker fields as columns

A Linker field can be a column like any other field, and its cell shows what the field shows on a work item: the referenced work items, one line each, drawn with the built-in columns the field's own context configured under Display, the key as a link, the summary, the status, the assignee, the priority and the type. Custom-field columns of the referenced work items are not repeated in the cell; they belong in the field's own table, not in a column of another table. Reading them costs one request per section, covering the referenced work items of all loaded rows together, at most 100 of them.

In a panel with inline editing, clicking such a cell opens Linker's own picker, the same one the field carries on a work item: the work items currently in the field as chips, and a search bounded by that field's JQL filter for that row, so currentIssue("…") placeholders resolve against the row's own work item rather than against the work item the panel sits on. Several picks at a time are possible, and a context in the single selection mode keeps the newest pick, as it does everywhere else.

Saving writes the field and the links exactly as the field's own editor does: links are created or removed and the counterpart fields are aligned, so nothing is left half-done. Keys that lie outside the filter stay in the value, are not linked, and are named in the flag, so nobody has to guess which one was left alone. The viewer must be allowed to edit the work item the row belongs to, as for any other edit in the panel, and the key is shown as plain text inside the editable cell, so that a click opens the editor instead of following a link.

Icons and avatars

The Assignee, Priority and Type columns are drawn with the same avatars and icons Jira uses, so a panel reads like a Jira list rather than like a copy of one. Each of the three can be configured as icon only or as icon and name.

Jira hands out standard icons to anyone, but the avatars a space uploaded itself only to a logged-in Jira session, and an app panel is not one. Linker deals with that quietly: when Jira refuses an icon, the panel fetches it once through Jira's API and embeds it, and if that fails too, the name takes over, which is the information the icon stood for anyway. So a work type may occasionally read Bug instead of showing its icon, and nothing is ever blank or broken.

When a section cannot load

Sections are built one by one, and one of them failing no longer takes the page with it. Two things can happen, and both keep the rest of the panel usable:

• The rows cannot be looked up, for example because one key in the list no longer exists. The section then lists its work items as bare keys, without summary, status or the other columns, so you can still see and open what is linked.
• The section cannot be built at all, for example because its field configuration is unreachable. That one section shows its own message; every other section on the work item renders normally.

When the cause is Jira limiting how many requests the app may make, the panel says in plain words that Jira is busy and that it will work again shortly, rather than showing an HTTP status code. See Limitations & timing.

Freshness

The panel keeps itself up to date on its own: details on Limitations & timing. The section menu, the column sorting, Only open work items, the CSV export and the sums change nothing about that: they work on the rows a section already holds and cost no request at all. Saving an inline edit is the one action there that talks to Jira, once per change.

Recipe: a links panel without a visible field

Want a rich, self-maintaining table of a work item's links, with no field involved at all? A link-type panel does exactly that:

1. Open the Global panels page and create a new panel (in a single space, its Linker Panels page does the same job for that space).
2. Choose native links as its content, pick the link types (and directions) you care about, then set the scope and columns.

Every work item in scope now shows those links as a table: status colors, icons, any Jira columns. (If you also want the links searchable with JQL, Jira's search language, you still need a Linker field; see the Configuration reference.)