Edit software icon

[eugkuo]

Goal

User story
As an IT admin,
I want to add a custom icon for my software
so that my end users can easily find the software they need on the My device > Self-service page.

Roadmap item

None

Key result

Customer request

Original requests

• Ability to edit icon, name, and version for custom packages uploaded to Fleet #24802

Context

• Product Designer: @marko-lisica
• Engineer: @iansltx

Make sure to solve this: #29886

Changes

Product

• UI changes: Figma link
• CLI (fleetctl) usage changes: No changes.
• YAML changes: [API/YAML] Edit software icon #31324
• REST API changes: [API/YAML] Edit software icon #31324
• Fleet's agent (fleetd) changes: No changes.
• GitOps changes: Specified in Figma above.
• GitOps generation changes:
  • Specified in Figma above.
  • gitops-generate command should download icons.
• Activity changes: [Activity changes] Edit software icon #31382
• Permissions changes: Global/team admins and maintainers can apply update icon. Covered by "Add, edit, and delete software" in permissions guide.
• Changes to paid features or tiers: Available in Fleet Free and Premium.
• My device and fleetdm.com/better changes: The icon added by user will display on self-service and software inventory tabs on My device page.
• First draft of test plan added
• Other reference documentation changes: No changes.
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed. @marko-lisica: verified this in dogfood.

Engineering

• Test plan is finalized
• Contributor API changes: [API/YAML] Edit software icon #31324
• Feature guide changes: Update self-service, custom package, VPP articles to reference icons/how to change them
  • UPDATE: @noahtalerman: Decided to only update the self-service software guide: Self-service software: Edit software icon #32986
    • Why? Self-service is the primary use case. Avoid maintaining duplicate information in guides.
• Database schema migrations: Add software_title_icons table with title ID, team ID, icon filename, and icon storage ID (will dump icons onto the software installers bucket)

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

QA

Risk assessment

• 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.

UI

• Make sure that the edit action is available next to the software title name, only if the software title has a package or VPP app added.
• Verify that the user can upload a PNG icon by clicking on the edit icon next to the software title name in the Edit software modal.
• Verify that the user can only select PNG files.
• Verify that Fleet returns an error if the icon doesn't fit into specs defined in Figma.
• Make sure that the user can preview the icon in the Edit software modal, once it's selected and before it's uploaded.
• Verify that the icon in the preview is displayed according to the priority order described in Figma..
• Make sure that the preview under the Fleet tab shows the real software title name, icon, type and versions count. The table underneath the transparent overlay should be static.
• Make sure that the preview under the Self-service tab shows the real software title name and icon. Other data should be static.
• Make sure that if the user deletes the selected or uploaded icon, the preview shows the fallback icon.
• Verify that when the VPP icon is available, the upload form is still available in the Edit software modal, so the user can override that icon with a custom PNG.
• Make sure that the uploaded icon shows on software title details, version details, titles list, versions list, on a team where the icon is added.
• Make sure that we do client-side validation if the icon size doesn't fit specs, before the user hit "Save" (upload) icon. Show error flash message specified in Figma.
• Make sure that the uploaded icon shows on the host's software library and inventory pages, on a host that is a member of the team where the icon is uploaded.
• Make sure that the uploaded icon shows on the My device software and self-service tabs, on a host that is a member of the team where the icon is uploaded.
• Make sure that the uploaded icon shows in /controls/setup-experience/install-software when selecting software to be installed
• Verify that when GitOps mode is enabled, on the software title details page, the edit button (next to the software title name) is disabled, and that the GitOps tooltip is displayed on hover.

API

• Verify that the icon can be updated with the new PUT /api/v1/fleet/software/titles/:id/icon endpoint.
• Verify that an icon can be added to "no team" via the new PUT /api/v1/fleet/software/titles/:id/icon endpoint.
• Verify that the updated icon can be deleted with the new DELETE /api/v1/fleet/software/titles/:id/icon endpoint.
• Verify that the updated icon can be downloaded with the new GET /api/v1/fleet/software/titles/:id/icon endpoint.
• Verify that Fleet errors if icons are not PNG, not square, or not between 120x120px and 1024x1024px, when user tries to upload with PUT endpoint.
• Make sure that icon_url is available on the top level for each software item in GET /api/v1/fleet/software/titles.
• Make sure that icon_url is available on the top level for each software item in GET /api/v1/fleet/software/titles/:id.
• Make sure that icon_url is available on the top level for each software item in GET /api/v1/fleet/device/{token}/software.
• Verify that if no uploaded icon and no VPP added, icon_url is null (for every endpoint above).
• Create a software package, add icon to software installer, edit the package (change something that is not icon related), delete the software package. This should generate a number of activities.

1 for creation (icon url blank)
1 for adding icon (icon url in activity)
1 for editing package (icon url in activity)
1 for deleting package (icon url in activity)

• Create a vpp app, add icon to vpp app, edit the vpp app (change something not icon related), delete vpp app. This should generate a number of activities.

1 for creation (icon url blank)
1 for adding icon (icon url in activity)
1 for editing vpp app (icon url in activity)
1 for deleting vpp app (icon url in activity)

• Create a vpp app, edit vpp app, delete vpp app. This should generate a number of activities.

1 for creation (icon url blank)
1 for editing vpp app (icon url in activity, note that this is the vpp_app.icon_url, not the custom icon)
1 for deleting vpp app (icon url in activity, note that this is the vpp_app.icon_url, not the custom icon)

OUT OF SCOPE FOR 4.74: GitOps

moved these tests to #31897

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan.
2. QA: Added comment to user story confirming successful completion of test plan.

[iansltx]

Heads-up: "name" editing would change which software_title the package is associated with based on how we're linking titles and packages right now, for OSes other than macOS, and that has implications for e.g. software updates where inventoried software need to name-match the corresponding installer. We also have validation that prevents package edits from changing the associated software title. So we'll need to sort those implications out if we include name in scope here (this issue doesn't apply to icon and version).

[eugkuo]

@iansltx & @noahtalerman I've added a link to a figma design file to get the ball rolling. I've also created this prototype

So here are a few comments/questions based on the way in which this ticket is written:

1. I have the display name set as metadata under the installer package name.
   1. Should the display name replace the package name?
   2. Should the package display name replace the software title display name?
      1. If yes, in the future when we have multiple installer packages what should the software title display name be? The latest installer package?
2. Similar to the above, if an icon is updated on an installer package should that icon also update the icon at the top of the software title page?
   1. If yes, in the future when we have multiple installer packages what icon should be displayed? The latest installer package?
3. I find updating the version number part of this ticket odd. If the package has a version number why would someone want to change it to something that could be wrong. Why would Fleet want to allow such a potential mismatch?
4. Lastly, should the icon and the display name actually be edited at the software title page level instead of the package level? It seems like that's what people would care more about?
   1. Note: At one point there was a request to name custom packages mainly for admin identity purposes. In this world we could have title editing at both levels, with the custom package titles be reference titles for admins.

Thoughts?

[ddribeiro]

@eugkuo As part of this story, would a Fleet admin be able to specify the custom app name in their yaml files in GitOps?

[noahtalerman]

FYI @eugkuo

[eugkuo]

@eugkuo As part of this story, would a Fleet admin be able to specify the custom app name in their yaml files in GitOps?

@mostlikelee do you want to include GitOps in this ticket or should GitOps and UI tickets be separated for reasons of scoping, etc.

cc @ddribeiro