Scripting API: Jira Entities

Part of the Scripting API reference. Issues | Jira Entities | Service Management | Utilities | Smart Values

List methods on this page (Users.find, Projects.list, Fields.getContexts, Fields.getOptions, Boards.list, Boards.getSprints, Groups.*, Labels.list) return every page - one API call per page, at most 20 pages. Passing startAt or maxResults reads a single page instead. See List methods and pagination.

Users

Look up and search for Jira users.

Method Description API calls
Users.current() Get the current user (cached after first call) 1 (first call only)
Users.get(accountId) Get user by account ID 1
Users.find(query, opts?) Search users by name/email (all pages) 1 per page
Users.findAssignable(project, query?, opts?) Find users assignable to a project (all pages) 1 per page

find / findAssignable options: { startAt?: number, maxResults?: number } - passing either reads a single page instead of all of them.

const me = Users.current()
log(me.displayName, me.accountId)

const user = Users.get("5b10ac8d82e05b22cc7d4ef5")
log(user.emailAddress)

// Search users - every page, not just the first 50
const users = Users.find("alice")
for (const u of users) {
  log(u.displayName, u.accountId)
}

// A single page, when the API budget matters
const firstTen = Users.find("alice", { maxResults: 10 })

// Find assignable users for a project
const assignable = Users.findAssignable("PROJ", "bob")
log(assignable.length, "users found")

User wrapper

Users.current() and Users.get(accountId) return User wrapper objects with typed properties. Also accessible via issue.assigneeUser and issue.reporterUser on RichIssue objects.

Property Description
displayName User display name
accountId Atlassian account ID
emailAddress User email address
avatarUrl Avatar URL (48x48)
active Is account active
timeZone User timezone
locale User locale
Method Description
toString() Returns displayName or accountId
toJSON() Plain object representation
equals(other) Compare by accountId
const user = Users.current()
log(user.displayName)
log(user.timeZone)

const issue = Issues.get("TEST-1")
log(issue.assigneeUser?.displayName)
log(issue.reporterUser?.equals(user))

Projects

Access Jira project data.

Method Description API calls
Projects.get(key) Get project by key. Returns RichProject 1
Projects.list(opts?) List all accessible projects (all pages) 1 per page
Projects.validateKey(key) Validate a project key for creation (returns Jira’s validation result) 1

list options: { startAt?: number, maxResults?: number } - passing either reads a single page.

RichProject methods

Method Description API calls
project.getComponents() Get project components 1
project.getVersions() Get project versions 1
project.getStatuses() Get project statuses 1
project.getRoles() Get project roles 1
project.listProperties() List project property keys 1
project.getProperty(key) Read a project property value 1
project.setProperty(key, value) Write a project property 1
project.deleteProperty(key) Delete a project property 1
const project = Projects.get("PROJ")
log(project.name)

const components = project.getComponents()
const versions = project.getVersions()

const projects = Projects.list()
for (const p of projects) {
  log(p.key + ": " + p.name)
}

Project wrapper

Projects.get(key) returns a Project wrapper with typed properties and async methods. Also accessible via issue.projectObj on RichIssue objects.

Property Description
key Project key
name Project name
id Project ID
projectTypeKey Project type (software, etc.)
description Project description
lead Project lead (User wrapper or null)
url Project URL
Method Description
getComponents() Get project components
getVersions() Get project versions
getStatuses() Get project statuses
getRoles() Get project roles
listProperties() List project property keys
getProperty(key) Get project property value
setProperty(key, value) Set project property
deleteProperty(key) Delete project property
toString() Returns project key
equals(other) Compare by key
const proj = Projects.get("PROJ")
log(proj.name)
log(proj.lead?.displayName)
const comps = proj.getComponents()

// Access from issue
const issue = Issues.get("TEST-1")
log(issue.projectObj?.name)

Fields

Work with Jira field metadata.

Method Description API calls
Fields.list() Get all fields 0-1 (cached)
Fields.get(nameOrId) Get field by name or ID 0-1 (cached)
Fields.id(name) Resolve field name to its ID 0-1 (cached)
Fields.getOption(optionId) Get custom field option by ID 1
Fields.create(data) Create a custom field 1
Fields.getContexts(fieldId, opts?) Get contexts for a field (all pages) 1 per page
Fields.createContext(fieldId, data) Create a context for a field 1
Fields.getOptions(fieldId, contextId, opts?) Get the options of a field context (all pages) 1 per page
Fields.createOptions(fieldId, contextId, data) Add options to a field context 1
Fields.updateOptions(fieldId, contextId, data) Update options of a field context 1

getContexts and getOptions options: { startAt?: number, maxResults?: number } - passing either reads a single page instead of all of them.

Context options. Options belong to a context, not to the field: a select field carries a separate option set in every context, so both ids are required. createOptions appends, updateOptions rewrites the options addressed by id. Both take the Jira body shape { options: [...] } and answer with the stored options ({ options: [{ id, value, disabled }] }) - the returned id is what updateOptions and Fields.getOption(optionId) expect. Field and context ids may be passed as a string or as a number.

Caching. The first Fields.list(), Fields.get(), or Fields.id() call loads the entire field list once (1 API call) and caches it for the rest of the script execution. Subsequent calls to any of these three methods use the cached data and do not consume your API call budget. Use Fields.id('Story Points') or Fields.get('Priority') freely - there is no penalty for calling them multiple times.

const fields = Fields.list()

const priority = Fields.get("Priority")
log(priority.id)

// Resolve custom field name to ID
const fieldId = Fields.id("Story Points")
log(fieldId)  // e.g., "customfield_10016"

// Create a custom field
const created = Fields.create({
  name: 'My Field',
  description: 'A custom text field',
  type: 'com.atlassian.jira.plugin.system.customfieldtypes:textfield'
})
log(created.id)

// Get and create contexts
const contexts = Fields.getContexts('customfield_10100')
for (const ctx of contexts) {
  log(ctx.id, ctx.name, ctx.isGlobalContext)
}

// Paginate: second page of 50
const page2 = Fields.getContexts('customfield_10100', { startAt: 50, maxResults: 50 })

const newCtx = Fields.createContext('customfield_10100', {
  name: 'Project context',
  projectIds: ['10000']
})
log(newCtx.id)

// Fill the context with options
const added = Fields.createOptions('customfield_10100', newCtx.id, {
  options: [{ value: 'Red' }, { value: 'Green' }, { value: 'Blue', disabled: true }]
})
log(added.options.length)   // => 3

// Read the options back
const options = Fields.getOptions('customfield_10100', newCtx.id)
for (const opt of options) {
  log(opt.id, opt.value, opt.disabled)
}

// Rename an option and re-enable it - ids come from getOptions/createOptions
Fields.updateOptions('customfield_10100', newCtx.id, {
  options: [{ id: added.options[2].id, value: 'Navy', disabled: false }]
})

Components

CRUD operations on project components.

Method Description API calls
Components.get(id) Get component by ID 1
Components.create(projectKey, name, fields?) Create a component 1
Components.update(id, fields) Update a component 1
Components.delete(id) Delete a component 1

Project components can also be read with project.getComponents() (see Projects).

const comp = Components.create("PROJ", "Backend", {
  description: "Backend services"
})

Components.update(comp.id, { description: "Updated" })

const fetched = Components.get(comp.id)
log(fetched.name)

Components.delete(comp.id)

Versions

Manage project versions (releases).

Method Description API calls
Versions.get(id) Get version by ID 1
Versions.create(projectId, name, fields?) Create a version 1
Versions.update(id, fields) Update a version 1
Versions.delete(id, opts?) Delete a version; opts: { moveFixIssuesTo?, moveAffectedIssuesTo? } (version IDs) 1
Versions.release(id) Mark version as released (sets releaseDate to today) 1

Project versions can also be read with project.getVersions() (see Projects).

const version = Versions.create("10001", "v2.0", {
  description: "Major release",
  startDate: "2024-01-01",
  releaseDate: "2024-06-01"
})

Versions.update(version.id, { description: "Updated" })

Versions.release(version.id)

Boards

Access Jira Software boards.

Method Description API calls
Boards.get(boardId) Get board by ID 1
Boards.list(opts?) List boards (filter by project/type, all pages) 1 per page
Boards.getSprints(boardId, state?, opts?) Get board sprints (all pages) 1 per page
Boards.getIssues(boardId, opts?) Get board issues as RichIssue array (one page; opts: { jql?, maxResults? }) 1
Boards.moveToBacklog(issueKeys[]) Move issues to the backlog (remove from sprint) 1

Board and sprint IDs must be passed as numbers - a string ID raises an error.

// Find scrum boards for a project (every page)
const boards = Boards.list({ projectKeyOrId: "PROJ", type: "scrum" })
log(boards.length, "boards found")
const board = Boards.get(1)

// Get active sprints
const sprints = Boards.getSprints(1, "active")
for (const s of sprints) {
  log(s.name + ": " + s.state)
}

// Get board issues
const issues = Boards.getIssues(1, { maxResults: 20 })

Sprints

Work with Jira Software sprints.

Method Description API calls
Sprints.get(sprintId) Get sprint by ID 1
Sprints.getIssues(sprintId, opts?) Get sprint issues as RichIssue array (one page; opts: { jql?, maxResults? }) 1
Sprints.moveIssues(sprintId, issueKeys[]) Move issues to a sprint 1
Sprints.create(boardId, name, opts?) Create a sprint; opts: { startDate?, endDate?, goal? } 1
Sprints.update(sprintId, fields) Update sprint fields (name, state, startDate, endDate, goal) 1

RichIssue array

Boards.getIssues(), Sprints.getIssues() and Epics.getIssues() return an array of RichIssue objects with all the same properties and methods as Issues.get() - you can call .update(), .transition(), .addComment(), etc. directly on each issue. See RichIssue.

const sprint = Sprints.get(10)
log(sprint.name)

const issues = Sprints.getIssues(10)
for (const issue of issues) {
  log(issue.key, issue.status, issue.assignee)
  if (issue.isOverdue) {
    issue.addComment('This issue is overdue')
  }
}

// Move issues to sprint
Sprints.moveIssues(10, ["TEST-1", "TEST-2", "TEST-3"])

Manage issue link types and links between issues.

Method Description API calls
Links.types() List issue link types 1
Links.create(typeName, inwardKey, outwardKey) Create an issue link of the named type 1
Links.get(linkId) Get an issue link by ID 1
Links.delete(linkId) Delete an issue link by ID 1

Links.types() returns all issue link types configured in your Jira instance as Array<{ id, name, inward, outward }>:

Field Type Description
id string Link type ID
name string Link type name (e.g., “Blocks”, “Duplicate”)
inward string Inward description (e.g., “is blocked by”)
outward string Outward description (e.g., “blocks”)
const types = Links.types()
for (const t of types) {
  log(`${t.name}: ${t.outward} / ${t.inward}`)
}
// => Blocks: blocks / is blocked by
// => Duplicate: duplicates / is duplicated by
// => Relates: relates to / relates to

// Create a link
Links.create("Blocks", "TEST-1", "TEST-2")

// Get and delete a link
const link = Links.get(12345)
Links.delete(12345)

A typical use of Links.types() is finding the link type ID for a raw requestJira() call:

const types = Links.types()
const blocks = types.find(t => t.name === "Blocks")

requestJira("/rest/api/3/issueLink", {
  method: "POST",
  body: {
    type: { id: blocks.id },
    inwardIssue: { key: "TEST-2" },
    outwardIssue: { key: "TEST-1" },
  },
})

Attachments

The Attachments namespace reads attachment metadata and copies attachments between Jira issues. Copy is binary-safe: it downloads the original bytes from the source issue and re-uploads them to the target using multipart form-data.

Method Description API calls
Attachments.list(issueKey) Read attachment metadata (from the issue’s attachment field). Returns Array<{ id, filename, size, mimeType, created, author }> 1
Attachments.copy(sourceKey, targetKey, opts?) Copy attachments from sourceKey to targetKey. Returns a report 1 (2 with skipExisting) + 2 per file (download + upload)
issue.copyAttachmentsTo(targetKey, opts?) Method form on the RichIssue returned by Issues.get(). Equivalent to Attachments.copy(issue.key, targetKey, opts) same

See also issue.getAttachments() and issue.deleteAttachment() on RichIssue.

Copy options

All opts fields are optional. Passing a value above the hard cap raises a validation error rather than being silently clamped.

Option Default Hard cap Meaning
maxFileSize 5 MB 10 MB Skip files larger than this. Reason too-large
maxFiles 20 50 Stop after this many copies. Extras get reason limit
maxTotalSize 25 MB 50 MB Total-bytes budget for the call. Once exhausted, remaining files get reason limit
skipExisting true - If a file with the same filename already exists on the target, skip it. Reason exists
filenames - 50 entries Whitelist of filenames to copy. Everything else gets reason not-selected

Copy report

{
  copied:  [{ id, filename, size }],       // successfully uploaded to target
  skipped: [{ filename, reason }],         // "too-large" | "limit" | "exists" | "not-selected"
  failed:  [{ filename, error }],          // download or upload rejected by Jira
  bytes:   <number>                        // total bytes copied
}

Per-file failures never abort the copy - they land in failed and processing continues.

Copy errors

copy throws (and aborts the whole call) only when:

  • an argument fails validation (invalid issue key, opts field above hard cap, non-array filenames);
  • the source or target issue cannot be fetched (returns non-OK status);
  • the shared API call budget for the trigger is exhausted;
  • the endpoint is blocked by the whitelist, script whitelist, blacklist, or the read-only trigger set (scripted fields, UIM) - see API Restrictions;
  • Attachments.copy is called in an execution context that does not wire the multipart transport (in that case only Attachments.list works).

Copy cost and limits

Each attachment copy consumes 2 API calls (download + upload) from the same counter shared by requestJira, Jira.*, and every other namespace. Add the initial metadata reads: 1 for the source issue, plus 1 for the target issue when skipExisting is on (the default). Plan trigger budgets accordingly - see the per-trigger limits.

Beyond the per-call opts limits, the platform enforces:

  • Per-file transport ceiling: 10 MB. Even without maxFileSize, a single attachment cannot exceed this.
  • Filename filter list: up to 50 entries per call.
  • The filename in the multipart header is sanitised (CR/LF, ", \, and control bytes stripped). Empty results fall back to attachment-<id>.

For the shared engine limits (execution time, memory, log calls, etc.) see Limits.

Attachment examples

// Copy every attachment, default limits
const report = Attachments.copy("SRC-1", "DST-1")
log(`${report.copied.length} copied, ${report.skipped.length} skipped, ${report.failed.length} failed`)
log(`${report.bytes} bytes total`)

// Copy only specific files, smaller per-file cap
Attachments.copy("SRC-1", "DST-1", {
  filenames: ["diagram.png", "spec.pdf"],
  maxFileSize: 2 * 1024 * 1024,
  skipExisting: true,
})

// Method form on a RichIssue
const src = Issues.get("SRC-1")
const report2 = src.copyAttachmentsTo("DST-1", { maxFiles: 5 })

// Read metadata only
const files = Attachments.list("PROJ-1")
files.forEach(f => log(f.filename, f.size, f.mimeType))

Epics

Work with Jira Software epics.

Method Description API calls
Epics.get(epicIdOrKey) Get epic by ID or key 1
Epics.getIssues(epicIdOrKey, opts?) Get epic issues as RichIssue array (one page; opts: { jql?, maxResults? }) 1
Epics.moveIssues(epicIdOrKey, issueKeys[]) Move issues to the epic 1
Epics.removeIssues(issueKeys[]) Remove issues from their epic 1
const epic = Epics.get(10001)
log(epic.name)

const issues = Epics.getIssues(10001, { maxResults: 50 })

// Move issues to epic
Epics.moveIssues(10001, ["TEST-1", "TEST-2"])

// Remove issues from any epic
Epics.removeIssues(["TEST-3"])

Groups

Manage Jira groups and membership.

Method Description API calls
Groups.find(query?) Find groups by name. With a query - group picker, one request, at most 200 groups; without - walks all groups 1 / 1 per page
Groups.get({ groupId?, groupName? }) Get a group by ID or name 1
Groups.getBulk(opts?) Get groups, all pages (opts: maxResults, startAt, groupId[], groupName[]) 1 per page
Groups.getMembers(groupName, opts?) Get group members, all pages (opts: maxResults, startAt) 1 per page (+1 to resolve the group ID)
Groups.create(name) Create a group 1
Groups.addUser(groupName, accountId) Add user to group 1 (+1 to resolve the group ID)
Groups.removeUser(groupName, accountId) Remove user from group 1 (+1 to resolve the group ID)
const groups = Groups.find("developers")

const members = Groups.getMembers("jira-software-users", { maxResults: 50 })
for (const m of members) {
  log(m.displayName)
}

Groups.create("new-team")
Groups.addUser("new-team", "5b10ac8d82e05b22cc7d4ef5")
Groups.removeUser("new-team", "5b10ac8d82e05b22cc7d4ef5")

Filters

Manage saved Jira filters.

All Filters methods cost 1 API call each.

Method Description
Filters.get(id) Get filter by ID
Filters.getMy() Get current user’s filters
Filters.getFavourites() Get current user’s favourite filters
Filters.create(name, jql, opts?) Create a filter (opts: description, favourite, etc.)
Filters.update(id, fields) Update filter fields
Filters.delete(id) Delete a filter
const myFilters = Filters.getMy()
for (const f of myFilters) {
  log(f.name + ": " + f.jql)
}

const filter = Filters.create("Open Bugs", "type = Bug AND status != Done", {
  description: "All unresolved bugs"
})
log(filter.id)

Filters.update(filter.id, { name: "Active Bugs" })
Filters.delete(filter.id)

Labels

Access Jira labels.

Method Description
Labels.list(opts?) List all labels - 1000 per page, all pages (1 API call per page); opts: startAt, maxResults read a single page
const labels = Labels.list({ maxResults: 100 })
for (const label of labels) {
  log(label)
}

JQL

Validate and autocomplete JQL queries.

Method Description
JQL.validate(jql) Validate JQL syntax and return parse results (1 API call)
JQL.autocomplete() Get JQL autocomplete suggestions (field names, functions) (1 API call)
const result = JQL.validate("project = TEST AND status = Open")
log(result)

const suggestions = JQL.autocomplete()

Permissions

Check the permissions of the acting user.

Method Description
Permissions.my({ permissions?, issueKey?, projectKey? }) Get the acting user’s permissions (1 API call)
// Check specific permissions for a project
const perms = Permissions.my({
  permissions: "BROWSE_PROJECTS,CREATE_ISSUES",
  projectKey: "PROJ"
})

// Check permissions for a specific issue
const issuePerms = Permissions.my({
  permissions: "EDIT_ISSUES",
  issueKey: "PROJ-123"
})

Configuration and JSM namespaces

Configuration namespaces (Workflows, Screens, IssueTypes, Statuses, schemes, Roles, Dashboards, …) and Assets are described in Configuration & Assets; the JSM namespace (service desks, customer requests, SLA, approvals) in Service Management.


Next steps


JiBrok Studio for Jira Cloud JiBrok Studio for Jira Cloud
Release notes
Core Features
Triggers
Extensions
Data Storage
Scripting Overview
JavaScript Engine
Python Engine
Groovy Engine
Scripting API
Administration
Guides