JQL guide
Every Linker picker can carry a JQL filter that decides which work items the search suggests. This page shows what the filter does, gives copy-paste examples, and explains dynamic filters that react to the work item they run on.
What the JQL filter does
The filter limits which work items the picker suggests, nothing else. It never touches existing values, links or sync: a work item that arrived in the field through a hand-made link stays there even if the filter would not suggest it. You write the rule in JQL, Jira's search language, in the field's context configuration (see the Configuration reference).
The editor helps you: it is the same editor Jira uses in its own search bar. It highlights the syntax, marks errors inline and suggests fields, operators and values while you type. Validity is checked again when you save, and a live match count shows roughly how many work items the filter allows. Leave the filter empty to allow every work item.
project = ABC, issuekey and issuetype. Every example on this page uses the wording JQL actually accepts.Basic examples
Copy any of these into the filter and adjust the names:
| Filter | What the picker suggests |
|---|---|
issuetype = Story | Only stories. |
assignee = currentUser() | Only work items assigned to the person searching. |
project in (ABC, XYZ) AND status != Done | Unfinished work from two spaces. |
created >= startOfMonth() | Work items created this month. |
labels = backend ORDER BY updated DESC | Work items labeled backend, the recently updated ones first. |
Dynamic filters: currentIssue()
A filter can look at the work item the picker is opened on. Write currentIssue("field") anywhere in the filter, and Linker replaces it with the value that work item carries in the field, read fresh every time someone searches.
Fields can be referenced in three ways:
- By a system alias such as
project,statusorassignee, see the table below. - By display name:
currentIssue("Customer"), exactly as the field is named in Jira, upper and lower case do not matter. - By field id:
currentIssue("customfield_10264"). System field ids work too, for examplecurrentIssue("timeoriginalestimate").
Supported placeholders
| Placeholder | Resolves to |
|---|---|
key, issuekey | The key of the current work item, e.g. DEL-42. |
summary | The summary text. |
environment | The environment text. |
project | The space key. |
issuetype, type, work type | The name of the work type. |
status | The status name. |
statusCategory, status category | The status category (new, indeterminate, done). |
priority | The priority name. |
resolution | The resolution name. |
assignee, reporter, creator | The account id of that person, which is what JQL compares user fields against. |
labels | Every label, as a list. |
components, component | Every component name, as a list. |
fixVersions, fix version | Every fix version name, as a list. |
versions, affected versions | Every affected version name, as a list. |
parent | The key of the parent work item. |
epic, epic link | The epic: the Epic Link field in company-managed spaces, the parent in team-managed ones. |
sprint | The ids of every sprint the work item belongs to. Ids, not names, because sprint names repeat across boards. |
due, duedate, due date | The due date. |
created, updated | Creation and last change time, shortened to the minute so JQL accepts them. |
resolved, resolutiondate | The time the work item was resolved. |
"Customer", customfield_10264 | Any custom field, by its display name or by its id. Date and date-time fields are converted to a JQL date automatically. |
Copy-paste examples
| Filter | What the picker suggests |
|---|---|
project = currentIssue("project") AND key != currentIssue("key") | Only work items from the same space, excluding the item itself. |
assignee = currentIssue("assignee") | Only work items with the same assignee. |
"Customer" = currentIssue("Customer") | Cascading pickers: only work items of the same customer. |
labels IN currentIssue("labels") | Only work items sharing at least one label with the current one. |
sprint IN currentIssue("sprint") AND statusCategory != Done | Unfinished work from the same sprints. |
parent = currentIssue("epic") AND duedate <= currentIssue("due") | Siblings under the same epic that are due no later than this work item. |
component IN currentIssue("components") AND assignee = currentIssue("reporter") | Work in the same component, owned by the person who reported this item. |
A field that holds several values is written as a parenthesized list automatically, so IN works without adding brackets by hand. Several placeholders can be combined in one query. A Linker field can also reference another Linker field, which allows cascading structures: pick a customer in one field, and the next field offers only that customer's items.
Linker functions you can use anywhere in Jira
Everything above shapes what a Linker field offers inside the app. Linker also contributes three JQL functions to Jira itself, so the ordinary work item search, boards, saved filters, dashboard gadgets and automation rules can ask about the same relationships. No Linker screen is involved: you type them into Jira's own search box.
| Function | Arguments | Finds |
|---|---|---|
linkerLinksTo | work item (required) field (optional) | Work items whose Linker field points at the named work item. Without a field name, every Linker field on the site counts, which is usually what a board filter wants: issue in linkerLinksTo("CLI-2"). Name a field to ask that one only: linkerLinksTo("CLI-2", "Client"). |
linkerSharesWith | work item (required) field (required) | Work items carrying the same value in that field as the named work item, the named item itself excluded: issue in linkerSharesWith("DEL-2", "Client"). This is the "all work for the same customer" question, asked outside a panel. |
linkerHasLinks | field (optional) | Work items where a Linker field carries anything at all. Negated it is the more useful half: issue not in linkerHasLinks() lists everything nobody has connected yet. Name a field to look at one: linkerHasLinks("Contract"). |
The field argument takes the field's name as Jira shows it, or its id (customfield_10264), which the Fields page prints under every field name. Upper and lower case do not matter and stray spaces around the argument are ignored, so linkerLinksTo("CLI-2", "client") finds the field named Client. All three functions accept in and not in; not in negates the whole condition.
What a function returns
A Linker function does not hand Jira a list of work items. It hands back a piece of JQL that Jira folds into your query and then runs as you. Three consequences, and they are the reason these functions are worth using:
- Your own permissions still decide what comes back. Nobody sees more through a Linker function than through a normal search.
- There is no result cap. Nothing is precomputed, so there is no list that could be truncated.
- The answer is current. The fields are read at the moment the query runs, so a saved filter or a board follows your data as it changes, with no refresh job behind it.
Limits
| Situation | What happens |
|---|---|
| The field name is unknown, or names a field that is not a Linker field | The condition matches nothing. |
| Two Linker fields carry the same display name | The name resolves to the first of them and the query runs normally. To ask about the other one, pass its field id instead of the name. Internally the functions address fields by id, not by name, which is what keeps a duplicate name from breaking a saved filter. |
linkerSharesWith called without a field name | Matches nothing. "The same value" only means something for one named field, which is why that argument is required. |
| The named work item does not exist, or carries no value in that field | Matches nothing. Nothing shares a value with an empty field. |
| The site has no Linker field at all | Matches nothing. |
Any of the above together with not in | Still matches nothing, deliberately: a lookup that came back empty never widens a search into "everything". So if a not in query comes back empty out of nowhere, check the arguments first. |
| Jira itself does not answer, for example while it is throttling the app | This is the one case that is not answered with "matches nothing". Jira shows the person the message “Linker could not reach Jira to answer this query. Please try again shortly.” and no results. The distinction is deliberate: "there is no field by that name" is an answer, "Jira would not say which fields exist" is not, and quietly turning the second into an empty result is how one bad minute empties every board on the site. |
linkerLinksTo or linkerHasLinks without a field name on a site with many Linker fields | They work, but the generated condition grows with every field. Name the field when you know which one you mean. |
| Sorting | A Linker field holds a list, so ORDER BY on the field itself is not possible. Sort by anything else, for example ORDER BY updated DESC. |
linkerSharesWith, Linker reads that work item's field value with the app's access, so the function also works for people who cannot browse the item themselves. What the search gives back is still filtered by your own permissions.Worked examples
project = DEL AND issue in linkerSharesWith("DEL-2", "Client") AND status != DoneEverything in Delivery for the same client as DEL-2 that is not finished. Used as a board filter it follows the field: change the client on a work item, and the board follows on the next load.
project = SUP AND issue not in linkerHasLinks("Client") AND created >= -30dSupport requests from the last 30 days that nobody has given a client yet. A useful saved filter for a triage dashboard.
issue in linkerLinksTo("CLI-2") ORDER BY updated DESCEverything pointing at the client CLI-2 through any Linker field: contracts, delivery work and support requests in one list, most recently touched first.
In Jira Automation the same expressions work in a JQL condition, in a Lookup work items action and in a JQL branch, so a rule can act on "everything belonging to this client" without knowing which field carries the relationship. See Jira Automation.
How dynamic filters behave
- No live match count. The placeholder is resolved per work item, so the editor checks the syntax but cannot show how many work items match.
- Empty or unknown field: no suggestions. When the referenced field is empty on this work item, or unknown, the filter deliberately matches nothing instead of running a broken query.
- Create screen: placeholders cannot resolve. The work item does not exist yet. Configure the JQL filter for the create screen for that case: the input appears in the field configuration as soon as the main filter uses
currentIssue(), and the picker uses it on the create screen instead. If it stays empty, the picker shows no suggestions there. - Create screen: the filter comes from the space's own context. Jira tells the picker which space the create form belongs to, so it uses that space's context, not the field's global default. If two spaces give the field different filters, the create screen already shows the right one. See the Configuration reference.
- Work item view and transition screens: normal. There, the placeholder resolves against the open work item as expected.
Panel JQL filters accept the same placeholders, on the Global panels page and in the panels a space builds for itself.