430 Rename System channels User channels to reflect usage

CHANGELOG.md

@@ -24,6 +24,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Upgraded web access statements from SHOULD to MUST in the API specification ([#440](https://github.com/finos/FDC3/pull/440))
 * Updated copyright notices ([#467](https://github.com/finos/FDC3/pull/467))
 * Adjusted wording in API spec and documentation to acknowledge the possibility of methods of intent resolution other than a resolver UI ([#461](https://github.com/finos/FDC3/pull/461))
+* Replaced 'System channels' with 'User channels' throughout the spec, documentation, API and methods.ts. Clarified spec and documentation where it is referring to User channels vs. App channels. Added support to methods.ts for automatic fallback to `getSystemChannels` if `getUserChannels` doesn't exist. ([#470](https://github.com/finos/FDC3/pull/479))
 * Moved the Icon type definition into the Types documentation page for consistency with other types. ([#493](https://github.com/finos/FDC3/pull/493)
 * The `fdc3.joinChannel()`, `fdc3.getCurrentChannel()` and `fdc3.leaveCurrentChannel()` functions have been made optional for FDC3 API compliance, but are recommended through the application of the SHOULD keyword. ([#512](https://github.com/finos/FDC3/pull/512)) 
 * All DesktopAgent and Channel API functions are now async for consistency, changing the return type of the `broadcast`, `addIntentListener`, `addContextListener` and `getInfo` functions ([#516](https://github.com/finos/FDC3/pull/516))

docs/api/ref/Channel.md

@@ -8,7 +8,7 @@ hide_title: true
 
 Represents a context channel that applications can join to share context data.
 
-A channel can be either a well-known "system" channel (retrieved with [`getSystemChannels`](DesktopAgent#getsystemchannels)) or a custom "app" channel (obtained through [`getOrCreateChannel`](DesktopAgent#getorcreatechannel)).
+A channel can be either a "User" channel (retrieved with [`getUserChannels`](DesktopAgent#getuserchannels)) or a custom "App" channel (obtained through [`getOrCreateChannel`](DesktopAgent#getorcreatechannel)).
 
 Channels each have a unique identifier, some display metadata and operations for broadcasting context to other applications, or receiving context from other applications.
 
@@ -34,9 +34,9 @@ interface Channel {
 
 * [`Context`](Types#context)
 * [`Listener`](Types#listener)
-* [`DesktopAgent.getSystemChannels`](DesktopAgent#getsystemchannels)
+* [`DesktopAgent.getUserChannels`](DesktopAgent#getuserchannels)
 * [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel)
-* [`DesktopAgent.joinChannel`](DesktopAgent#joinchannel)
+* [`DesktopAgent.joinUserChannel`](DesktopAgent#joinuserchannel)
 
 ## Properties
 
@@ -46,7 +46,7 @@ interface Channel {
 public readonly id: string;
 ```
 
-Uniquely identifies the channel. It is either assigned by the desktop agent (system channel) or defined by an application (app channel).
+Uniquely identifies the channel. It is either assigned by the desktop agent (User Channel) or defined by an application (App Channel).
 
 ### `type`
 
@@ -62,7 +62,7 @@ Can be _system_ or _app_.
 public readonly displayMetadata?: DisplayMetadata;
 ```
 
-DisplayMetadata can be used to provide display hints for channels intended to be visualized and selectable by end users.
+DisplayMetadata can be used to provide display hints for User Channels intended to be visualized and selectable by end users.
 
 #### See also
 * [`DisplayMetadata`](Metadata#displaymetadata)
@@ -133,7 +133,7 @@ instrumentListener.unsubscribe();
 public broadcast(context: Context): Promise<void>;
 ```
 
-Broadcasts a context on the channel. This function can be used without first joining the channel, allowing applications to broadcast on channels that they aren't a member of.
+Broadcasts a context on the channel. This function can be used without first joining the channel, allowing applications to broadcast on both App Channels and User Channels that they aren't a member of.
 
 If the broadcast is denied by the channel or the channel is not available, the method will return an `Error` with a string from the [`ChannelError`](ChannelError) enumeration.
 

docs/api/ref/DesktopAgent.md

@@ -22,7 +22,7 @@ interface DesktopAgent {
   broadcast(context: Context): Promise<void>;
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
   /**
-   * @deprecated 'Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
+   * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)`
    */
   addContextListener(handler: ContextHandler): Promise<Listener>;
 
@@ -35,14 +35,23 @@ interface DesktopAgent {
 
   // channels
   getOrCreateChannel(channelId: string): Promise<Channel>;
-  getSystemChannels(): Promise<Array<Channel>>;
+  getUserChannels(): Promise<Array<Channel>>;
   // optional channel management functions
-  joinChannel(channelId: string) : Promise<void>;
+  joinUserChannel(channelId: string) : Promise<void>;
   getCurrentChannel() : Promise<Channel | null>;
   leaveCurrentChannel() : Promise<void>;
 
   //implementation info
   getInfo(): Promise<ImplementationMetadata>;
+
+  /**
+   * @deprecated Use `getUserChannels()` instead of `getSystemChannels()`
+   */
+  getSystemChannels(): Promise<Array<Channel>>;
+  /**
+   * @deprecated Use `joinUserChannel()` instead of `joinChannel()`
+   */
+  joinChannel(channelId: string) : Promise<void>;
 }
 ```
 
@@ -59,9 +68,7 @@ addContextListener(handler: ContextHandler): Promise<Listener>;
 ```
 Adds a listener for incoming context broadcasts from the Desktop Agent. If the consumer is only interested in a context of a particular type, they can specify that type. If the consumer is able to receive context of any type or will inspect types received, then they can pass `null` as the `contextType` parameter to receive all context types. 
 
-Context broadcasts are only received from apps that are joined to the same channel as the listening application, hence, if the application is not currently joined to a channel no broadcasts will be received. 
-
-If this function is called after the app has joined a channel and the channel already contains context that would be passed to the context listener, then it will be called immediately with that context. If a listener is added first and then the app is joined to a channel, with current context that would be passed to the context listener, then the listener will again be called immediately with that context.
+Context broadcasts are only received from apps that are joined to the same User Channel as the listening application, hence, if the application is not currently joined to a User Channel no broadcasts will be received. If this function is called after the app has already joined a channel and the channel already contains context that would be passed to the context listener, then it will be called immediately with that context.
 
 #### Examples
 ```js
@@ -105,7 +112,7 @@ const listener = await fdc3.addIntentListener('StartChat', context => {
 broadcast(context: Context): Promise<void>;
 ```
 
-Publishes context to other apps on the desktop.  Calling `broadcast` at the `DesktopAgent` scope will push the context to whatever `Channel` the app is joined to.  If the app is not currently joined to a channel, calling `fdc3.broadcast` will have no effect.  Apps can still directly broadcast and listen to context on any channel via the methods on the `Channel` class.
+Publishes context to other apps on the desktop.  Calling `broadcast` at the `DesktopAgent` scope will push the context to whatever _User Channel_ the app is joined to.  If the app is not currently joined to a channel, calling `fdc3.broadcast` will have no effect.  Apps can still directly broadcast and listen to context on any channel via the methods on the `Channel` class.
 
 DesktopAgent implementations should ensure that context messages broadcast to a channel by an application joined to it are not delivered back to that same application.
 
@@ -251,11 +258,10 @@ If the resolution fails, the promise will return an `Error` with a string from t
 getCurrentChannel() : Promise<Channel | null>;
 ```
 
-Optional function that returns the `Channel` object for the current channel membership.  In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. 
+Optional function that returns the `Channel` object for the current User channel membership.  In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly. 
 
 Returns `null` if the app is not joined to a channel.
 
-
 #### Examples
 
 ```js
@@ -299,15 +305,15 @@ if (fdc3.getInfo && versionIsAtLeast(await fdc3.getInfo(), "1.2")) {
 getOrCreateChannel(channelId: string): Promise<Channel>;
 ```
 
-Returns a Channel object for the specified channel, creating it (as an _App_ channel) - if it does not exist.
+Returns a Channel object for the specified channel, creating it (as an _App Channel_) - if it does not exist.
 `Error` with a string from the [`ChannelError`](ChannelError) enumeration if channel could not be created or access was denied.
 
 #### Example
 
 ```js
 try {
   const myChannel = await fdc3.getOrCreateChannel("myChannel");
-  const myChannel.addContextListener(null, context => {});
+  myChannel.addContextListener(null, context => { /* do something with context */});
 }
 catch (err){
   //app could not register the channel
@@ -318,30 +324,42 @@ catch (err){
 #### See also
 *  [`Channel`](Channel)
 
-### `getSystemChannels`
+### `getUserChannels`
 ```ts
-getSystemChannels() : Promise<Array<Channel>>;
+getUserChannels() : Promise<Array<Channel>>;
 ```
-Retrieves a list of the System channels available for the app to join.
+
+Retrieves a list of the User Channels available for the app to join. 
 
 #### Example
 
 ```js
-const systemChannels = await fdc3.getSystemChannels();
-const redChannel = systemChannels.find(c => c.id === 'red');
+const userChannels = await fdc3.getUserChannels();
+const redChannel = userChannels.find(c => c.id === 'red');
 ```
 
 #### See also
 * [`Channel`](Channel)
 
+### `getSystemChannels`
+```ts
+/**
+ * @deprecated Use `getUserChannels` instead.
+ */
+getSystemChannels() : Promise<Array<Channel>>;
+```
+
+Alias to the [`getUserChannels`](#getuserchannels) function provided for backwards compatibility with version 1.1 & 1.2 of the FDC3 standard.
+#### See also
+* [`getUserChannels`](#getuserchannels)
 
-### `joinChannel`
+### `joinUserChannel`
 
 ```ts
-joinChannel(channelId: string) : Promise<void>;
+joinUserChannel(channelId: string) : Promise<void>;
 ```
 
-Optional function that joins the app to the specified channel. In most cases, applications SHOULD be joined to channels via UX provided to the application by the desktop agent, rather than calling this function directly.
+Optional function that joins the app to the specified User channel. In most cases, applications SHOULD be joined to channels via UX provided to the application by the desktop agent, rather than calling this function directly.
 
 If an app is joined to a channel, all `fdc3.broadcast` calls will go to the channel, and all listeners assigned via `fdc3.addContextListener` will listen on the channel. 
 
@@ -354,29 +372,42 @@ Rejects with an error if the channel is unavailable or the join request is denie
 #### Examples
 
 ```js
-// get all system channels
-const channels = await fdc3.getSystemChannels();
+// get all user channels
+const channels = await fdc3.getUserChannels();
 
-// create UI to pick from the system channels
+// create UI to pick from the User channels
 
 // join the channel on selection
-fdc3.joinChannel(selectedChannel.id);
+fdc3.joinUserChannel(selectedChannel.id);
 
 ```
 #### See also
-* [`getSystemChannels`](#getSystemChannels)
+* [`getUserChannels`](#getuserchannels)
 
 
+### `joinChannel`
+
+```ts
+/**
+   * @deprecated Use `joinUserChannel()` instead of `joinChannel()`
+   */
+joinChannel(channelId: string) : Promise<void>;
+```
+Alias to the [`joinUserChannel`](#joinUserChannel) function provided for backwards compatibility with version 1.1 & 1.2 of the FDC3 standard.
+
+#### See also
+* [`joinUserChannel`](#joinuserchannel)
+
 
 ### `leaveCurrentChannel`
 
 ```ts
 leaveCurrentChannel() : Promise<void>;
 ```
 
-Optional function that removes the app from any channel membership.  In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly.
+Optional function that removes the app from any User channel membership.  In most cases, an application's membership of channels SHOULD be managed via UX provided to the application by the desktop agent, rather than calling this function directly.
 
-Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be a no-op when the app is not joined to a channel.
+Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be a no-op when the app is not joined to a User channel.
 
 #### Examples
 

docs/api/ref/Errors.md

@@ -51,10 +51,10 @@ enum ChannelError {
 }
 ```
 
-Contains constants representing the errors that can be encountered when calling channels using the [`joinChannel`](DesktopAgent#joinchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object.
+Contains constants representing the errors that can be encountered when calling channels using the [`joinUserChannel`](DesktopAgent#joinuserchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object.
 
 #### See also
-* [`DesktopAgent.joinChannel`](DesktopAgent#joincannel)
+* [`DesktopAgent.joinUserChannel`](DesktopAgent#joinusercannel)
 * [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel)
 * [`Channel.broadcast`](Channel#broadcast)
 * [`Channel.addContextListener`](Channel#addcontextlistener)

docs/api/ref/Metadata.md

@@ -15,7 +15,7 @@ interface AppIntent {
 An interface that represents the binding of an intent to apps, returned as part of intent disocvery.
 For each intent, it reference the applications that support that intent.
 
-#### See also
+### See also
 * [`AppMetadata`](AppMetadata)
 * [`IntentMetadata`](IntentMetadata)
 * [`DesktopAgent.findIntent`](DesktopAgent#findintent)
@@ -65,14 +65,13 @@ Optionally, extra information from the app directory can be returned, to aid in
 
 In situations where a desktop agent connects to multiple app directories or multiple versions of the same app exists in a single app directory, it may be neccessary to specify appId and version to target applications that share the same name.
 
-`AppMetadata`
-
 #### See also
 * [`AppIntent.apps`](AppIntent)
 * [`Icon`](Icon)
 * [`DesktopAgent.findIntent`](DesktopAgent#findintent)
 * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
 
+
 ## `DisplayMetadata`
 
 ```ts
@@ -85,7 +84,7 @@ In situations where a desktop agent connects to multiple app directories or mult
 
 A desktop agent (typically for _system_ channels) may want to provide additional information about how a channel can be represented in a UI. A common use case is for color linking.
 
-#### Properties
+### Properties
 
 #### `name`
 
@@ -111,10 +110,10 @@ glyph: string;
 
 A URL of an image that can be used to display this channel.
 
-#### See also
+### See also
 
 * [`Channel`](Channel)
-* [`DesktopAgent.getSystemChannels`](DesktopAgent#getsystemchannels)
+* [`DesktopAgent.getUserChannels`](DesktopAgent#getuserchannels)
 
 ## `ImplementationMetadata`
 
@@ -128,7 +127,7 @@ public interface ImplementationMetadata {
 
 Metadata relating to the FDC3 [DesktopAgent](DesktopAgent) object and its provider, including the supported version of the FDC3 specification and the name of the provider of the implementation.
 
-#### See also
+### See also
 * [`DesktopAgent.getInfo`](DesktopAgent#getInfo)
 
 ## `IntentMetadata`
@@ -143,7 +142,7 @@ interface IntentMetadata {
 The interface used to describe an intent within the platform.
 
 
-#### See also
+### See also
 * [`AppIntent.intent`](AppIntent)
 
 ## `IntentResolution`
@@ -191,7 +190,7 @@ try {
 catch (err) { ... }
 ```
 
-#### See also
+### See also
 * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent)
 * [`DesktopAgent.raiseIntentForContext`](DesktopAgent#raiseintentforcontext)
 * [`TargetApp`](TargetApp)