Manage Custom Fields

Create, rename, and delete the custom fields on your site.

HAPI's fields module manages the custom fields on your site: creating them, changing their name or description, and deleting them. These change your site's field configuration rather than any individual work item.

To set a field's value on a work item, see Update work items. To find an existing field's ID, see Finding a field's ID.

Pattern for managing custom fields with HAPI

The pattern for managing custom fields is:

Import the fields module.
Put your code inside export default async function () {}. This is the only function ScriptRunner runs, so if you split your code into several functions, call them from there. .
Pass a name, type, and optional description when creating, and a field ID for everything else.

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

export default async function () {
  // Create a custom field
  const field = await Fields.create({
    name: 'Risk Level',
    description: 'How risky this work is',
    type: 'select',
  })

  return field.id
}

Available functions


Function	Description
`create(options)`	Create a custom field. Takes a `name` and `type`, with an optional `description` and `searcherKey`
`update(fieldId, options)`	Change a field's `name`, `description`, or `searcherKey`
`deleteField(field)`	Delete a custom field. Accepts a field ID or a field object

Warning: Deleting a custom field removes it from every screen and every work item that used it, along with the values stored in it. This cannot be undone.

Custom field types

The type you pass to create is a short name. You do not need Jira's full type key.


Type	Creates
`textfield`, or `text`	A single line of text
`textarea`	A multi-line text field
`float`, or `number`	A number field
`datepicker`, or `date`	A date field
`datetime`	A date and time field
`select`	A single select list
`multiselect`	A multi-select list
`cascadingselect`	A cascading select list
`radiobuttons`	Radio buttons
`multicheckboxes`	Checkboxes
`labels`	A labels field
`userpicker`, or `user`	A single user picker
`multiuserpicker`, or `multiuser`	A multiple user picker
`grouppicker`	A single group picker
`multigrouppicker`	A multiple group picker
`version`	A single version picker
`multiversion`	A multiple version picker
`project`	A space picker
`url`	A URL field
`readonlyfield`	A read-only text field
`importid`	An import ID field

Note: You can also pass a full Jira type key, or the key of a field type provided by another app, and it is used as given.