finos
Support changes to the set of User Channels in the Desktop Agent API
Minor Issue
Area of Issue
- [ ] App Directory
- [x] API
- [ ] Context Data
- [ ] Intents
- [ ] Desktop Agent Bridging
- [ ] Use Cases
- [x] Other : DACP Protocol.
Issue Description:
The new event listener system supports an event userChannelChanged which allows the desktop agent to tell an app that its user channel has changed.
In the latest fdc3-agent-proxy code, this is used to update the injected ChannelSelector in the following piece of code:
// DefaultChannelSupport.ts
this.channelSelector.updateChannel(theChannel?.id ?? null, this.userChannels);
However, this uses an internally-cached selection of user channels (this.userChannels), which is presumed to not change after the app has loaded.
However, it seems sensible that the selection of user channels might change, as the user may configure more or rename them.
We should therefore support a second event (e.g. userChannelsUpdated) that the Desktop Agent can send to the proxy to let it know that there is a modified set of user channels.
Additional Context:
- #1541
- #1540
The issue description is slightly conflating the API event userChannelChanged event with the (related) DACP message that delivers it (from the DA to the app), ChannelChangedEvent.
The first thing we need to consider is whether changing the set of User channels (created by the Desktop Agent) is something that should happen in FDC3 - the (Desktop Agent) API specification doesn't explicitly ban the channels changing, but it also doesn't provide any support for it; apps can retrieve a list of the user channels, but there is no event that they can listen for that will announce changes to that set. That lack then feeds into the Desktop Agent Communication Protocol not including a message for the DA to tell the DA Proxy (and any injected channel selectors) that the set has changed.
If changes to the set of user channels (rather than just which user channel is selected) is use case that community recognises as something that FDC3 should support, then we should add both an event to the API and messages to support both firing that event and passing updates to DA Proxy, which it can pass onto any injected channel selectors so they know about the new channel set.
However, it seems sensible that the selection of user channels might change, as the user may configure more or rename them.
I guess this then prompts the question of whether changing the set of user channels is a feature that Desktop Agent MAY implement outside the API, or whether they SHOULD or MUST implement new standard API calls that allow users or apps to do that...
Do you want to try and fit in a quick a chat on this in today's meeting, or defer to a later one @robmoffat ?
From the last Web Browsers meeting, I was asked to try and justify why I think this would be a good change to the standard:
Although FDC3 recommends a set of user channels, I would like this to be controllable in Sail so that users can have channels for their own purposes. E.g. A user might want to create a channel called "EMEA" where they look at their EMEA stocks, or a channel called "Pension" where they open apps and do some analysis on their pension fund. Having channels just called "Red", "Green" etc. means that the user has to manage a mapping in their head between their assigned purpose of the channel and its colour.
Furthermore, FDC3 recommends 8 (I think) different coloured channels. This is often Too Many. As a user, I probably don't have eight different things on the go at once. Clearly, the reason we recommend this many is to accommodate people who do have lots of stuff happening, but for everyone else this is over-complicating things.
Colour channels are a long established pattern in a multi-application environments in finance, enabling users to visually link windows they see on their desktop. All UIs I've seen demonstrated for channel based linking rely on colours for most users (with glyphs to support the colour-blind) as part of a compact control that is quickly visually assessed and the current set of user channel metadata is arranged around that, with the names and ids playing a supporting roll through the API.
What you propose seems to depart from the established use cases and we would need to assess whether there is consensus amongst the FDC3 community that we need to support this use case, whether that will constitute a breaking change (primarily for Desktop Agent vendors, but also app developers where they need to interact with a changing channel set) and on what API calls, events and DACP and bridging protocol messages need to be created - including whether it will be necessary or possible to agree sync of channels over the bridging protocol (which was specifically rejected/avoided the first time round by consensus). Further, Desktop Agent vendors that support saved layouts or workspaces etc. (terms vary as they are un-standardized but very common features) will also need to work through the implications for saved or shared layouts - including in situations where layouts are deployed to multiple users or shared between them (again this is relatively common). That in turn may necessitate bringing those concepts into the standard in some form (even if they don't have direct API support).
As this is potentially a significant (set of) change(s), I think it should be discussed through the Standards Working Group rather than any of the current discussion groups.
Finally, I foresee one alternative solution based on your use case (remembering a mapping of user channel to purpose), the ability to attach additional metadata to user channels - i.e. the channels don't change but you add an annotation to them that can be used as part of the UI. This could be done with or without API support (i.e. it could be a particular DA's feature or it could be a feature of the FDC3 API). API support could be as simple as an extra field on DisplayMetadata or also include an API to set the metadata (although its probably not for an app to do so, but the DA's own UI).
P.S. I remember that we debated going with 6 or 8 channels when the recommend set was established. It was decided that we would go with 8 for future proofing - the was a consensus that a set that was too small for power user was worse than a larger set with some channels going unused.
There is more detail on the discussions around the recommended channel set in:
- the issue: #717
- the PR: #727
- Bridging discussion group meeting minutes, including at least:
- #611
- #628
- #692
Thanks for the colour - this is my understanding of the state of things, and yes I remember #717
I did just check the standard around this, and we have:
Desktop Agent implementation MAY support configuration of the user channels.
So clearly some earlier thought existed around making this configurable too?
So clearly some earlier thought existed around making this configurable too?
Yes, but configurable was intended to mean offline / read on or during start-up of the environment, rather than it changing at runtime - I confess that wording doesn't make it explicit. Its also the type of config that you'd expect to be adopted and managed across a whole organisation, rather than individually (based on my own experience and comments we've had from sell-side participants in a past meetings).
Regarding your purpose-based naming of user channels use case, could it be satisfied using the existing name field of DisplayMetadata? name is a metadata field used for display purposes. Its only appearance in or use through the API is when it is provided with a Channel (retrieved via getCurrentChannel or getUserChannels as aChannel.displaymetadata.name) and so it has little impact on other functionality (such as saved or shared layouts/workspaces) as its the Channel.id field that will be used as a parameter or value by API calls (joinUserChannel, getOrCreateChannel, FDC3ChangedChangedEvent).
If a DA supports changing the display name of the channel the main thing that the Standard needs to include is just an event providing notification of the user channel metadata changing (allowing name, glyph and colour to be mutable) - which is an additive and non-breaking change (IMHO anyway - the only thing it would affect is an in-app channel selector that used the DisplayMetadata.name)
I like @kriswest's proposed solution to this. It won't break anything and should fairly easy for anyone to implement as an opt in feature. I think we'd jsut need to add another event that would allow the name, glyph and color of one or multipel channels to be updaetd at runtime.
I broadly agree with @kriswest's comment, however I think it would be preferable to just have an event to say something about the user channels in general has changed. This should prompt the app to call getUserChannels, which provides a canonical snapshot of the state of the user channels.
If we start giving details about which piece of metadata has changed on which channel, this could get quite complex to keep track of in the event of multiple changes occurring.
Also this would allow for increasing the number of user channels still.
As far as Sail is concerned, I think the main change here is that instead of setting the channel ID for the first eight channels, this would be pre-baked ('one', 'two' etc) and the user should only set the display name, colour and glyph. For channels beyond the eighth I can just use a string-to-int of the channel number.
Although tbh I think this last part is a concern of the DA vendor rather than the standard.