- Users
- Projects
- Fields
- Components
- Versions
- Boards
- Sprints
- Links
- Attachments
- Epics
- Groups
- Filters
- Labels
- JQL
- Permissions
- Configuration and JSM namespaces
- Next steps
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. PassingstartAtormaxResultsreads 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(), orFields.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. UseFields.id('Story Points')orFields.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"])
Links
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,
optsfield above hard cap, non-arrayfilenames); - 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.copyis called in an execution context that does not wire the multipart transport (in that case onlyAttachments.listworks).
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 toattachment-<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
- Scripting API: Issues - Search, create, update, and transition issues
- Scripting API: Service Management -
JSMnamespace: service desks, requests, SLA, approvals - Scripting API: Configuration & Assets - Workflows, screens, schemes,
Statuses, roles, JSM Assets - Scripting API: Utilities - Adf, DateUtils, Arrays, Strings, CSV
- Use Cases - Practical scripting examples
