Jira Service Management (version v1.*.*)

add_customers#

Adds one or more customers to a service desk. If any of the passed customers are associated with the service desk, no changes will be made for those customers and the resource returns a 204 success code.

Permissions required: Service desk administrator

{
  "accountIds" : [ "string" ],
  "usernames" : [ "string" ]
}

add_organization#

This method adds an organization to a service desk. If the organization ID is already associated with the service desk, no change is made and the resource returns a 204 success code.

Permissions required: Service desk's agent.

{
  "organizationId" : "List of organizations, specified by 'ID' field values, to add to or remove from the service desk."
}

add_request_participants#

This method adds participants to a customer request.

Permissions required: Permission to manage participants on the customer request.

Note, participants can be added when creating a customer request using the request resource, by defining the participants in the requestParticipants field.

{
  "accountIds" : [ "string" ],
  "usernames" : [ "string" ]
}

add_users_to_organization#

This method adds users to an organization.

Permissions required: Service desk administrator or agent. Note: Permission to add users to an organization can be switched to users with the Jira administrator permission, using the Organization management feature.

{
  "accountIds" : [ "string" ],
  "usernames" : [ "string" ]
}

answer_approval#

This method enables a user to Approve or Decline an approval on a customer request. The approval is assumed to be owned by the user making the call.

Permissions required: User is assigned to the approval request.

{
  "decision" : "Response to the approval request."
}

create_attachment#

This method adds one or more temporary files (attached to the request's service desk using servicedesk/{serviceDeskId}/attachTemporaryFile) as attachments to a customer request and set the attachment visibility using the public flag. Also, it is possible to include a comment with the attachments.

To get a list of attachments for a comment on the request use servicedeskapi/request/{issueIdOrKey}/comment/{commentId}/attachment.

Permissions required: Permission to add an attachment.

Request limitations: Customers can set attachments to public visibility only.

{
  "temporaryAttachmentIds" : [ "string" ],
  "public" : "Indicates whether the attachments are to be public (true) or private/internal (false).",
  "additionalComment" : {
    "body" : "Content of the comment."
  }
}

create_customer#

This method adds a customer to the Jira Service Management instance by passing a JSON file including an email address and display name. The display name does not need to be unique. The record's identifiers, name and key, are automatically generated from the request details.

Permissions required: Jira Administrator Global permission

{
  "displayName" : "Customer's name for display in the UI.",
  "fullName" : "Deprecated, please use 'displayName'.",
  "email" : "Customer's email address."
}

create_customer_request#

This method creates a customer request in a service desk.

The JSON request must include the service desk and customer request type, as well as any fields that are required for the request type. A list of the fields required by a customer request type can be obtained using servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field.

The fields required for a customer request type depend on the user's permissions:

• raiseOnBehalfOf is not available to Users who have the customer permission only.
• requestParticipants is not available to Users who have the customer permission only or if the feature is turned off for customers.

requestFieldValues is a map of Jira field IDs and their values. See Field input formats, for details of each field's JSON semantics and the values they can take.

Permissions required: Permission to create requests in the specified service desk.

{
  "requestParticipants" : [ "string" ],
  "raiseOnBehalfOf" : "The `accountId` of the customer that the request is being raised on behalf of.",
  "serviceDeskId" : "ID of the service desk in which to create the request.",
  "requestTypeId" : "ID of the request type for the request.",
  "channel" : "(Experimental) Shows extra information for the request channel.",
  "requestFieldValues" : { }
}

create_organization#

This method creates an organization by passing the name of the organization.

Permissions required: Service desk administrator or agent. Note: Permission to create organizations can be switched to users with the Jira administrator permission, using the Organization management feature.

{
  "name" : "Name of the organization."
}

create_request_comment#

This method creates a public or private (internal) comment on a customer request, with the comment visibility set by public. The user recorded as the author of the comment.

Permissions required: User has Add Comments permission.

Request limitations: Customers can set comments to public visibility only.

{
  "public" : "Indicates whether the comment is public (true) or private/internal (false).",
  "body" : "Content of the comment."
}

create_request_type#

This method enables a customer request type to be added to a service desk based on an issue type. Note that not all customer request type fields can be specified in the request and these fields are given the following default values:

• Request type icon is given the headset icon.
• Request type groups is left empty, which means this customer request type will not be visible on the customer portal.
• Request type status mapping is left empty, so the request type has no custom status mapping but inherits the status map from the issue type upon which it is based.
• Request type field mapping is set to show the required fields as specified by the issue type used to create the customer request type.

These fields can be updated by a service desk administrator using the Request types option in Project settings.
Request Types are created in next-gen projects by creating Issue Types. Please use the Jira Cloud Platform Create issue type endpoint instead.

Permissions required: Service desk's administrator

{
  "issueTypeId" : "ID of the request type to add to the service desk.",
  "helpText" : "Help text for the request type on the service desk.",
  "name" : "Name of the request type on the service desk.",
  "description" : "Description of the request type on the service desk."
}

delete_feedback#

This method deletes the feedback of request using it's requestKey or requestId

Permissions required: User must be the reporter or an Atlassian Connect app.

delete_organization#

This method deletes an organization. Note that the organization is deleted regardless of other associations it may have. For example, associations with service desks.

Permissions required: Jira administrator.

delete_organization_property#

Removes a property from an organization.

Permissions required: Service Desk Administrator or Agent.

Note: Permission to manage organizations can be switched to users with the Jira administrator permission, using the Organization management feature.

delete_request_type#

This method deletes a customer request type from a service desk, and removes it from all customer requests.
This only supports classic projects.

Permissions required: Service desk administrator.

delete_request_type_property#

Removes a property from a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore can also be deleted by calling the Jira Cloud Platform Delete issue type property endpoint.

Permissions required: Jira project administrator with a Jira Service Management agent license.

get_approval#

This method returns an approval. Use this method to determine the status of an approval and the list of approvers.

Permissions required: Permission to view the customer request.

get_articles_for_service_desk#

Returns articles which match the given query and belong to the knowledge base linked to the service desk.

Permissions required: Permission to access the service desk.

get_attachments_for_request#

This method returns all the attachments for a customer requests.

Permissions required: Permission to view the customer request.

Response limitations: Customers will only get a list of public attachments.

get_cloud_id#

This operation has no parameters

get_comment_attachments#

This method returns the attachments referenced in a comment.

Permissions required: Permission to view the customer request.

Response limitations: Customers can only view public comments, and retrieve their attachments, on requests where they are the reporter or a participant whereas agents can see both internal and public comments.

get_customer_request#

This method returns a customer request.

Permissions required: Permission to access the specified service desk.

Response limitations: For customers, only a request they created, was created on their behalf, or they are participating in will be returned.

[ "string" ]

get_customer_request_status#

This method returns a list of all the statuses a customer Request has achieved. A status represents the state of an issue in its workflow. An issue can have one active status only. The list returns the status history in chronological order, most recent (current) status first.

Permissions required: Permission to view the customer request.

get_customer_transitions#

This method returns a list of transitions, the workflow processes that moves a customer request from one status to another, that the user can perform on a request. Use this method to provide a user with a list if the actions they can take on a customer request.

Permissions required: Permission to view the customer request.

get_feedback#

This method retrieves a feedback of a request using it's requestKey or requestId

Permissions required: User has view request permissions.

get_info#

This method retrieves information about the Jira Service Management instance such as software version, builds, and related links.

Permissions required: None, the user does not need to be logged in.

get_issues_in_queue#

This method returns the customer requests in a queue. Only fields that the queue is configured to show are returned. For example, if a queue is configured to show description and due date, then only those two fields are returned for each customer request in the queue.

Permissions required: Service desk's agent.

get_organization#

This method returns details of an organization. Use this method to get organization details whenever your application component is passed an organization ID but needs to display other organization details.

Permissions required: Any

Response limitations: Customers can only retrieve organization of which they are members.

get_organization_properties_keys#

Returns the keys of all properties for an organization. Use this resource when you need to find out what additional properties items have been added to an organization.

Permissions required: Any

Response limitations: Customers can only access properties of organizations of which they are members.

get_organization_property#

Returns the value of a property from an organization. Use this method to obtain the JSON content for an organization's property.

Permissions required: Any

Response limitations: Customers can only access properties of organizations of which they are members.

get_organizations_for_service_desk#

This method returns a list of all organizations associated with a service desk.

Permissions required: Service desk's agent.

get_queue#

This method returns a specific queues in a service desk. To include a customer request count for the queue (in the issueCount field) in the response, set the query parameter includeCount to true (its default is false).

Permissions required: service desk's Agent.

get_request_comment#

This method returns details of a customer request's comment.

Permissions required: Permission to view the customer request.

Response limitations: Customers can only view public comments on requests where they are the reporter or a participant whereas agents can see both internal and public comments.

[ "string" ]

get_request_type#

This method returns a customer request type from a service desk.

Permissions required: Permission to access the service desk.

[ "string" ]

get_request_type_fields#

This method returns the fields for a service desk's customer request type.

Also, the following information about the user's permissions for the request type is returned:

• canRaiseOnBehalfOf returns true if the user has permission to raise customer requests on behalf of other customers. Otherwise, returns false.
• canAddRequestParticipants returns true if the user can add customer request participants. Otherwise, returns false.

Permissions required: Permission to view the Service Desk. However, hidden fields would be visible to only Service desk's Administrator.

[ "string" ]

get_request_type_groups#

This method returns a service desk's customer request type groups. Jira Service Management administrators can arrange the customer request type groups in an arbitrary order for display on the customer portal; the groups are returned in this order.

Permissions required: Permission to view the service desk.

get_request_type_properties_keys#

Returns the keys of all properties for a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore the keys of all properties for a request type are also available by calling the Jira Cloud Platform Get issue type property keys endpoint.

Permissions required: The user must have permission to view the request type.

get_request_type_property#

Returns the value of the property from a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore also available by calling the Jira Cloud Platform Get issue type property endpoint.

Permissions required: User must have permission to view the request type.

get_service_desk#

This method returns a service desk. Use this method to get service desk details whenever your application component is passed a service desk ID but needs to display other service desk details.

Permissions required: Permission to access the Service Desk. For example, being the Service Desk's Administrator or one of its Agents or Users.

get_sla_information#

This method returns the details for an SLA on a customer request.

Permissions required: Agent for the Service Desk containing the queried customer request.

get_subscription_status#

This method returns the notification subscription status of the user making the request. Use this method to determine if the user is subscribed to a customer request's notifications.

Permissions required: Permission to view the customer request.

get_users_in_organization#

This method returns all the users associated with an organization. Use this method where you want to provide a list of users for an organization or determine if a user is associated with an organization.

Permissions required: Service desk administrator or agent.

list_all_request_types#

This method returns all customer request types used in the Jira Service Management instance, optionally filtered by a query string.

Use servicedeskapi/servicedesk/{serviceDeskId}/requesttype to find the customer request types supported by a specific service desk.

The returned list of customer request types can be filtered using the query parameter. The parameter is matched against the customer request types' name or description. For example, searching for "Install", "Inst", "Equi", or "Equipment" will match a customer request type with the name "Equipment Installation Request".

Permissions required: Any

[ "string" ]

[ "integer" ]

list_approvals#

This method returns all approvals on a customer request.

Permissions required: Permission to view the customer request.

list_articles#

Returns articles which match the given query string across all service desks.

Permissions required: Permission to access the customer portal.

list_customer_requests#

This method returns all customer requests for the user executing the query.

The returned customer requests are ordered chronologically by the latest activity on each request. For example, the latest status transition or comment.

Permissions required: Permission to access the specified service desk.

Response limitations: For customers, the list returned will include request they created (or were created on their behalf) or are participating in only.

[ "string" ]

[ "string" ]

list_customers#

This method returns a list of the customers on a service desk.

The returned list of customers can be filtered using the query parameter. The parameter is matched against customers' displayName, name, or email. For example, searching for "John", "Jo", "Smi", or "Smith" will match a user with display name "John Smith".

Permissions required: Permission to view this Service Desk's customers.

list_organizations#

This method returns a list of organizations in the Jira Service Management instance. Use this method when you want to present a list of organizations or want to locate an organization by name.

Permissions required: Any. However, to fetch organizations based on accountId the user must have a Service Desk agent license.

Response limitations: If the user is a customer, only those organizations of which the customer is a member are listed.

list_queues#

This method returns the queues in a service desk. To include a customer request count for each queue (in the issueCount field) in the response, set the query parameter includeCount to true (its default is false).

Permissions required: service desk's Agent.

list_request_comments#

This method returns all comments on a customer request. No permissions error is provided if, for example, the user doesn't have access to the service desk or request, the method simply returns an empty response.

Permissions required: Permission to view the customer request.

Response limitations: Customers are returned public comments only.

[ "string" ]

list_request_participants#

This method returns a list of all the participants on a customer request.

Permissions required: Permission to view the customer request.

list_request_types#

This method returns all customer request types from a service desk. There are two parameters for filtering the returned list:

• groupId which filters the results to items in the customer request type group.
• searchQuery which is matched against request types' name or description. For example, the strings "Install", "Inst", "Equi", or "Equipment" will match a request type with the name "Equipment Installation Request".

Permissions required: Permission to access the service desk.

[ "string" ]

list_service_desks#

This method returns all the service desks in the Jira Service Management instance that the user has permission to access. Use this method where you need a list of service desks or need to locate a service desk by name or keyword.

Permissions required: Any

list_sla_information#

This method returns all the SLA records on a customer request. A customer request can have zero or more SLAs. Each SLA can have recordings for zero or more "completed cycles" and zero or 1 "ongoing cycle". Each cycle includes information on when it started and stopped, and whether it breached the SLA goal.

Permissions required: Agent for the Service Desk containing the queried customer request.

perform_customer_transition#

This method performs a customer transition for a given request and transition. An optional comment can be included to provide a reason for the transition.

Permissions required: The user must be able to view the request and have the Transition Issues permission. If a comment is passed the user must have the Add Comments permission.

{
  "id" : "ID of the transition to be performed.",
  "additionalComment" : {
    "body" : "Content of the comment."
  }
}

post_feedback#

This method adds a feedback on an request using it's requestKey or requestId

Permissions required: User must be the reporter or an Atlassian Connect app.

{
  "rating" : "A numeric representation of the rating, this must be an integer value between 1 and 5.",
  "comment" : {
    "body" : "Content of the comment."
  },
  "type" : "Indicates the type of feedback, supported values: `csat`."
}

remove_customers#

This method removes one or more customers from a service desk. The service desk must have closed access. If any of the passed customers are not associated with the service desk, no changes will be made for those customers and the resource returns a 204 success code.

Permissions required: Services desk administrator

{
  "accountIds" : [ "string" ],
  "usernames" : [ "string" ]
}

remove_organization#

This method removes an organization from a service desk. If the organization ID does not match an organization associated with the service desk, no change is made and the resource returns a 204 success code.

Permissions required: Service desk's agent.

{
  "organizationId" : "List of organizations, specified by 'ID' field values, to add to or remove from the service desk."
}

remove_request_participants#

This method removes participants from a customer request.

Permissions required: Permission to manage participants on the customer request.

{
  "accountIds" : [ "string" ],
  "usernames" : [ "string" ]
}

remove_users_from_organization#

This method removes users from an organization.

Permissions required: Service desk administrator or agent. Note: Permission to delete users from an organization can be switched to users with the Jira administrator permission, using the Organization management feature.

{
  "accountIds" : [ "string" ],
  "usernames" : [ "string" ]
}

set_organization_property#

Sets the value of a property for an organization. Use this resource to store custom data against an organization.

Permissions required: Service Desk Administrator or Agent.

Note: Permission to manage organizations can be switched to users with the Jira administrator permission, using the Organization management feature.

set_request_type_property#

Sets the value of a request type property. Use this resource to store custom data against a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore can also be set by calling the Jira Cloud Platform Set issue type property endpoint.

Permissions required: Jira project administrator with a Jira Service Management agent license.

subscribe#

This method subscribes the user to receiving notifications from a customer request.

Permissions required: Permission to view the customer request.

unsubscribe#

This method unsubscribes the user from notifications from a customer request.

Permissions required: Permission to view the customer request.