Rename 'System Channels' 'User Channels'

[kriswest]

Output from the Channels, Feeds & Transactions discussion group: #420
Supercedes issues: #376

The FDC3 spec defines two types of channels:

• System Channels
• App Channels

The name 'System channels' causes some confusion when people first encounter the FDC3 specification. I believe the name was originally derived from the fact that the 'system' or desktop agent creates these channels, whereas app channels are created by apps. Their intended purpose is to support user-controlled context linking between components (aka colour channel linking).

However, the 'system' could also create App channels, to be used for other purposes - these should not be returned by the fdc3.getSystemChannels function, nor used with the fdc.joinChannel function.

It is suggested that the channels used for colour channel linking are renamed according to the usage, becoming 'user channels', whose purpose is therefore much easier to understand. Doing so would involve:

• Updating the specification to define 'User channels'
• Updating the documentation to use the revised term
• (possibly) renaming the fdc3.getSystemChannels() function to getUserChannels (deprecate the existing function but leave it in place for backwards compatibility).
• (possibly) add to the specification that the desktop agent can only call fdc3.joinChannel with a user channel (not an app channel)

[kriswest]

Recommendation from discussion group:

• Also rename joinChannel -> joinUserChannel and deprecate joinChannel

[Qiana-Citi]

@kriswest I do have some queries about the possible/potential changes.

1. As we know, the global channel is used for backward compatibility, if it's deprecated in the future, how to get all existing apps to join channels explicitly without any changes on app side?

2. Still the issue of backward compatibility, some of our downstream apps are already using the APIs of FDC3 v1.2, so renaming joinChannel to joinUserChannel will require code changes on app side. Please refer to my comments in #431, some of our downstream apps are joining/leaving app channels rather than user channels.

3. Does it mean that apps cannot call joinChannel to join a system channel? If so, how should I understand the wording ‘an app or system channel should be joined explicitly through the relevant APIs’ in https://fdc3.finos.org/docs/next/api/spec#the-global-channel.

However, the 'system' could also create App channels, to be used for other purposes - these should not be returned by the fdc3.getSystemChannels function, nor used with the fdc.joinChannel function.

[kriswest]

Hi @Qiana-Citi

1. As we know, the global channel is used for backward compatibility, if it's deprecated in the future, how to get all existing apps to join channels explicitly without any changes on app side?

This is already possible via a desktop agent's UI for selecting channels, allowing the user to select the channel (since FDC3 1.1). The functionality of fdc3.broadcast and fdc3.addContextListener remain the same - hence no code changes should be required.

What is different is that the (global) channel is not automatically selected (and there is currently no standard way to express a default channel selection, e.g. through an appD config). The default selection of global channel was already optional from FDC3 1.1 (note the keyword MAY in the specification) and deprecated in FDC3 1.2. A number of users of the standard found it confusing as (where supported) all applications were initially on the global channel, but after joining another channel and leaving were on no channel (this is defined in the specification), leading behaviour to sometimes be inconsistent with UI and user expectations (particularly if the implementation chose to "filter out the 'global' option in their UI for system channel pickers" as was allowed by the spec.

2. Still the issue of backward compatibility, some of our downstream apps are already using the APIs of FDC3 v1.2, so renaming joinChannel to joinUserChannel will require code changes on app side. Please refer to my comments in Make optional: fdc3.joinChannel and fdc3.leaveChannel #431, some of our downstream apps are joining/leaving app channels rather than user channels

The proposed rename of joinChannel to joinUserChannel would only deprecate joinChannel in 2.0, it would be expected to remain (as an alias of joinUserChannel) until at least an FDC3 3.0 version someday in the future, allowing plenty of time for any required code changes.

Although it is poorly defined in the specification, it was never intended (I'm told) that apps be allowed to join App channels, rather they should retrieve the channel object via fdc3.getOrCreateChannel and interact with it directly. This was discussed extensively through the working group as the lack of DisplayMetadata for app channels meant there were differences displaying an app channel that you've 'joined' in the channel selector UI (note: these channels are not supposed to be 'discoverable' either) and programmatically joining app channels would cause you to leave user selected channels (which most consider to be a poor UX decision).

See issue #243 for the discussion. That discussion gave rise to this issue which intends to clarify the naming (and description of expected behaviour) in the specification.

3. Does it mean that apps cannot call joinChannel to join a system channel? If so, how should I understand the wording ‘an app or system channel should be joined explicitly through the relevant APIs’ in https://fdc3.finos.org/docs/next/api/spec#the-global-channel.

No, an app should be able to call fdc3.joinUserChannel to join (what would be renamed from 'System Channels' to) 'User Channels', and (until it is removed someday in the future) can expect the same behaviour from fdc3.joinChannel (which will be an alias to fdc3.joinUserChannel for backwards compatibility. However, after this change an app should not expect to be able to use those functions to join an 'App channel' (which would be clarified in the specification).

[MichaelMCoates]

On the topic of clarifying behavior around getOrCreateChannel, if we're saying that joinUserChannel is for User Channels and not App Channels, can we also say that getOrCreateChannel is solely for App Channels and shouldn't be a way to connect to a User Channel? The conflation of the two can be confusing, and also makes implementation more complicated.

[kriswest]

On the topic of clarifying behavior around getOrCreateChannel, if we're saying that joinUserChannel is for User Channels and not App Channels, can we also say that getOrCreateChannel is solely for App Channels and shouldn't be a way to connect to a User Channel? The conflation of the two can be confusing, and also makes implementation more complicated.

Happy to talk through that (and largely agree). Can you raise a new issue with details and perhaps a proposal?