JSM service desk

Jira Service Management (JSM) is Jira's help-desk layer, built on top of ordinary Jira issues. Customers submit requests through a portal (the customer-facing view) into a service desk (the underlying project); agents then work those requests using queues, SLAs (service level agreements — time-bound targets like "respond within 4 hours"), and optional approvals. This page covers the agent's JSM tools: requests, comments and participants, approvals and SLAs, portals and service desks, request types, organizations, and queues.

Example prompts

• "What service desks do I have access to?"
• "File an IT support request: my laptop won't boot, black screen on power-on."
• "What's the status of ITS-42?"
• "What request types are available on the IT Help desk?"
• "Add an internal note to ITS-42 saying we're waiting on a replacement part."
• "Add a public comment to ITS-42 telling the customer their part shipped."
• "What SLA does ITS-42 have, and is it at risk of breaching?"
• "Add jane.doe as a participant on ITS-42."
• "Approve the pending change request on ITS-55."
• "List my open requests."
• "What organizations are linked to the IT Help desk?"
• "Show me the queues on the IT Help desk and what's in the 'Unassigned' queue."
• "Create a new organization called Acme Corp and add three users to it."
• "What fields are required to raise a 'New laptop' request?"
• "Move ITS-42 to the next customer-facing status."

What's available

Requests

Tool	What it does
jsm_create_request	Create a new JSM customer request.
jsm_get_request	Get a JSM customer request by issue ID or key.
jsm_list_my_requests	List customer requests visible to the acting user.
jsm_get_request_status	Get the customer-facing status history of a request.
jsm_get_request_transitions	List customer-facing workflow transitions available on a request.
jsm_perform_customer_transition	Perform a customer-facing workflow transition on a request.

Comments & participants

Tool	What it does
jsm_add_comment	Add a comment to a request; public by default, set internal explicitly.
jsm_get_request_comment	Get a single comment on a request by comment ID.
jsm_get_request_comments	List comments on a request.
jsm_get_request_participants	List participants on a request.
jsm_add_request_participants	Add participants (by username) to a request. Requires confirmation.
jsm_remove_request_participants [ADMIN]	Remove participants (by username) from a request. Requires confirmation.
jsm_attach_temporary_file	Upload one or more files as temporary attachments on a service desk.
jsm_add_request_attachment	Attach previously-uploaded temporary files to a request, with an optional comment.

Approvals & SLAs

Tool	What it does
jsm_get_request_approvals	List approvals on a request (e.g. change/service request approvals).
jsm_get_request_approval	Get a single approval on a request by ID.
jsm_get_request_approval_config	Get the comment-requirement configuration for an approval.
jsm_answer_approval	Answer a pending approval on a request (approve or decline).
jsm_get_request_sla	List SLA metrics tracked on a request (e.g. time to resolution).
jsm_get_request_sla_by_id	Get a single SLA metric's detail (breach/pause state, completed cycles).

Portals & service desks

Tool	What it does
jsm_get_info	Get runtime info about the JSM instance (version, build date, license status).
jsm_list_service_desks	List service desk projects visible to the acting user.
jsm_get_service_desk	Get a single service desk (service project) by ID.
jsm_list_portals	List customer portals — the customer-facing view of a service desk.
jsm_get_portal	Get a single customer portal by ID.
jsm_get_portal_by_project_key	Get a single customer portal by its underlying project key.
jsm_create_customer [ADMIN]	Create a JSM customer account not yet associated with any service project — the new account can sign in to the customer portal. Requires confirmation.
jsm_add_service_desk_customers	Add existing customers (by username/email) to a service desk. Requires confirmation.

Request types

Tool	What it does
jsm_list_request_types	List request types available on a service desk.
jsm_get_request_type	Get a single request type by ID.
jsm_get_request_type_fields	Get the field definitions for a request type — which are required, and what values the dropdown-style ones accept.
jsm_create_request_type	Create a request type on a service desk from an existing issue type.
jsm_update_request_type	Update a request type's name, description, or help text.
jsm_delete_request_type	Delete a request type from a service desk. Requires confirmation.
jsm_get_request_type_groups	Get the request type groups configured on a service desk.
jsm_get_request_type_permissions [ADMIN]	Get the permission rules for who can raise a request type.
jsm_upsert_request_type_permissions [ADMIN]	Fully overwrite the customer permissions for a request type. Requires confirmation.

Organizations

Tool	What it does
jsm_list_organizations	List JSM organizations (customer groupings) visible to the acting user.
jsm_get_organization	Get a single JSM organization by ID.
jsm_create_organization	Create a new JSM organization.
jsm_delete_organization [ADMIN]	Delete a JSM organization. Requires confirmation.
jsm_get_organization_users	List users belonging to a JSM organization.
jsm_add_organization_users	Add users (by username) to a JSM organization. Requires confirmation.
jsm_remove_organization_users [ADMIN]	Remove users (by username) from a JSM organization. Requires confirmation.
jsm_get_service_desk_organizations	List organizations linked to a service desk.
jsm_add_service_desk_organization	Link an organization to a service desk. Requires confirmation.
jsm_remove_service_desk_organization [ADMIN]	Unlink an organization from a service desk. Requires confirmation.
jsm_get_organization_cleanup_preview	Preview which organizations a cleanup would remove, without deleting anything.
jsm_cleanup_organizations	Bulk-delete every organization the instance considers inactive. Requires confirmation.

Queues

Tool	What it does
jsm_list_queues	List queues on a service desk (agent-facing groupings of requests).
jsm_get_queue	Get a single queue by ID, including its JQL definition.
jsm_get_queue_issues	Get the issues currently in a queue.
jsm_create_queue	Create a new queue on a service desk from a name and a JQL definition.
jsm_update_queue	Update a queue's name, JQL, or displayed fields.
jsm_delete_queue	Delete a queue from a service desk. Requires confirmation.
jsm_reorder_queues	Reorder a service desk's queues in the desired display order.
jsm_get_queue_settings [ADMIN]	Get queue-count display settings for a project's service desk.
jsm_set_project_queue_include_count	Set whether a project's service desk queues include an issue count.
jsm_set_project_queue_cache_count	Set whether a project's service desk queues use a cached issue count.
jsm_set_queue_include_count_global [ADMIN]	Set instance-wide whether JSM queues include an issue count at all.
jsm_set_queue_cache_count_global [ADMIN]	Set instance-wide whether JSM queues use a cached issue count.

Things to know

• Comments are public by default. jsm_add_comment posts a comment the customer can see unless you explicitly ask for an "internal" or "agent-only" note. This is easy to get wrong — always be specific when you want a note kept off the customer's view.
• A "request" is JSM's own object type (CustomerRequestDTO) — it has a status and a reporter like a regular issue, but its fields come back as a list of {fieldId, value} pairs rather than fixed properties, which the agent normalizes for you before showing it.
• Creating a request needs a serviceDeskId and requestTypeId. If you don't know them, ask the agent to list service desks and request types first — jsm_list_service_desks and jsm_list_request_types will do that.
• jsm_create_request checks the request type's fields before creating anything. It looks the request type's field definitions up first and refuses the call — without reaching JSM — when a required field isn't among what you supplied, naming the field and listing its allowed values so it can be filled in. This is a change in behaviour: a request like that previously went through to JSM and came back as an error from there. To skip the check (and its one extra lookup) and send the request straight to JSM as before, ask the agent to pass skipFieldValidation: true. If the check's own lookup fails, the error says so explicitly and points at that same option.
• 10 of the 61 tools on this page need JIRA_ADMIN_TOKEN, each marked [ADMIN] in the tables above; without it they are not advertised to the agent at all. They are jsm_create_customer, jsm_remove_request_participants, jsm_get_request_type_permissions, jsm_upsert_request_type_permissions, jsm_delete_organization, jsm_remove_organization_users, jsm_remove_service_desk_organization, jsm_get_queue_settings, jsm_set_queue_include_count_global and jsm_set_queue_cache_count_global. jsm_get_request_type_groups used to be listed here and is not admin-gated any more. Note also that jsm_upsert_request_type_permissions needs the instance admin token, not service-desk-admin rights: the identity administering the very desk under test is still refused.
• 12 tools require explicit confirmation. Removing or deleting (7): jsm_delete_request_type, jsm_delete_queue, jsm_delete_organization, jsm_cleanup_organizations, jsm_remove_request_participants, jsm_remove_organization_users and jsm_remove_service_desk_organization. Granting visibility or access (5) — new, and gated because adding someone deserves the same confirmation removing them already had: jsm_add_request_participants (the participant can then see the request and its comments), jsm_add_service_desk_customers, jsm_add_organization_users, jsm_add_service_desk_organization (every member of the organization gains visibility into the desk's requests) and jsm_upsert_request_type_permissions (rewrites who may raise a request type). The agent will check with you first.

See docs/api-catalog.md for the complete technical reference (every field, every parameter). For errors, see Troubleshooting.