Limitations & timing

Everything Linker cannot do instantly (or cannot do at all), collected on one page. Check here when something seems slow or missing before assuming it is broken: in most cases, the behavior is expected and explained below.

Sync timing

• Saving the field is instant. Links are created and removed the moment you press Save.
• Everything automatic can take up to ~3 minutes. The safety net (changes made through bulk edits, Automation, imports or scripts) and reverse sync (links made or removed by hand) rely on Jira's event delivery, which is outside our control.
• Counterpart fields: when you link through the field, the other work item's field fills immediately. When the change came through the API or automation, it fills with the safety-net delay instead.
• Opening the work item skips the wait. When a field holds work items whose links are missing, for example right after the create screen or a CSV import, the links are written the moment somebody displays the field, without waiting for the event. That repair only ever adds links, it never runs in the customer portal, and it stays out of the way once this field has created a link on that work item, so a link you deleted by hand stays deleted. See How linking works.

Page and panel refresh

• An already-open work item needs a page reload to show synced changes to the field.
• The Linker panel refreshes itself: instantly after edits made on the page, when you return to the browser tab, and in a short catch-up window after a change (one, two and three minutes later) while the app's own sync may still be on its way. There is no standing poll: an idle tab costs nothing.
• Admin changes can take up to two minutes to appear on work items: panel and field loads are served from a short-lived server-side cache (two minutes for panel definitions and field configuration, five for the project and link type lists), so a saved change may need that long to show on work items that are already open. The admin pages themselves always read fresh.
• The panel is added once via the Apps button in the work item toolbar; choosing Show for all work items in its ⋯ menu then makes it appear everywhere automatically, which is Jira standard behavior for app panels.
• One failing section does not take the panel with it. A section whose rows cannot be looked up falls back to bare keys, and a section that cannot be built at all shows its own message while every other section renders normally. See Work item panels.
• The section menu works on what is loaded. Copy keys, Open in Jira search, Only open work items, Export as CSV, Show sums and sorting by a column header all run in the browser over the rows a section has already loaded, so a truncated section gives you what it holds rather than the full set. The exported file and the sums therefore cover the loaded rows, not every match, and a sum appears only for a custom column whose loaded cells are all numbers. None of them costs a request. A sort lasts as long as the page; the filter and the collapsed state are remembered per viewer in the browser. See Work item panels.
• Inline editing covers plain fields only. Where a panel allows it, viewers can edit text and paragraph custom fields, number, date, date with time, the summary, the due date, the assignee, the priority and Linker's own fields. Selects, option fields, cascading fields and multi-value fields stay read only, as do the work type, the parent, the description and other rich text, and the fields belonging to other apps, because an app cannot render another app's editor. The status is not edited either, it has its own transition menu. Each save writes one field in the viewer's name, so Jira's edit permission and the work item's edit screen decide whether it goes through. On such a panel a click on a row no longer opens its work item, so that a correction is not interrupted; the key column still links. See Work item panels.
• A Linker field column shows the built-in columns only. A cell that renders a Linker field lists its work items with the built-in columns of that field's Display settings, key, summary, status, assignee, priority and type; custom-field columns of the referenced work items do not appear in the cell. The referenced work items of a whole section are fetched in one request, at most 100 of them. See Work item panels.
• A transition that needs a form opens a second tab. Transitions run inline in the panel, except those that ask for a resolution, a comment or an assignee: those open Jira's own transition screen. The panel does not learn when you finished there, so the new status appears on its next refresh, when you return to the tab or shortly after. See Work item panels.

Workflow validator

• It counts by status category, not by resolution. The validator Linker: no open linked work items treats a linked work item as finished as soon as its status is in Jira's Done category, whatever the status is called and whether or not a resolution is set.
• An unconfigured validator blocks nothing. Without a link type and a side it lets every transition pass, so a half-finished setup never stops anybody.
• It is a Jira expression. Jira evaluates it itself at transition time and the app runs nothing, so it costs no invocation, and equally it cannot do anything an expression cannot: it checks the links and their status categories, nothing else. See Workflow validator.

Icons

• Icons a site uploaded itself may be replaced by their name. Jira serves those only to a logged-in Jira session, which an app screen is not. The panel fetches them once through Jira's API and embeds them; the field table and the picker fall back to the name straight away. Nothing is ever shown broken. See Icons and avatars.
• A fetched icon is remembered for about an hour, so a changed space avatar can take that long to appear in a panel.

When Jira throttles

• Jira limits how many requests an app may make. When it throttles a call, Linker waits and repeats it, up to three times, with a short and slightly randomised pause between the attempts, so parallel work does not come back in lockstep. Only throttling is repeated: an ordinary error is reported straight away.
• When Jira asks for a pause of more than five seconds, Linker does not sit it out. The call fails immediately with Jira's message, which keeps a screen responsive instead of freezing it. Try again in a moment.
• Bulk work is unaffected by that rule: a resync runs as a background job and simply picks its page up again later.

Licence

• An inactive licence stops the paths that write or search: the picker search, creating from the picker, adding and removing links in a panel, changing a status there, and starting a resync.
• Reading keeps working: fields and panels still show what is already linked, and the whole admin area stays open, so an expired licence never locks an admin out of the configuration they need in order to fix it.
• The background sync keeps running: links made by hand still flow into the fields, so nothing drifts apart while a licence is being renewed.
• A missing licence, as in a development site or a free installation, counts as licensed. Only an explicitly inactive licence gates anything.

JQL editors

• No live match count for dynamic queries. A filter that uses currentIssue() depends on the work item it runs on, so the configuration and panel editors check its syntax but cannot show how many work items match; a hint in the editor says so. See Dynamic JQL.

Single selection mode

• Single selection is enforced by the picker, not by Jira. Edits that bypass Linker, such as bulk edits, the REST API or CSV imports, can still write several values into a single-mode field; the sync then converges the field on the newest matching link. See Configuration reference.
• JQL ORDER BY on a Linker field is not possible. The field stores a list value in both selection modes, and Jira cannot sort search results by a list field.

Exports

• Formatted CSV exports cannot be re-imported into Jira 1:1. If you rely on exporting and importing back, keep export formatting off. See CSV export.
• Export blocks other than the work item key take their data from the links. With link creation switched off, they come out empty.

Size limits

• A field holds at most 100 work items per work item; in a context with the single selection mode it holds at most one.
• A table (field or panel) shows at most 10 columns.
• A link-type panel section without a JQL filter can page through all its links in chunks. With a JQL filter, the first 100 links are filtered and shown, with a note saying so. A JQL panel section behaves like the filtered case: it shows the first 100 matches, with a note, and pages through them via Show more. See Work item panels.
• Long tables load lazily: the field table starts with the first 10 rows; panel sections start with their configured Work items per page (10 unless changed). A Show N more button loads the rest, and the count in the section heading is always the real total.
• Pasting work item keys into the picker handles at most 100 keys at once, which is the same 100 the field itself holds. Anything past that is reported back as not added rather than dropped in silence, in the same list as keys that were not found. The paste offer appears only in a context that holds several work items.
• In the customer portal a field shows at most 10 work items, followed by a line saying how many are not shown. There is no Show more there.
• At most 50 panel definitions per site. Global panels and the panels of every space share that one budget.
• The Recent app activity list in the admin area keeps the last 200 entries.
• Configuration export and import travel by names and keys, never by ids: fields by name, spaces by key, work types by name. An import therefore updates a context only where this site has a field of the same name with a context over exactly the same spaces, and it drops the scope entries this site does not know. One document holds at most 50 fields, 200 contexts, 50 panels and 256 KB of text. See Configuration reference.

How it behaves on a large site

Measured on a Jira Cloud site with 2000 work items in one space, so these are numbers rather than estimates.

• The picker does not get slower with the size of the site. One page of suggestions out of 2000 work items took 0.3 s, and filling a full field of 50 values with their summary, status and assignee took 0.2 s. Both go through Jira's own index, so a hundred thousand work items behave the same as two thousand.
• A resync is bounded by Jira, not by the app. Creating one link costs about 0.5 s, and a resync creates one per work item it has to repair. So roughly 1000 links per 8 minutes: ten thousand take about an hour and a half, a hundred thousand take most of a day. The resync runs in the background with a progress display and a cancel button, and it is idempotent, so it may be stopped and started again.
• Only work items that need a link cost anything. A resync reads its scope page by page and skips everything that already matches, so a second run over the same scope is fast.
• The everyday paths are unaffected by all of this: the immediate path on save writes one link, and the safety-net trigger handles one work item per event.

Space panels

• A space administrator cannot build a field panel. In a space's settings the content selector offers link types and queries only, because a field panel depends on a field context and a context is site-wide configuration. A Jira administrator builds those as global panels with a matching scope. See Space panels.
• A panel cannot change its space. The binding is set when the panel is created, from the space whose settings it was built in, and nobody can move it later: not the space administrator, and not a Jira administrator on the Space panels page. Build a new panel where it belongs and delete the old one.
• A space panel is invisible outside its space. It does not render on the work items of another space, whatever its work-type scope says, and it is not listed in another space's settings.
• Ordering does not cross the boundary. Global panels always render before the space's own, and reordering inside one space never moves a global panel or another space's panel.
• Switching delegation off does not remove anything. The page disappears from every space's settings and further writes are refused, but the space panels that exist keep rendering. Delete them on the Space panels page if that is what you want.
• Panels built before this existed have no author. The name under a panel is only recorded from the moment the panel is created, so older definitions show nothing rather than a guess.

Customer portal

• No JQL filter means no content. A context without a filter shows nothing in the portal at all: no suggestions, no values, no pasted keys. This is deliberate, because the filter is the only boundary there. The setup check warns about it when a service desk space is in scope, and the message the customer sees is translated like everything else. See Service desk portal.
• Customers never create work items from the picker, whatever the context allows internally.
• A work item created from the picker gets no request type, so pointing the create target at a service desk space produces items the portal never shows. See Create and link.

Team-managed spaces

• The field must be added to each work type's layout by hand; screens do not apply there. See Team-managed spaces.