Scripting API: Service Management

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 GET on all of /rest/servicedeskapi/**, plus POST/PUT on customer requests and DELETE on /rest/servicedeskapi/request/*/participant. The default user whitelist is read-only (GET only). A call outside the effective whitelist raises a ScriptSecurityError before any request is sent - see API Restrictions and Security.
  • App actor: removeParticipants uses DELETE, 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 requestJira and 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


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