Part of the Scripting API reference. Issues | Jira Entities | Service Management | Configuration & Assets
The JSM namespace wraps the Jira Service Management REST API (/rest/servicedeskapi): service desks,
queues, request types, customer requests, comments, SLA, participants, approvals, organizations and
customers.
JSM is injected as a top-level variable in all three engines (JS, Python, Groovy) - use
JSM.getRequest("SD-1"), not .Jira.JSM.getRequest("SD-1")
Every *Id argument accepts a string or a number. Methods that read a collection return the API
values array directly (an empty array when the response carries none); methods that read a single
entity return the raw JSON object.
Methods
Service desks, queues and request types
| Method | Description | API calls |
|---|---|---|
JSM.getServiceDesks(opts?) |
List service desks | 1 |
JSM.getServiceDesk(id) |
Get a service desk by ID | 1 |
JSM.getRequestTypes(serviceDeskId, opts?) |
List request types of a service desk | 1 |
JSM.getQueues(serviceDeskId, opts?) |
List queues of a service desk | 1 |
JSM.getQueueIssues(serviceDeskId, queueId, opts?) |
List the issues currently in a queue | 1 |
JSM.getCustomers(serviceDeskId, query?) |
Search customers of a service desk | 1 |
Customer requests
| Method | Description | API calls |
|---|---|---|
JSM.createRequest(serviceDeskId, requestTypeId, fields, opts?) |
Create a customer request | 1 |
JSM.getRequest(key, opts?) |
Get one request | 1 |
JSM.getRequests(opts?) |
Search requests | 1 |
JSM.getRequestStatus(key, opts?) |
Status transition history | 1 |
JSM.transitionRequest(key, transitionId, comment?) |
Run a customer transition, returns true |
1 |
Comments
| Method | Description | API calls |
|---|---|---|
JSM.getComments(key, opts?) |
List request comments | 1 |
JSM.addComment(key, body, opts?) |
Add a public or internal comment | 1 |
SLA
| Method | Description | API calls |
|---|---|---|
JSM.getSla(key, opts?) |
List SLA cycles of a request | 1 |
JSM.getSlaById(key, slaId) |
Get one SLA metric | 1 |
Participants and approvals
| Method | Description | API calls |
|---|---|---|
JSM.getParticipants(key, opts?) |
List request participants | 1 |
JSM.addParticipants(key, accountIds) |
Add participants, returns the updated list | 1 |
JSM.removeParticipants(key, accountIds) |
Remove participants, returns the updated list | 1 |
JSM.getApprovals(key, opts?) |
List approvals of a request | 1 |
JSM.answerApproval(key, approvalId, decision) |
Answer an approval ("approve" / "decline") |
1 |
Organizations
| Method | Description | API calls |
|---|---|---|
JSM.getOrganizations(opts?) |
List organizations on the site | 1 |
JSM.getOrganization(id) |
Get an organization by ID | 1 |
JSM.getRequestOrganizations(key, opts?) |
List organizations attached to a request | 1 |
Options
All list methods that take opts accept paging there (getCustomers takes only a query string). Each call reads one page - pass start/limit to read further:
| Option | Type | Description |
|---|---|---|
start |
number | Paging offset |
limit |
number | Page size |
Unlike the Jira list methods (see List methods and pagination), JSM methods do not walk all pages for you.
Method-specific options:
| Method | Option | Type | Description |
|---|---|---|---|
getRequestTypes |
searchQuery |
string | Filter request types by name |
getRequestTypes |
groupId |
string | Filter by request type group |
getQueues |
includeCount |
boolean | Include the issue count of every queue |
getRequest |
expand |
string[] | "participant", "status", "sla", "requestType", "serviceDesk" |
getRequests |
serviceDeskId |
string|number | Limit to one service desk |
getRequests |
requestTypeId |
string|number | Limit to one request type |
getRequests |
requestOwnership |
string | OWNED_REQUESTS, PARTICIPATED_REQUESTS, ORGANIZATION, ALL_REQUESTS |
getRequests |
requestStatus |
string | OPEN_REQUESTS, CLOSED_REQUESTS, ALL_REQUESTS |
getRequests |
approvalStatus |
string | MY_PENDING_APPROVAL, MY_HISTORY_APPROVAL |
getRequests |
searchTerm |
string | Free-text search |
getRequests |
expand |
string[] | Extra fields to expand |
getComments |
public |
boolean | Include customer-visible comments |
getComments |
internal |
boolean | Include internal comments |
getComments |
expand |
string[] | "attachment", "renderedBody" |
addComment |
public |
boolean | true (default) = the customer sees the comment, false = agents only |
createRequest |
raiseOnBehalfOf |
string | Customer accountId the request is raised for |
createRequest |
requestParticipants |
string[] | Participant accountIds |
createRequest |
channel |
string | Request channel |
getOrganizations |
accountId |
string | Only organizations the user belongs to |
Examples
Work through a queue
const desks = await JSM.getServiceDesks()
const sd = desks[0]
const queues = await JSM.getQueues(sd.id, { includeCount: true })
for (const q of queues) {
log(`${q.name}: ${q.issueCount}`)
}
const issues = await JSM.getQueueIssues(sd.id, queues[0].id, { limit: 50 })
for (const i of issues) {
log(i.key, i.fields.summary)
}
Create a request on behalf of a customer
const types = await JSM.getRequestTypes(sd.id, { searchQuery: 'access' })
const created = await JSM.createRequest(sd.id, types[0].id, {
summary: 'VPN access',
description: 'Needed for the new laptop',
}, {
raiseOnBehalfOf: '5b10a2844c20165700ede21g',
requestParticipants: ['5b10ac8d82e05b22cc7d4ef5'],
})
log(created.issueKey)
Reply to the customer, or leave an internal note
// public = the customer sees it in the portal and by email
await JSM.addComment('SD-1', 'We are on it, ETA today')
// internal = visible to agents only
await JSM.addComment('SD-1', 'Waiting for the vendor to confirm', { public: false })
// read back only the internal notes
const notes = await JSM.getComments('SD-1', { public: false, internal: true })
JSM comments are plain text, not ADF - pass a string as body.
Check SLA
for (const sla of await JSM.getSla('SD-1')) {
const cycle = sla.ongoingCycle
log(sla.name, cycle ? `breached=${cycle.breached}` : 'no ongoing cycle')
}
Participants, approvals and organizations
await JSM.addParticipants('SD-1', ['5b10a2844c20165700ede21g'])
await JSM.removeParticipants('SD-1', ['5b10ac8d82e05b22cc7d4ef5'])
log((await JSM.getParticipants('SD-1')).length)
for (const a of await JSM.getApprovals('SD-1')) {
if (a.finalDecision === 'pending') {
await JSM.answerApproval('SD-1', a.id, 'approve')
}
}
const orgs = await JSM.getRequestOrganizations('SD-1')
const customers = await JSM.getCustomers(sd.id, 'acme.com')
Transition a request
// Customer transitions, not Jira workflow transition IDs - read the available
// ones from the request status screen or the portal.
await JSM.transitionRequest('SD-1', 21, 'Resolved by script')
Permissions and limits
- Scopes:
read:servicedesk-request,write:servicedesk-request,manage:servicedesk-customer. - Whitelist: the default admin whitelist allows
GETon all of/rest/servicedeskapi/**, plusPOST/PUTon customer requests andDELETEon/rest/servicedeskapi/request/*/participant. The default user whitelist is read-only (GETonly). A call outside the effective whitelist raises aScriptSecurityErrorbefore any request is sent - see API Restrictions and Security. - App actor:
removeParticipantsusesDELETE, which is blocked for scripts running as the app. Run the script as the current user for that method. - API budget: every method costs one call from the shared per-execution API budget (the same
counter as
requestJiraand the other namespaces) - see the per-trigger limits. - Errors: a non-2xx response throws
JSM.<method> failed: <status> - <detail>. Invalid arguments throw before the request, e.g.JSM.getRequest: key: must be a non-empty string.
Some JSM endpoints (queues, customers) are marked experimental by Atlassian and can require the “Service Desk agent” role on the project for the acting user.
Next steps
- Scripting API: Configuration & Assets - Jira configuration namespaces and JSM Assets (CMDB)
- Scripting API: Jira Entities - Core Jira operations
- Scripting API: requestJira - Low-level REST API for unlisted endpoints
