Allow Specification of Channel MetaData during Channel Creation

[sgd2z]

Enhancement Request

According to the the spec - "Always, there SHOULD be a clear UX indicator of what channel an app is joined to.". However, when creating channels it is currently not possible to specify displayMetaData.

Use Case:

1. This would allow the user to see the channel that the Desktop Agent is joined to if it is not one of the system channels.
2. This would also allow the creation of visual channels using the API as opposed just invisible channels.
3. In conjunction with our other request - Allow Desktop Agent To Join Multiple Channels #242 - this would allow a component to not lose user connected channels when the API connects the desktop agent to another channel.

PR: #244

[rikoe]

I think the issue here is that display metadata was intended to only apply to "system" or "public" channels. createChannel by definition creates "private" app channels which aren't meant to show up in a picker, and hence don't have display metadata.

We could change this, but we would have first to agree to change the semantics of system vs. app channels for that.

The way that I would instead see this work, is that if your framework allows dynamic creation of system channels (i.e. visible channels exposed through getSystemChannels() you should provide an fdc3 extension for that. If we don't do this, there would be an inconsistency where a channel shows up in the picker because createChannel was called, but is not returned by the getSystemChannels call.

[nkolba]

Seconding @rikoe 's comments here. Visual channels are supposed to be system channels. Systems (i.e. desktop agents) can allow for extensions to their registry of these channels as they see fit.

[kriswest]

I think the issue here is that display metadata was intended to only apply to "system" or "public" channels. createChannel by definition creates "private" app channels which aren't meant to show up in a picker, and hence don't have display metadata.

@rikoe @nkolba The DesktopAgent can join those private channels (programmatically) currently, which would force them to leave any system channel they are currently joined to and the current specification states that 'Always, there SHOULD be a clear UX indicator of what channel an app is joined to.'. If you show no indication (because you have no display metadata) you are not telling the user they will be leaving that invisible channel if they select another... To be fully internally consistent the spec would need to either:

• modify the above quoted statement to define behaviour when joined to a non-system channel
• specify that you can't join non-system channels
• be extended with some combination of the following:
  • allow the creation of system channels (with display metadata),
  • allow the creation of non-system channels (with display metadata - thats only displayed when code programmically joined you to it)
  • allow creation of non-system channels without display metadata which you can't join

In terms of usecases, consider integration with a large vendor app (e.g. an OMS) with an existing non-FDC3 channel system (there are a few) that doesn't match up with the Desktop Agent's set. The OMS wshes to create some additional system channels representing its internal channels for apps under the desktop agent to join - and for those links to be created by the user. At present there are only two options:

• build a patch panel that bridges the external app channels to desktop agent channels (clunky, but what we're currently doing)
• join the channels programmatically - requiring forknowledge of the channel names (doesn't enable interop without prior coordination between vendors).

While we can happily knock-out an extension to allow system channels to be added, that will mean the standard is missing what we are starting to see as a common use-case for the vendors most likely to be used under multiple desktop agent implementations. We'd be interested to discuss further. Having written this I realise the above proposal may need to be extended further (along the lines of the above bullets).

[rikoe]

@kriswest @sgd2z I think the issue here is that you would like to do something not supported by the current spec (i.e. a new requirement).

As I understand the requirement, it is: "allow applications to request new system channels from the desktop agent, which will have visual representation, and can be used in channel pickers".

I think this is a perfectly fine requirement, which we should consider. I have some questions about display metadata which now becomes an input parameter, not information about existing channels, and all the implications of that (e.g. what if different visual metadata is requested/provided by different parties).

The line from the spec you reference (Always, there SHOULD be a clear UX indicator of what channel an app is joined to) is in my view referring exclusively to the "join" APIs, which afaik only applies to system channels, as it is being discussed under the "joining channels" section of the specification. I agree that the spec can be clearer in this regard.

I do not think extending the getOrCreateChannel call with display metadata, as proposed in #244, is a good one. This API is intended for creating app channels (or "private" channels, as I still like to call them) - channels that only exist at an API-level. The call can also be used to retrieve system channels by name (if the name is known).

During the 1.1 release timeframe, we tried very hard to create a unified channel API that caters for two discrete use cases:

• Coloured channel linking via a channel selector in desktop agents. This is supported for one channel only, as no one was asking for multiple channels at the time, and the standards group thought it would add unnecessary complexity
• The ability to create "private", application-specific channels that allows two applications who both know the channel name by mutual agreement, to exchange context types without user interaction.

I hope you can agree that extending the getOrCreateChannel API with input display metadata as you suggest, significantly muddies the waters between these two uses cases, and a separate, less ambiguous API may be more beneficial.

@nkolba is anything I've said above massively off-base?

[kriswest]

@rikoe we're not getting from the spec as written that you shouldn't be able to fdc3.joinChannel to a non-system channel. Hence, you can do so programmatically in our implementation, which knocks you off any user-selected channel (as at present you can only join one channel). We figure this may be confusing to a user. If we're doing it wrong I'd love to know and get some clarification into the API docs for fdc3.joinChannel.

@rikoe rather than splitting into two APIs, what about making the public/private decision more explicit:
getOrCreateChannel(channelId: string, private: boolean = true, displayMetadata?: DisplayMetadata): Promise<Channel>;
(which is backwards compatible with the current API, but requires additional args to create a visible channel)

[nkolba]

@rikoe @kriswest

Some comments:

1. The spec doesn't weigh in on whether or not an app can be joined to an app/private channel by design. The short explanation being that this didn't seem like a convention worth enforcing.
2. One of the key points of app channels is that they don't appear in the system channels list. A key point about system channels is that they are trusted to come from the desktop agent. If an app can arbitrarily declare displayMetadata for a channel it creates and have it appear in a list alongside system channels this would defeat the purpose of this distinction.
3. We discussed multiple-channel membership in 1.1. The conclusion was that use cases where an app was listening (or broadcasting) to multiple channels had a number of complex UX considerations that were better managed by the listener/broadcast apis than join. For example, if a chart is mapping multiple color channels to different plots its rendering.
4. The primary purpose of the joinChannel method is that the app will receive the channel context over the global contextListener. Also, if an app is joined to a channel by UI outside of its control (e.g. a toolbar owned by the desktop agent) it will receive the context over its global contextListener - and the app developer doesn't need to code anything specific around channel management. If an app can be joined to multiple channels, these scenarios become much more complicated.

[sgd2z]

@nkolba

1. Since it is not enforced, we get into our current problem. Either we go out of spec and enforce that or we run into the problems we are running into now. Also if we enforce FDC3 system channels and disallow the creation of more channels that are not user selectable it gets very difficult to get proper integration of systems that already have their own visual channels.
2. I think the point here of system vs app channels makes sense. However, it makes more sense to differentiate channels as user selectable vs not user selectable. Because otherwise we get into scenarios which are confusing in practical usage. The end user doesn't really care about "system" or "app". They care more about joinable vs not joinable. If the point is that system channels are joinable but app channels are not, that should be explicit. And there should be some mechanism to add system channels.
3. The proposed use case in our multi channel issue has no complex UX considerations. In fact, not doing so and trying to work around the inability to join multiple channels has more complex UX considerations as Kris described before and is confusing to end users.
4. I'm not really sure I understand this. The app developer doesn't need to code anything about joining multiple channels anyway. They just call desktopAgent.addContextListener() and they just get the context broadcasted on all channels they are joined to. In fact, currently the platform provider has to write a lot of code that makes no sense - like joinchannel calling leave channel on the previous channel. This will make things simpler for both platform provider and the end app developer and less confusing to the end user - channels won't be toggles anymore. At the same time it will allow different applications that already have some kind of color channel concept to better integrate with other things.

[sgd2z]

@nkolba @rikoe @kriswest
I'm working on PRs for all the issues I've submitted for 1.2 and for this one, here is a poll:

1. Allow creation of system channels via API (so DisplayMetadata can be specified for new channels). Explicitly disallow joining app channels.

2. Optionally allow specification of DisplayMeta for App channels and allow joining any channels with DisplayMetadata specified.

[nkolba]

@sgd2z

Unfortunately, I wouldn't vote for either option. Option #1 has real security implications, as an app would be able to create a system channel via a client API. #2 - as @rikoe points out - blurs the line between system and app channels and essentially creates a backdoor to the same problem we have with option #1.

I would point out that if your DesktopAgent wants to allow apps to register system channels - there is nothing preventing you from exposing an API within your DA to do so.

If there's no further activity on this Issue and related PR - I'd recommend we close for now. We can always revise the discussion post -1.2 and perhaps when we have more use cases.

-Nick

[nicholasdgoodman]

I know this is a nearly-closed issue, but I would chime in with @sgd2z here that I see no compelling reason to make such a strong distinction between system channels and app channels; although this discussion treats these categories as some form of public / private segmentation, there is nothing in the spec that states explicitly or implicitly that app channels app channels should be hidden to the end user, and that they cannot be joined.

Our implementation allows joining to app-defined channels, and there is no reason to suggest that this means they have to be discoverable system wide and affect the getSystemChannels API in any way. Apps leveraging this capability would have in-app channel management, and are able to display a superset of the channels that are available on the system.

This is not a hypothetical scenario, either; we have customers who want to leverage FDC3 for user-controlled context sharing but also have the option to sometimes restrict the channel linking to within their suite of applications.

[rikoe]

I don't think the issue is that we want to prevent it, but that there is no way currently to distinguish between app channels that are being displayed (or intended for display) and ones that aren't.

App channels were intended to be private in 1.1, that is the use case they are trying to meet - background exchange of data.

What this rather sounds like is there is a third use case (beyond well-known, predefined system channels, and private app channels), which is on-demand, or custom, system-wide channels.

If that use case exists, let's try and support it properly in the API, instead of shoe-horning the concept of display metadata into app channels...

[nicholasdgoodman]

To clarify, our use case is not custom system wide channels; but rather "joinable private channels"; although, I do think the adding to the global channel list is another feature worth considering.

There are two independent facets to consider:

1. Public vs Private (Discoverability): Currently system channels are discoverable and implicitly public, whereas app channels are not discoverable therefore implicitly private. There is currently no means to create an app channel that can be discovered by other apps, and this capability warrants further discussion as I believe it is a valid use case - separate to this discussion.

2. Joinable / Visually Displayed: The Channel interface allows for display metadata to be defined; however, the only API for creating channel instances, getOrCreateChannel, lacks this capability. Whether or not a given channel is displayed in a channel selector and therefore user-joinable, can be simply controlled by the presence or absence of this metadata.

External channel managers would simply omit app channels (since they are not discoverable), but in-app channel managers can display all known app channels that have defined display metadata.

This doesn't seem to be shoehorning to me, as predefined system channels are just a special case of an app channel, and not a wholly different class of entities. I believe this request is both logical and consistent with the API at large, and offers a great deal of expanded functionality with little cost or risk to implementers.

[nkolba]

@nicholasdgoodman you are correct that nothing in the spec states that app channels should be hidden from the end user or can't be joined.

I don't see any reason why an in-app channel manager couldn't display app channels known to it along with system channels and allow end users to join the app channels.

The main question here is whether apps should be able to self-declare their own display metadata when declaring app channels. This seems a separate concern - there are trust issues here as well as just issues of consistency and contention of colors and other markers for a channel.

The example UI you included above - showing app channels extending the system channel menu - could be done today using the existing 1.1 APIs. This doesn't require the app channels to declare their own metadata - indeed, you show the app channels with uniform styling - which helps to distinguish them from the system channels.

[sgd2z]

The example UI you included above - showing app channels extending the system channel menu - could be done today using the existing 1.1 APIs. This doesn't require the app channels to declare their own metadata - indeed, you show the app channels with uniform styling - which helps to distinguish them from the system channels.

That is not the full UI. The UI also includes showing joined channels on something like a window titlebar (not just in the channel joiner) and it will be janky to show some color channels and some letter channels. The end user does not need to know the distinction between system and app channels. This arbitrary distinction created by us just makes FDC3 more confusing for the end user. What does it mean to join a pink channel vs Channel A? There is no practical difference and showing those things differently is just problematic

The main question here is whether apps should be able to self-declare their own display metadata when declaring app channels. This seems a separate concern - there are trust issues here as well as just issues of consistency and contention of colors and other markers for a channel.

Contention of colors is not a big deal, just fail the channel creation. FDC3 currently doesn't deal with the trust issues at all. Also I dont understand how showing a channel as A vs pink removes trust issues? What are we telling the user? Don't do this because these channels are untrusted?

I don't see any reason why an in-app channel manager couldn't display app channels known to it along with system channels and allow end users to join the app channels.

This is exactly what we are asking to be made part of the spec so "in-app channel manager" is consistent across compliant systems.

[nicholasdgoodman]

Sorry, I do not mean to over-emphasize the juxtaposition of color-named channels and letter-named channels. That was an extreme example. The actual request we received was to only show internally defined app channels. Without display metadata, container providers have no standard way to enable app writers to define joinable app channels.

This request is driven by institutional clients who are interested in leveraging FDC3 for internal interop, but not with third-party vendors. Of course, wanting to leverage FDC3 for "closed communication" may be antithetical to desktop interop as a concept... but this was the actual feedback we had received.

Disclaimer: I no longer represent any official implementations of FDC3

[kriswest]

After the Channels, Feeds & Transactions working group we've decided to close this issue and instead focus on refining the definition of channel types #376 and other extensions to the spec to enable additional interop use- cases.