Scopes Justification

Below we explain why the app requires each of the permissions (scopes) declared in manifest.yml. The descriptions are concise and refer to real usage in the code and the available gadgets.

• storage:app

  • Used to store data and cache report/gadget results in Forge Storage/KVS (see src/reportDataStorageService.ts).

  • Allows saving and reading chunked visualization data to speed up loading and reduce API limits. It does not grant access to Jira data outside the app’s own storage space.

• read:jira-work

  • Used to read issue/work data in Jira (JQL, fields, statuses), required by: Request distribution over time, Agent's workload, Request Channel Type, SLA - Met %, and Assignee - Average CSAT.

  • Rationale: these gadgets analyze issue fields (including JSM fields stored on the issue). Without this scope, running queries and reading fields would not be possible.

• read:servicedesk-request

  • Specifically required for: GET /rest/servicedeskapi/assets/workspace to detect Assets availability and obtain workspaceId used by the "Assets Structure" flow (static/spa/src/api/serviceDeskApi.ts – getWorkspace;

• read:cmdb-schema:jira

  • Used to read Assets/CMDB schemas (listing Object Schemas). Used by the "Assets Structure" gadget to configure and select the data scope (static/spa/src/api/assetsApi.ts – getObjectSchemaList).

• read:cmdb-object:jira

  • Used to read Assets/CMDB objects and to execute AQL queries (getObjectsByAql/fetchObjectsByAql). Necessary to count and aggregate assets in the "Assets Structure" gadget.

• manage:servicedesk-customer

  • Used for operations on customers/organizations in JSM. In our app it is required to read customer lists within organizations and organizational data via the Service Desk API, which Atlassian protects with a "manage"-level permission (static/spa/src/api/serviceDeskApi.ts – organization and user endpoints).

  • This permission also allows creating and editing customers, but our app does not perform such actions. Ideally we would switch to granular read-only permissions; however, we are not doing so now to avoid triggering a new major app version.

  • Used by gadgets: Organizations (number of customers per organization) and Number of requests per organizations.