Best Practices

Scripts that perform updates, such as creating or editing work items, transitioning issues, sending notifications, apply changes to your Jira instance immediately when run. Always test in a non-production environment before deploying to production.

In several features, your script receives a work item object that appears complete but contains only a few properties, such as id and key, which can be misleading. For example, writing event.issue.fields.priority in an event listener returns undefined even if the work item has a priority set. To read field data, fetch the work item with HAPI , requesting the fields you need.

Here is how it works in each affected feature:

• Event listeners and workflow actions:event.issue is a partial work item. Use getByKey() to fetch it, requesting the fields you need:
  Copy script

  1

  const issue = await Issues.getByKey(event.issue.key, { fields: ['priority'] })

• Workflow actions: The same applies. The default boilerplate script includes a commented-out example showing how to do this. Uncomment the Issues import and the getByKey() call to get started.
• Workflow validators: The default boilerplate script already fetches the work item for you using getByKey(). This is intentional: removing that line means field access silently returns undefined rather than throwing an error, which is difficult to debug.
• Scripted fields: There is no event.issue. Use getById() with the context.id property instead:
  Copy script

  1

  const issue = await Issues.getById(context.id, { fields: ['summary'] })

The script console is the fastest way to test ideas, explore HAPI, and debug scripts before wiring them up to a feature. Use it to:

• Check what a HAPI method returns before using it in a listener or workflow rule
• Run one-off bulk updates safely
• Verify that your async/await logic works as expected

Forgetting await is one of the most common mistakes when writing TypeScript scripts. Without it, you get a Promise object instead of the actual data, and your script will behave unexpectedly without throwing an obvious error.

// ✅ Correct
const issue = await Issues.getByKey('JRA-1')
console.log(issue.key)

// ❌ Incorrect — issue is a Promise, not an Issue object
const issue = Issues.getByKey('JRA-1')
console.log(issue.key) // undefined

If a value is coming back as undefined or [object Promise], a missing await is usually the cause.

The await keyword can only be used inside an async function. Your script's entry point is always async by default, but if you extract logic into helper functions, remember to mark those as async too.

// ✅ Correct
const getIssue = async (key: string) => {
 return await Issues.getByKey(key)
}

// ❌ Incorrect — await cannot be used in a non-async function
const getIssue = (key: string) => {
 return await Issues.getByKey(key) // SyntaxError
}

When you need to fetch or update multiple things that do not depend on each other, use Promise.all() to run them simultaneously. This can significantly reduce execution time.

// ❌ Sequential — takes 3x as long
const issue1 = await Issues.getByKey('JRA-1')
const issue2 = await Issues.getByKey('JRA-2')
const issue3 = await Issues.getByKey('JRA-3')

// ✅ Parallel — all three fetched at once
const [issue1, issue2, issue3] = await Promise.all([
  Issues.getByKey('JRA-1'),
  Issues.getByKey('JRA-2'),
  Issues.getByKey('JRA-3'),
])

Use sequential await only when one operation depends on the result of another.

When fetching work items, specify only the fields your script actually uses. Fetching unnecessary fields increases the response size and slows your script.

// ✅ Only fetch what you need
const issue = await Issues.getByKey('JRA-1', {
  fields: ['summary', 'status'],
})

// ❌ Fetches everything — slower and wasteful
const issue = await Issues.getByKey('JRA-1')

This is especially important when iterating over large search result sets.

Jira fields are not always populated. Accessing a property on a null or undefined value will throw an error and stop your script. Use optional chaining ( ?.) and nullish coalescing ( ??) to handle missing values safely.

// ✅ Safe — returns undefined if fields or priority is null
const priority = issue?.fields?.priority?.name

// ✅ Safe — falls back to 0 if story points is null
const storyPoints = issue?.fields?.StoryPoints ?? 0

// ❌ Unsafe — throws if fields is undefined
const priority = issue.fields.priority.name

ScriptRunner already catches anything your script throws. The error and its stack are written to the invocation log, and the run is marked Failed, so it shows up in the activity history and in the failure count for event listeners and scheduled jobs.

Because of that, the most common error-handling mistake is catching an error and only logging it:

// Don't do this: the run reports success
try {
  await Issues.update({ issueIdOrKey: 'JRA-1', body: { fields: { summary: 'New' } } })
} catch (error) {
  console.error(`Update failed: ${error}`)
}

console.error is logged at ERROR severity, which is below the level that marks an invocation as failed. The script above swallows a real failure and reports Ok. Prefer letting the error propagate:

await Issues.update({ issueIdOrKey: 'JRA-1', body: { fields: { summary: 'New' } } })

const issue = await Issues.getByKey('JRA-1')

if (!issue) {
  // Decide whether this is expected (skip) or a real problem (throw)
  throw new Error('JRA-1 not found, or not visible to this script')
}

await Issues.addComment(issue, { body: 'Done!' })

try {
  await Issues.transition(issue, 'Close Issue')
} catch (error) {
  throw new Error(`Could not close ${issue.key}`, { cause: error })
}

try {
  await Issues.update({ issueIdOrKey: 'JRA-1', body: { fields: { customfield_10011: 'x' } } })
} catch (error) {
  const status = (error as { response?: { status?: number } }).response?.status

  if (status === 403) {
    console.warn('No edit permission, skipping')
    return 'Skipped: no permission'
  }

  throw error
}

export default async function () {
  const failures: string[] = []
  let updated = 0

  for await (const issue of Issues.search('project = JRA AND status = Open')) {
    try {
      await Issues.addComment(issue, { body: 'Reminder: still open' })
      updated++
    } catch (error) {
      failures.push(`${issue.key}: ${error instanceof Error ? error.message : String(error)}`)
    }
  }

  if (failures.length) {
    throw new Error(`Commented on ${updated}, failed on ${failures.length}:\n${failures.join('\n')}`)
  }

  return `Commented on ${updated} work item(s)`
}

const result = await Issues.createMany({ body: [...] })

if (result.errors?.length) {
  throw new Error(`${result.errors.length} of the work items could not be created`)
}

A raw fetch call returns the response whatever the status, so check it:

const response = await fetch('/rest/api/3/myself')

if (!response.ok) {
  throw new Error(`Jira returned ${response.status}: ${await response.text()}`)
}

Use console.log to inspect values at runtime. The output appears in the script console's output panel, and in the logs for listeners and scheduled jobs. This is the quickest way to understand what your script is actually receiving and returning.

const issue = await Issues.getByKey('JRA-1')
console.log(JSON.stringify(issue)) // Inspect the full shape of the object

Remove or comment out debug logs before deploying to production to keep your output clean.

Scripts run with a 20-second execution limit. Long-running scripts, particularly those that iterate over large result sets or make many sequential API calls, can hit this limit and fail. See Scripting limitations for the full list of limits.

To stay within limits:

• Use parallel execution with Promise.all() where possible
• Only fetch the fields you need
• Spread large bulk operations across multiple scheduled runs
• Avoid unnecessary API calls inside loops

ScriptRunner is permissive by default; if your scripted field returns an incorrect value, the field will silently render as empty rather than throwing an error. This can make bugs hard to track down.

To catch return type errors early, explicitly declare the return type on your function signature. TypeScript will then flag any mismatches when you write the script, before it ever runs. For example, a scripted field that should return a user might look like this:

export default async function (context: DateTimeScriptFieldContext): Promise<User | null>

With this declaration in place, returning an incorrect value, such as { name: "Gustavo Bishop" } as a plain object instead of a proper User type, will produce a type error immediately, rather than silently rendering as empty at runtime.

This applies to all scripted field types. Always match the return type in your function signature to the field type you have configured.

Using the wrong feature for a task makes scripts harder to maintain and debug. As a quick guide:

• Need to react to a work item change? Use an event listener for broad reactions across spaces, or a workflow rule if the logic is tied to a specific transition.
• Need to display calculated data in a field? Use a scripted field.
• Need to control how fields behave on a screen? Use field behaviours.
• Need to run something on a schedule? Use a scheduled job.
• Need to expose Jira data to an external system? Use an HTTP endpoint.
• Need to add custom logic to an automation flow? Use an automation integration.

When in doubt, the script console is always a good place to start. You can prototype logic there before committing it to a feature.