Run JQL searches from an Exalate script in Jira Data Center

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.loggedInUser is 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. getUserByName returns 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 matches 1234.

The approach

  1. 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.
  2. Validate the JQL first. searchService.parseQuery checks the query. An invalid query stops the sync with the exact JQL error.
  3. Search with SearchService. The results are loaded as full issue objects, so you can read any field from them.
  4. 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 JIRAUSER00000 with your Exalate proxy user key from General Settings. The proxy user needs Browse permission on the projects you search.
  • Replace PROJ with your project key and 10000 with your custom field ID (twice: in the JQL and in getCustomFieldObject).
  • To find a custom field ID: Jira administration → Issues → Custom fields → edit the field, the ID is in the URL.
  • results.results works on Jira 8 and later. On Jira 7, use results.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 like ABC "x" would otherwise end the string early and give an invalid query. Escaped, the JQL becomes cf[10000] ~ "ABC \"x\"", and Jira searches for the quotes as normal text.
  • The last line is a debug.error that shows what was found. Remove it once the search returns what you expect, and use exact in 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}")

Great breakdown of the challenges and solutions for running JQL searches from Exalate sync scripts in Jira Data Center! Your approach is spot-on for handling the quirks of user context, JQL validation, and field matching.

To summarize and clarify for anyone looking to implement this:

  • Always run JQL searches as the Exalate proxy user (found in General Settings as a key like JIRAUSER12345). Use getUserByKey to fetch the user object.
  • Validate your JQL before running it using searchService.parseQuery. This ensures any syntax errors are caught early and reported clearly.
  • Use custom field IDs (cf[10000]) in your JQL instead of names to avoid issues with typos or duplicates.
  • Remember that ~ in JQL is a “contains” search, so always filter results in code for exact matches if needed.
  • Escape double quotes in your search values to prevent JQL parsing errors.
  • The closure you provided is reusable and will fail loudly if the proxy user or JQL is invalid, making debugging much easier.

For reference, you can find more details and best practices for scripting in Jira Data Center with Exalate in the official documentation:
https://docs.exalate.com/docs/scripting-for-jira-dc

Your script is well-structured and should work reliably for most use cases where you need to look up issues dynamically during syncs. Just remember to update the PROXY_USER_KEY, project key, and custom field ID for your environment.

If you need more examples or want to see how to adapt this for other platforms, check out the scripting guides in the documentation above.