Self-service: Custom self-service software categories, with “Install all in category" button

[noahtalerman]

Goal

User story
As an IT admin,
I want to create a custom self-service software category and give end users an “Install all in category" button
so that I can bucket applications for specific teams in my organization (ex. "Engineering") and give my end users an easy way to install all apps for their team.

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes: No changes.
• YAML changes: [YAML/API/Guide/Activity] Self-service: Custom software categories + Install all in category #45463
• REST API changes: [YAML/API/Guide/Activity] Self-service: Custom software categories + Install all in category #45463
• Fleet's agent (fleetd) changes: No changes.
• Fleet server configuration changes: No changes.
• Exposed, public API endpoint changes: No changes.
• fleetdm.com changes: No changes.
• GitOps mode UI changes: Specified in Figma.
• GitOps generation changes: It should export categories for each fleet.
• Activity changes: [YAML/API/Guide/Activity] Self-service: Custom software categories + Install all in category #45463
• Permissions changes: Admins and maintainers (gloabal and fleet) should be able to add/edit/delete categories.
• Changes to paid features or tiers: Fleet Premium only.
• My device and fleetdm.com/better changes: Changes to My device page specified in Figma
• Usage statistics: No changes.
• Other reference documentation changes: No changes.
• First draft of test plan added
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed. Dogfood: Self-service: Custom self-service software categories, with “Install all in category" button #48076

Engineering

• Test plan is finalized
• Contributor API changes: TODO
• Feature guide changes: [YAML/API/Guide/Activity] Self-service: Custom software categories + Install all in category #45463
• Database schema migrations: TODO
• Load testing: TODO
• Pre-QA load test: TODO
• Load testing/osquery-perf improvements: TODO
• This is a premium only feature: Yes / No

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

Risk assessment

• Requires testing in a hosted environment: No
• Requires load testing: No
• Risk level: Low

Test plan

Make sure to go through the list and consider all events that might be related to this story, so we catch edge cases earlier.

Core flow

• Make sure that the user can hit the "Install all" button to install all software items in the category, or just all of them when the category isn't selected.
• Only items that aren't installed (failed included) should be queued for install.
• Installs should be queued in alphanumeric order.
• Number (n) in the button "Install all (n)" should reflect the number of software items that are not installed.
  • In case count of the software items is 0, don't show (0).
• When the user clicks "Install all (n)" it will switch to "Install all" (disabled) and stay until there are pending items. When no pending items in the category or "All" then the button is hidden.
• Make sure that the container for labels (under Target > Custom) is changed across Fleet UI (height change). Figma.
• When the user hits "Install all," make sure that Fleet triggers activity for that action, and rest of software installs are tracked in the activity as usual.

UI

• Verify that all UI changes specified in the Figma wireframes are correctly implemented FLEET FREE
• Verify expected UI states (loading, empty, error states if applicable)
• Verify the "Install all" button appears visually disabled (not just non-functional) when any app in the list has an in-progress install, update, or uninstall.
• Verify that hovering over the disabled "Install all" button shows a tooltip or other affordance explaining why it is disabled.
• Verify the disabled state applies per-category (i.e. only the relevant category's button is disabled, not all "Install all" buttons on the page, if multiple categories are shown).

API

• Test all API endpoints added or modified in the API changes section of this issue
• Verify any new API endpoints appear in the list when adding an API-only user. The API endpoints display name, method, and path is the same as listed in the API reference docs
• Verify error handling for invalid inputs where applicable
• POST /device/{token}/software/install_all — when one or more apps in the list are currently installing, updating, or uninstalling, verify the endpoint returns an appropriate error with a human-readable message.
• POST /device/{token}/software/install_all — verify that no apps are queued or double-queued when the request is rejected due to an in-progress operation.
• Verify the error response body includes enough detail to identify which app(s) are blocking the request (or at minimum that the message is actionable for the end user).

GitOps (generate + run)

• Configure the feature through the UI and run fleetctl generate-gitops
• Confirm the generated .yml includes the expected fields (compare with YAML changes in the Product section)
• Modify the generated .yml and run fleetctl gitops
• Confirm the configuration updates correctly in Fleet
• Enable GitOps mode and verify the feature behaves correctly

Permissions

• Verify role restrictions are applied correctly for global roles
• Verify role restrictions are applied correctly for fleet-level roles

Supplemental testing

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan (include any special setup, test data, or configuration used during development/testing if applicable).
2. QA: Added comment to user story confirming successful completion of test plan.
3. QA: Determined whether this story needs Playwright automation.
   • Needs automation: Yes / No
   • If yes, filed a follow-up issue in the :help-qa project with status "Needs automation": TODO

[lukeheath]

@georgekarrv @cdcme Would you please add a t-shirt estimate to this story? Thanks!

[georgekarrv]

Added a S because the backend for custom categories might be about half a S and then the frontend to accommodate would probably bring the total to S.