fleetdm
Custom packages: edit icon
Goal
| User story |
|---|
| As an IT admin, |
| I want to add a custom icon for my custom packages |
| so that my end users can easily find the software they need on the My device > Self-service page. |
Key result
Customer request
Original requests
- #24802
Context
- Product Designer: @eugkuo
- Engineer: @iansltx
Changes
Product
- [ ] UI changes:
- [ ] CLI (fleetctl) usage changes: TODO
- [ ] YAML changes: TODO
- [ ] REST API changes: TODO
- [ ] Fleet's agent (fleetd) changes: TODO
- [ ] GitOps changes: TODO
- [ ] Activity changes: TODO
- [ ] Permissions changes: TODO
- [ ] Changes to paid features or tiers: TODO
- [ ] My device and fleetdm.com/better changes: TODO
- [ ] First draft of test plan added
- [ ] Other reference documentation changes: TODO
- [ ] Once shipped, requester has been notified
- [ ] Once shipped, dogfooding issue has been filed
Engineering
- [ ] Test plan is finalized
- [ ] Contributor API changes: TODO
- [ ] Feature guide changes: TODO
- [ ] Database schema migrations: TODO
- [ ] Load testing: TODO
ℹ️ Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".
QA
Risk assessment
- Requires load testing: TODO
- Risk level: Low / High TODO
- Risk description: TODO
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.
- Navigate to a software title page
- Click the edit button next to the package.
- Ensure that the app icon now shows on the edit software modal
- Ensure that rolling over the app icon shows a pencil.
- Ensure that clicking on the app icon opens a system modal to let you choose an image from your desktop.
- Click upload and ensure that only pngs are selectable as uploadabile files.
- Ensure an error message appears if the file is not square or is outside the 120 to 1024px bounds
- Ensure that when saving, the new app icon replaces the icon next to the package as well as the icon at the top of the page.
- Ensure that the new icon appears in self-service
Testing notes
Confirmation
- [ ] Engineer: Added comment to user story confirming successful completion of test plan.
- [ ] QA: Added comment to user story confirming successful completion of test plan.
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).
@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:
- I have the display name set as metadata under the installer package name.
- Should the display name replace the package name?
- Should the package display name replace the software title display name?
- If yes, in the future when we have multiple installer packages what should the software title display name be? The latest installer package?
- 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?
- 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?
- 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?
- 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?
@eugkuo As part of this story, would a Fleet admin be able to specify the custom app name in their yaml files in GitOps?
@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
@eugkuo Given that GitOps is a core differentiator for Fleet and given that the requesting customer wants GitOps for their workflows, GitOps needs to be part of the spec here (though it'll get its own subtask), as does generate-gitops support.
@mostlikelee I neglected to mention you on these so re-adding to ping you:
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:
- I have the display name set as metadata under the installer package name.
- Should the display name replace the package name?
- Should the package display name replace the software title display name?
- If yes, in the future when we have multiple installer packages what should the software title display name be? The latest installer package?
- 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?
- If yes, in the future when we have multiple installer packages what icon should be displayed? The latest installer package?
- 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?
- 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?
- 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?
So, where we display the updated name/icon/version is going to determine at which level we need to implement, which will in turn have interplay with both inventory and access controls. Probably also useful to walk through how we get name/version/icon now and where they're stored.
Key questions:
- Are any fields globally editable? If so, that means only global roles can edit them, right?
- For names, what happens when an associated app arrives in inventory with a different name?
Name
For everything without a bundle ID, gets set once on first inventory or package upload, and is the unique key for associating both installers and inventory for that source globally. The name is at the software_title level, and is visible in a bunch of places (self-service, software title details, etc.).
For apps with bundle IDs, this is added on initial upload or inventory, but may be edited later during software ingestion if we have a more "canonical" name come in from inventory. There's also the contributor API endpoint for editing names manually, but inventory may overwrite them. Unique key in these cases is bundle ID. The name is still at the software_title level, and is still visible in the same places.
Icon
For software that has been added as a VPP app on a team, each app has a URL for the 512x512 version of the Apple icon, as a PNG, loaded on-the-fly from Apple by the client. Icons are revised when they're revised upstream.
For software titles without an associated VPP app on the same team, icons are shown based on matching to SVGs embedded in the code, based on name + source matching. This means that Fleet server updates determine which icon is shown.
The above means that icons are currently team-specific with a global fallback.
Inventory doesn't affect icons. For example, iOS apps inventoried via MDM will have the generic Apple icon unless we have an SVG override (or the same app was added as a VPP app for that team).
Icons could be extracted from some types of custom packages on upload.
Version
The below information is orthogonal to inventoried (installed) version.
Software version is attached to the package or VPP app, so it's team-specific rather than global.
For VPP apps, version is set on add and updated hourly from Apple, since the latest version is pushed when a VPP app is installed.
For FMAs, the version in the FMA manifest is copied over when the FMA is imported into the software library.
For custom packages, the version is extracted as metadata on upload.
Since it's come up before on other features, the tradeoff with allowing edits of these values is that we'll get fewer bug reports when we're parsing metadata incorrectly on upload/inventory, as IT admins will just fix the names/icons/versions they care about if there aren't too many of them. My suggestion here would be to add analytics for cases where name/icon/version needed to be edited, and check in with customers who use that feature a lot to make sure we're not overlooking bugged behavior. How that data point is implemented will vary depending on how software field overrides work.
Given that scope has dropped on this, seems like we want to treat this as another piece of self-service, attached to the software_installer.
On the most recent review call I mentioned "square PNG with dimension min/max" and GitOps. Need to dig into this further.
@iansltx and @mostlikelee I've updated the designs and prototype to reflect that the only additional update is for the app icon.
LMK what you think.
@iansltx Does #29177 block this ticket? Also, there's no reason we don't allow jpgs and gifs as well as pngs once 29177 is done is there?
cc @mostlikelee
@eugkuo 29177 doesn't block this, though there's some implementation overlap such that if we hit both of these in the same sprint we'll need to be more careful about subtask traffic jams (still two swimlanes worth of backend across the two tickets though).
Re: JPG/GIF, those formats aren't the right match for icons, unlike SVG vs. PNG don't bring anything special to the table for the icon use case that PNG doesn't, and it's trivial to convert JPEG -> PNG or GIF -> PNG (since all are raster formats) where the raster -> vector PNG -> SVG conversion is less straightforward.
Figma looks good, thanks @eugkuo !
- Copy suggestion: "Icons must be square PNG files with dimensions between 120×120 px and 1024×1024 px."
- Only other thing to spec is how we want to show the error if it's not a square between specific dimensions.
Copy suggestion: "Icons must be square PNG files with dimensions between 120×120 px and 1024×1024 px."
@RachelElysia Love the suggestion. Updated!
@jmwatts I've added a test plan to this ticket. LMK what you think.
@iansltx I know we discussed this yesterday but I can't quite remember the answer. When this icon is updated is it updated throughout our system? Like will it show up in the library and inventory with the new icon as well?
cc @mostlikelee @RachelElysia
@eugkuo Sorry for the delay on this. Originally my thought was "just follow what we do for VPP apps", which I thought was:
- Icon is associated with the VPP app
- Icon shows up when viewing the software title on the team that has the VPP app set
- Icon shows up in self-service for the associated team
- Icon shows up in host details for the associated team if the VPP app is in scope
With the above assumption, custom package icons would behave as follows:
- Icon is associated with the software package
- Icon shows up when viewing the software title on the team that has the package set
- Icon shows up in self-service for the associated team
- Icon shows up in host details for the associated team if the installer is in scope
In reality, if a VPP app gets added on any team, a zero value-looking object gets tacked onto the all-teams view for that title; you can see this for Keynote in Dogfood. This object includes the App Store icon URL. We can do this in part because VPP icons are global for a given Apple app ID (and the icon URL is stored on the global VPP apps table in the DB rather than on the team-specific table).
I'm still thinking that we handle custom packages according to the above (tied to the package, only shows up where we would populate package info), but that's not actually consistent with VPP if current VPP behavior is intended VPP behavior.
A side effect of handling package icons this way is that an All Teams view of software wouldn't have an icon. The only workarounds for this would be:
- We pick the first (for some definition of "first") icon we find for a custom package
- We make software icon overrides global rather than package/team based
...so this is a good design review discussion, both to determine desired VPP behavior and desired behavior here (which may be influenced by the "why" behind desired VPP behavior).
Per this morning's discussion, I'm pausing digging in on eng DRI on this in favor of getting #27983 spec'd, as the expectation is that this will not make it into the 4.71 dev sprint. There are also questions around existing behavior that should probably be cleaned up, as that will provide a consistent foundation to build this on. Those questions are documented in #29886.
@iansltx and @mostlikelee
I've updated the Prototype so that editing app icons happens at the title level and not at the package level. I've also removed icons at the package level to avoid confusion.
The expectation is that the icon at the sotware title level would be associated with the software everywhere this title is shown (in library and inventory and self-service).
@RachelElysia Thoughts on wanting/needing a loading screen for the modal and a confirmation save vs immediately jumping back to the software title page with a toast confirmation?
One pivotal question that will determine a bunch of implementation details: are these icons 1:1 with software_installers records (in which case currently they're 1:1 with teams) or are they more global than that?
Looking at the 1:1 with software_installers option:
Pros
- Consistent with self-service flag and categories
- Allows for e.g. marking app icons as "beta" (or using a version-specific logo) on a canary team if that team has a different app version
- Doesn't interfere with VPP app icon semantics if a custom-icon package is available on one team and a VPP app is available on another (once we sort out which wins for All Teams)
- Access control for icon edit matches access control for all software package edits, vs. requiring a global role
Cons
- Icon must be set once per team (less of a big deal with GitOps?)
- Undefined behavior for showing software in "All Teams" (worse than VPP's current undefined behavior)
- Potentially jarring if switching teams changes or loses an icon (this happens with VPP)
- If implemented as "an icon URL under software package", inventoried software versions won't see the icon
Question is how many of the pros/cons matter in this particular use case. FWIW I would expect that in either case we would be consistent with the icon shown within a team, for calls to software endpoints (not software version endpoints). Since My device only calls software endpoints (not versions), the icon on the software list would match the icon for self-service install (and update).
One thing to add to what @iansltx is saying is that there are apps that have/will change icons with various releases (see Adobe products, which look like they update their icon every few years).
So. It seems like we should go back to associating icons with installer packages. I still feel like the Software title icon should inherit the latest installer package icon.
WRT All teams and defining icons. Why can't we show installer packages on the all teams level and let people edit the icons there when editing. If a software title is selected from "All teams" we would show all the installer packages that have been added (surfacing the team(s) the packages are tied to). Ideally we'd be able to collapse all the installer packages so that we would only need to show one installer package that had been uploaded associated with multiple teams.
I'm sure this is blowing up scope and throwing wrenches all over the place, but what do we think about the idea?
@iansltx @mostlikelee
@eugkuo What would you define as "latest" here? Most-recently uploaded/updated? Would that work cross-team? How would that interact with VPPs, which have their versions automatically bumped within ~1 hour of a new version coming out on Apple's side?
Re: showing all installers when viewing All Teams, while that's useful, that would require decent-sized API and frontend changes, so deserves its own ticket.
@iansltx I'd define latest as the latest version number (newest version).
I totally hear you on showing all installers on All teams being its own ticket. I'll write that as a feature request when I get a chance.
@eugkuo Hm. So the idea would be that, for All Teams, we'd check all VPP apps and all packages with icons customized, rank by version number descending, and use the icon of whatever was at the top? Which would usually be the VPP app due to auto-updates, but might fall back to an FMA or the like.
If that's the idea, we might have to do some finagling to make sure the version calculation is fast...and we'll need to decide on what happens if the same package is uploaded to two different teams with two different icons...but that would mean that at least the "all teams" part of #29886 is now expected/intended behavior, which is good (still need to decide what to do with version view there though).
@iansltx Would you be doing the finagling on a chron job that would run in the background every now and again?
The part where someone adds the same package to two different teams is def an issue. Which makes me wonder why we allow it? If we see someone uploading a package that already exists in our system wouldn't it be cooler to say "do you mean x" and use what we already have along with the associated icon? Similarly to how back in the day when the Apple Music store came out they looked at all of your music and automagically upgraded songs to the Apple Music Library version and filled in all the metadata for you.
@mostlikelee could you gut check us on what we're talking about here? I know you were trying to keep this from getting out of hand and I don't want to explode things unknowingly. Clearly some of this is looking into the future, but could you make sure to ground us to what we 'need' or 'should' be doing at this time?
Thanks!
oh my, we may have officially took a detour to the dark side of icon town. lets get a chat on the books for next week.
@iansltx Would you be doing the finagling on a chron job that would run in the background every now and again?
Original thought was handle it on retrieval but we could handle the recalculation when the criteria for which icon wins changed. That would be in the VPP version bump cron, when a custom icon was added/deleted, when a package was edited/deleted, or eventually when a FMA was added. For the last bit, FMA icons would actually get lower priority than custom icons because they're currently implemented as just software title matching based defaults, but I'd expect that to change to the same "priority" as custom package icons once #29177 is implemented.
We'd need to add a column to software_titles for this, to point to the software_installer we want to use the custom icon of (if any), but that's doable if we need icon display at the All Teams level to work a specific way.
The part where someone adds the same package to two different teams is def an issue. Which makes me wonder why we allow it? If we see someone uploading a package that already exists in our system wouldn't it be cooler to say "do you mean x" and use what we already have along with the associated icon? Similarly to how back in the day when the Apple Music store came out they looked at all of your music and automagically upgraded songs to the Apple Music Library version and filled in all the metadata for you.
Right now, structurally, a software package lives on exactly one team, though we deduplicate identical installer bytes on disk via hash. One reason for this is access controls: users can have team-limited roles, and while users can affect multiple teams (or operate globally) we don't currently have the infrastructure (FE or BE) to handle operations on an entity that spans multiple teams by a user that isn't global. For example, "did you mean X package" doesn't make sense when the existing package is on a team that the admin doesn't have access to, and if the admin has write on one team and read on another, do they get to edit the package they just added if it's cross-team?
@mostlikelee I have it at the top of the design review column in the drafting board so was intending to make this the first thing we talk about at DR on Tuesday. If you think this warrants its own time I'm open to it.
Right now, structurally, a software package lives on exactly one team, though we deduplicate identical installer bytes on disk via hash. One reason for this is access controls: users can have team-limited roles, and while users can affect multiple teams (or operate globally) we don't currently have the infrastructure (FE or BE) to handle operations on an entity that spans multiple teams by a user that isn't global. For example, "did you mean X package" doesn't make sense when the existing package is on a team that the admin doesn't have access to, and if the admin has write on one team and read on another, do they get to edit the package they just added if it's cross-team?
@iansltx . But wouldn't it be cooooool if fleet recognizes a unique software package that's uploaded to our servers and pushes that out to everyone? Like why hold duplicates of the same thing? The icon thing we could do by organization so that doesn't get too wonky. If an organization wants to change their icon it will affect the entire organization but it won't affect others. So if Zorro corp wants to bastardize all their app icons with a flaming 'z' they can go for it but it won't touch Acorn Inc.