Create Work Items

Learn how to use Issues.create to add work items with required, system, and custom fields, create subtasks, and link work items during creation.

With HAPI, you can create work items and control how they're set up using the Issues.create method.

Pattern for creating work items with HAPI

When you create a work item with HAPI, you can follow this basic pattern:

Import Issues from @scriptrunnerhq/hapi/issues.
Call Issues.create inside your script's default async function.
Provide a body.fields object with the fields you want to set.
Optionally use body.update for operations like adding links or versions.

The following example shows this general pattern:

import * as Issues from '@scriptrunnerhq/hapi/issues'
 
export default async function () {
  // Create a new issue (work item) in a given project (space)
  const issue = await Issues.create({
    body: {
      fields: {
        // Target project/space
        project: { key: 'SPACE_KEY' },
 
        // Issue type/work item type (e.g. Task, Bug, Story)
        issuetype: { name: 'Task' },
 
        // Required summary/title
        summary: 'Summary text',
 
        // Add any other system or custom fields here
        // e.g. description, custom fields, priority, etc.
      },
    },
  })
 
  // Return the created issue so you can inspect it or use its key
  return issue
}

The in‑app example scripts build on this pattern to cover specific use cases, such as creating a basic work item, working with custom fields and system fields, and creating subtasks.

Note: Field aliases and type‑safe creation

When you set fields under body.fields, HAPI gives you type‑checked access to both system fields (like summary, description, priority) and custom fields via their aliases (for example, SelectListA, MultiSelectA). These aliases map to your underlying Jira custom fields, so you don't have to work with customfield_12345 IDs directly. See the Why use HAPI? section for more details.

In-app example scripts

The following examples are available in-app:

Create a work item: Shows how to create a work item using only the required fields: project.key, issuetype.name, and summary.
Create a work item with custom fields: Demonstrates how to create a work item and populate custom fields under fields, including single select, multi-select, and user/group picker fields.
Create a work item with system fields: Shows how to create a work item and set common system fields such as description, versions, components, priority, duedate, and timetracking. It also demonstrates how to use body.update.issuelinks to create work item links during creation.
Create a subtask: Shows how to create a subtask using the same Issues.create pattern, with issuetype.name set to a subtask type and fields.parent.key set to the parent work item key.