Update, Read, and Delete Work Items

Learn how to update, read, and delete work items with HAPI, when to use fields or update sections, and how to use security overrides.

With HAPI, you can update, read, and delete work items using Issues.update, Issues.getByKey, and Issues.deleteIssue. You can make changes in either the fields section or the update section of a request.

Pattern for updating work items with HAPI

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

Import Issues from @scriptrunnerhq/hapi/issues.
Call Issues.update inside your script's default async function.
Provide issueIdOrKey to identify the work item.
Provide a body.fields object with the fields you want to change.
Optionally use body.update for more advanced operations (for example, adding/removing values from multi‑select fields).

A general update pattern looks like this:

import * as Issues from '@scriptrunnerhq/hapi/issues'
 
export default async function () {
  await Issues.update({
    // The work item key or ID you want to update
    issueIdOrKey: 'WORKITEM_KEY',
    body: {
      fields: {
        // Set any fields you want to change here
        summary: 'Updated summary',
        // e.g. description, priority, custom fields, etc.
      },
 
      // Optionally, you can use the `update` section here as well:
      // update: {
      //   // Add a new fix version to the issue
      //   fixVersions: [
      //     {
      //       add: { name: '1.0' },
      //     },
      //   ],
      //
      //   // Add DDD and remove BBB from a multi-select field
      //   MultiSelectA: [
      //     { add: { value: 'DDD' } },
      //     { remove: { value: 'BBB' } },
      //   ],
      // },
    },
  })
 
  // Optionally log or return something after the update
  console.log('Work item updated successfully')
}

You can use the same Issues.update pattern to modify any editable field on a work item. In‑app examples build on this pattern to show how to:

Update a work item's fields (for example, change its summary).
Perform privileged updates with security overrides.
Modify multi‑value fields using the update section.

Note: Field aliases and type‑safe creation

When you update fields with HAPI, you use the same type‑safe aliases you saw when creating work items. Under both fields and update, you can refer to custom fields by their alias names (for example, SelectListA, MultiSelectA) instead of raw Jira IDs like customfield_12345. This keeps your update code readable and lets the editor type‑check what you're setting. See the Why use HAPI? section for more details.

Using fields vs update

HAPI exposes both fields and update within Issues.update. They target the same underlying Jira API but are used for different scenarios.

What's the difference between fields and update?

Use fields as a simple way to set a value. Use update to add/remove/replace in a more granular way.

fields is a shortcut for calling update with the set operation. For example, you can set description via fields as follows:

{
 "fields": {
 "description": "a new description"
  }
}

You can also use update with a set operation on description to get the same result:

{
 "update": {
 "description": {
 "set": "a new description"
    }
  }
}

update is useful for fields with multiple values, where you want to add and/or remove from the existing set instead of replacing it entirely. For example, when adding labels to an issue:

Using set (via fields) would overwrite all existing labels.
Using update with add / remove lets you add a new label without removing the existing ones.

Warning: The same field should never appear in both the fields and update sections in the same request payload.

When to use fields

Use fields when you want to:

Set or replace the value of a field in one go.
Update simple fields like summary, description, priority, or single‑value custom fields.

When to use update

Use update when you want to:

Add or remove individual values from multi‑value fields (fix versions, labels, multi‑select custom fields, etc.).
Make granular changes without overwriting everything that's already there.

Reading field values from work items

To work efficiently with fields, you can control which fields you retrieve and whether you want Jira's rendered representation of some fields. With Issues.getByKey, you can:

Ask for specific fields.
Optionally include Jira's rendered representation of some fields.

Fetching specific fields

Use this when you just need one or two values (for example, a custom field):

const issue = await Issues.getByKey('WORKITEM_KEY', {
  fields: ['SelectListA'],
})
 
const value = issue!.fields.SelectListA

Fetching rendered field values

Some fields (like description) can also be returned in a rendered form (for example, HTML).

Use expand: ['renderedFields'] to get those:

const issue = await Issues.getByKey('WORKITEM_KEY', {
  fields: ['FreeTextA', 'description', 'created'],
  expand: ['renderedFields'],
})
 
const rendered = issue!.renderedFields

Finding a field's ID

Most of the time you can refer to a field by its name. When you do need its ID, for example customfield_10006, look it up rather than hardcoding it. Custom field IDs differ between sites, so a hardcoded ID breaks as soon as the script runs anywhere else.

Import the fields module and look the field up by name:

import * as Fields from '@scriptrunnerhq/hapi/fields'

export default async function () {
  const field = await Fields.getByName('Story Points')

  return field?.id
}

The fields module gives you four ways to find a field:


Function	Description
`getByName(name)`	A single field with that name
`findByName(name)`	Every field with that name, for when more than one matches
`getById(fieldId)`	A field by its ID
`getAll(options?)`	Every field on your site

Note: Field names are not unique in Jira. If more than one field shares a name, use findByName and choose the one you want, rather than relying on getByName to pick correctly. getByName returns nothing if no field matches, so use optional chaining on the result.

Privileged updates with security overrides

Sometimes you need to update fields that aren't normally editable for the current user (for example, hidden from the edit screen or marked read‑only). HAPI supports privileged updates by:

Wrapping your update in Users.asApp(...) from @scriptrunnerhq/jira-client.
Passing overrideScreenSecurity and overrideEditableFlag to Issues.update.

Deleting work items

To permanently delete a work item, use Issues.deleteIssue(issueIdOrKey).

In-app example scripts

The following examples are available in-app:

Update a work item: Shows how to update an existing work item's fields using Issues.update with body.fields (for example, changing the summary).
Update a work item with security overrides: Demonstrates how to perform a privileged update by wrapping the call in Users.asApp(...) and passing overrideScreenSecurity and overrideEditableFlag to Issues.update, so you can modify fields that are normally hidden or read‑only.
Delete a work item: Shows how to permanently delete a work item by its key using Issues.deleteIssue(issueIdOrKey).
Update work item (issue) fields using the update object : Demonstrates how to use body.update for incremental changes, such as adding a fix version or adding/removing options from a multi‑select custom field, without overwriting existing values.
Get a custom field value from a work item: Shows how to call Issues.getByKey with a limited fields list to efficiently retrieve and log the value of a specific custom field.
Get rendered field values from a work item: Shows how to use Issues.getByKey with expand: ['renderedFields'] to retrieve rendered representations of fields (for example, description) alongside their raw values.