HAPI

HAPI is more than just a convenience wrapper around the Jira REST API. Two key benefits are:

• Type-checked fields and operations: HAPI surfaces Jira objects as TypeScript-friendly APIs. In the script editor, you get autocomplete for functions and fields (for example, summary, description, SelectListA), and type-checking on what you pass and what you read (for example, objects vs strings, arrays vs single values).
• Friendly field aliases instead of raw field IDs: You don't have to work with customfield_12345. HAPI lets you use human-readable field aliases (for example, SelectListA, MultiSelectA, FreeTextA) when setting fields (such as in Issues.create and Issues.update) and when reading them (such as from issue.fields or issue.renderedFields).

Whenever you see custom field names used directly in code, those are HAPI aliases behind the scenes that resolve to your actual Jira custom fields.

Every HAPI script follows the same basic pattern:

1. Import the HAPI modules you need. At the top of your script, you pull in the functionality you want to use. For example, @scriptrunnerhq/hapi/issues gives you functions for working with work items (issues). Without importing a module, its functions won't be available in your script.
2. Export a default async function. ScriptRunner runs whatever you export as the default function from your script file. Marking this function as async tells TypeScript that it will perform time-consuming work (such as calling Jira over the network) and return a Promise when it finishes. ScriptRunner waits for this function to complete before it considers the script done.
3. Call HAPI functions inside that function. All your actual logic, such as creating work items, updating them, searching, etcs, goes inside the default function. Because HAPI functions (like Issues.create and Issues.update) are asynchronous, you usually call them with await so you can use their results directly.
4. Optionally return a value and/or write to the log. You can return data (for example, the work item you just created), which is useful when you want to see the result, pass it to another tool, or debug your script. You can also use console.log(...) to write messages to the log.

For example, the following script creates a basic Jira work item with only the required fields:

import * as Issues from '@scriptrunnerhq/hapi/issues'
 
export default async function () {
  const issue = await Issues.create({
    body: {
      fields: {
        project: {
          // change this to a valid project key
          key: 'JRA',
        },
        issuetype: {
          // ensure this issue type is valid for your project
          name: 'Task',
        },
        summary: 'Test issue',
      },
    },
  })
 
  return issue
}

The default export is async because HAPI operations such as Issues.create and Issues.update return Promises. You can return values (useful for debugging or pipelines) and use console.log for logging.