[21858] feat(jira_service_desk): add find-service-desk-customers & find-users actions #21883
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| import app from "../../jira_service_desk.app.mjs"; | ||
|
|
||
| export default { | ||
| key: "jira_service_desk-find-service-desk-customers", | ||
| name: "Find Service Desk Customers", | ||
| description: | ||
| "Finds the customers of one service desk by name or email address and returns the `accountId` of each match." | ||
| + " **Pick this tool when the person is the one the ticket is being raised for on a service desk you can identify**, i.e. to fill `raiseOnBehalfOf` on **Create Request**." | ||
| + " Natural-language cues: \"raise a ticket for Jean on the IT desk\", \"open a request on behalf of john@acme.com\", \"file this for my colleague Dana\", \"submit a hardware request for the new starter\"." | ||
| + " Pick **Find Users** instead when the person does not have to be a customer of this desk, such as an approver, manager, or agent you are adding to `requestParticipants`, or when you cannot tell which service desk applies." | ||
| + " Prefer this tool wherever both would work: it searches only this desk's customer list, so a match proves the person can actually raise a request here, and bot accounts are excluded (a site-wide search on a live site returned 17 users of which 16 were integrations)." | ||
| + " Use **List Sites** for `cloudId` and **List Service Desks** for `serviceDeskId` first." | ||
| + " Worked example: for \"open a laptop request for Joseph Wilson on the IT desk\", call this with Service Desk ID `1` and Query `Joseph Wilson`, read `accountId` `5b10a2844c20165700ede21g` off the single match, then call **Create Request** with Service Desk ID `1` and that `accountId` as `raiseOnBehalfOf`." | ||
| + " Omit Query to list every customer of the desk, which answers \"who can raise requests on this desk?\"." | ||
| + " Query is matched against `displayName` and `emailAddress`, and matches more than just the start of them. Pass a full name or a full email address to keep the result set tight." | ||
| + " If nobody matches, the person may exist on the site without being a customer of this desk, retry with **Find Users**." | ||
| + " Results are paginated automatically up to `maxResults`." | ||
| + " Returns `{ users, truncated }`, where `truncated` is `true` when more matches remained unfetched." | ||
| + " `accountId` is the only field guaranteed present: Atlassian's profile visibility rules hide `emailAddress` on users who have not made it public, so match on `displayName` and never require an email to be returned." | ||
| + " An unknown or inaccessible Service Desk ID fails with a 404 rather than returning an empty list, so an empty list really does mean nobody matched." | ||
| + " [See the documentation](https://developer.atlassian.com/cloud/jira/service-desk/rest/api-group-servicedesk/#api-rest-servicedeskapi-servicedesk-servicedeskid-customer-get)", | ||
| version: "0.0.1", | ||
| type: "action", | ||
| ai: "optimized", | ||
| annotations: { | ||
| destructiveHint: false, | ||
| openWorldHint: true, | ||
| readOnlyHint: true, | ||
| }, | ||
| props: { | ||
| app, | ||
| cloudId: { | ||
| propDefinition: [ | ||
| app, | ||
| "cloudId", | ||
| ], | ||
| }, | ||
| serviceDeskId: { | ||
| propDefinition: [ | ||
| app, | ||
| "serviceDeskId", | ||
| ], | ||
| description: "The service desk whose customers to search, e.g. `1`. Run **List Service Desks** to map a project name or key to its ID. Use the same ID you will pass to **Create Request**, so the match is checked against the desk the ticket will actually be raised on.", | ||
| }, | ||
| query: { | ||
| type: "string", | ||
| label: "Query", | ||
| description: "Name or email address to search for, e.g. `Joseph Wilson` or `joseph@example.com`. Matched against `displayName` and `emailAddress`. Omit to list every customer of the desk.", | ||
| optional: true, | ||
| }, | ||
| maxResults: { | ||
| propDefinition: [ | ||
| app, | ||
| "maxResults", | ||
| ], | ||
| description: "Maximum number of customers to return across all pages (1-1000).", | ||
| }, | ||
| }, | ||
| async run({ $ }) { | ||
| const { | ||
| app, | ||
| cloudId, | ||
| serviceDeskId, | ||
| query, | ||
| maxResults, | ||
| } = this; | ||
|
|
||
| const { | ||
| results, hasMore, | ||
| } = await app.searchServiceDeskCustomers({ | ||
| $, | ||
| cloudId, | ||
| serviceDeskId, | ||
| query, | ||
| maxResults, | ||
| }); | ||
|
|
||
| // Dropping the avatar URLs and `_links` the raw payload carries. | ||
| const users = results.map(({ | ||
| accountId, displayName, emailAddress, active, | ||
| }) => ({ | ||
| accountId, | ||
| displayName, | ||
| emailAddress, | ||
| active, | ||
| })); | ||
|
|
||
| $.export("$summary", `Found ${users.length} customer${users.length === 1 | ||
| ? "" | ||
| : "s"} on service desk ${serviceDeskId}${query | ||
| ? ` matching "${query}"` | ||
| : ""}${hasMore | ||
| ? ", truncated at Max Results; raise it to fetch more" | ||
| : ""}`); | ||
| return { | ||
| users, | ||
| truncated: hasMore, | ||
| }; | ||
| }, | ||
| }; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| import app from "../../jira_service_desk.app.mjs"; | ||
|
|
||
| export default { | ||
| key: "jira_service_desk-find-users", | ||
| name: "Find Users", | ||
| description: | ||
| "Finds any active user on an Atlassian site by name or email address and returns the `accountId` of each match." | ||
| + " **Pick this tool when the person does not have to be a customer of one particular service desk**, i.e. to fill `requestParticipants` on **Create Request** with an approver, manager, watcher, or agent, or when the user names somebody but no service desk is known yet." | ||
| + " Natural-language cues: \"add my manager Dana as a participant\", \"cc the security lead on this ticket\", \"loop in john@acme.com\", \"what is the account ID for Jean?\"." | ||
| + " Pick **Find Service Desk Customers** instead when you already know the service desk and the person is the one the ticket is being raised for (`raiseOnBehalfOf`). That tool is more precise, confirms the person can actually raise a request on that desk, and excludes bots." | ||
| + " Use **List Sites** first to obtain the required `cloudId`." | ||
| + " Worked example: for \"open a laptop request and add Dana Lee as a participant\", call this with Query `Dana Lee`, read `accountId` `5b10a2844c20165700ede21g` off the match whose `accountType` is `atlassian`, then pass `[\"5b10a2844c20165700ede21g\"]` as `requestParticipants` on **Create Request**." | ||
| + " Most users on a Jira site are bots, not people. Integrations come back as ordinary matches carrying `accountType` `app`, so read `accountType` and use only `atlassian` accounts as `raiseOnBehalfOf` or `requestParticipants`." | ||
| + " Query is matched against `displayName` and `emailAddress`, and matches more than just the start of them. Pass a full name or a full email address to keep the result set tight." | ||
| + " Results are paginated automatically up to `maxResults`." | ||
| + " Returns `{ users, truncated }`, where `truncated` is `true` when more matches remained unfetched." | ||
| + " `accountId` is the only field guaranteed present: Atlassian's profile visibility rules hide `emailAddress` on users who have not made it public, so match on `displayName` and never require an email to be returned." | ||
| + " An empty `users` list means either nobody matched or the connected account lacks the \"Browse users and groups\" global permission, which Atlassian reports as zero results rather than as an error." | ||
| + " [See the documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-user-search/#api-rest-api-3-user-search-get)", | ||
| version: "0.0.1", | ||
| type: "action", | ||
| ai: "optimized", | ||
| annotations: { | ||
| destructiveHint: false, | ||
| openWorldHint: true, | ||
| readOnlyHint: true, | ||
| }, | ||
| props: { | ||
| app, | ||
| cloudId: { | ||
| propDefinition: [ | ||
| app, | ||
| "cloudId", | ||
| ], | ||
| }, | ||
| query: { | ||
| type: "string", | ||
| label: "Query", | ||
| description: "Name or email address to search for, e.g. `Joseph Wilson` or `joseph@example.com`. Matched against `displayName` and `emailAddress`. A full name or full email address gives the tightest result set.", | ||
| }, | ||
|
Comment on lines
+36
to
+40
Contributor
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Move the shared Both actions define
As per coding guidelines, props used by more than one component must be defined in the app file. As per path instructions, reused props must be referenced with 📍 Affects 2 files
🤖 Prompt for AI AgentsSources: Coding guidelines, Path instructions |
||
| maxResults: { | ||
| propDefinition: [ | ||
| app, | ||
| "maxResults", | ||
| ], | ||
| description: "Maximum number of users to return across all pages (1-1000).", | ||
| }, | ||
| }, | ||
| async run({ $ }) { | ||
| const { | ||
| app, | ||
| cloudId, | ||
| query, | ||
| maxResults, | ||
| } = this; | ||
|
|
||
| const { | ||
| results, hasMore, | ||
| } = await app.searchUsers({ | ||
| $, | ||
| cloudId, | ||
| query, | ||
| maxResults, | ||
| }); | ||
|
|
||
| // Dropping the four avatar URLs per user the raw payload carries. | ||
| const users = results.map(({ | ||
| accountId, displayName, emailAddress, active, accountType, | ||
| }) => ({ | ||
| accountId, | ||
| displayName, | ||
| emailAddress, | ||
| active, | ||
| accountType, | ||
| })); | ||
|
|
||
| $.export("$summary", `Found ${users.length} user${users.length === 1 | ||
| ? "" | ||
| : "s"} on the site matching "${query}"${hasMore | ||
| ? ", truncated at Max Results; raise it to fetch more" | ||
| : ""}`); | ||
| return { | ||
| users, | ||
| truncated: hasMore, | ||
| }; | ||
| }, | ||
| }; | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
Repository: PipedreamHQ/pipedream
Length of output: 214
🏁 Script executed:
Repository: PipedreamHQ/pipedream
Length of output: 8462
🌐 Web query:
Atlassian Jira Service Management Cloud REST API create customer request raiseOnBehalfOf open closed service desk associated customer💡 Result:
To create a customer request in Jira Service Management (JSM) Cloud on behalf of another user, you use the 'raiseOnBehalfOf' field within the REST API request body [1][2]. Key Requirements and Considerations: 1. API Endpoint: Use the POST /rest/servicedeskapi/request endpoint to create the request [1][2]. 2. Payload Structure: Include the 'raiseOnBehalfOf' field, which accepts the username or email address of the customer on whose behalf the request is being created [1][3][4]. Example JSON payload: { "serviceDeskId": "10", "requestTypeId": "23", "requestFieldValues": { "summary": "Request via REST API", "description": "I need help with my account." }, "raiseOnBehalfOf": "customer-email@example.com" } 3. Permissions: The 'raiseOnBehalfOf' field is not available to users who only possess the Service Desk Customer permission [1][2][5]. The user performing the API call (typically the user owning the API token or credentials) must have appropriate permissions within the project, often equivalent to a Service Desk Agent or a user with the 'Modify Reporter' permission, to successfully create requests on behalf of others [6]. 4. Customer Association: For the request to be successfully created on behalf of a user, that user must typically already exist as a customer within the relevant JSM project [4]. If you cannot guarantee the user is already a customer, you may need to handle creation differently, such as by storing the requestor's information in a custom field instead [4]. For further verification of your specific environment's capabilities, you can use the servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field endpoint to inspect the fields available for a specific request type based on your current authenticated user's permissions [1][3].
Citations:
🏁 Script executed:
Repository: PipedreamHQ/pipedream
Length of output: 19339
🌐 Web query:
site:developer.atlassian.com/cloud/jira/service-desk open service desk closed service desk customer associated user raiseOnBehalfOf💡 Result:
In Jira Service Management, the ability to use the raiseOnBehalfOf field when creating a request via the REST API is governed by both the service desk's access configuration and the user's specific permissions [1][2]. 1. Service Desk Access Types: - Public (Sign up): Allows anyone with the URL to submit requests, automatically creating a customer account [2]. - Open: Allows any user in the system to submit requests, regardless of whether they are explicitly associated with the service desk [2]. - Closed: Restricts request submission to only those users who are already associated with the service desk [2]. 2. raiseOnBehalfOf Permissions: - The raiseOnBehalfOf field is used to create a request on behalf of another customer [1][3]. - This field is not available to users who only have standard customer permissions [1]. - To use this field, the user performing the API request must typically have agent or project administrator privileges [3]. You can verify if a user has this capability for a specific request type by checking the canRaiseOnBehalfOf permission returned by the Get request type fields endpoint [4]. In summary, while the service desk type determines who can initiate requests [2], the permission to raise them on behalf of others is a separate, more restricted capability that requires higher-level project access [1][3].
Citations:
Make the
Find Usersfallback conditional.Find Usersonly confirms a site-wide account. Because closed service desks require an associated customer, this unconditional fallback can pass an ineligible account toraiseOnBehalfOfand fail validation. State that Find Users is valid only when the selected service desk allows non-customer requesters; otherwise require a Find Service Desk Customers match.🤖 Prompt for AI Agents
Source: MCP tools