Merge pull request #727 from finos/717-recommended-channels

717 Add a recommended set of user channels to the Standard

CHANGELOG.md

@@ -22,6 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added a Trademarks page to website to acknowledge trademarks used within the Standard not owned by FINOS or the Linux Foundation ([#534](https://github.com/finos/FDC3/pull/534))
 * Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
 * Added a new experimental features policy, which exempts features designated as experimental from the versioning and deprecation policies, to the FDC3 compliance page ([#549](https://github.com/finos/FDC3/pull/549))
+* Added a recommended set of user channel definitions to the API docs and typescript sources ([#727](https://github.com/finos/FDC3/pull/726))
 * Added the optional exposure of originating app metadata to messages received via `addContextListener` and `addIntentListener` via the new `ContextMetadata` type. ([#725](https://github.com/finos/FDC3/pull/725))
 * Added the current app's `AppMetadata` to the `ImplementationMetadata` returned by `fdc3.getInfo()` allowing an app to retrieve its own metadata, according to the Desktop Agent ([#726](https://github.com/finos/FDC3/pull/726))
 * Added a context type representing a range of time (`fdc3.timerange`). ([#706](https://github.com/finos/FDC3/pull/706))

docs/api/spec.md

@@ -374,7 +374,90 @@ Calling `fdc3.broadcast` will now route context to the joined channel.
 
 Channel implementations SHOULD ensure that context messages broadcast by an application on a channel are not delivered back to that same application if they are joined to the channel.
 
-  > Prior to FDC3 2.0, 'user' channels were known as 'system' channels. They were renamed in FDC 2.0 to reflect their intended usage, rather than the fact that they are created by system (which could also create 'app' channels). The `joinChannel` function was also renamed to `joinUserChannel` to clarify that it is only intended to be used to join 'user', rather than 'app', channels.
+  > Prior to FDC3 2.0, 'user' channels were known as 'system' channels. They were renamed in FDC3 2.0 to reflect their intended usage, rather than the fact that they are created by system (which could also create 'app' channels). The `joinChannel` function was also renamed to `joinUserChannel` to clarify that it is only intended to be used to join 'user', rather than 'app', channels.
+
+### Recommended User Channel Set
+
+Desktop Agent implementations SHOULD use the following set of channels, to enable a consistent user experience across different implementations. Desktop Agent implementation MAY support configuration of the user channels.
+
+> Note: Future versions of the FDC3 Standard may support connections between desktop agents, where differing user channel sets may cause user experience issues.
+
+```javascript
+const recommendedChannels = [
+  {
+    id: 'fdc3.channel.1',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 1',
+      color: 'red',
+      glyph: '1',
+    },
+  },
+  {
+    id: 'fdc3.channel.2',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 2',
+      color: 'orange',
+      glyph: '2',
+    },
+  },
+  {
+    id: 'fdc3.channel.3',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 3',
+      color: 'yellow',
+      glyph: '3',
+    },
+  },
+  {
+    id: 'fdc3.channel.4',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 4',
+      color: 'green',
+      glyph: '4',
+    },
+  },
+  {
+    id: 'fdc3.channel.5',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 5',
+      color: 'cyan',
+      glyph: '5',
+    },
+  },
+  {
+    id: 'fdc3.channel.6',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 6',
+      color: 'blue',
+      glyph: '6',
+    },
+  },
+  {
+    id: 'fdc3.channel.7',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 7',
+      color: 'magenta',
+      glyph: '7',
+    },
+  },
+  {
+    id: 'fdc3.channel.8',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 8',
+      color: 'purple',
+      glyph: '8',
+    },
+  },
+];
+```
 
 ### Direct Listening and Broadcast on Channels
 
@@ -422,9 +505,10 @@ if another application broadcasts to "my_custom_channel" (by retrieving it and b
 `PrivateChannels` are created to support the return of a stream of responses from a raised intent, or private dialog between two applications.
 
 It is intended that Desktop Agent implementations:
-  - - SHOULD restrict external apps from listening or publishing on this channel.
-  - - MUST prevent `PrivateChannels` from being retrieved via `fdc3.getOrCreateChannel`.
-  - - MUST provide the `id` value for the channel as required by the `Channel` interface.
+
+- SHOULD restrict external apps from listening or publishing on this channel.
+- MUST prevent `PrivateChannels` from being retrieved via `fdc3.getOrCreateChannel`.
+- MUST provide the `id` value for the channel as required by the `Channel` interface.
 
 The `PrivateChannel` type also supports synchronisation of data transmitted over returned channels. They do so by extending the `Channel` interface with event handlers which provide information on the connection state of both parties, ensuring that desktop agents do not need to queue or retain messages that are broadcast before a context listener is added and that applications are able to stop broadcasting messages when the other party has disconnected.
 

src/api/RecommendedChannels.ts

@@ -0,0 +1,90 @@
+/**
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright FINOS FDC3 contributors - see NOTICE file
+ */
+
+import { DisplayMetadata } from './DisplayMetadata';
+
+/** Interface representing the data fields of a user channel, without the functions. */
+interface UserChannelTemplate {
+  readonly id: string;
+  readonly type: 'user';
+  readonly displayMetadata?: DisplayMetadata;
+}
+
+const recommendedChannels: Array<UserChannelTemplate> = [
+  {
+    id: 'fdc3.channel.1',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 1',
+      color: 'red',
+      glyph: '1',
+    },
+  },
+  {
+    id: 'fdc3.channel.2',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 2',
+      color: 'orange',
+      glyph: '2',
+    },
+  },
+  {
+    id: 'fdc3.channel.3',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 3',
+      color: 'yellow',
+      glyph: '3',
+    },
+  },
+  {
+    id: 'fdc3.channel.4',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 4',
+      color: 'green',
+      glyph: '4',
+    },
+  },
+  {
+    id: 'fdc3.channel.5',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 5',
+      color: 'cyan',
+      glyph: '5',
+    },
+  },
+  {
+    id: 'fdc3.channel.6',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 6',
+      color: 'blue',
+      glyph: '6',
+    },
+  },
+  {
+    id: 'fdc3.channel.7',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 7',
+      color: 'magenta',
+      glyph: '7',
+    },
+  },
+  {
+    id: 'fdc3.channel.8',
+    type: 'user',
+    displayMetadata: {
+      name: 'Channel 8',
+      color: 'purple',
+      glyph: '8',
+    },
+  },
+];
+
+export default recommendedChannels;

src/index.ts

@@ -19,6 +19,7 @@ export * from './api/IntentResolution';
 export * from './api/Listener';
 export * from './api/ImplementationMetadata';
 export * from './api/Methods';
+export * from './api/RecommendedChannels';
 export * from './context/ContextType';
 export * from './context/ContextTypes';
 export * from './intents/Intents';

website/blog/2017-09-25-testing-rss.md

@@ -9,3 +9,4 @@ authorFBID: 661277173
 This should be truncated.
 <!--truncate-->
 This line should never render in XML.
+