diff --git a/CHANGELOG.md b/CHANGELOG.md index 48df1dd62..7456fde07 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,11 +17,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * 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 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 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 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)) @@ -42,6 +43,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added `localizedVersions` field to AppD application records to support localized versions of descriptive fields in the app records and alternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670)) * Added `type` and `details` elements to AppD application records to support vendor-agnostic launch details for both web and native apps ([#671](https://github.com/finos/FDC3/pull/671)) * Added `categories` field and recommended categories list to AppD application records to enable category based browsing of AppDs ([#673](https://github.com/finos/FDC3/pull/673)) +* Added an `interop` field to AppD application records, replacing the `intents` field, to more fully describe an app's use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697)) * Added `AppIdentifier` type, which is a new parent of `AppMetadata` and clarifies required fields for API call parameters which now prefer `appId` and `instanceId` over `name` ([#722](https://github.com/finos/FDC3/pull/722)) ### Changed @@ -62,6 +64,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * App Directory endpoint for searching applications was removed as searches over multiple app directories are better implemented by retrieving all the records and searching over the resulting combined dataset ([#696](https://github.com/finos/FDC3/pull/696)) * Extended Intent Naming conventions and added hyperlinks for existing Intent spec definitions ([#701](https://github.com/finos/FDC3/pull/701)) * Extended recommended field type conventions for contexts to include types for ids, times, dates, currency codes and country codes. The `fdc3.country` context type was updated to comply with the recommended field name for country codes (`COUNTRY_ISOALPHA2`). ([#704](https://github.com/finos/FDC3/pull/704)) +* The `intents` field of an AppD application records has been replaced with the `interop` field, to more fully describe an app's use of FDC3 and enable search for apps that 'interoperate' with a selected app ([#697](https://github.com/finos/FDC3/pull/697)) ### Deprecated diff --git a/docs/api/ref/Errors.md b/docs/api/ref/Errors.md index ad30be91a..76ab4070e 100644 --- a/docs/api/ref/Errors.md +++ b/docs/api/ref/Errors.md @@ -10,11 +10,18 @@ Some FDC3 API operations return promises that can result in errors. enum OpenError { /** Returned if the specified application is not found.*/ AppNotFound = 'AppNotFound', + /** Returned if the specified application fails to launch correctly.*/ ErrorOnLaunch = 'ErrorOnLaunch', - /** Returned if the specified application launches but fails to add a context listener in order to receive the context passed to the `fdc3.open` call.*/ + + /** Returned if the specified application launches but fails to add a context + * listener in order to receive the context passed to the `fdc3.open` call. + */ AppTimeout = 'AppTimeout', - /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/ + + /** Returned if the FDC3 desktop agent implementation is not currently able + * to handle the request. + */ ResolverUnavailable = 'ResolverUnavailable', } ``` @@ -22,25 +29,48 @@ enum OpenError { Contains constants representing the errors that can be encountered when calling the [`open`](DesktopAgent#open) method on the [DesktopAgent](DesktopAgent) object. #### See also + * [`DesktopAgent.open`](DesktopAgent#open) ## `ResolveError` ```typescript export enum ResolveError { - /** SHOULD be returned if no apps are available that can resolve the intent and context combination.*/ + /** SHOULD be returned if no apps are available that can resolve the intent + * and context combination. + */ NoAppsFound = 'NoAppsFound', - /** Returned if the FDC3 desktop agent implementation is not currently able to handle the request.*/ + + /** Returned if the FDC3 desktop agent implementation is not currently able + * to handle the request. + */ ResolverUnavailable = 'ResolverUnavailable', - /** Returned if the user cancelled the resolution request, for example by closing or cancelling a resolver UI.*/ + + /** Returned if the user cancelled the resolution request, for example by + * closing or cancelling a resolver UI. + */ UserCancelled = 'UserCancelledResolution', - /** SHOULD be returned if a timeout cancels an intent resolution that required user interaction. Please use `ResolverUnavailable` instead for situations where a resolver UI or similar fails.*/ + + /** SHOULD be returned if a timeout cancels an intent resolution that + * required user interaction. Please use `ResolverUnavailable` instead for + * situations where a resolver UI or similar fails. + */ ResolverTimeout = 'ResolverTimeout', - /** Returned if a specified target application is not available or a new instance of it cannot be opened. */ + + /** Returned if a specified target application is not available or a new + * instance of it cannot be opened. + */ TargetAppUnavailable = 'TargetAppUnavailable', - /** Returned if a specified target application instance is not available, for example because it has been closed. */ + + /** Returned if a specified target application instance is not available, + * for example because it has been closed. + */ TargetInstanceUnavailable = 'TargetInstanceUnavailable', - /** Returned if the intent and context could not be delivered to the selected application or instance, for example because it has not added an intent handler within a timeout.*/ + + /** Returned if the intent and context could not be delivered to the selected + * application or instance, for example because it has not added an intent + * handler within a timeout. + */ IntentDeliveryFailed = 'IntentDeliveryFailed', } ``` @@ -48,6 +78,7 @@ export enum ResolveError { Contains constants representing the errors that can be encountered when calling the [`findIntent`](DesktopAgent#findintent), [`findIntentsByContext`](DesktopAgent#findintentsbycontext), [`raiseIntent`](DesktopAgent#raiseintent) or [`raiseIntentForContext`](DesktopAgent#raiseintentforcontext) methods on the [DesktopAgent](DesktopAgent). #### See also + * [`DesktopAgent.findIntent`](DesktopAgent#findintent) * [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext) * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) @@ -57,9 +88,14 @@ Contains constants representing the errors that can be encountered when calling ```typescript enum ResultError { - /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context or Channel object. */ + /** Returned if the intent handler exited without returning a Promise or that + * Promise was not resolved with a Context or Channel object. + */ NoResultReturned = 'NoResultReturned', - /** Returned if the Intent handler function processing the raised intent throws an error or rejects the Promise it returned. */ + + /** Returned if the Intent handler function processing the raised intent + * throws an error or rejects the Promise it returned. + */ IntentHandlerRejected = 'IntentHandlerRejected', } ``` @@ -67,6 +103,7 @@ enum ResultError { Contains constants representing the errors that can be encountered when calling the [`getResult`](DesktopAgent#findintent) method on the [IntentResolution](Metadata#intentresolution) Object. #### See also + * [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener) * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) * [`IntentResolution`](Metadata#intentresolution) @@ -75,11 +112,20 @@ Contains constants representing the errors that can be encountered when calling ```typescript enum ChannelError { - /** Returned if the specified channel is not found when attempting to join a channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`).*/ + /** Returned if the specified channel is not found when attempting to join a + * channel via the `joinUserChannel` function of the DesktopAgent (`fdc3`). + */ NoChannelFound = 'NoChannelFound', - /** SHOULD be returned when a request to join a user channel or to a retrieve a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods of the DesktopAgent (`fdc3`) object is denied. */ + + /** SHOULD be returned when a request to join a user channel or to a retrieve + * a Channel object via the `joinUserChannel` or `getOrCreateChannel` methods + * of the DesktopAgent (`fdc3`) object is denied. + */ AccessDenied = 'AccessDenied', - /** SHOULD be returned when a channel cannot be created or retrieved via the `getOrCreateChannel` method of the DesktopAgent (`fdc3`).*/ + + /** SHOULD be returned when a channel cannot be created or retrieved via the + * `getOrCreateChannel` method of the DesktopAgent (`fdc3`). + */ CreationFailed = 'CreationFailed', } ``` @@ -87,6 +133,7 @@ enum ChannelError { 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.joinUserChannel`](DesktopAgent#joinuserchannel) * [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel) * [`Channel.broadcast`](Channel#broadcast) diff --git a/docs/api/ref/Metadata.md b/docs/api/ref/Metadata.md index 3a8c38798..54895f4a9 100644 --- a/docs/api/ref/Metadata.md +++ b/docs/api/ref/Metadata.md @@ -8,8 +8,11 @@ FDC3 API operations return various types of metadata. ```ts interface AppIntent { - /** Details of the intent whose relationship to resolving applications is being described. */ + /** Details of the intent whose relationship to resolving applications is + * being described. + */ readonly intent: IntentMetadata; + /** Details of applications that can resolve the intent. */ readonly apps: Array; } @@ -30,37 +33,51 @@ For each intent, it reference the applications that support that intent. ```ts interface AppMetadata extends AppIdentifier { /** - The 'friendly' app name. - This field was used with the `open` and `raiseIntent` calls in FDC3 <2.0, which now require an `AppIdentifier` wth `appId` set. - Note that for display purposes the `title` field should be used, if set, in preference to this field. + /** + * The 'friendly' app name. This field was used with the `open` and + * `raiseIntent` calls in FDC3 <2.0, which now require an `AppIdentifier` + * with `appId` set. + * + * Note that for display purposes the `title` field should be used, if set, + * in preference to this field. */ readonly name?: string; /** The version of the application. */ readonly version?: string; - /** An optional set of, implementation specific, metadata fields that can be used to disambiguate instances, such as a window title or screen position. Must only be set if `instanceId` is set. */ + /** An optional set of, implementation specific, metadata fields that can be + * used to disambiguate instances, such as a window title or screen position. + * Must only be set if `instanceId` is set. + */ readonly instanceMetadata?: Record; - /** A more user-friendly application title that can be used to render UI elements */ + /** A more user-friendly application title that can be used to render UI + * elements. + */ readonly title?: string; - /** A tooltip for the application that can be used to render UI elements */ + /** A tooltip for the application that can be used to render UI elements. */ readonly tooltip?: string; - /** A longer, multi-paragraph description for the application that could include mark-up */ + /** A longer, multi-paragraph description for the application that could + * include mark-up. + */ readonly description?: string; - /** A list of icon URLs for the application that can be used to render UI elements */ + /** A list of icon URLs for the application that can be used to render UI + * elements. + */ readonly icons?: Array; /** Images representing the app in common usage scenarios that can be used to render UI elements */ readonly screenshots?: Array; /** The type of result returned for any intent specified during resolution. - * May express a particular context type (e.g. "fdc3.instrument"), channel - * (e.g. "channel") or a channel that will receive a specified type - * (e.g. "channel"). */ + * May express a particular context type (e.g. "fdc3.instrument"), channel + * (e.g. "channel") or a channel that will receive a specified type + * (e.g. "channel"). + */ readonly resultType?: string | null; } ``` @@ -76,6 +93,7 @@ Note that as `AppMetadata` instances are also `AppIdentifiers` they may be passe * [`AppIdentifier`](Types#AppIdentifier) * [`AppIntent.apps`](#appintent) * [`Icon`](#icon) +* [`Image`](#image) * [`DesktopAgent.open`](DesktopAgent#open) * [`DesktopAgent.findIntent`](DesktopAgent#findintent) * [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) @@ -109,16 +127,17 @@ Metadata relating to a context or intent & context received through the `addCont ```ts interface DisplayMetadata { /** - * A user-readable name for this channel, e.g: `"Red"` - */ + * A user-readable name for this channel, e.g: `"Red"`. */ readonly name?: string; + /** - * The color that should be associated within this channel when displaying this channel in a UI, e.g: `#FF0000`. May be any color value supported by CSS, e.g. name, hex, rgba, etc.. - */ + * The color that should be associated within this channel when displaying + * this channel in a UI, e.g: `#FF0000`. May be any color value supported by + * CSS, e.g. name, hex, rgba, etc.. */ readonly color?: string; + /** - * A URL of an image that can be used to display this channel - */ + * A URL of an image that can be used to display this channel. */ readonly glyph?: string; } ``` @@ -235,18 +254,24 @@ The media type of the image. If not provided the Desktop Agent may refer to the ```ts interface ImplementationMetadata { - /** The version number of the FDC3 specification that the implementation provides. - * The string must be a numeric semver version, e.g. 1.2 or 1.2.1. + /** The version number of the FDC3 specification that the implementation + * provides. The string must be a numeric semver version, e.g. 1.2 or 1.2.1. */ readonly fdc3Version: string; - /** The name of the provider of the FDC3 Desktop Agent Implementation (e.g. Finsemble, Glue42, OpenFin etc.). */ + /** The name of the provider of the FDC3 Desktop Agent Implementation + * (e.g.Finsemble, Glue42, OpenFin etc.). + */ readonly provider: string; - - /** The version of the provider of the FDC3 Desktop Agent Implementation (e.g. 5.3.0). */ + + /** The version of the provider of the FDC3 Desktop Agent Implementation + * (e.g. 5.3.0). + */ readonly providerVersion?: string; - /** The calling application instance's own metadata, according to the Desktop Agent (MUST include at least the `appId` and `instanceId`). */ + /** The calling application instance's own metadata, according to the + * Desktop Agent (MUST include at least the `appId` and `instanceId`). + */ readonly appMetadata: AppMetadata; } ``` @@ -262,9 +287,12 @@ Metadata relating to the FDC3 [DesktopAgent](DesktopAgent) object and its provid ```ts interface IntentMetadata { - /** The unique name of the intent that can be invoked by the raiseIntent call */ + /** The unique name of the intent that can be invoked by the raiseIntent call. */ readonly name: string; - /** A friendly display name for the intent that should be used to render UI elements */ + + /** A friendly display name for the intent that should be used to render UI + * elements. + */ readonly displayName: string; } ``` @@ -280,35 +308,34 @@ The interface used to describe an intent within the platform. ```ts interface IntentResolution { - /** - * Metadata about the app instance that was selected (or started) to resolve the intent. - * `source.instanceId` MUST be set, indicating the specific app instance that - * received the intent. + /** Metadata about the app instance that was selected (or started) to resolve + * the intent. `source.instanceId` MUST be set, indicating the specific app + * instance that received the intent. */ readonly source: AppMetadata; - /** - * The intent that was raised. May be used to determine which intent the user - * chose in response to `fdc3.raiseIntentForContext()`. + + /** The intent that was raised. May be used to determine which intent the user + * chose in response to `fdc3.raiseIntentForContext()`. */ readonly intent: string; - /** - * The version number of the Intents schema being used. + + /** The version number of the Intents schema being used. */ readonly version?: string; - /** - * Retrieves a promise that will resolve to either `Context` data returned - * by the application that resolves the raised intent or a `Channel` - * established and returned by the app resolving the intent. + + /** Retrieves a promise that will resolve to either `Context` data returned + * by the application that resolves the raised intent or a `Channel` + * established and returned by the app resolving the intent. * - * A `Channel` returned MAY be of the `PrivateChannel` type. The - * client can then `addContextListener()` on that channel to, for example, - * receive a stream of data. + * A `Channel` returned MAY be of the `PrivateChannel` type. The + * client can then `addContextListener()` on that channel to, for example, + * receive a stream of data. * - * If an error occurs (i.e. an error is thrown by the handler function, - * the promise it returns is rejected, or a promise is not returned by the - * handler function) then the Desktop Agent MUST reject the promise returned - * by the `getResult()` function of the `IntentResolution` with a string from - * the `ResultError` enumeration. + * If an error occurs (i.e. an error is thrown by the handler function, + * the promise it returns is rejected, or a promise is not returned by the + * handler function) then the Desktop Agent MUST reject the promise returned + * by the `getResult()` function of the `IntentResolution` with a string from + * the `ResultError` enumeration. */ getResult(): Promise; } @@ -319,7 +346,7 @@ IntentResolution provides a standard format for data returned upon resolving an #### Examples ```js -//resolve a "Chain" type intent +// Resolve a "Chain" type intent let resolution = await agent.raiseIntent("intentName", context); // Use metadata about the resolving app instance to target a further intent @@ -327,12 +354,12 @@ try { const resolution = await fdc3.raiseIntent('StageOrder', context); ... - //some time later + //Some time later await agent.raiseIntent("UpdateOrder", context, resolution.source); } catch (err) { ... } -//resolve a "Client-Service" type intent with a data or channel response +//Resolve a "Client-Service" type intent with a data or channel response let resolution = await agent.raiseIntent("intentName", context); try { const result = await resolution.getResult(); diff --git a/docs/api/ref/Types.md b/docs/api/ref/Types.md index 190b8cef8..36d89975d 100644 --- a/docs/api/ref/Types.md +++ b/docs/api/ref/Types.md @@ -12,9 +12,14 @@ If the `instanceId` field is set then the `AppMetadata` object represents a spec ```ts interface AppIdentifier { - /** The unique application identifier located within a specific application directory instance. An example of an appId might be 'app@sub.root' */ + /** The unique application identifier located within a specific application + * directory instance. An example of an appId might be 'app@sub.root'. + */ readonly appId: string; - /** An optional instance identifier, indicating that this object represents a specific instance of the application described.*/ + + /** An optional instance identifier, indicating that this object represents a + * specific instance of the application described. + */ readonly instanceId?: string; } ``` @@ -101,7 +106,7 @@ Optional metadata about the intent & context message, including the app that ori type IntentResult = Context | Channel; ``` -Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution). +Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution). Represented as a union type in TypeScript, however, this type may be rendered as an interface in other languages that both the `Context` and `Channel` types implement, allowing either to be returned by an `IntentHandler`. diff --git a/docs/api/spec.md b/docs/api/spec.md index fa19baf24..c312dd589 100644 --- a/docs/api/spec.md +++ b/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. diff --git a/docs/app-directory/overview.md b/docs/app-directory/overview.md index 39feefd3e..564aae7a2 100644 --- a/docs/app-directory/overview.md +++ b/docs/app-directory/overview.md @@ -36,7 +36,7 @@ Typically, software evolves over time. The app versions you are running today wi #### Agent-agnostic -As a part of the FDC3 standard, appD isn't tied to any specific vendor. This is important, as it allows you more flexibility in that you are not tied to any specific container or desktop agent implementation. If at any point you want to switch to a different desktop agent, the process won’t be prohibitively difficult. The existing appD will work without any additional effort from you, as long as your new desktop agent is also FDC3-compliant. This is in contrast with proprietary solutions, where you would have to produce a new configuration and integration for every application. +As a part of the FDC3 standard, appD isn't tied to any specific vendor. This is important, as it allows you more flexibility in that you are not tied to any specific container or desktop agent implementation. If at any point you want to switch to a different desktop agent, the process won’t be prohibitively difficult. The existing appD will work without any additional effort from you, as long as your new desktop agent is also FDC3-compliant. This is in contrast with proprietary solutions, where you would have to produce a new configuration and integration for every application. AppD reduces fragmentation in the market and allows end-users more flexibility in what applications can be included in their desktop. @@ -62,7 +62,7 @@ By hosting our own appD we can easily combine applications from various provider ## Relationship to Other Standards -The App Directory's application record is similar to application manifests defined in other standards, in particular the W3C's [Web Application Manifest](https://www.w3.org/TR/appmanifest/). However, the App Directory, and by extension the application record, serve a different set of use-cases specific to application interoperability on financial services desktops, which other standards do not fully address. +The App Directory's application record is similar to application manifests defined in other standards, in particular the W3C's [Web Application Manifest](https://www.w3.org/TR/appmanifest/). However, the App Directory, and by extension the application record, serve a different set of use-cases specific to application interoperability on financial services desktops, which other standards do not fully address. Wherever possible, FDC3 seeks to draw inspiration from, align itself with and reference other standards - ensuring that conventions and best practices developed by those standards are reused, along with the standard itself (e.g. data formats in ISO standard formats, external links to technology-specific manifest file formats etc.). For a list of standards that FDC3 references, see the [References](../references) page. @@ -107,7 +107,7 @@ Although the concept of fully qualified application IDs are useful in resolving ## Service Discovery -In order to support the discovery of applications that can be used with a desktop agent, it is necessary to access data stored in one or more app directory instances. +In order to support the discovery of applications that can be used with a desktop agent, it is necessary to access data stored in one or more app directory instances. ![img](assets/appd_service_distribution.png) @@ -115,7 +115,7 @@ However, in order to do so, you must first discover the location of an app direc Three methods for discovering app directory services are defined in this Standard: - 1. **Static configuration:** Statically defined URI records for use within client applications (typically a desktop agent implementation) directly. + 1. **Static configuration:** Statically defined URI records for use within client applications (typically a desktop agent implementation) directly. 2. **Fully-qualified appID namespace syntax host resolution:** Discovery of the appD location using a fully qualified application ID (appId) domain name. 3. **DNS lookup by domain name:** Discovery of the appD location using a domain name to lookup DNS SRV records identifying the host server location and TCP port. ([RFC2782](https://tools.ietf.org/html/rfc2782)) @@ -134,14 +134,12 @@ An app directory URI can be constructed using a [fully qualified application ID] A launcher can then easily construct a URI by: 1. URI protocol is defaulted to `https`, but can be overridden by the launcher. -2. URI hostname is the fully qualified domain of the application ID. +2. URI hostname is the fully qualified domain of the application ID. 3. URI port is default `https/443`, but can be overridden by the launcher 4. URI url is by default `"/api/appd/(version)"` . Calls that are made without version MUST automatically default to latest, i.e. `"/api/appd/app1"` should return the same result as `"/api/appd/v2/app1"`. The resulting URI to retrieve application data for "app1" would be "[https://appd.foo.com/api/appd/v2/app1@appd.foo.com](https://appd.foo.com/api/appd/v2/app1@appd.foo.com)" - - ### DNS/SRV Records Another approach to support app directory service discovery (resolution) is through use of existing domain name service (DNS) implementations that are broadly used on the Internet today (see: [RFCs](https://www.isc.org/community/rfcs/dns/)). Name service implementations can be considered critical infrastructure and are proven stable with over twenty years of use. Name services can be used both through public Internet or locally deployed intranet, which provides optionality to deployment schemes. @@ -159,8 +157,8 @@ zone name { _service._proto.name. TTL class SRV priority weight port target.} - *class*: standard DNS class field (this is always *IN*). - *priority*: the priority of the target host, lower value means more preferred. - *weight*: A relative weight for records with the same priority, higher value means more preferred. -- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. -- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. +- *port*: the TCP or UDP port on which the service is to be found. For AppD service, TCP should always be used. +- *target*: the canonical hostname of the machine providing the service, ending in a dot. This would be the host where the AppD service is running. For AppD Service the SRV record MUST use the following definitions: diff --git a/src/api/RecommendedChannels.ts b/src/api/RecommendedChannels.ts new file mode 100644 index 000000000..502181a85 --- /dev/null +++ b/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 = [ + { + 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; diff --git a/src/app-directory/pom.xml b/src/app-directory/pom.xml index 59fa822f2..37426ba95 100644 --- a/src/app-directory/pom.xml +++ b/src/app-directory/pom.xml @@ -27,7 +27,7 @@ 2.3.1 false 9.2.9.v20150224 - 2.2.4 + 2.8.9 LATEST diff --git a/src/app-directory/specification/appd.yaml b/src/app-directory/specification/appd.yaml index c6d720358..945a4e784 100644 --- a/src/app-directory/specification/appd.yaml +++ b/src/app-directory/specification/appd.yaml @@ -29,6 +29,8 @@ paths: schema: $ref: '#/components/schemas/Application' examples: + MyAppDefinition: + $ref: '#/components/examples/MyAppDefinition' FDC3WorkbenchAppDefinition: $ref: '#/components/examples/FDC3WorkbenchAppDefinition' '400': @@ -64,8 +66,8 @@ paths: schema: $ref: '#/components/schemas/AllApplicationsResponse' examples: - FDC3WorkbenchAppDefinitionAllAppsResponse: - $ref: '#/components/examples/FDC3WorkbenchAppDefinitionAllAppsResponse' + AllAppsResponse: + $ref: '#/components/examples/AllAppsResponse' '400': description: Bad request. content: @@ -420,15 +422,10 @@ components: custom data from an App Directory to a launcher. items: $ref: '#/components/schemas/NameValuePair' - intents: - type: array - description: > - The list of intents implemented by the Application as defined by - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - items: - $ref: '#/components/schemas/Intent' hostManifests: $ref: '#/components/schemas/HostManifests' + interop: + $ref: '#/components/schemas/Interop' Application: description: > Defines an application retrieved from an FDC3 App Directory, which can @@ -448,105 +445,6 @@ components: properties: localizedVersions: $ref: '#/components/schemas/LocalizedVersions' - ApplicationV1: - description: > - (Deprecated v1 API version) Defines an application retrieved from an FDC3 App Directory, which can - then be launched. - Launching typically means running for a user on a desktop. - The details around 'launching' including who or what might do it, and how the launch action is initiated are - discussed elsewhere in the FDC3 App Directory spec. - required: - - appId - - name - - manifest - - manifestType - properties: - appId: - type: string - description: > - The unique application identifier located within a specific - application directory instance. - name: - type: string - description: > - The name of the application. - The name should be unique within an FDC3 App Directory instance. The - exception to the uniqueness constraint is that an App Directory can - hold definitions for multiple versions of the same app. - The same appName could occur in other directories. We are not - currently specifying app name conventions in the document. - manifest: - type: string - description: > - URI or full JSON of the application manifest providing all details related to launch - and use requirements as described by the vendor. - The format of this manifest is vendor specific, but can be identified by - the manifestType attribute. - manifestType: - type: string - description: > - The manifest type which relates to the format and structure of the manifest content. - The definition is based on the vendor specific format and definition outside of this specification. - version: - type: string - description: >- - Version of the application. This allows multiple app versions to be - defined using the same app name. This can be a triplet but can also - include things like 1.2.5 (BETA) - title: - type: string - description: >- - Optional title for the application, if missing use appName, - typically used in a launcher UI. - tooltip: - type: string - description: Optional tooltip description e.g. for a launcher - description: - type: string - description: >- - Description of the application. This will typically be a 1-2 - paragraph style blurb about the application. Allow mark up language - images: - type: array - description: >- - Array of images to show the user when they are looking at app - description. Each image can have an optional description/tooltip - items: - $ref: '#/components/schemas/AppImageV1' - contactEmail: - type: string - format: email - description: Optional e-mail to receive queries about the application - supportEmail: - type: string - format: email - description: Optional e-mail to receive support requests for the application - publisher: - type: string - description: >- - The name of the company that owns the application. The publisher has - control over their namespace/app/signature. - icons: - type: array - description: >- - Holds Icons used for the application, a Launcher may be able to use - multiple Icon sizes or there may be a 'button' Icon - items: - $ref: '#/components/schemas/IconV1' - customConfig: - type: array - description: >- - An optional set of name value pairs that can be used to deliver - custom data from an App Directory to a launcher. - items: - $ref: '#/components/schemas/NameValuePair' - intents: - type: array - description: > - The list of intents implemented by the Application as defined by - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - items: - $ref: '#/components/schemas/IntentV1' AllApplicationsResponse: properties: applications: @@ -559,18 +457,6 @@ components: type: string description: | Response message providing status of query - ApplicationSearchResponseV1: - properties: - applications: - type: array - description: | - List of applications - items: - $ref: '#/components/schemas/ApplicationV1' - message: - type: string - description: | - Response message providing status of query NameValuePair: description: Simple name value pair properties: @@ -593,13 +479,6 @@ components: type: type: string description: Image media type. If not present the Desktop Agent may use the src file extension - IconV1: - description: (Deprecated v1 API version) Icon holder - properties: - icon: - type: string - format: uri - description: Icon URL Screenshot: description: Images representing the app in common usage scenarios properties: @@ -616,70 +495,6 @@ components: label: type: string description: Optional caption for the image - AppImageV1: - description: App Image holder - properties: - url: - type: string - format: uri - description: App Image URL - Intent: - description: >- - An intent definition as defined by spec - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - required: - - name - properties: - name: - type: string - description: The name of the intent to 'launch'. In this case the name of an Intent supported by an Application. - displayName: - type: string - description: An optional display name for the intent that may be used in UI instead of the name. - contexts: - type: array - items: - type: string - description: >- - A comma separated list of the types of contexts the intent offered by the application can process, - where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" - resultType: - type: string - description: >- - An optional type for output returned by the application, if any, when resolving this intent. - May indicate a context type by type name (e.g. "fdc3.instrument"), a channel (e.g. "channel") - or a combination that indicates a channel that returns a particular context type - (e.g. "channel"). - customConfig: - type: object - description: >- - Custom configuration for the intent that may be required for a - particular desktop agent. - IntentV1: - description: >- - (Deprecated v1 API version) An intent definition as defined by spec - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - required: - - name - properties: - name: - type: string - description: The name of the intent to 'launch'. In this case the name of an Intent supported by an Application. - displayName: - type: string - description: An optional display name for the intent that may be used in UI instead of the name. - contexts: - type: array - items: - type: string - description: >- - A comma separated list of the types of contexts the intent offered by the application can process. - where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" - customConfig: - type: object - description: >- - Custom configuration for the intent that may be required for a - particular desktop agent. Type: type: string description: | @@ -784,6 +599,276 @@ components: additionalProperties: x-additionalPropertiesName: Language tag $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers. + Intent: + description: >- + Definition of an intent that an app listens for + required: + - contexts + properties: + displayName: + type: string + description: An optional display name for the intent that may be used in UI instead of the name. + contexts: + type: array + items: + type: string + description: >- + A comma separated list of the types of contexts the intent offered by the application can process, + where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" + resultType: + type: string + description: >- + An optional type for output returned by the application, if any, when resolving this intent. + May indicate a context type by type name (e.g. "fdc3.instrument"), a channel (e.g. "channel") + or a combination that indicates a channel that returns a particular context type + (e.g. "channel"). + customConfig: + type: object + description: >- + Custom configuration for the intent that may be required for a + particular desktop agent. + Interop: + type: object + description: | + Metadata that describes how the application uses FDC3 APIs. This metadata serves multiple purposes: + + - It supports intent resolution by a desktop agent, by declaring what intents an app listens for. + - It may be used, for example in an app catalog UI, to find apps that 'interoperate with' other apps. + - It provides a standard location to document how the app interacts with user channels, app channels, + and intents, for use by other app developers and desktop assemblers. + properties: + intents: + type: object + description: Describes the app's interactions with intents. + properties: + listensFor: + type: object + description: | + A mapping of Intents names that an app listens for via `fdc3.addIntentListener()` to their + configuration. + + Used to support intent resolution by desktop agents. Replaces the `intents` element used in appD records prior to FDC3 2.0. + additionalProperties: + x-additionalPropertiesName: Intent name + items: + $ref: '#/components/schemas/Intent' + raises: + type: object + description: | + A mapping of Intent names that an app raises (via `fdc3.raiseIntent`) to an array of context + type names that it may be raised with. + + Use the intent name "any" to represent use of the `fdc3.raiseIntentForContext` and + `fdc3.findIntentForContext` functions, which allow the user to select from intents available for a + specified context type. + + This metadata is not currently used by the desktop agent, but is provided to help find apps + that will interoperate with this app and to document API interactions for use by other app + developers. + additionalProperties: + x-additionalPropertiesName: Intent name + type: array + description: Context type names that the intent may be raised with. + items: + type: string + userChannels: + type: object + description: | + Describes the application's use of context types on User Channels. + + This metadata is not currently used by the desktop agent, but is provided to help find apps + that will interoperate with this app and to document API interactions for use by other app + developers. + properties: + broadcasts: + type: array + description: Context type names that are broadcast by the application. + items: + type: string + listensFor: + type: array + description: Context type names that the application listens for. + items: + type: string + appChannels: + type: array + description: | + Describes the application's use of App Channels. + + This metadata is not currently used by the desktop agent, but is provided to help find apps + that will interoperate with this app and to document API interactions for use by other app + developers. + items: + type: object + required: + - name + properties: + name: + type: string + description: The name of the App Channel. + description: + type: string + description: A description of how the channel is used. + broadcasts: + type: array + description: Context type names that are broadcast by the application on the channel. + items: + type: string + listensFor: + type: array + description: Context type names that the application listens for on the channel. + items: + type: string + AppImageV1: + description: App Image holder + properties: + url: + type: string + format: uri + description: App Image URL + IconV1: + description: (Deprecated v1 API version) Icon holder + properties: + icon: + type: string + format: uri + description: Icon URL + IntentV1: + description: >- + (Deprecated v1 API version) An intent definition as defined by spec + https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + required: + - name + properties: + name: + type: string + description: The name of the intent to 'launch'. In this case the name of an Intent supported by an application. + displayName: + type: string + description: An optional display name for the intent that may be used in UI instead of the name. + contexts: + type: array + items: + type: string + description: >- + A comma sepaarted list of the types of contexts the intent offered by the application can process. + where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" + customConfig: + type: object + description: >- + Custom configuration for the intent that may be required for a + particular desktop agent. + ApplicationV1: + description: > + (Deprecated v1 API version) Defines an application retrieved from an FDC3 App Directory, which can + then be launched. + Launching typically means running for a user on a desktop. + The details around 'launching' including who or what might do it, and how the launch action is initiated are + discussed elsewhere in the FDC3 App Directory spec. + required: + - appId + - name + - manifest + - manifestType + properties: + appId: + type: string + description: > + The unique application identifier located within a specific + application directory instance. + name: + type: string + description: > + The name of the application. + The name should be unique within an FDC3 App Directory instance. The + exception to the uniqueness constraint is that an App Directory can + hold definitions for multiple versions of the same app. + The same appName could occur in other directories. We are not + currently specifying app name conventions in the document. + manifest: + type: string + description: > + URI or full JSON of the application manifest providing all details related to launch + and use requirements as described by the vendor. + The format of this manifest is vendor specific, but can be identified by + the manifestType attribute. + manifestType: + type: string + description: > + The manifest type which relates to the format and structure of the manifest content. + The definition is based on the vendor specific format and definition outside of this specification. + version: + type: string + description: >- + Version of the application. This allows multiple app versions to be + defined using the same app name. This can be a triplet but can also + include things like 1.2.5 (BETA) + title: + type: string + description: >- + Optional title for the application, if missing use appName, + typically used in a launcher UI. + tooltip: + type: string + description: Optional tooltip description e.g. for a launcher + description: + type: string + description: >- + Description of the application. This will typically be a 1-2 + paragraph style blurb about the application. Allow mark up language + images: + type: array + description: >- + Array of images to show the user when they are looking at app + description. Each image can have an optional description/tooltip + items: + $ref: '#/components/schemas/AppImageV1' + contactEmail: + type: string + format: email + description: Optional e-mail to receive queries about the application + supportEmail: + type: string + format: email + description: Optional e-mail to receive support requests for the application + publisher: + type: string + description: >- + The name of the company that owns the application. The publisher has + control over their namespace/app/signature. + icons: + type: array + description: >- + Holds Icons used for the application, a Launcher may be able to use + multiple Icon sizes or there may be a 'button' Icon + items: + $ref: '#/components/schemas/IconV1' + customConfig: + type: array + description: >- + An optional set of name value pairs that can be used to deliver + custom data from an App Directory to a launcher. + items: + $ref: '#/components/schemas/NameValuePair' + intents: + type: array + description: > + The list of intents implemented by the application as defined by + https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + items: + $ref: '#/components/schemas/IntentV1' + ApplicationSearchResponseV1: + properties: + applications: + type: array + description: | + List of applications + items: + $ref: '#/components/schemas/ApplicationV1' + message: + type: string + description: | + Response message providing status of query examples: FDC3WorkbenchAppDefinition: value: @@ -804,11 +889,6 @@ components: supportEmail: fdc3-maintainers@finos.org moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists publisher: FDC3 - intents: [{ - name: ViewChart, - displayName: View Chart, - contexts: [fdc3.instrument] - }] type: web details: url: https://fdc3.finos.org/toolbox/fdc3-workbench/ @@ -869,9 +949,234 @@ components: } } summary: A sample app definition for the FDC3 Workbench application - FDC3WorkbenchAppDefinitionAllAppsResponse: + MyAppDefinition: + value: + appId: my-application + name: my-application + title: My Application + description: An example application that uses FDC3 and fully describes itself in an AppD record. + categories: [market data, research, news] + version: 1.0.0 + tooltip: My example application definition + lang: en-US + icons: + - src: http://example.domain.com/assets/my-app-icon.png + size: 256x256 + type: image/png + screenshots: + - src: http://example.domain.com/assets/my-app-screenshot-1.png + label: The first screenshot of my example app + type: image/png + size: 800x600 + - src: http://example.domain.com/assets/my-app-screenshot-2.png + label: The second screenshot of my example app + type: image/png + size: 800x600 + contactEmail: fdc3@finos.org + supportEmail: fdc3-maintainers@finos.org + moreInfo: http://example.domain.com/ + publisher: Example App, Inc. + type: web + details: + url: http://example.domain.com/app.html + hostManifests: { + Finsemble: { + window: { + left: 120, + top: 120, + width: 600, + height: 800, + options: { + minWidth: 75 + } + }, + foreign: { + components: { + App Launcher: { + launchableByUser: true + }, + Window Manager: { + FSBLHeader: true, + persistWindowState: true + } + } + }, + interop: { + autoConnect: true + } + }, + Glue42: { + type: window, + details: { + height: 800, + width: 600, + left: 120, + top: 120, + mode: tab, + allowChannels: true, + loader: { + enabled: true, + hideOnLoad: true + } + }, + customProperties: { + folder: FDC3 Toolbox + } + }, + Web App Manifest: http://example.domain.com/my-app.json + } + interop: + intents: + listensFor: + ViewChart: + displayName: View Chart + contexts: + - fdc3.instrument + myApp.GetPrice: + displayName: Get Price + contexts: + - fdc3.instrument + resultType: myApp.quote + raises: + ViewOrders: + - fdc3.instrument + - fdc3.organization + StartEmail: + - fdc3.email + userChannels: + broadcasts: + - fdc3.instrument + - fdc3.organization + listensFor: + - fdc3.instrument + - fdc3.organization + appChannels: + - name: myApp.quotes, + description: >- + Used to share a stream of quotes for currently displayed instrument and may be used to change the currently displayed symbol, + broadcasts: + - myApp.quote + listensFor: + - fdc3.instrument + localizedVersions: + fr-FR: + title: Mon application, + description: Un exemple d'application qui utilise FDC3 et se décrit entièrement dans un enregistrement AppD. + summary: A sample app definition for an application that describes its use of interop. + AllAppsResponse: value: applications: # you can't $ref inside a $ref so example is repeated here for search response + - appId: my-application + name: my-application + title: My Application + description: An example application that uses FDC3 and fully describes itself in an AppD record. + categories: [market data, research, news] + version: 1.0.0 + tooltip: My example application definition + lang: en-US + icons: + - src: http://example.domain.com/assets/my-app-icon.png + size: 256x256 + type: image/png + screenshots: + - src: http://example.domain.com/assets/my-app-screenshot-1.png + label: The first screenshot of my example app + type: image/png + size: 800x600 + - src: http://example.domain.com/assets/my-app-screenshot-2.png + label: The second screenshot of my example app + type: image/png + size: 800x600 + contactEmail: fdc3@finos.org + supportEmail: fdc3-maintainers@finos.org + moreInfo: http://example.domain.com/ + publisher: Example App, Inc. + type: web + details: + url: http://example.domain.com/app.html + hostManifests: { + Finsemble: { + window: { + left: 120, + top: 120, + width: 600, + height: 800, + options: { + minWidth: 75 + } + }, + foreign: { + components: { + App Launcher: { + launchableByUser: true + }, + Window Manager: { + FSBLHeader: true, + persistWindowState: true + } + } + }, + interop: { + autoConnect: true + } + }, + Glue42: { + type: window, + details: { + height: 800, + width: 600, + left: 120, + top: 120, + mode: tab, + allowChannels: true, + loader: { + enabled: true, + hideOnLoad: true + } + }, + customProperties: { + folder: FDC3 Toolbox + } + }, + Web App Manifest: http://example.domain.com/my-app.json + } + interop: + intents: + listensFor: + ViewChart: + displayName: View Chart + contexts: + - fdc3.instrument + myApp.GetPrice: + displayName: Get Price + contexts: + - fdc3.instrument + resultType: myApp.quote + raises: + ViewOrders: + - fdc3.instrument + - fdc3.organization + StartEmail: + - fdc3.email + userChannels: + broadcasts: + - fdc3.instrument + - fdc3.organization + listensFor: + - fdc3.instrument + - fdc3.organization + appChannels: + - name: myApp.quotes, + description: >- + Used to share a stream of quotes for currently displayed instrument and may be used to change the currently displayed symbol, + broadcasts: + - myApp.quote + listensFor: + - fdc3.instrument + localizedVersions: + fr-FR: + title: Mon application, + description: Un exemple d'application qui utilise FDC3 et se décrit entièrement dans un enregistrement AppD. - appId: fdc3-workbench name: fdc3-workbench title: FDC3 Workbench @@ -888,11 +1193,6 @@ components: contactEmail: fdc3@finos.org, supportEmail: fdc3-maintainers@finos.org, publisher: FDC3, - intents: [{ - name: ViewChart, - displayName: View Chart, - contexts: [fdc3.instrument] - }] type: web details: url: https://fdc3.finos.org/toolbox/fdc3-workbench/ @@ -953,4 +1253,4 @@ components: } } message: OK - summary: A sample 'all applications' listing response containing the FDC3 Workbench application + summary: A sample 'all applications' listing response diff --git a/src/index.ts b/src/index.ts index 2ff8d8bed..0657d8c44 100644 --- a/src/index.ts +++ b/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'; diff --git a/toolbox/fdc3-workbench/yarn.lock b/toolbox/fdc3-workbench/yarn.lock index 153feb00a..55248a8ff 100644 --- a/toolbox/fdc3-workbench/yarn.lock +++ b/toolbox/fdc3-workbench/yarn.lock @@ -4913,9 +4913,9 @@ events@^3.0.0: integrity sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q== eventsource@^1.0.7: - version "1.1.0" - resolved "https://registry.yarnpkg.com/eventsource/-/eventsource-1.1.0.tgz#00e8ca7c92109e94b0ddf32dac677d841028cfaf" - integrity sha512-VSJjT5oCNrFvCS6igjzPAt5hBzQ2qPBFIbJ03zLI9SE0mxwZpMw6BfJrbFHm1a141AavMEB8JHmBhWAd66PfCg== + version "1.1.1" + resolved "https://registry.yarnpkg.com/eventsource/-/eventsource-1.1.1.tgz#4544a35a57d7120fba4fa4c86cb4023b2c09df2f" + integrity sha512-qV5ZC0h7jYIAOhArFJgSfdyz6rALJyb270714o7ZtNnw2WSJ+eexhKtE0O8LYPRsHZHf2osHKZBxGPvm3kPkCA== dependencies: original "^1.0.0" diff --git a/website/blog/2017-09-25-testing-rss.md b/website/blog/2017-09-25-testing-rss.md index b7ff8129c..401995913 100644 --- a/website/blog/2017-09-25-testing-rss.md +++ b/website/blog/2017-09-25-testing-rss.md @@ -9,3 +9,4 @@ authorFBID: 661277173 This should be truncated. This line should never render in XML. + \ No newline at end of file diff --git a/website/data/users.json b/website/data/users.json index f297acb2c..e563ece50 100644 --- a/website/data/users.json +++ b/website/data/users.json @@ -102,5 +102,12 @@ "infoLink": "https://www.singletrack.com/", "pinned": true, "isMember": true - } + }, + { + "caption": "Symphony", + "image": "/img/users/Symphony.png", + "infoLink": "https://www.symphony.com/", + "pinned": true, + "isMember": true + } ] diff --git a/website/static/img/users/Symphony.png b/website/static/img/users/Symphony.png new file mode 100644 index 000000000..510f319f3 Binary files /dev/null and b/website/static/img/users/Symphony.png differ diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml index c6d720358..945a4e784 100644 --- a/website/static/schemas/next/app-directory.yaml +++ b/website/static/schemas/next/app-directory.yaml @@ -29,6 +29,8 @@ paths: schema: $ref: '#/components/schemas/Application' examples: + MyAppDefinition: + $ref: '#/components/examples/MyAppDefinition' FDC3WorkbenchAppDefinition: $ref: '#/components/examples/FDC3WorkbenchAppDefinition' '400': @@ -64,8 +66,8 @@ paths: schema: $ref: '#/components/schemas/AllApplicationsResponse' examples: - FDC3WorkbenchAppDefinitionAllAppsResponse: - $ref: '#/components/examples/FDC3WorkbenchAppDefinitionAllAppsResponse' + AllAppsResponse: + $ref: '#/components/examples/AllAppsResponse' '400': description: Bad request. content: @@ -420,15 +422,10 @@ components: custom data from an App Directory to a launcher. items: $ref: '#/components/schemas/NameValuePair' - intents: - type: array - description: > - The list of intents implemented by the Application as defined by - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - items: - $ref: '#/components/schemas/Intent' hostManifests: $ref: '#/components/schemas/HostManifests' + interop: + $ref: '#/components/schemas/Interop' Application: description: > Defines an application retrieved from an FDC3 App Directory, which can @@ -448,105 +445,6 @@ components: properties: localizedVersions: $ref: '#/components/schemas/LocalizedVersions' - ApplicationV1: - description: > - (Deprecated v1 API version) Defines an application retrieved from an FDC3 App Directory, which can - then be launched. - Launching typically means running for a user on a desktop. - The details around 'launching' including who or what might do it, and how the launch action is initiated are - discussed elsewhere in the FDC3 App Directory spec. - required: - - appId - - name - - manifest - - manifestType - properties: - appId: - type: string - description: > - The unique application identifier located within a specific - application directory instance. - name: - type: string - description: > - The name of the application. - The name should be unique within an FDC3 App Directory instance. The - exception to the uniqueness constraint is that an App Directory can - hold definitions for multiple versions of the same app. - The same appName could occur in other directories. We are not - currently specifying app name conventions in the document. - manifest: - type: string - description: > - URI or full JSON of the application manifest providing all details related to launch - and use requirements as described by the vendor. - The format of this manifest is vendor specific, but can be identified by - the manifestType attribute. - manifestType: - type: string - description: > - The manifest type which relates to the format and structure of the manifest content. - The definition is based on the vendor specific format and definition outside of this specification. - version: - type: string - description: >- - Version of the application. This allows multiple app versions to be - defined using the same app name. This can be a triplet but can also - include things like 1.2.5 (BETA) - title: - type: string - description: >- - Optional title for the application, if missing use appName, - typically used in a launcher UI. - tooltip: - type: string - description: Optional tooltip description e.g. for a launcher - description: - type: string - description: >- - Description of the application. This will typically be a 1-2 - paragraph style blurb about the application. Allow mark up language - images: - type: array - description: >- - Array of images to show the user when they are looking at app - description. Each image can have an optional description/tooltip - items: - $ref: '#/components/schemas/AppImageV1' - contactEmail: - type: string - format: email - description: Optional e-mail to receive queries about the application - supportEmail: - type: string - format: email - description: Optional e-mail to receive support requests for the application - publisher: - type: string - description: >- - The name of the company that owns the application. The publisher has - control over their namespace/app/signature. - icons: - type: array - description: >- - Holds Icons used for the application, a Launcher may be able to use - multiple Icon sizes or there may be a 'button' Icon - items: - $ref: '#/components/schemas/IconV1' - customConfig: - type: array - description: >- - An optional set of name value pairs that can be used to deliver - custom data from an App Directory to a launcher. - items: - $ref: '#/components/schemas/NameValuePair' - intents: - type: array - description: > - The list of intents implemented by the Application as defined by - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - items: - $ref: '#/components/schemas/IntentV1' AllApplicationsResponse: properties: applications: @@ -559,18 +457,6 @@ components: type: string description: | Response message providing status of query - ApplicationSearchResponseV1: - properties: - applications: - type: array - description: | - List of applications - items: - $ref: '#/components/schemas/ApplicationV1' - message: - type: string - description: | - Response message providing status of query NameValuePair: description: Simple name value pair properties: @@ -593,13 +479,6 @@ components: type: type: string description: Image media type. If not present the Desktop Agent may use the src file extension - IconV1: - description: (Deprecated v1 API version) Icon holder - properties: - icon: - type: string - format: uri - description: Icon URL Screenshot: description: Images representing the app in common usage scenarios properties: @@ -616,70 +495,6 @@ components: label: type: string description: Optional caption for the image - AppImageV1: - description: App Image holder - properties: - url: - type: string - format: uri - description: App Image URL - Intent: - description: >- - An intent definition as defined by spec - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - required: - - name - properties: - name: - type: string - description: The name of the intent to 'launch'. In this case the name of an Intent supported by an Application. - displayName: - type: string - description: An optional display name for the intent that may be used in UI instead of the name. - contexts: - type: array - items: - type: string - description: >- - A comma separated list of the types of contexts the intent offered by the application can process, - where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" - resultType: - type: string - description: >- - An optional type for output returned by the application, if any, when resolving this intent. - May indicate a context type by type name (e.g. "fdc3.instrument"), a channel (e.g. "channel") - or a combination that indicates a channel that returns a particular context type - (e.g. "channel"). - customConfig: - type: object - description: >- - Custom configuration for the intent that may be required for a - particular desktop agent. - IntentV1: - description: >- - (Deprecated v1 API version) An intent definition as defined by spec - https://github.com/FDC3/Intents/blob/master/src/Intent.yaml - required: - - name - properties: - name: - type: string - description: The name of the intent to 'launch'. In this case the name of an Intent supported by an Application. - displayName: - type: string - description: An optional display name for the intent that may be used in UI instead of the name. - contexts: - type: array - items: - type: string - description: >- - A comma separated list of the types of contexts the intent offered by the application can process. - where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" - customConfig: - type: object - description: >- - Custom configuration for the intent that may be required for a - particular desktop agent. Type: type: string description: | @@ -784,6 +599,276 @@ components: additionalProperties: x-additionalPropertiesName: Language tag $ref: '#/components/schemas/BaseApplication' # due to a bug in redoc this may display as a recursive definition, it is not. It will render correctly in swagger and other OpenAPI parsers. + Intent: + description: >- + Definition of an intent that an app listens for + required: + - contexts + properties: + displayName: + type: string + description: An optional display name for the intent that may be used in UI instead of the name. + contexts: + type: array + items: + type: string + description: >- + A comma separated list of the types of contexts the intent offered by the application can process, + where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" + resultType: + type: string + description: >- + An optional type for output returned by the application, if any, when resolving this intent. + May indicate a context type by type name (e.g. "fdc3.instrument"), a channel (e.g. "channel") + or a combination that indicates a channel that returns a particular context type + (e.g. "channel"). + customConfig: + type: object + description: >- + Custom configuration for the intent that may be required for a + particular desktop agent. + Interop: + type: object + description: | + Metadata that describes how the application uses FDC3 APIs. This metadata serves multiple purposes: + + - It supports intent resolution by a desktop agent, by declaring what intents an app listens for. + - It may be used, for example in an app catalog UI, to find apps that 'interoperate with' other apps. + - It provides a standard location to document how the app interacts with user channels, app channels, + and intents, for use by other app developers and desktop assemblers. + properties: + intents: + type: object + description: Describes the app's interactions with intents. + properties: + listensFor: + type: object + description: | + A mapping of Intents names that an app listens for via `fdc3.addIntentListener()` to their + configuration. + + Used to support intent resolution by desktop agents. Replaces the `intents` element used in appD records prior to FDC3 2.0. + additionalProperties: + x-additionalPropertiesName: Intent name + items: + $ref: '#/components/schemas/Intent' + raises: + type: object + description: | + A mapping of Intent names that an app raises (via `fdc3.raiseIntent`) to an array of context + type names that it may be raised with. + + Use the intent name "any" to represent use of the `fdc3.raiseIntentForContext` and + `fdc3.findIntentForContext` functions, which allow the user to select from intents available for a + specified context type. + + This metadata is not currently used by the desktop agent, but is provided to help find apps + that will interoperate with this app and to document API interactions for use by other app + developers. + additionalProperties: + x-additionalPropertiesName: Intent name + type: array + description: Context type names that the intent may be raised with. + items: + type: string + userChannels: + type: object + description: | + Describes the application's use of context types on User Channels. + + This metadata is not currently used by the desktop agent, but is provided to help find apps + that will interoperate with this app and to document API interactions for use by other app + developers. + properties: + broadcasts: + type: array + description: Context type names that are broadcast by the application. + items: + type: string + listensFor: + type: array + description: Context type names that the application listens for. + items: + type: string + appChannels: + type: array + description: | + Describes the application's use of App Channels. + + This metadata is not currently used by the desktop agent, but is provided to help find apps + that will interoperate with this app and to document API interactions for use by other app + developers. + items: + type: object + required: + - name + properties: + name: + type: string + description: The name of the App Channel. + description: + type: string + description: A description of how the channel is used. + broadcasts: + type: array + description: Context type names that are broadcast by the application on the channel. + items: + type: string + listensFor: + type: array + description: Context type names that the application listens for on the channel. + items: + type: string + AppImageV1: + description: App Image holder + properties: + url: + type: string + format: uri + description: App Image URL + IconV1: + description: (Deprecated v1 API version) Icon holder + properties: + icon: + type: string + format: uri + description: Icon URL + IntentV1: + description: >- + (Deprecated v1 API version) An intent definition as defined by spec + https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + required: + - name + properties: + name: + type: string + description: The name of the intent to 'launch'. In this case the name of an Intent supported by an application. + displayName: + type: string + description: An optional display name for the intent that may be used in UI instead of the name. + contexts: + type: array + items: + type: string + description: >- + A comma sepaarted list of the types of contexts the intent offered by the application can process. + where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact" + customConfig: + type: object + description: >- + Custom configuration for the intent that may be required for a + particular desktop agent. + ApplicationV1: + description: > + (Deprecated v1 API version) Defines an application retrieved from an FDC3 App Directory, which can + then be launched. + Launching typically means running for a user on a desktop. + The details around 'launching' including who or what might do it, and how the launch action is initiated are + discussed elsewhere in the FDC3 App Directory spec. + required: + - appId + - name + - manifest + - manifestType + properties: + appId: + type: string + description: > + The unique application identifier located within a specific + application directory instance. + name: + type: string + description: > + The name of the application. + The name should be unique within an FDC3 App Directory instance. The + exception to the uniqueness constraint is that an App Directory can + hold definitions for multiple versions of the same app. + The same appName could occur in other directories. We are not + currently specifying app name conventions in the document. + manifest: + type: string + description: > + URI or full JSON of the application manifest providing all details related to launch + and use requirements as described by the vendor. + The format of this manifest is vendor specific, but can be identified by + the manifestType attribute. + manifestType: + type: string + description: > + The manifest type which relates to the format and structure of the manifest content. + The definition is based on the vendor specific format and definition outside of this specification. + version: + type: string + description: >- + Version of the application. This allows multiple app versions to be + defined using the same app name. This can be a triplet but can also + include things like 1.2.5 (BETA) + title: + type: string + description: >- + Optional title for the application, if missing use appName, + typically used in a launcher UI. + tooltip: + type: string + description: Optional tooltip description e.g. for a launcher + description: + type: string + description: >- + Description of the application. This will typically be a 1-2 + paragraph style blurb about the application. Allow mark up language + images: + type: array + description: >- + Array of images to show the user when they are looking at app + description. Each image can have an optional description/tooltip + items: + $ref: '#/components/schemas/AppImageV1' + contactEmail: + type: string + format: email + description: Optional e-mail to receive queries about the application + supportEmail: + type: string + format: email + description: Optional e-mail to receive support requests for the application + publisher: + type: string + description: >- + The name of the company that owns the application. The publisher has + control over their namespace/app/signature. + icons: + type: array + description: >- + Holds Icons used for the application, a Launcher may be able to use + multiple Icon sizes or there may be a 'button' Icon + items: + $ref: '#/components/schemas/IconV1' + customConfig: + type: array + description: >- + An optional set of name value pairs that can be used to deliver + custom data from an App Directory to a launcher. + items: + $ref: '#/components/schemas/NameValuePair' + intents: + type: array + description: > + The list of intents implemented by the application as defined by + https://github.com/FDC3/Intents/blob/master/src/Intent.yaml + items: + $ref: '#/components/schemas/IntentV1' + ApplicationSearchResponseV1: + properties: + applications: + type: array + description: | + List of applications + items: + $ref: '#/components/schemas/ApplicationV1' + message: + type: string + description: | + Response message providing status of query examples: FDC3WorkbenchAppDefinition: value: @@ -804,11 +889,6 @@ components: supportEmail: fdc3-maintainers@finos.org moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists publisher: FDC3 - intents: [{ - name: ViewChart, - displayName: View Chart, - contexts: [fdc3.instrument] - }] type: web details: url: https://fdc3.finos.org/toolbox/fdc3-workbench/ @@ -869,9 +949,234 @@ components: } } summary: A sample app definition for the FDC3 Workbench application - FDC3WorkbenchAppDefinitionAllAppsResponse: + MyAppDefinition: + value: + appId: my-application + name: my-application + title: My Application + description: An example application that uses FDC3 and fully describes itself in an AppD record. + categories: [market data, research, news] + version: 1.0.0 + tooltip: My example application definition + lang: en-US + icons: + - src: http://example.domain.com/assets/my-app-icon.png + size: 256x256 + type: image/png + screenshots: + - src: http://example.domain.com/assets/my-app-screenshot-1.png + label: The first screenshot of my example app + type: image/png + size: 800x600 + - src: http://example.domain.com/assets/my-app-screenshot-2.png + label: The second screenshot of my example app + type: image/png + size: 800x600 + contactEmail: fdc3@finos.org + supportEmail: fdc3-maintainers@finos.org + moreInfo: http://example.domain.com/ + publisher: Example App, Inc. + type: web + details: + url: http://example.domain.com/app.html + hostManifests: { + Finsemble: { + window: { + left: 120, + top: 120, + width: 600, + height: 800, + options: { + minWidth: 75 + } + }, + foreign: { + components: { + App Launcher: { + launchableByUser: true + }, + Window Manager: { + FSBLHeader: true, + persistWindowState: true + } + } + }, + interop: { + autoConnect: true + } + }, + Glue42: { + type: window, + details: { + height: 800, + width: 600, + left: 120, + top: 120, + mode: tab, + allowChannels: true, + loader: { + enabled: true, + hideOnLoad: true + } + }, + customProperties: { + folder: FDC3 Toolbox + } + }, + Web App Manifest: http://example.domain.com/my-app.json + } + interop: + intents: + listensFor: + ViewChart: + displayName: View Chart + contexts: + - fdc3.instrument + myApp.GetPrice: + displayName: Get Price + contexts: + - fdc3.instrument + resultType: myApp.quote + raises: + ViewOrders: + - fdc3.instrument + - fdc3.organization + StartEmail: + - fdc3.email + userChannels: + broadcasts: + - fdc3.instrument + - fdc3.organization + listensFor: + - fdc3.instrument + - fdc3.organization + appChannels: + - name: myApp.quotes, + description: >- + Used to share a stream of quotes for currently displayed instrument and may be used to change the currently displayed symbol, + broadcasts: + - myApp.quote + listensFor: + - fdc3.instrument + localizedVersions: + fr-FR: + title: Mon application, + description: Un exemple d'application qui utilise FDC3 et se décrit entièrement dans un enregistrement AppD. + summary: A sample app definition for an application that describes its use of interop. + AllAppsResponse: value: applications: # you can't $ref inside a $ref so example is repeated here for search response + - appId: my-application + name: my-application + title: My Application + description: An example application that uses FDC3 and fully describes itself in an AppD record. + categories: [market data, research, news] + version: 1.0.0 + tooltip: My example application definition + lang: en-US + icons: + - src: http://example.domain.com/assets/my-app-icon.png + size: 256x256 + type: image/png + screenshots: + - src: http://example.domain.com/assets/my-app-screenshot-1.png + label: The first screenshot of my example app + type: image/png + size: 800x600 + - src: http://example.domain.com/assets/my-app-screenshot-2.png + label: The second screenshot of my example app + type: image/png + size: 800x600 + contactEmail: fdc3@finos.org + supportEmail: fdc3-maintainers@finos.org + moreInfo: http://example.domain.com/ + publisher: Example App, Inc. + type: web + details: + url: http://example.domain.com/app.html + hostManifests: { + Finsemble: { + window: { + left: 120, + top: 120, + width: 600, + height: 800, + options: { + minWidth: 75 + } + }, + foreign: { + components: { + App Launcher: { + launchableByUser: true + }, + Window Manager: { + FSBLHeader: true, + persistWindowState: true + } + } + }, + interop: { + autoConnect: true + } + }, + Glue42: { + type: window, + details: { + height: 800, + width: 600, + left: 120, + top: 120, + mode: tab, + allowChannels: true, + loader: { + enabled: true, + hideOnLoad: true + } + }, + customProperties: { + folder: FDC3 Toolbox + } + }, + Web App Manifest: http://example.domain.com/my-app.json + } + interop: + intents: + listensFor: + ViewChart: + displayName: View Chart + contexts: + - fdc3.instrument + myApp.GetPrice: + displayName: Get Price + contexts: + - fdc3.instrument + resultType: myApp.quote + raises: + ViewOrders: + - fdc3.instrument + - fdc3.organization + StartEmail: + - fdc3.email + userChannels: + broadcasts: + - fdc3.instrument + - fdc3.organization + listensFor: + - fdc3.instrument + - fdc3.organization + appChannels: + - name: myApp.quotes, + description: >- + Used to share a stream of quotes for currently displayed instrument and may be used to change the currently displayed symbol, + broadcasts: + - myApp.quote + listensFor: + - fdc3.instrument + localizedVersions: + fr-FR: + title: Mon application, + description: Un exemple d'application qui utilise FDC3 et se décrit entièrement dans un enregistrement AppD. - appId: fdc3-workbench name: fdc3-workbench title: FDC3 Workbench @@ -888,11 +1193,6 @@ components: contactEmail: fdc3@finos.org, supportEmail: fdc3-maintainers@finos.org, publisher: FDC3, - intents: [{ - name: ViewChart, - displayName: View Chart, - contexts: [fdc3.instrument] - }] type: web details: url: https://fdc3.finos.org/toolbox/fdc3-workbench/ @@ -953,4 +1253,4 @@ components: } } message: OK - summary: A sample 'all applications' listing response containing the FDC3 Workbench application + summary: A sample 'all applications' listing response