717 Add a recommended set of user channels to the Standard

CHANGELOG.md

@@ -16,12 +16,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added a field to specify the Context type that intent can return to the AppD Application schema and extended the findIntent API calls to be able to use it for resolution. ([#499](https://github.com/finos/FDC3/pull/499))
 * Added the ability to return a Channel from an intent (via the `IntentResult` type), resolver support for intents that return Channels and the concept of PrivateChannels. ([#508](https://github.com/finos/FDC3/pull/508))
 * Added error `UserCancelled` to the `ResolveError` enumeration to be used when user closes the resolver UI or otherwise cancels resolution of a raised intent ([#522](https://github.com/finos/FDC3/pull/522))
-* Added `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
+* Added error `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
 * Added an `instanceId` (and optional `instanceMetadata`) field to `AppMetadata` allowing it to refer to specific app instances and thereby supporting targetting of intents to specific app instances. Also added a `findInstances()` function to the desktop agent and `TargetAppUnavailable` and `TargetInstanceUnavailable` Errors to the `ResolveError` enumeration. ([#509]((https://github.com/finos/FDC3/pull/509))
 * Added a References and Bibliography section to the Standard's documentation to hold links to 'normative references' and other documentation that is useful for understanding the standard ([#530](https://github.com/finos/FDC3/pull/530))
 * 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 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))
 * Added a context type representing a Currency (`fdc3.currency`). ([#708](https://github.com/finos/FDC3/pull/708))

docs/api/spec.md

@@ -367,7 +367,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
 
@@ -415,9 +498,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

@@ -18,6 +18,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.
+