Platforms: Jira Data Center ↔ any
The problem
Sometimes a sync script needs to find other issues in Jira, not just the one being synced. A few examples: connect an incoming item to an issue that already exists, check for duplicates before creating a new issue, or look up a related issue by a custom field value.
Jira DC has no built-in helper for this in the Exalate script, but the Jira API can run JQL directly. There are a few traps that make it look like the search works while it returns nothing:
- No logged-in user. During a sync,
jiraAuthenticationContext.loggedInUseris null. A search with a null user runs as anonymous and returns 0 results, with no error at all. - The proxy user is shown as a key. Exalate’s General Settings show the proxy user as a key like
JIRAUSER12345.getUserByNamereturns null for a key, so the search again runs as nobody. - Field names are fragile. Custom field names can have typos, trailing periods or duplicates. A JQL query on the wrong name returns nothing or fails.
~is a contains search. On text fields,cf[10000] ~ "123"also matches1234.
The approach
- Run the search as the Exalate proxy user. The script looks the user up by key with
userManager.getUserByKey, so the search runs with that user’s Browse permission. If the user isn’t found, the sync stops with a clear error instead of silently finding nothing. - Validate the JQL first.
searchService.parseQuerychecks the query. An invalid query stops the sync with the exact JQL error. - Search with
SearchService. The results are loaded as full issue objects, so you can read any field from them. - Use
cf[<id>]and check exact values. The query uses the custom field ID instead of its name, and the results are filtered in code to the exact value, so a contains match never picks the wrong issue.
The result
A reusable jqlSearch closure you can call anywhere in a Jira DC sync script with any JQL. It returns real results while the sync runs, and fails loudly when the user or the query is wrong instead of returning an empty list.
Notes
- Replace
JIRAUSER00000with your Exalate proxy user key from General Settings. The proxy user needs Browse permission on the projects you search. - Replace
PROJwith your project key and10000with your custom field ID (twice: in the JQL and ingetCustomFieldObject). - To find a custom field ID: Jira administration → Issues → Custom fields → edit the field, the ID is in the URL.
results.resultsworks on Jira 8 and later. On Jira 7, useresults.issues.searchValue.replace('"', '\\"')puts a backslash in front of every double quote in the value. The JQL wraps the value in double quotes, so a value likeABC "x"would otherwise end the string early and give an invalid query. Escaped, the JQL becomescf[10000] ~ "ABC \"x\"", and Jira searches for the quotes as normal text.- The last line is a
debug.errorthat shows what was found. Remove it once the search returns what you expect, and useexactin your own logic.
The Scripts
1. Jira DC script (incoming or outgoing): JQL search
// Exalate | Jira Data Center | Run a JQL search from a sync script
//
// Configure:
// PROXY_USER_KEY Exalate proxy user KEY (General Settings shows a key like JIRAUSER12345).
// Use getUserByKey, not getUserByName: getUserByName returns null for a key.
//
// Notes:
// - In the sync there is no logged-in user. A null user searches as anonymous and returns 0 hits
// with NO error. Always pass a real user with Browse permission on the project.
// - Prefer cf[<id>] over field names in JQL (names can have typos, trailing periods or duplicates).
// - ~ is a contains/word search on text fields; verify the exact value in code if it matters.
// - results.results works on Jira 8+; on Jira 7 use results.issues.
import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.bc.issue.search.SearchService
import com.atlassian.jira.web.bean.PagerFilter
final String PROXY_USER_KEY = "JIRAUSER00000"
// Runs a JQL search as the proxy user and returns the matching issues as full issue objects.
def jqlSearch = { String jql ->
def searchService = ComponentAccessor.getComponent(SearchService)
def user = ComponentAccessor.jiraAuthenticationContext.loggedInUser
?: ComponentAccessor.userManager.getUserByKey(PROXY_USER_KEY)
if (!user) {
debug.error("Proxy user ${PROXY_USER_KEY} not found, cannot run JQL.")
}
def parse = searchService.parseQuery(user, jql)
if (!parse.isValid()) {
debug.error("Invalid JQL: ${parse.errors}")
}
def results = searchService.search(user, parse.query, PagerFilter.getUnlimitedFilter()).results
results.collect { ComponentAccessor.issueManager.getIssueObject(it.id) }
}
// Example: find issues in PROJ where custom field 10000 holds the remote issue key
def searchValue = replica.key
// The JQL puts the value between double quotes: cf[10000] ~ "value".
// A double quote inside the value would end that string too early and break the JQL,
// so put a backslash in front of each one. Example: ABC "x" becomes ABC \"x\"
def safeValue = searchValue.replace('"', '\\"')
def found = jqlSearch("project = PROJ AND cf[10000] ~ \"${safeValue}\"")
// ~ is a contains search, so keep only exact matches
def cf = ComponentAccessor.customFieldManager.getCustomFieldObject(10000L)
def exact = found.findAll { it.getCustomFieldValue(cf)?.toString()?.trim() == searchValue }
// Debug, remove after testing
debug.error("Found ${found.size()}, exact ${exact.size()}: ${exact*.key}")