From 528ad2a8418284dc835da873e32ddfd1cd650819 Mon Sep 17 00:00:00 2001 From: Riko Eksteen Date: Fri, 9 Apr 2021 10:26:58 +0100 Subject: [PATCH 1/2] chore: publish version 1.2 website - create version 1.2 in docusaurus and make it the default - update footer links - simplify change log and add recent releases --- CHANGELOG.md | 146 +++--- website/core/Footer.js | 34 +- website/pages/schemas/1.2/app-directory.html | 24 + website/static/schemas/1.2/app-directory.yaml | 383 +++++++++++++++ .../static/schemas/1.2/contact.schema.json | 18 + .../schemas/1.2/contactList.schema.json | 15 + .../static/schemas/1.2/context.schema.json | 15 + .../static/schemas/1.2/country.schema.json | 18 + .../static/schemas/1.2/instrument.schema.json | 25 + .../schemas/1.2/instrumentList.schema.json | 15 + .../schemas/1.2/organization.schema.json | 19 + .../static/schemas/1.2/portfolio.schema.json | 15 + .../static/schemas/1.2/position.schema.json | 13 + .../version-1.2/api/overview.md | 79 ++++ .../version-1.2/api/ref/Channel.md | 202 ++++++++ .../version-1.2/api/ref/DesktopAgent.md | 436 ++++++++++++++++++ .../version-1.2/api/ref/Errors.md | 58 +++ .../version-1.2/api/ref/Globals.md | 69 +++ .../version-1.2/api/ref/Listener.md | 32 ++ .../version-1.2/api/ref/Metadata.md | 150 ++++++ .../version-1.2/api/ref/Types.md | 67 +++ .../versioned_docs/version-1.2/api/spec.md | 316 +++++++++++++ .../version-1.2/app-directory/spec.md | 17 + .../version-1.2/context/ref/Contact.md | 55 +++ .../version-1.2/context/ref/ContactList.md | 72 +++ .../version-1.2/context/ref/Context.md | 79 ++++ .../version-1.2/context/ref/Country.md | 59 +++ .../version-1.2/context/ref/Instrument.md | 82 ++++ .../version-1.2/context/ref/InstrumentList.md | 77 ++++ .../version-1.2/context/ref/Organization.md | 61 +++ .../version-1.2/context/ref/Portfolio.md | 99 ++++ .../version-1.2/context/ref/Position.md | 74 +++ .../version-1.2/context/spec.md | 269 +++++++++++ .../version-1.2/fdc3-charter.md | 43 ++ .../version-1.2/fdc3-compliance.md | 56 +++ .../versioned_docs/version-1.2/fdc3-intro.md | 51 ++ .../version-1.2/intents/spec.md | 60 +++ .../version-1.2/supported-platforms.md | 69 +++ .../versioned_docs/version-1.2/why-fdc3.md | 18 + .../version-1.2-sidebars.json | 87 ++++ website/versions.json | 1 + 41 files changed, 3387 insertions(+), 91 deletions(-) create mode 100644 website/pages/schemas/1.2/app-directory.html create mode 100644 website/static/schemas/1.2/app-directory.yaml create mode 100644 website/static/schemas/1.2/contact.schema.json create mode 100644 website/static/schemas/1.2/contactList.schema.json create mode 100644 website/static/schemas/1.2/context.schema.json create mode 100644 website/static/schemas/1.2/country.schema.json create mode 100644 website/static/schemas/1.2/instrument.schema.json create mode 100644 website/static/schemas/1.2/instrumentList.schema.json create mode 100644 website/static/schemas/1.2/organization.schema.json create mode 100644 website/static/schemas/1.2/portfolio.schema.json create mode 100644 website/static/schemas/1.2/position.schema.json create mode 100644 website/versioned_docs/version-1.2/api/overview.md create mode 100644 website/versioned_docs/version-1.2/api/ref/Channel.md create mode 100644 website/versioned_docs/version-1.2/api/ref/DesktopAgent.md create mode 100644 website/versioned_docs/version-1.2/api/ref/Errors.md create mode 100644 website/versioned_docs/version-1.2/api/ref/Globals.md create mode 100644 website/versioned_docs/version-1.2/api/ref/Listener.md create mode 100644 website/versioned_docs/version-1.2/api/ref/Metadata.md create mode 100644 website/versioned_docs/version-1.2/api/ref/Types.md create mode 100644 website/versioned_docs/version-1.2/api/spec.md create mode 100644 website/versioned_docs/version-1.2/app-directory/spec.md create mode 100644 website/versioned_docs/version-1.2/context/ref/Contact.md create mode 100644 website/versioned_docs/version-1.2/context/ref/ContactList.md create mode 100644 website/versioned_docs/version-1.2/context/ref/Context.md create mode 100644 website/versioned_docs/version-1.2/context/ref/Country.md create mode 100644 website/versioned_docs/version-1.2/context/ref/Instrument.md create mode 100644 website/versioned_docs/version-1.2/context/ref/InstrumentList.md create mode 100644 website/versioned_docs/version-1.2/context/ref/Organization.md create mode 100644 website/versioned_docs/version-1.2/context/ref/Portfolio.md create mode 100644 website/versioned_docs/version-1.2/context/ref/Position.md create mode 100644 website/versioned_docs/version-1.2/context/spec.md create mode 100644 website/versioned_docs/version-1.2/fdc3-charter.md create mode 100644 website/versioned_docs/version-1.2/fdc3-compliance.md create mode 100644 website/versioned_docs/version-1.2/fdc3-intro.md create mode 100644 website/versioned_docs/version-1.2/intents/spec.md create mode 100644 website/versioned_docs/version-1.2/supported-platforms.md create mode 100644 website/versioned_docs/version-1.2/why-fdc3.md create mode 100644 website/versioned_sidebars/version-1.2-sidebars.json diff --git a/CHANGELOG.md b/CHANGELOG.md index f3a19b333..55811f46c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,43 +6,55 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [FDC3 Standard 1.2] - 2021-04-16 ### Added -* [API] New raiseIntentForContext method (#268) -* [API] Add fdc3Ready event to API specification (#269, #327) -* [API] Add optional appId and version properties to AppMetadata (#273) -* [API] Define new TargetApp type for use with open and raiseIntent (#279, #315) -* [API] New getInfo method with method data about implementation (#324) -* [Package] Build and publish an npm package for FDC3 (#252) -* [Package] Add enums for intents and context types (#264) -* [Package] Add ES6 module support to FDC3 API package (#266) +* New `raiseIntentForContext()` method ([#268](https://github.com/finos/FDC3/pull/268)) +* New `fdc3Ready` event ([#269](https://github.com/finos/FDC3/pull/269)) +* New `getInfo()` method that returns implementation metadata ([#324](https://github.com/finos/FDC3/pull/324)) ### Changed -* [API] Allow AppMetadata to be passed in as a target argument (#272) -* [API] Reject/throw as appropriate in ES6 exported methods if window.fdc3 is not available (#277) -* [API] API specification clarifications around intents/context and loops when broadcasting (#285, #307, 310) -* [API] `addContextListener(type, handler)` now accepts null for type, deprecate `addContextListener(handler)` (#329) -* [API] Deprecate 'global' channel and `IntentResolution.data` (#341) -* [Website] Add/update participant logos (#209, #225, #320, #335) -* [Website] Update "Get Involved" with standards governance info (#228, #249, #300, #286) -* [Docs] Add standard version number to specification files (#331) +* `fdc3.open()` and `fdc3.raiseIntent()` now takes `TargetApp`, which resolves to `string | AppMetadata` ([#272](https://github.com/finos/FDC3/pull/272)) +* `AppMetadata` return type can now optionally include `appId` and `version` ([#273](https://github.com/finos/FDC3/pull/273)) +* `addContextListener(contextType, handler)` now supports passing `null` as the context type ([#329](https://github.com/finos/FDC3/pull/329)) +* **Deprecated**: + - `addContextListener(handler)` ([#329](https://github.com/finos/FDC3/pull/329)) + - `IntentResolution.data` and `'global'` channel concept ([#341](https://github.com/finos/FDC3/pull/341)) +* Simplify API Reference documentation and add Supported Platforms with info about npm package ([#349](https://github.com/finos/FDC3/pull/349)) ### Fixed -* [API] Missing/wrong type signature for getCurrentChannel (#222) -* [API] Support nullable return type for getCurrentChannel (#282) -* [API] Implement missing leaveCurrentChannel method (#283) -* [Schemas] Correct invalid schema references (#224) -* [Docs] Fix raiseIntent examples (#211) -* [Docs] Fix Portfolio context data example (#251) - -### Technical -* [Readme] Fix AppDirectory Readme (#274) -* [Readme] Update main Readme (#275, #318, #338) -* [GitHub] Remove FINOS SVG from project root (#204) -* [GitHub] Switch builds from Travis to GitHub workflows (#239, #252, #253, #254) -* [GitHub] Meeting workflows and templates (#292, #293) -* [Security] Upgrade dependencies to address security vulnerabilities (#207, #226, #232, #235, #238, #258, #259, #260, #289, #290, #295, #297, #330, #333, #334, #339, #340) - -## [1.1] - 2020-04-09 +* Return type of `getCurrentChannel()` should be `Promise` ([#282](https://github.com/finos/FDC3/pull/282)) +* `leaveCurrentChannel()` is missing from `DesktopAgent` interface ([#283](https://github.com/finos/FDC3/pull/283)) + +## [npm v1.1.1] - 2021-04-15 +### Fixed +* `Intents` enum should contain `StartChat` not `StartChart` ([#364](https://github.com/finos/FDC3/pull/364)) + +## [npm v1.2.0-beta] - 2021-04-14 +### Added +* ES6 functions for `getInfo()` and `raiseIntentForContext()` ([#268](https://github.com/finos/FDC3/pull/268), [#324](https://github.com/finos/FDC3/pull/324)) +* `fdc3Ready()` utility function that wraps checks for the window.fdc3 global object and new fdc3Ready event +* `compareVersionNumbers()` and `versionIsAtLeast()` utility functions to complement `getInfo()` + +### Changed +* `addContextListener(contextType, handler)` now supports passing `null` as the context type ([#329](https://github.com/finos/FDC3/pull/329)) +* **Deprecated**: `addContextListener(handler)` ([#329](https://github.com/finos/FDC3/pull/329)) and `IntentResolution.data` ([#341](https://github.com/finos/FDC3/pull/341)) +* Type expansions that form part of [FDC3 Standard 1.2] + +### Fixed +* Return type of `getCurrentChannel()` should be `Promise` ([#282](https://github.com/finos/FDC3/pull/282)) +* Missing `leaveCurrentChannel()` export ([#283](https://github.com/finos/FDC3/pull/283)) + +## [npm v1.1.0] - 2021-04-14 +### Added +* Build an npm package with exported TypeScript typings for API, Context Data and `window.fdc3` global ([#252](https://github.com/finos/FDC3/pull/252)) +* Export helper enums for names of standardised `Intents` and `ContextTypes` ([#264](https://github.com/finos/FDC3/pull/264)) +* Export API operations as ES6 functions that can be directly imported ([#266](https://github.com/finos/FDC3/pull/266)) +* Check for the existence of `window.fdc3` in ES6 functions, and reject or throw if not defined ([#356](https://github.com/finos/FDC3/pull/356)) + +### Fixed +* Return type of `getCurrentChannel()` should be `Promise` ([#222](https://github.com/finos/FDC3/pull/222)) + +## [FDC3 Standard 1.1] - 2020-04-09 ### Added * JSON Schema definitions for agreed context types ([#119](https://github.com/finos/FDC3/pull/119)): - `fdc3.context` @@ -67,54 +79,50 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `ChannelError` type * Type filtering support for `getCurrentContext` ([#161](https://github.com/finos/FDC3/pull/161)) * Publish versioned JSON schemas to FDC3 website ([#170](https://github.com/finos/FDC3/pull/170)) +* Intent Reference and Context Data Reference documentation ([#172](https://github.com/finos/FDC3/pull/172)) ### Changed +* Remove FactSet-specific examples from docs ([#88](https://github.com/finos/FDC3/pull/88)) +* Apply FINOS branding, styles and logos to the website ([#96](https://github.com/finos/FDC3/pull/96)) +* Include ChartIQ in "Who is using FDC3?" section on website ([#100](https://github.com/finos/FDC3/pull/100)) * Expand `AppMetadata` interface with more application properties ([#157](https://github.com/finos/FDC3/pull/157)) - -### Fixed -* Upgrade dependencies to address security vulnerabilities - -### Docs -* Remove FactSet-specific examples ([#88](https://github.com/finos/FDC3/pull/88)) -* Add Intent Reference and Context Data Reference ([#172](https://github.com/finos/FDC3/pull/172)) * Restructure some docs ([#190](https://github.com/finos/FDC3/pull/190)) -* Fix several typos and broken links -### Website -* Apply FINOS branding, styles and logos to the website ([#96](https://github.com/finos/FDC3/pull/96)) -* Add ChartIQ to "Who is using FDC3?" section on website ([#100](https://github.com/finos/FDC3/pull/100)) +### Fixed +* Several typos and broken links in docs +* Various security vulnerabilities -## [1.0] - 2019-03-28 +## [FDC3 Standard 1.0] - 2019-03-28 ### Added +* Documentation website (generated with [Docusaurus]) and content from old separate FDC3 repos: + - [FDC3/API](https://github.com/FDC3/API) + - [FDC3/ContextData](https://github.com/FDC3/ContextData) + - [FDC3/Intents](https://github.com/FDC3/Intents) + - [FDC3/appd-api](https://github.com/FDC3/appd-api) + - [FDC3/use-cases](https://github.com/FDC3/use-cases) * Use Case 15 ([#49](https://github.com/finos/FDC3/pull/49)) * FDC3 Roadmap ([#55](https://github.com/finos/FDC3/pull/55)) -* User showcase on website ([#67](https://github.com/finos/FDC3/pull/67)) +* FDC3 feature icons on website landing page ([#57](https://github.com/finos/FDC3/pull/57)) +* Participant showcase on website landing page ([#67](https://github.com/finos/FDC3/pull/67)) + +[Docusaurus]: https://docusaurus.io ### Changed -* Use case text on front page of website ([#54](https://github.com/finos/FDC3/pull/54)) -* Feature icons on website ([#57](https://github.com/finos/FDC3/pull/57)) +* General cleanup of spelling, grammar and punctuation ([#34](https://github.com/finos/FDC3/pull/34)) +* Use cases callout on website landing page ([#54](https://github.com/finos/FDC3/pull/54)) +* Proofreading of docs ([#62](https://github.com/finos/FDC3/pull/62)) ### Fixed -* General cleanup of spelling, grammar and punctuation ([#34](https://github.com/finos/FDC3/pull/34)) * Remove unnecessary dates from use case file names ([#41](https://github.com/finos/FDC3/pull/41)) -* Fix header colouring on responsive website ([#56](https://github.com/finos/FDC3/pull/56)) -* Fix workflow numbers in Use Case 1 ([#60](https://github.com/finos/FDC3/pull/60)) -* More proofreading changes to existing docs ([62](https://github.com/finos/FDC3/pull/62)) -* Fix examples in Intent Overview doc ([#65](https://github.com/finos/FDC3/pull/65)) -* Fix errors in DesktopAgent API doc ([#66](https://github.com/finos/FDC3/pull/66)) -* Add hyperlink to FDC3 Intro doc ([#69](https://github.com/finos/FDC3/pull/69)) - -## [1.0.0-beta] - 2019-03-05 -## Added -* API content from [FDC3/API](https://github.com/FDC3/API). -* Intent content from [FDC3/Intents](https://github.com/FDC3/Intents). -* Context Data content from [FDC3/ContextData](https://github.com/FDC3/ContextData). -* App Directory content from [FDC3/appd-api](https://github.com/FDC3/appd-api). -* Use Case content from [FDC3/use-cases](https://github.com/FDC3/use-cases). -* Documentation website generated with [Docusaurus](https://docusaurus.io). - - -[Unreleased]: https://github.com/finos/FDC3/compare/v1.1..HEAD -[1.1]: https://github.com/finos/FDC3/compare/v1.1..v1.0 -[1.0]: https://github.com/finos/FDC3/compare/v1.0..v1.0.0-beta -[1.0.0-beta]: https://github.com/finos/FDC3/releases/tag/v1.0.0-beta +* Header colouring on responsive website ([#56](https://github.com/finos/FDC3/pull/56)) +* Workflow numbers in Use Case 1 ([#60](https://github.com/finos/FDC3/pull/60)) +* Examples in Intent Overview ([#65](https://github.com/finos/FDC3/pull/65)) +* Errors in DesktopAgent API Reference ([#66](https://github.com/finos/FDC3/pull/66)) + +[Unreleased]: https://github.com/finos/FDC3/compare/v1.2..HEAD +[npm v1.2.0-beta]: https://github.com/finos/FDC3/compare/v1.1.0..v1.2.0-beta +[FDC3 Standard 1.2]: https://github.com/finos/FDC3/compare/v1.2..v1.1 +[npm v1.1.1]: https://github.com/finos/FDC3/compare/v1.1.0..v1.1.1 +[npm v1.1.0]: https://github.com/finos/FDC3/compare/v1.1..v1.1.0 +[FDC3 Standard 1.1]: https://github.com/finos/FDC3/compare/v1.1..v1.0 +[FDC3 Standard 1.0]: https://github.com/finos/FDC3/v1.0 diff --git a/website/core/Footer.js b/website/core/Footer.js index e3430870e..31268b1fe 100644 --- a/website/core/Footer.js +++ b/website/core/Footer.js @@ -33,7 +33,7 @@ class Footer extends React.Component { render() { return ( diff --git a/website/pages/schemas/1.2/app-directory.html b/website/pages/schemas/1.2/app-directory.html new file mode 100644 index 000000000..a149a1725 --- /dev/null +++ b/website/pages/schemas/1.2/app-directory.html @@ -0,0 +1,24 @@ + + + + ReDoc + + + + + + + + + + + + + \ No newline at end of file diff --git a/website/static/schemas/1.2/app-directory.yaml b/website/static/schemas/1.2/app-directory.yaml new file mode 100644 index 000000000..762f275e9 --- /dev/null +++ b/website/static/schemas/1.2/app-directory.yaml @@ -0,0 +1,383 @@ +openapi: 3.0.0 +info: + title: FDC3 Application Directory + version: 1.2 + description: > + Application Directory specification providing both interface + definition and objects necessary to construct an application directory + service. + x-logo: + url: '/img/fdc3-logo-2019-color.png' + altText: FDC3 logo +security: +- bearerAuth: [] +paths: + '/v1/apps/{appId}': + get: + summary: Retrieve an application defintion + parameters: + - name: appId + in: path + required: true + schema: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Application' + '400': + description: Bad request. + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorDTO' + '403': + description: >- + Forbidden: Certificate authentication is not allowed for the + requested user. + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorDTO' + '500': + description: 'Server error, see response body for further details.' + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorDTO' + tags: + - Application + /v1/apps: + post: + summary: Create a new application definition + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ApplicationSearchResponse' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorDTO' + '403': + description: >- + Forbidden: Certificate authentication is not allowed for the + requested user. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorDTO' + '500': + description: 'Server error, see response body for further details.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorDTO' + tags: + - Application + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Application' + required: true + /v1/apps/search: + get: + summary: Retrieve a list of applications based on parameters provided. Depending on implementation, parameter + values should self describe search format and type (e.g. Regex) + parameters: + - in: query + name: appId + schema: + type: string + required: false + description: > + The unique application identifier located within a specific + application directory instance. + - in: query + name: name + schema: + type: string + required: false + 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. + - in: query + name: manifest + schema: + type: string + required: false + 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. + - in: query + name: version + schema: + type: string + required: false + 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) + - in: query + name: title + schema: + type: string + required: false + description: >- + Optional title for the application, if missing use appName, + typically used in a launcher UI. + - in: query + name: tooltip + schema: + type: string + required: false + description: Optional tooltip description e.g. for a launcher + - in: query + name: description + schema: + type: string + required: false + description: >- + Description of the application. This will typically be a 1-2 + paragraph style blurb about the application. Allow mark up language + - in: query + name: intent_name + schema: + type: string + required: false + description: name of intent + - in: query + name: intent_displayName + schema: + type: string + required: false + description: displayName of intent + - in: query + name: intent_context + schema: + type: string + required: false + description: search contexts list + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ApplicationSearchResponse' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorDTO' + '403': + description: >- + Forbidden: Certificate authentication is not allowed for the + requested user. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorDTO' + '500': + description: 'Server error, see response body for further details.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorDTO' + tags: + - Application + +servers: + - url: /appd +components: + securitySchemes: + bearerAuth: # arbitrary name for the security scheme + type: http + scheme: bearer + bearerFormat: JWT # optional, arbitrary value for documentation purposes + schemas: + ErrorDTO: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + Application: + description: > + 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/AppImage' + contactEmail: + type: string + description: Optional e-mail to receive queries about the application + supportEmail: + type: string + 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/Icon' + 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/Intent' + ApplicationSearchResponse: + properties: + applications: + type: array + description: | + List of applications + items: + $ref: '#/components/schemas/Application' + message: + type: string + description: | + Response message providing status of query + NameValuePair: + description: Simple name value pair + properties: + name: + type: string + description: name + value: + type: string + description: value + Icon: + description: Icon holder + properties: + icon: + type: string + description: Icon URL + AppImage: + description: App Image holder + properties: + url: + type: string + 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 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. diff --git a/website/static/schemas/1.2/contact.schema.json b/website/static/schemas/1.2/contact.schema.json new file mode 100644 index 000000000..23953f356 --- /dev/null +++ b/website/static/schemas/1.2/contact.schema.json @@ -0,0 +1,18 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/contact.schema.json", + "type": "object", + "title": "Contact", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.contact" }, + "id": { + "type": "object", + "properties": { + "email": { "type": "string" }, + "FDS_ID": { "type": "string" } + } + } + }, + "required": ["id"] +} diff --git a/website/static/schemas/1.2/contactList.schema.json b/website/static/schemas/1.2/contactList.schema.json new file mode 100644 index 000000000..d8fc62f56 --- /dev/null +++ b/website/static/schemas/1.2/contactList.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/contactList.schema.json", + "type": "object", + "title": "ContactList", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.contactList" }, + "contacts": { + "type": "array", + "items": { "$ref": "contact.schema.json#/" } + } + }, + "required": ["contacts"] +} diff --git a/website/static/schemas/1.2/context.schema.json b/website/static/schemas/1.2/context.schema.json new file mode 100644 index 000000000..2623995f1 --- /dev/null +++ b/website/static/schemas/1.2/context.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/context.schema.json", + "type": "object", + "title": "Context", + "properties": { + "type": { "type": "string" }, + "name": { "type": "string" }, + "id": { + "type": "object", + "additionalProperties": { "type": "string" } + } + }, + "required": ["type"] +} diff --git a/website/static/schemas/1.2/country.schema.json b/website/static/schemas/1.2/country.schema.json new file mode 100644 index 000000000..397180170 --- /dev/null +++ b/website/static/schemas/1.2/country.schema.json @@ -0,0 +1,18 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/country.schema.json", + "type": "object", + "title": "Country", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.country" }, + "id": { + "type": "object", + "properties": { + "ISOALPHA2": { "type": "string" }, + "ISOALPHA3": { "type": "string" } + } + } + }, + "required": ["id"] +} diff --git a/website/static/schemas/1.2/instrument.schema.json b/website/static/schemas/1.2/instrument.schema.json new file mode 100644 index 000000000..70b9e403b --- /dev/null +++ b/website/static/schemas/1.2/instrument.schema.json @@ -0,0 +1,25 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/instrument.schema.json", + "type": "object", + "title": "Instrument", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.instrument" }, + "id": { + "type": "object", + "properties": { + "BBG": { "type": "string" }, + "CUSIP": { "type": "string" }, + "FDS_ID": { "type": "string" }, + "FIGI": { "type": "string" }, + "ISIN": { "type": "string" }, + "PERMID": { "type": "string" }, + "RIC": { "type": "string" }, + "SEDOL": { "type": "string" }, + "ticker": { "type": "string" } + } + } + }, + "required": ["id"] +} diff --git a/website/static/schemas/1.2/instrumentList.schema.json b/website/static/schemas/1.2/instrumentList.schema.json new file mode 100644 index 000000000..a83e6088c --- /dev/null +++ b/website/static/schemas/1.2/instrumentList.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/instrumentList.schema.json", + "type": "object", + "title": "InstrumentList", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.instrumentList" }, + "instruments": { + "type": "array", + "items": { "$ref": "instrument.schema.json#/" } + } + }, + "required": ["instruments"] +} diff --git a/website/static/schemas/1.2/organization.schema.json b/website/static/schemas/1.2/organization.schema.json new file mode 100644 index 000000000..f9e875783 --- /dev/null +++ b/website/static/schemas/1.2/organization.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/organization.schema.json", + "type": "object", + "title": "Organization", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.organization" }, + "id": { + "type": "object", + "properties": { + "LEI": { "type": "string" }, + "PERMID": { "type": "string" }, + "FDS_ID": { "type": "string" } + } + } + }, + "required": ["id"] +} diff --git a/website/static/schemas/1.2/portfolio.schema.json b/website/static/schemas/1.2/portfolio.schema.json new file mode 100644 index 000000000..1ae98df03 --- /dev/null +++ b/website/static/schemas/1.2/portfolio.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/portfolio.schema.json", + "type": "object", + "title": "Portfolio", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.portfolio" }, + "positions": { + "type": "array", + "items": { "$ref": "position.schema.json#/" } + } + }, + "required": ["positions"] +} diff --git a/website/static/schemas/1.2/position.schema.json b/website/static/schemas/1.2/position.schema.json new file mode 100644 index 000000000..146fe6fee --- /dev/null +++ b/website/static/schemas/1.2/position.schema.json @@ -0,0 +1,13 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://fdc3.finos.org/schemas/1.2/position.schema.json", + "type": "object", + "title": "Position", + "allOf": [{ "$ref": "context.schema.json#/" }], + "properties": { + "type": { "const": "fdc3.position" }, + "instrument": { "$ref": "instrument.schema.json#/" }, + "holding": { "type": "number", "minimum": 0 } + }, + "required": ["instrument","holding"] +} \ No newline at end of file diff --git a/website/versioned_docs/version-1.2/api/overview.md b/website/versioned_docs/version-1.2/api/overview.md new file mode 100644 index 000000000..983f0254c --- /dev/null +++ b/website/versioned_docs/version-1.2/api/overview.md @@ -0,0 +1,79 @@ +--- +id: version-1.2-overview +sidebar_label: API Overview +title: API Overview +hide_title: true +original_id: overview +--- +# API Overview + +The API specification of the FDC3 standard support the following goals: +- Create a consistent developer interface for working with FDC3 +- Standardize interfaces for reference implementations +- Standardize interfaces between desktop agents + +The role of FDC3 API specification is to establish a baseline interface for interoperability between applications. Because FDC3 is largely an agreement between existing platforms and applications - standards should be optimized for ease of adoption rather than functional completeness. Functionality absent from a FDC3 specification is in no way a commentary on its importance. + +The focus of the FDC3 Standard Working Group has been to create a small but consistent API, the following docs go through the components and API's in detail. + +## Key Elements + +- [`window.fdc3`](ref/Globals#windowfdc3-object) global object and [`fdc3Ready`](ref/Globals#fdc3ready-event) event, for accessing FDC3 operations globally +- [`DesktopAgent`](ref/DesktopAgent) interface, which exposes FDC3 operations +- [`Channel`](ref/Channel) interface, for subscribing to specific context channels +- [`Listener`](ref/Listener) interface, which allows unsubscribing intent or context listeners + +## Usage + +There are two main ways FDC3 can be used from web applications: + +### 1. Direct Usage + +Simply rely on the global object being made available by your desktop agent, and address the API directly: + +```ts +function sendData() { + window.fdc3.broadcast({ + type: 'fdc3.instrument', + id: { ticker: 'AAPL' } + }) +} + +if (window.fdc3) { + sendData(); +} else { + window.addEventListener("fdc3Ready", sendData); +} +``` + + +### 2. NPM Wrapper + +The [`@finos/fdc3` npm package](https://www.npmjs.com/package/@finos/fdc3) provides a wrapper around FDC3, allowing you to use it with ES6 import syntax: + +```ts +import * as fdc3 from '@finos/fdc3' + +await fdc3.raiseIntent('ViewAnalysis', { + type: 'fdc3.instrument', + id: { ticker: 'AAPL' } +}) +``` + +It also includes a helper function you can use to wait for FDC3 to become available: + +```ts +import { fdc3Ready, addIntentListener } from '@finos/fdc3' + +await fdc3Ready(); + +const listener = addIntentListener('ViewAnalysis', instrument => { + // handle intent +}) +``` + +#### See also +* [`fdc3Ready() Function`](ref/Globals#fdc3ready-function) + + + diff --git a/website/versioned_docs/version-1.2/api/ref/Channel.md b/website/versioned_docs/version-1.2/api/ref/Channel.md new file mode 100644 index 000000000..c34d10256 --- /dev/null +++ b/website/versioned_docs/version-1.2/api/ref/Channel.md @@ -0,0 +1,202 @@ +--- +id: version-1.2-Channel +sidebar_label: Channel +title: Channel +hide_title: true +original_id: Channel +--- +# `Channel` + +Represents a context channel that applications can join to share context data. + +A channel can be either a well-known "system" channel (retrieved with [`getSystemChannels`](DesktopAgent#getsystemchannels)) or a custom "app" channel (obtained through [`getOrCreateChannel`](DesktopAgent#getorcreatechannel)). + +Channels each have a unique identifier, some display metadata and operations for broadcasting context to other applications, or receiving context from other applications. + +```ts +interface Channel { + // properties + id: string; + type: string; + displayMetadata?: DisplayMetadata; + + // methods + broadcast(context: Context): void; + getCurrentContext(contextType?: string): Promise; + addContextListener(contextType: string | null, handler: ContextHandler): Listener; + /** + * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)` + */ + addContextListener(handler: ContextHandler): Listener; +} +``` + +#### See also + +* [`Context`](Types#context) +* [`DesktopAgent.getSystemChannels`](DesktopAgent#getsystemchannels) +* [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel) +* [`DesktopAgent.joinChannel`](DesktopAgent#joinchannel) + +## Properties + +### `id` + +```ts +public readonly id: string; +``` + +Uniquely identifies the channel. It is either assigned by the desktop agent (system channel) or defined by an application (app channel). + +### `type` + +```ts +public readonly type: string; +``` + +Can be _system_ or _app_. + +### `displayMetadata` + +```ts +public readonly displayMetadata?: DisplayMetadata; +``` + +DisplayMetadata can be used to provide display hints for channels intended to be visualized and selectable by end users. + +#### See also +* [`DisplayMetadata`](Metadata#displaymetadata) + +## Methods + + +### `addContextListener` +```ts +public addContextListener(contextType: string | null, handler: ContextHandler): Listener; +``` +Adds a listener for incoming contexts of the specified _context type_ whenever a broadcast happens on this channel. + +```ts +/** + * @deprecated Use `addContextListener(null, handler)` instead of `addContextListener(handler)` + */ +public addContextListener(handler: ContextHandler): Listener; +``` +Adds a listener for incoming contexts whenever a broadcast happens on the channel. + + +#### Examples + +Add a listener for any context that is broadcast on the channel: + +```ts +const listener = channel.addContextListener(null, context => { + if (context.type === 'fdc3.contact') { + // handle the contact + } else if (context.type === 'fdc3.instrument') => { + // handle the instrument + } +}); + +// later +listener.unsubscribe(); +``` + +Adding listeners for specific types of context that is broadcast on the channel: + +```ts +const contactListener = channel.addContextListener('fdc3.contact', contact => { + // handle the contact +}); + +const instrumentListener = channel.addContextListener('fdc3.instrument', instrument => { + // handle the instrument +}); + +// later +contactListener.unsubscribe(); +instrumentListener.unsubscribe(); +``` + +#### See also +* [`Listener`](Listener) +* [`ContextHandler`](Types#contexthandler) +* [`broadcast`](#broadcast) +* [`getCurrentContext`](#getcurrentcontext) + +### `broadcast` + +```typescript +public broadcast(context: Context): void; +``` + +Broadcasts a context on the channel. This function can be used without first joining the channel, allowing applications to broadcast on channels that they aren't a member of. + +If the broadcast is denied by the channel or the channel is not available, the method will return an `Error` with a string from the [`ChannelError`](ChannelError) enumeration. + +Channel implementations should ensure that context messages broadcast by an application on a channel should not be delivered back to that same application if they are joined to the channel. + +#### Example + +```javascript +const instrument = { + type: 'fdc3.instrument', + id: { + ticker: 'AAPL' + } +}; + +try { + channel.broadcast(instrument); +} catch (err: ChannelError) { + // handler errror +} +``` + +#### See also +* [`ChannelError`](Errors#channelerror) +* [`getCurrentContext`](#getcurrentcontext) +* [`addContextListener`](#addcontextlistener) + +### `getCurrentContext` + +```ts +public getCurrentContext(contextType?: string): Promise; +``` + +When a _context type_ is provided, the most recent context matching the type will be returned, or `null` if no matching context is found. + +If no _context type_ is provided, the most recent context that was broadcast on the channel - regardless of type - will be returned. If no context has been set on the channel, it will return `null`. + +It is up to the specific Desktop Agent implementation whether and how recent contexts are stored. For example, an implementation could store context history for a channel in a single array and search through the array for the last context matching a provided type, or context could be maintained as a dictionary keyed by context types. An implementation could also choose not to support context history, in which case this method will return `null` for any context type not matching the type of the most recent context. + + +If getting the current context fails, the promise will return an `Error` with a string from the [`ChannelError`](ChannelError) enumeration. + +#### Examples + +Without specifying a context type: + +```ts +try { + const context = await channel.getCurrentContext(); +} catch (err: ChannelError) { + // handler errror +} +``` + +Specifying a context type: + +```ts +try { + const contact = await channel.getCurrentContext('fdc3.contact'); +} catch (err: ChannelError) { + // handler errror +} +``` + +#### See also +* [`ChannelError`](Errors#channelerror) +* [`broadcast`](#broadcast) +* [`addContextListener`](#addcontextlistener) + diff --git a/website/versioned_docs/version-1.2/api/ref/DesktopAgent.md b/website/versioned_docs/version-1.2/api/ref/DesktopAgent.md new file mode 100644 index 000000000..3a6f06d41 --- /dev/null +++ b/website/versioned_docs/version-1.2/api/ref/DesktopAgent.md @@ -0,0 +1,436 @@ +--- +id: version-1.2-DesktopAgent +sidebar_label: DesktopAgent +title: DesktopAgent +hide_title: true +original_id: DesktopAgent +--- +# `DesktopAgent` + +An FDC3 Desktop Agent is a desktop component (or aggregate of components) that serves as an orchestrator for applications in its domain. + +A Desktop Agent can be connected to one or more App Directories and will use directories for application identity and discovery. Typically, a Desktop Agent will contain the proprietary logic of a given platform, handling functionality like explicit application interop workflows where security, consistency, and implementation requirements are proprietary. + +It is expected that the `DesktopAgent` interface is made availabe via the [`window.fdc3`](Globals#windowfdc3-object) global object, and that the [`fdc3Ready`](Globals#fdc3ready-event) event fires when it is ready to be used. + +```ts +interface DesktopAgent { + // apps + open(app: TargetApp, context?: Context): Promise; + + // context + broadcast(context: Context): void; + addContextListener(contextType: string | null, handler: ContextHandler): Listener; + /** + * @deprecated 'Use `addContextListener(null, handler)` instead of `addContextListener(handler)` + */ + addContextListener(handler: ContextHandler): Listener; + + // intents + findIntent(intent: string, context?: Context): Promise; + findIntentsByContext(context: Context): Promise>; + raiseIntent(intent: string, context: Context, app?: TargetApp): Promise; + raiseIntentForContext(context: Context, app?: TargetApp): Promise; + addIntentListener(intent: string, handler: ContextHandler): Listener; + + // channels + getOrCreateChannel(channelId: string): Promise; + getSystemChannels(): Promise>; + joinChannel(channelId: string) : Promise; + getCurrentChannel() : Promise; + leaveCurrentChannel() : Promise; + + //implementation info + getInfo(): ImplementationMetadata; +} +``` + +## Methods + +### `addContextListener` + +```ts +addContextListener(contextType: string | null, handler: ContextHandler): Listener; +/** + * @deprecated 'Use `addContextListener(null, handler)` instead of `addContextListener(handler)` + */ +addContextListener(handler: ContextHandler): Listener; +``` +Adds a listener for incoming context broadcast from the Desktop Agent. If the consumer is only interested in +a context of a particular type, they can use the relevant overload that allows the type to be specified. + +#### Examples +```js +// any context +const listener = fdc3.addContextListener(null, context => { ... }); + +// listener for a specific type +const contactListener = fdc3.addContextListener('fdc3.contact', contact => { ... }); +``` + +#### See also +* [`Listener`](Listener) +* [`Context`](Types#context) + + + +### `addIntentListener` + +```ts +addIntentListener(intent: string, handler: ContextHandler): Listener; +``` + Adds a listener for incoming Intents from the Agent. + +#### Examples + +```js +const listener = fdc3.addIntentListener('StartChat', context => { + // start chat has been requested by another application +}); +``` + +#### See also +* [`Listener`](Listener) +* [`Context`](Types#context) + + + +### `broadcast` + +```ts +broadcast(context: Context): void; +``` + +Publishes context to other apps on the desktop. Calling `broadcast` at the `DesktopAgent` scope will push the context to whatever `Channel` the app is joined to. If the app is not currently joined to a channel, calling `fdc3.broadcast` will have no effect. Apps can still directly broadcast and listen to context on any channel via the methods on the `Channel` class. + +DesktopAgent implementations should ensure that context messages broadcast to a channel by an application joined to it should not be delivered back to that same application. + +#### Example +```js +const instrument = { + type: 'fdc3.instrument', + id: { + ticker: 'AAPL' + } +}; + +fdc3.broadcast(instrument); +``` +#### See also +* [addContextListener](#addcontextlistener) + + +### `findIntent` + +```ts +findIntent(intent: string, context?: Context): Promise; +``` + +Find out more information about a particular intent by passing its name, and optionally its context. + +_findIntent_ is effectively granting programmatic access to the Desktop Agent's resolver. +It returns a promise resolving to the intent, its metadata and metadata about the apps that are registered to handle it. +This can be used to raise the intent against a specific app. + +If the resolution fails, the promise will return an `Error` with a string from the [`ResolveError`](ResolveError) enumeration. + +#### Examples +```js +// I know 'StartChat' exists as a concept, and want to know more about it ... +const appIntent = await fdc3.findIntent("StartChat"); +// returns a single AppIntent: +// { +// intent: { name: "StartChat", displayName: "Chat" }, +// apps: [{ name: "Skype" }, { name: "Symphony" }, { name: "Slack" }] +// } + +// raise the intent against a particular app +await fdc3.raiseIntent(appIntent.intent.name, context, appIntent.apps[0].name); +``` + +#### See also +* [`ResolveError`](Errors#resolveerror) + +### `findIntentsByContext` + +```ts +findIntentsByContext(context: Context): Promise>; +``` + +Find all the avalable intents for a particular context. +_findIntentsByContext_ is effectively granting programmatic access to the Desktop Agent's resolver. +A promise resolving to all the intents, their metadata and metadata about the apps that registered as handlers is returned, based on the context types the intents have registered. + + If the resolution fails, the promise will return an `Error` with a string from the [`ResolveError`](ResolveError) enumeration. + + #### Example + ```js + // I have a context object, and I want to know what I can do with it, hence, I look for intents... + const appIntents = await fdc3.findIntentsByContext(context); + + // returns, for example: + // [{ + // intent: { name: "StartCall", displayName: "Call" }, + // apps: [{ name: "Skype" }] + // }, + // { + // intent: { name: "StartChat", displayName: "Chat" }, + // apps: [{ name: "Skype" }, { name: "Symphony" }, { name: "Slack" }] + // }]; + + // select a particular intent to raise + const startChat = appIntents[1]; + + // target a particular app + const selectedApp = startChat.apps[0]; + + // raise the intent, passing the given context, targeting the app + await fdc3.raiseIntent(startChat.intent.name, context, selectedApp.name); + ``` + +#### See also + * [`ResolveError`](Errors#resolveerror) + + + +### `getCurrentChannel` + +```ts +getCurrentChannel() : Promise; +``` + +Returns the `Channel` object for the current channel membership. Returns `null` if the app is not joined to a channel. + + +#### Examples + +```js +// get the current channel membership +let current = await fdc3.getCurrentChannel(); +``` + +#### See also +* [`Channel`](Channel) + + + +### `getInfo` + +```ts +getInfo(): ImplementationMetadata; +``` + +Retrieves information about the FDC3 Desktop Agent implementation, such as the implemented version of the FDC3 specification and the name of the implementation provider. + +Returns an [`ImplementationMetadata`](Metadata#implementationmetadata) object. This metadata object can be used to vary the behavior of an application based on the version supported by the Desktop Agent and for logging purposes. + +#### Example + +```js +import {compareVersionNumbers, versionIsAtLeast} from '@finos/fdc3'; + +if (fdc3.getInfo && versionIsAtLeast(fdc3.getInfo(), "1.2")) { + await fdc3.raiseIntentForContext(context); +} else { + await fdc3.raiseIntent("ViewChart", context); +} +``` + +#### See also +* [`ImplementationMetadata`](Metadata#implementationmetadata) + +### `getOrCreateChannel` + +```ts +getOrCreateChannel(channelId: string): Promise; +``` + +Returns a Channel object for the specified channel, creating it (as an _App_ channel) - if it does not exist. +`Error` with a string from the [`ChannelError`](ChannelError) enumeration if channel could not be created or access was denied. + +#### Example + +```js +try { + const myChannel = await fdc3.getOrCreateChannel("myChannel"); + const myChannel.addContextListener(null, context => {}); +} +catch (err){ + //app could not register the channel +} + +``` + +#### See also +* [`Channel`](Channel) + +### `getSystemChannels` +```ts +getSystemChannels() : Promise>; +``` +Retrieves a list of the System channels available for the app to join. This should include the 'global' channel. + +#### Example + +```js +const systemChannels = await fdc3.getSystemChannels(); +const redChannel = systemChannels.find(c => c.id === 'red'); +``` + +#### See also +* [`Channel`](Channel) + + +### `joinChannel` + +```ts +joinChannel(channelId: string) : Promise; +``` + +Joins the app to the specified channel. +If an app is joined to a channel, all _fdc3.broadcast_ calls will go to the channel, and all listeners assigned via _fdc3.addContextListener_ will listen on the channel. +An app can only be joined to one channel at a time. +Rejects with error if the channel is unavailable or the join request is denied. + `Error` with a string from the [`ChannelError`](Errors#channelerror) enumeration. + +#### Examples + +```js +// get all system channels +const channels = await fdc3.getSystemChannels(); + +// create UI to pick from the system channels + +// join the channel on selection +fdc3.joinChannel(selectedChannel.id); + +``` +#### See also +* [`getSystemChannels`](#getSystemChannels) + + + +### `leaveCurrentChannel` + +```ts +leaveCurrentChannel() : Promise; +``` + +Removes the app from any channel membership. Context broadcast and listening through the top-level `fdc3.broadcast` and `fdc3.addContextListener` will be in a no-op when the app is not on a channel. + + +#### Examples + +```js +//desktop-agent scope context listener +const fdc3Listener = fdc3.addContextListener(null, context => {}); + +await fdc3.leaveCurrentChannel(); +//the fdc3Listener will now cease recieving context + +//listening on a specific channel though, will continue to work +redChannel.addContextListener(null, channelListener); + +``` + + + +### `open` + +```ts +open(app: TargetApp, context?: Context): Promise; +``` + +Launches an app with target information, which can be either be a string like a name, or an [`AppMetadata`](Metadata#appmetadata) object. + +The `open` method differs in use from [`raiseIntent`](#raiseIntent). Generally, it should be used when the target application is known but there is no specific intent. For example, if an application is querying the App Directory, `open` would be used to an app returned in the search results. + +**Note**, if both the intent and target app name are known, it is recommended to instead use [`raiseIntent`](#raiseIntent) with the `app` argument. + +If a [`Context`](Types#context) object is passed in, this object will be provided to the opened application via a contextListener. +The Context argument is functionally equivalent to opening the target app with no context and broadcasting the context directly to it. + +If opening errors, it returns an `Error` with a string from the [`OpenError`](Errors#openerror) enumeration. + +#### Example + ```js +// no context +await fdc3.open('myApp'); + +// no context, with AppMetadata object as target +await fdc3.open({ + name: 'myApp', + title: 'The title for the application myApp.', + description: '...' +}); + +// with context +await fdc3.open('myApp', context); +``` + +#### See also +* [`Context`](Types#context) +* [`OpenError`](Errors#openerror) + +### `raiseIntent` + +```ts +raiseIntent(intent: string, context: Context, app?: TargetApp): Promise; +``` +Raises a specific intent against a target app. + +The desktop agent will resolve the correct app to target based on the provided intent name and context data. + +If multiple matching apps are found, the user may be presented with an app picker. +Alternatively, the specific app to target can also be provided (if known). + +Returns an `IntentResolution` object with a handle to the app that responded to the intent. + +If a target app for the intent cannot be found with the criteria provided, an `Error` with a string from the [`ResolveError`](Errors#resolverrror) enumeration is returned. + +#### Example + +```js +// find apps to resolve an intent to start a chat with a given contact +const appIntent = await fdc3.findIntent("StartChat", context); + +// use the name of one of the associated apps returned by findIntent as the specific intent target +await fdc3.raiseIntent("StartChat", context, appIntent.apps[0].name); + +// or use the metadata of the app to fully describe the target app for the intent +await fdc3.raiseIntent("StartChat", context, appIntent.apps[0]); +``` +#### See also +* [`Context`](Types#context) +* [`TargetApp`](Types#targetapp) +* [`IntentResolution`](Metadata#intentresolution) +* [`ResolveError`](Errors#resolveerror) + +### `raiseIntentForContext` + +```ts +raiseIntentForContext(context: Context, app?: TargetApp): Promise; +``` + +Finds and raises an intent against a target app based purely on context data. + +The desktop agent will resolve the correct app to target based on the provided context. + +This is similar to calling `findIntentsByContext`, and then raising an intent against one of the returned apps, except in this case +the desktop agent has the opportunity to provide the user with a richer selection interface where they can choose the intent and target app. + +Returns an `IntentResolution` object with a handle to the app that responded to the selected intent. + +If a target app for the intent cannot be found with the criteria provided, an `Error` with a string from the [`ResolveError`](Errors#resolveerror) enumeration is returned. + +#### Example + +```js +const intentResolution = await fdc3.raiseIntentForContext(context); +``` + +#### See also +* [`Context`](Types#context) +* [`TargetApp`](Types#targetapp) +* [`IntentResolution`](Metadata#intentresolution) +* [`ResolveError`](Errors#resolveerror) diff --git a/website/versioned_docs/version-1.2/api/ref/Errors.md b/website/versioned_docs/version-1.2/api/ref/Errors.md new file mode 100644 index 000000000..306a08cde --- /dev/null +++ b/website/versioned_docs/version-1.2/api/ref/Errors.md @@ -0,0 +1,58 @@ +--- +title: Errors +id: version-1.2-Errors +original_id: Errors +--- + +Some FDC3 API operations return promises that can result in errors. + +## `OpenError` + +```typescript +enum OpenError { + AppNotFound = "AppNotFound", + ErrorOnLaunch = "ErrorOnLaunch", + AppTimeout = "AppTimeout", + ResolverUnavailable = "ResolverUnavailable" +} +``` + +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 +enum ResolveError { + NoAppsFound = "NoAppsFound", + ResolverUnavailable = "ResolverUnavailable", + ResolverTimeout = "ResolverTimeout" +} +``` + +Contains constants representing the errors that can be encountered when calling the [`findIntent`](DesktopAgent#findintent) or [`findIntentsByContext`](DesktopAgent#findintentsbycontext) methods on the [DesktopAgent](DesktopAgent). + +#### See also +* [`DesktopAgent.findIntent`](DesktopAgent#findintent) +* [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext) + +## `ChannelError` + +```typescript +enum ChannelError { + NoChannelFound = "NoChannelFound", + AccessDenied = "AccessDenied", + CreationFailed = "CreationFailed" +} +``` + +Contains constants representing the errors that can be encountered when calling channels using the [`joinChannel`](DesktopAgent#joinchannel) or [`getOrCreateChannel`](DesktopAgent#getorcreatechannel) methods, or the [`getCurrentContext`](Channel#getcurrentcontext), [`broadcast`](Channel#broadcast) or [`addContextListener`](Channel#addcontextlistener) methods on the `Channel` object. + +#### See also +* [`DesktopAgent.joinChannel`](DesktopAgent#joincannel) +* [`DesktopAgent.getOrCreateChannel`](DesktopAgent#getorcreatechannel) +* [`Channel.broadcast`](Channel#broadcast) +* [`Channel.addContextListener`](Channel#addcontextlistener) +* [`Channel.getCurrentContext`](Channel#getcurrentcontext) diff --git a/website/versioned_docs/version-1.2/api/ref/Globals.md b/website/versioned_docs/version-1.2/api/ref/Globals.md new file mode 100644 index 000000000..a966cd906 --- /dev/null +++ b/website/versioned_docs/version-1.2/api/ref/Globals.md @@ -0,0 +1,69 @@ +--- +title: Globals +id: version-1.2-Globals +original_id: Globals +--- + +Since FDC3 is typically available to the whole web application, desktop agents are expected to make the [`DesktopAgent`](DesktopAgent) interface available at a global level. + +## `window.fdc3` Object + +The global `fdc3` object can be used to access FDC3 API operations, if the current desktop agent supports FDC3. + +### Example + +```ts +// check if fdc3 is available +if (window.fdc3) { + // raise an intent + await window.fdc3.raiseIntent('StartChat', { + type: 'fdc3.contact', + id: { email: 'johndoe@mail.com' } + }) +} +``` + +## `fdc3Ready` Event + +The global `window.fdc3` should only be available after the API is ready to use. To prevent the API from being used before it is ready, implementors should provide an `fdc3Ready` event. + +### Example + +```ts +function fdc3Action() { + // Make some fdc3 API calls here +} + +if (window.fdc3) { + fdc3Action(); +} else { + window.addEventListener('fdc3Ready', fdc3Action); +} +``` + +## `fdc3Ready()` Function + +If you are using the `@finos/fdc3` NPM package, it includes a handy wrapper function that will check for the existence of `window.fdc3` and wait on the `fdc3Ready` event for you. + +It returns a promise that will resolve immediately if the `window.fdc3` global is already defined, or reject with an error if the `fdc3Ready` event doesn't fire after a specified timeout period (default: 5 seconds). + +### Example + +```ts +import { fdc3Ready, broadcast } from '@finos/fdc3' + +async function fdc3Action() { + try { + await fdc3Ready(1000); // wait for (at most) 1 second + broadcast({ + type: 'fdc3.instrument', + id: { ticker: 'AAPL' } + }) + } catch (error) { + // handle error + } +} +``` + + + diff --git a/website/versioned_docs/version-1.2/api/ref/Listener.md b/website/versioned_docs/version-1.2/api/ref/Listener.md new file mode 100644 index 000000000..a67b03071 --- /dev/null +++ b/website/versioned_docs/version-1.2/api/ref/Listener.md @@ -0,0 +1,32 @@ +--- +id: version-1.2-Listener +sidebar_label: Listener +title: Listener +hide_title: true +original_id: Listener +--- +# `Listener` + +A Listener object is returned when an application subscribes to intents or context broadcasts via the [`addIntentListener`](#addintentlistener) or [`addContextListener`](#addcontextlistener) methods on the [DesktopAgent](DesktopAgent) object. + +```typescript +interface Listener { + unsubscribe(): void; +} +``` + +## Methods + +### `unsubscribe` + +```ts +unsubscribe(): void; +``` + +Allows an application to unsubscribe from listening to intents or context broadcasts. + +#### See also +* [`DesktopAgent.addIntentListener`](DestkopAgent#addintentlistener) +* [`DesktopAgent.addContextListener`](DesktopAgent#addcontextlistener) +* [`Channel.addContextListener`](Channel#addcontextlistener) +* [`ContextHandler`](Types#contexthandler) diff --git a/website/versioned_docs/version-1.2/api/ref/Metadata.md b/website/versioned_docs/version-1.2/api/ref/Metadata.md new file mode 100644 index 000000000..2b201ef2a --- /dev/null +++ b/website/versioned_docs/version-1.2/api/ref/Metadata.md @@ -0,0 +1,150 @@ +--- +title: Metadata +id: version-1.2-Metadata +original_id: Metadata +--- + +FDC3 API operations return various types of metadata. + +## `AppIntent` + +```ts +interface AppIntent { + intent: IntentMetadata; + apps: Array; +} +``` +An interface that represents the binding of an intent to apps, returned as part of intent disocvery. +For each intent, it reference the applications that support that intent. + +#### See also +* [`AppMetadata`](AppMetadata) +* [`IntentMetadata`](IntentMetadata) +* [`DesktopAgent.findIntent`](DesktopAgent#findintent) +* [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext) + +## `AppMetadata` + +```ts +interface AppMetadata { + name: string; + appId?: string; + version?: string; + title?: string; + tooltip?: string; + description?: string; + icons?: Array; + images?: Array; +} +``` + +App metadata is provided by the FDC3 App Directory that the desktop agent connects to. + +It always includes at least a `name` property, which can be used with [`open`](DesktopAgent#open) and [`raiseIntent`](DesktopAgent#raiseIntent). + +Optionally, extra information from the app directory can be returned, to aid in rendering UI elements, e.g. a context menu. +This includes a title, description, tooltip and icon and image URLs. + +In situations where a desktop agent connects to multiple app directories or multiple versions of the same app exists in a single app directory, it may be neccessary to specify appId and version to target applications that share the same name. + +#### See also +* [`AppIntent.apps`](AppIntent) + +## `DisplayMetadata` + +```ts + public interface DisplayMetadata { + name?: string; + color?: string; + glyph?: string; +} +``` + +A desktop agent (typically for _system_ channels) may want to provide additional information about how a channel can be represented in a UI. A common use case is for color linking. + +#### See also + +* [`Channel`](Channel) +* [`DesktopAgent.getSystemChannels`](DesktopAgent#getsystemchannels) + +### Properties + +#### `name` + +```ts +name?: string; +``` + +The display name for the channel. + +#### `color` + +```ts +color?: string; +``` + +A name, hex, rgba, etc. that should be associated within the channel when displaying it in a UI. + +#### `glyph` + +```ts +glyph: string; +``` + +A URL of an image that can be used to display this channel. + +## `ImplementationMetadata` + +```typescript +public interface ImplementationMetadata { + fdc3Version: string; + provider: string; + providerVersion?: string; +} +``` + +Metadata relating to the FDC3 [DesktopAgent](DesktopAgent) object and its provider, including the supported version of the FDC3 specification and the name of the provider of the implementation. + +#### See also +* [`DesktopAgent.getInfo`](DesktopAgent#getInfo) + +## `IntentMetadata` + +```ts +interface IntentMetadata { + name: string; + displayName: string; +} +``` + +The Interface used to describe an Intent within the platform. + + +#### See also +* [`AppIntent.intent`](AppIntent) + +## `IntentResolution` + +```ts +interface IntentResolution { + source: TargetApp; + /** + * @deprecated not assignable from intent listeners + */ + data?: object; + version: string; +} +``` + +IntentResolution provides a standard format for data returned upon resolving an intent. + +#### Example +```js +// resolve a "Chain" type intent +const intentResolution = await fdc3.raiseIntent("intentName", context); +``` + +#### See also +* [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) +* [`DesktopAgent.raiseIntentForContext`](DesktopAgent#raiseintentforcontext) +* [`TargetApp`](TargetApp) diff --git a/website/versioned_docs/version-1.2/api/ref/Types.md b/website/versioned_docs/version-1.2/api/ref/Types.md new file mode 100644 index 000000000..5d56c97e0 --- /dev/null +++ b/website/versioned_docs/version-1.2/api/ref/Types.md @@ -0,0 +1,67 @@ +--- +title: Types +id: version-1.2-Types +original_id: Types +--- + +FDC3 API operations make use of several type declarations. + +## `Context` + +```typescript +type Context = object; +``` + +The base object that all contexts should extend. + +The API specification allows this to be any object, but typically this is supposed to be a context data object adhering to the [Context Data Specification](../../context/spec). + +This means that it must at least have a `type` property that indicates what type of data it represents, e.g. `'fdc3.contact'`. + +The `type` property of context objects is important for certain FDC3 operations, like [`Channel.getCurrentContext`](Channel#getCurrentContext) and [`DesktopAgent.addContextListener`](DesktopAgent#addContextListener), which allows you to filter contexts by their type. + +#### See also +* [`ContextHandler`](#contexthandler) +* [`DesktopAgent.open`](DesktopAgent#open) +* [`DesktopAgent.broadcast`](DesktopAgent#broadcast) +* [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener) +* [`DesktopAgent.addContextListener`](DesktopAgent#addcontextlistener) +* [`DesktopAgent.findIntent`](DesktopAgent#findintent) +* [`DesktopAgent.findIntentsByContext`](DesktopAgent#findintentsbycontext) +* [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) +* [`DesktopAgent.raiseIntentForContext`](DesktopAgent#raiseIntentForContext) +* [`Channel.broadcast`](Channel#broadcast) +* [`Channel.getCurrentContext`](Channel#getCurrentContext) +* [`Channel.addContextListener`](Channel#addContextListener) + +## `ContextHandler` + +```typescript +type ContextHandler = (context: Context) => void; +``` + +Describes a callback that handles a context event. + +Used when attaching listeners for context broadcasts and raised intents. + +#### See also +* [`Context`](#context) +* [`DesktopAgent.addIntentListener`](DesktopAgent#addintentlistener) +* [`DesktopAgent.addContextListener`](DesktopAgent#addcontextlistener) +* [`Channel.addContextListener`](Channel#addcontextlistener) + +## `TargetApp` + +```typescript +type TargetApp = string | AppMetadata; +``` + +Operations that target apps (like `open` or `raiseIntent`) can identify an app just by by its name, +or pass full app metadata, giving the desktop agent more information about the targeted app. + +#### See also +* [`AppMetadata`](Metadata#appmetadata) +* [`DesktopAgent.open`](DesktopAgent#open) +* [`DesktopAgent.raiseIntent`](DesktopAgent#raiseintent) +* [`DesktopAgent.raiseIntentForContext`](DesktopAgent#raiseintentforcontext) +* [`IntentResolution`](Metadata#intentresolution) diff --git a/website/versioned_docs/version-1.2/api/spec.md b/website/versioned_docs/version-1.2/api/spec.md new file mode 100644 index 000000000..6dc6874f1 --- /dev/null +++ b/website/versioned_docs/version-1.2/api/spec.md @@ -0,0 +1,316 @@ +--- +id: version-1.2-spec +sidebar_label: API Specification +title: API Specification 1.2 +original_id: spec +--- + +## Components +### Desktop Agent +A Desktop Agent is a desktop component (or aggregate of components) that serves as a launcher and message router (broker) for applications in its domain. A Desktop Agent can be connected to one or more App Directories and will use directories for application identity and discovery. Typically, a Desktop Agent will contain the proprietary logic of a given platform, handling functionality like explicit application interop workflows where security, consistency, and implementation requirements are proprietary. + +Examples of Desktop Agents include: + +- Autobahn +- Cosaic's Finsemble +- OpenFin +- Refinitiv Eikon + +Desktop Agents expose an FDC3 standard API to applications they have launched. When an App is launched by a Desktop Agent and is given access to the Agent's API to interoperate, it is running in that Desktop Agent's *context*. + +#### Desktop Agent Implementation +The FDC3 API specification consists of interfaces. It is expected that each Desktop Agent will implement these interfaces. A typical implemention would provide instantiable classes for the following interfaces: + +- `DesktopAgent` +- `Channel` +- `Listener` + +Other interfaces defined in the spec are not critical to define as concrete types. Rather, the Desktop Agent should expect to have objects of the interface shape passed into or out of their library. These interfaces include: + +- `Context` +- `AppIntent` +- `IntentResolution` +- `AppMetadata` +- `IntentMetadata` +- `DisplayMetadata` + + +#### API Access +The FDC3 API can be made available to an application through a number of different methods. In the case of web applications, a Desktop Agent SHOULD provide the FDC3 API via a global accessible as _window.fdc3_. Implementors MAY additionally make the API available through modules, imports, or other means. + +The global `window.fdc3` must only be available after the API is ready to use. To prevent the API from being used before it is ready, implementors SHOULD provide a global `fdc3Ready` event. Here is code demonstrating the use of the FDC3 API and the ready event: + +```js +function fdc3Stuff() { + // Make some fdc3 API calls here +} + +if (window.fdc3) { + fdc3Stuff(); +} else { + window.addEventListener('fdc3Ready', fdc3Stuff); +} +``` + +#### Standards vs. Implementation +![Desktop Agent - Standards Schematic](assets/api-1.png) + +The surface area of FDC3 standardization (shown in *white* above) itself is quite small in comparison to the extent of a typical desktop agent implementation (in *grey*). + +For example: +- workspace management +- user identity and SSO +- entitlements +- UX of application resolution + +Are all areas of functionality that any feature complete desktop agent would implement, but are not currently areas considered for standardization under FDC3. + +#### Inter-Agent Communication +A goal of FDC3 standards is that applications running in different Desktop Agent contexts on the same desktop would be able to interoperate. And that one Desktop Agent context would be able to discover and launch an application in another Desktop Application context. + +![Desktop Agent - Interop](assets/api-2.png) + +Desktop Agent interop is supported by common standards for APIs for App discovery and launching. So, an App in one Desktop Agent context would not need to know a different syntax to call an App in another Desktop Agent context. + +The actual connection protocol between Desktop Agents is not currently in scope for FDC3 standards. Given that there are a relatively small number of Desktop Agents, and that any given desktop will have a finite and relatively static number of Desktop Agents installed at any given time, the connectivity between different Agents can be adequetly handled for the time being on a case-by-case basis. + +### Application +An application is any endpoint on the desktop that is: +- Registered with/known by a Desktop Agent +- Launchable by a Desktop Agent +- Addressable by a Desktop Agent + +Examples of End Points include: +- Native Applications +- PWA/Web Applications +- Headless “services” running on the desktop + +## Functional Use Cases +### Open an Application by Name +Linking from one application to another is a critical basic workflow that the web revolutionized via the hyperlink. Supporting semantic addressing of applications across different technologies and platform domains greatly reduces friction in linking different applications into a single workflow. + +### Raising Intents +Often, we want to link from one app to another to dynamically create a workflow. Enabling this without requiring prior knowledge between apps is a key goal of FDC3. + +Intents provide a way for an app to request functionality from another app and defer the discovery and launching of the destination app to the Desktop Agent. There are multiple models for interop that Intents can support. + +- **Chain**: In this case the workflow is completely handed off from one app to another (similar to linking). Currently, this is the primary focus in FDC3. +- **Client-Service**: A Client invokes a Service via the Intent, the Service performs some function, then passes the workflow back to the Client. Typically, there is a data payload type associated with this intent that is published as the standard contract for the intent. +- **Remote API**: An app wants to remote an entire API that it owns to another App. In this case, the API for the App cannot be standardized. However, the FDC3 API can address how an App connects to another App in order to get access to a proprietary API. + +#### Intents and Context +When raising an Intent a specific context may be provided. The type of the provided context may determine which applications can resolve the Intent. + +A Context type may also be associated with multiple Intents. For example, an `fdc3.instrument` could be associated with `ViewChart`, `ViewNews`, `ViewAnalysis` or other Intents. In addition to raising a specific intent, you can raise an Intent for a specific Context allowing the Desktop Agent or the user (if the Intent is ambiguous) to select the appropriate Intent for the selected Context and then to raise that Intent for resolution. + +#### Intent Resolution +Raising an Intent will return a Promise-type object that will resolve/reject based on a number of factors. + +##### Resolve +- Intent was resolved unambiguously and the receiving app was launched successfully. +- Intent was ambiguous, a resolution was chosen by the end user, and the chosen application was launched successfully. + +##### Reject +- No app matching the intent and context (if specified) was found. +- A match was found, but the receiving app failed to launch. +- The intent was ambiguous and the resolver experienced an error. + +##### Resolution Object + +> **Deprecation notice** +> +> It is not currently possible to provide a value for the `data` property described below, +as intent listeners don't currently offer a way to return values. +> +> Future versions of FDC3 plan to remove the optional `data` property from the intent resolution object, +and include a more robust mechanism for intents that need to return data back to the caller. + +If the raising of the intent resolves (or rejects), a standard object will be passed into the resolver function with the following format: + +```js +{ + source: String; + data?: Object; + version: String; +} +``` +- *source* = identifier for the Application resolving the intent (null if the intent could not be resolved) +- *data* = return data structure - if one is provided for the given intent +- *version* = the version number of the Intents schema being used + + +For example, to raise a specific Intent: + +```js +try { + const result = await fdc3.raiseIntent('StageOrder'); +} +catch (er){ + console.log(er.message); +} +``` + +or to raise an Intent for a specific context: +```js +try { + const result = await fdc3.raiseIntentForContext(context); + if (result.data) { + const orderId = result.data.id; + } +} +catch (er){ + console.log(er.message); +} +``` + +##### Upgrading to a Remote API Connection +There are a wide range of workflows where decoupled intents and/or context passing do not provide rich enough interactivity and applications are better off exposing proprietary APIs. In these cases, an App can use the *source* property on the resolution of an intent to connect directly to another App and from there, call remote APIs using the methods available in the Desktop Agent context for the App. For example: + +```js +const chart = await fdc3.raiseIntent('ViewChart'); +// construct a vendor wrapper for the App +const chartApp = fin.Application.wrap(chart.source); +// do some vendor-specific stuff +``` +![Upgrading Connection to Remote API](assets/api-3.png) + +### Register an Intent +Applications need to let the system know the Intents they can support. Typically, this is done via registration with the App Directory. It is also possible for Intents to be registered at the application level as well to support ad-hoc registration which may be helpful at development time. While, dynamic registration is not part of this specification, a Desktop Agent agent may choose to support any number of registration paths. + +#### Compliance with Intent Standards +Intents represent a contract with expected behavior if an app asserts that it supports the intent. Where this contract is enforceable by schema (for example, return object types), the FDC3 API implementation should enforce compliance and return an error if the interface is not met. + +It is expected that App Directories will also curate listed apps and ensure that they are complying with declared intents. + +Like FDC3 Context Data, the Intent schemas need to be versioned. Desktop Agents will be responsible to declare which version of the Intent schema they are using. Applications may also assert a specific version requirement when raising an Intent. Version negotation may be supported by a given Desktop Agent. + +### Send/broadcast Context +On the financial desktop, applications often want to broadcast context to any number of applications. Context sharing needs to support concepts of different groupings of applications as well as data privacy concerns. Each Desktop Agent will have its own rules for supporting these features. However, a Desktop Agent should ensure that context messages broadcast to a channel by an application joined to it should not be delivered back to that same application. + +### Retrieve Metadata about the Desktop Agent implementation +From version 1.2 of the FDC3 specification, it is possible to retrieve information about the version of the FDC3 specification supported by a Desktop Agent implementation and the name of the implementation provider. This metadata can be used to vary the behavior of an application based on the version supported by the Desktop Agent, e.g.: + +```js +import {compareVersionNumbers, versionIsAtLeast} from '@finos/fdc3'; + +if (fdc3.getInfo && versionIsAtLeast(fdc3.getInfo(), '1.2')) { + await fdc3.raiseIntentForContext(context); +} else { + await fdc3.raiseIntent('ViewChart', context); +} +``` + +## Resolvers +Intents functionality is dependent on resolver functionality to map the intent to a specific App. This will often require end-user input. Resolution can either be performed by the Desktop Agent (raising UI to pick the desired App for the intent) or by the app launching the intent - in which case the calling App will handle the resolution itself (using the findIntents API below) and then invoke an explicit Intent object. + +## Context Channels + +Context channels allows a set of apps to share a stateful piece of data between them, and be alerted when it changes. Use cases for channels include color linking between applications to automate the sharing of context and topic based pub/sub such as theme. + +There are two types of channels, which are functionally identical, but have different visibility and discoverability semantics. + +1. The 'system' channels, which have a well understood identity. + + > **Deprecation notice:** Earlier versions of FDC3 include the concept of a 'global' system channel + for backwards compatibility with FDC3 1.0. In future, there won't be a 'global' channel + (see [below](#the-global-channel) for more detail). + +2. The 'app' channels, which have a transient identity and need to be revealed + + +### Joining Channels +Apps can join channels. An app can only be joined to one channel at a time. When an app joins a channel it will automatically recieve the current context for that channel. + +When an app is joined to a channel, calls to fdc3.broadcast and listeners added through fdc3.addContextListener will be routed to that channel. If an app is not joined to a channel these methods will be no-ops, but apps can still choose to listen and broadcast to specific channels via the methods on the `Channel` class. + +It is possible that a call to join a channel could be rejected. If for example, the desktop agent wanted to implement controls around what data apps can access. + +Joining channels in FDC3 is intended to be a behavior initiated by the end user. For example: by color linking or apps being grouped in the same workspace. Most of the time, it is expected that apps will be joined to a channel by mechanisms outside of the app. Always, there SHOULD be a clear UX indicator of what channel an app is joined to. + +### The 'global' Channel + +> **Deprecation notice** +> +> The global channel, which exists only for backward compatibility with FDC3 1.0, +will be removed in a future version of the FDC3 API Specification. +> +> Instead of relying on being joined to a 'default' channel by the desktop agent on startup, +an app or system channel should be joined explicitly through the relevant APIs, +or through a channel selection UI. + +The 'system' channels include a 'global' channel which serves as the backwards compatible layer with the 'send/broadcast context' behavior in FDC3 1.0. A desktop agent MAY choose to make membership in the 'global' channel the default state for apps on start up. + +The 'global' channel should be returned as part of the response from the `fdc3.getSystemChannels` call. Desktop Agents may want to filter out the 'global' option in their UI for system channel pickers. + + +### Examples + +An app queries the current context of the `red` channel. + +```js +const redChannel = await fdc3.getOrCreateChannel('red'); +const context = await redChannel.getCurrentContext('fdc3.instrument'); +``` + +An app can still explicitly receive context events on any channel, regardless of the channel it is currently joined to. + +```js +// check for current fdc3 channel +let joinedChannel = await fdc3.getCurrentChannel() +//current channel is null, as the app is not currently joined to a channel + +const redChannel = await fdc3.getSystemChannels.filter(c => c.id === 'red') +const context = await redChannel.getCurrentContext('fdc3.instrument') +// context is instrument AAPL on the global channel + +fdc3.joinChannel('blue') +joinedChannel = await fdc3.getCurrentChannel() +//current channel is now the 'blue' channel + +``` + +### Direct Listening and Broadcast on Channels +While joining channels automates a lot of the channel behavior for an app, it has the limitation in that an app can belong to only one channel at a time. Listening and Broadcasting to channels using the _Channel.addBroadcastListener_ and the _Channel.broadcast_ APIs provides an app with fine-grained controls for specific channels. This is especially useful for working with dynamic _App Channels_. + +### Examples +To find a system channel, one calls + +```js +// returns an array of channels +const allChannels = await fdc3.getSystemChannels(); +const redChannel = allChannels.find(c => c.id === 'red'); +``` +#### Joining channels + +To join a channel. one calls + +```js +fdc3.joinChannel(redChannel.id); +``` + +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 should not be delivered back to that same application if they are joined to the channel. + +#### App Channels + +App channels are topics dynamically created by applications connected via FDC3. For example, an app may create a channel to broadcast to others data or status specific to that app. + +To get (or create) a channel reference, then interact with it + +```js +const appChannel = await fdc3.getOrCreateChannel('my_custom_channel'); +// get the current context of the channel +const current = await appChannel.getCurrentContext(); +// add a listener +appChannel.addContextListener(null, context => {...}); +// broadcast to the channel +appChannel.broadcast(context); + +``` + +## APIs +The APIs are defined in TypeScript in [src], with documentation generated in the [docs] folder. + +[src]: https://github.com/finos/FDC3/tree/master/src/api +[docs]: https://github.com/finos/FDC3/tree/master/docs/api diff --git a/website/versioned_docs/version-1.2/app-directory/spec.md b/website/versioned_docs/version-1.2/app-directory/spec.md new file mode 100644 index 000000000..4bd43d406 --- /dev/null +++ b/website/versioned_docs/version-1.2/app-directory/spec.md @@ -0,0 +1,17 @@ +--- +id: version-1.2-spec +sidebar_label: App Directory Specification +title: App Directory Specification 1.2 +original_id: spec +--- +## API + +View the [full specification](/schemas/1.2/app-directory) in [OpenAPI v3.0](https://www.openapis.org/) format (generated with [ReDoc](https://github.com/Redocly/redoc/)). + +## Endpoints + + Endpoint | Method | Description + ------------------ | ------ | ----------- + `/v1/apps` | POST | Create a new application definition + `/v1/apps/{appId}` | GET | Retrieve an application defintion + `/v1/apps/search` | GET | Retrieve a list of applications diff --git a/website/versioned_docs/version-1.2/context/ref/Contact.md b/website/versioned_docs/version-1.2/context/ref/Contact.md new file mode 100644 index 000000000..3d8f289ca --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/Contact.md @@ -0,0 +1,55 @@ +--- +id: version-1.2-Contact +sidebar_label: Contact +title: Contact +hide_title: true +original_id: Contact +--- +# `Contact` + +A person contact that can be engaged with through email, calling, messaging, CMS, etc. + +## Type + +`fdc3.contact` + +## Schema + +https://fdc3.finos.org/schemas/1.2/contact.schema.json + +## Details + +| Property | Type | Required | Example Value | +|-------------|---------|----------|-------------------| +| `type` | string | Yes | `'fdc3.contact'` | +| `name` | string | No | `'Jane Doe'` | +| `id.email` | string | No | `'jane@mail.com'` | +| `id.FDS_ID` | string | No | `'ABC123-E'` | + +## Example + +```js +const contact = { + type: 'fdc3.contact' + name: 'Jane Doe', + id: { + email: 'jane.doe@mail.com' + } +} + + +fdc3.broadcast(contact) +``` + +## See Also + +Other Types +- [ContactList](ContactList) + +Intents +- [StartChat](../../intents/ref/StartChat) +- [StartCall](../../intents/ref/StartCall) +- [ViewContact](../../intents/ref/ViewContact) + +FINOS Financial Objects +- [Contact](https://fo.finos.org/docs/objects/contact) \ No newline at end of file diff --git a/website/versioned_docs/version-1.2/context/ref/ContactList.md b/website/versioned_docs/version-1.2/context/ref/ContactList.md new file mode 100644 index 000000000..29ba06f25 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/ContactList.md @@ -0,0 +1,72 @@ +--- +id: version-1.2-ContactList +sidebar_label: ContactList +title: ContactList +hide_title: true +original_id: ContactList +--- +# `ContactList` + +A collection of contacts, e.g. for chatting to or calling multiple contacts. + +Notes: + +- The contact list schema does not explicitly include identifiers in the `id` section, as there +is not a common standard for such identifiers. Applications can, however, populate +this part of the contract with custom identifiers if so desired. + +## Type + +`fdc3.contactList` + +## Schema + +https://fdc3.finos.org/schemas/1.2/contactList.schema.json + +## Details + +| Property | Type | Required | Example Value | +|-------------|-----------|----------|------------------------| +| `type` | string | Yes | `'fdc3.contactList'` | +| `id` | object | No | `{ customId: '5576' }` | +| `name` | string | No | `'My address book'` | +| `contacts` | Contact[] | Yes | `[contact1, contact2]` | + +## Example + +```js +const contacts = { + type: 'fdc3.contactList', + contacts: [ + { + type: 'fdc3.contact', + name: 'Jane Doe', + id: { + email: 'jane.doe@mail.com' + } + }, + { + type: 'fdc3.contact', + name: 'John Doe', + id: { + email: 'john.doe@mail.com' + } + }, + ] +} + + +fdc3.raiseIntent('StartChat', contacts) +``` + +## See Also + +Other Types +- [Contact](Contact) + +Intents +- [StartChat](../../intents/ref/StartChat) +- [StartCall](../../intents/ref/StartCall) + +FINOS Financial Objects +- [ContactList](https://fo.finos.org/docs/objects/contactlist) \ No newline at end of file diff --git a/website/versioned_docs/version-1.2/context/ref/Context.md b/website/versioned_docs/version-1.2/context/ref/Context.md new file mode 100644 index 000000000..c63c323e8 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/Context.md @@ -0,0 +1,79 @@ +--- +id: version-1.2-Context +sidebar_label: Context +title: Context +hide_title: true +original_id: Context +--- +# `Context` + +The `fdc3.context` type defines the basic contract or "shape" for all data exchanged by FDC3 operations. As such, it is not +really meant to be used on its own, but is imported by more specific type definitions (standardised or custom) to provide +the structure and properties shared by all FDC3 context data types. + +The key element of FDC3 context types is their mandatory `type` property, which is used to identify what type of data the +object represents, and what shape it has. + +Notes: + +- The FDC3 context type, and all derived types, define the minimum set of fields a context data object of a particular type +can be expected to have, but this can always be extended with custom fields as appropriate. + +## Type + +`fdc3.context` + +## Schema + +https://fdc3.finos.org/schemas/1.2/context.schema.json + +## Details + +| Property | Type | Required | Example Value | +|-------------|---------|----------|----------------------------------| +| `type` | string | Yes | `'fdc3.context'` | +| `name` | string | No | `'Display name'` | +| `id` | object | No | `{ id: 'value', 'id': 'value' }` | + +### `type` (required) + +The type property is the only _required_ part of the FDC3 context data schema. +The FDC3 [API](../../api/overview) relies on the `type` property being present to route shared context data appropriately. + +FDC3 [Intents](../../intents/overview) also register the context data types they support in an FDC3 [App Directory](../..app-directory/overview), used for intent discovery and routing. + +Standardised FDC3 context types have well-known `type` properties prefixed with the `fdc3` namespace, e.g. `fdc3.instrument`. +For non-standard types, e.g. those defined and used by a particular organisation, the convention is to prefix them with an +organization-specific namespace, e.g. `blackrock.fund`. + +See the [Context Data Specification](../../context/spec) for more information about context data types. + +### `name` (optional) + +Context data objects may include a name property that can be used for more information, or display purposes. Some +derived types may require the name object as mandatory, depending on use case. + +### `id` (optional) + +Context data objects may include a set of equivalent key-value pairs that can be used to help applications +identify and look up the context type they receive in their own domain. The idea behind this design is that applications can provide as many equivalent identifiers to a target application as possible, e.g. an instrument may be represented by an ISIN, CUSIP or Bloomberg identifier. + +Identifiers do not make sense for all types of data, so the `id` property is therefore optional, but some derived types may choose to require at least one identifier. + +## See Also + +FDC3 Specifications +- [Context Data](../../context/spec) +- [Intents](../../intents/spec) +- [API](../../api/spec) +- [App Directory](../../app-directory/spec) + +FDC3 Context Types +- [Contact](Contact) +- [ContactList](ContactList) +- [Country](Country) +- [Instrument](Instrument) +- [InstrumentList](InstrumentList) +- [Organization](Organization) +- [Position](Position) +- [Portfolio](Portfolio) diff --git a/website/versioned_docs/version-1.2/context/ref/Country.md b/website/versioned_docs/version-1.2/context/ref/Country.md new file mode 100644 index 000000000..709293a86 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/Country.md @@ -0,0 +1,59 @@ +--- +id: version-1.2-Country +sidebar_label: Country +title: Country +hide_title: true +original_id: Country +--- +# `Country` + +A country entity. + +Notes: + +- It is valid to include extra properties and metadata as part of the country payload, but the minimum requirement +is for at least one standardised identifier to be provided. + +- Try to only use country identifiers as intended and specified in the [ISO standard](https://en.wikipedia.org/wiki/ISO_3166-1). E.g. the `ISOALPHA2` property must be a recognized value and not a proprietary two-letter code. If the identifier you want to share is not a standardised and recognized one, rather define a property that makes it clear what value it is. This makes it easier for target applications. + + +## Type + +`fdc3.country` + +## Schema + +https://fdc3.finos.org/schemas/1.2/country.schema.json + +## Details + +| Property | Type | Required | Example Value | +|------------------|---------|----------|----------------------| +| `type` | string | Yes | `'fdc3.country'` | +| `name` | string | No | `'Sweden'` | +| `id.ISOALPHA2` | string | No | `'SE'` | +| `id.ISOALPHA3` | string | No | `'SWE'` | + +## Example + +```js +const country = { + type: 'fdc3.country' + name: 'Sweden', + id: { + ISOALPHA3: 'SWE' + } +} + + +fdc3.broadcast(country) +``` + +## See Also + +Intents +- [ViewNews](../../intents/ref/ViewNews) +- [ViewAnalysis](../../intents/ref/viewAnalysis) + +FINOS Financial Objects +- [Country](https://fo.finos.org/docs/objects/country) diff --git a/website/versioned_docs/version-1.2/context/ref/Instrument.md b/website/versioned_docs/version-1.2/context/ref/Instrument.md new file mode 100644 index 000000000..35bc433b8 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/Instrument.md @@ -0,0 +1,82 @@ +--- +id: version-1.2-Instrument +sidebar_label: Instrument +title: Instrument +hide_title: true +original_id: Instrument +--- +# `Instrument` + +A financial instrument from any asset class. + +Any combination of instrument identifiers can be used together to resolve ambiguity, or for a better match. + +Notes: + +- Not all applications will use the same instrument identifiers, which is why FDC3 allows for multiple to be specified. +In general, the more identifiers an application can provide, the easier it will be to achieve interoperability. + +- It is valid to include extra properties and metadata as part of the instrument payload, but the minimum requirement +is for at least one instrument identifier to be provided. + +- Try to only use instrument identifiers as intended. E.g. the `ticker` property is meant for stock tickers specifically, +if the identifier you want to share is not a stock ticker, or one of the other standardised ones, rather define +a property that makes it clear what value it is. This makes it easier for target applications. + +## Type + +`fdc3.instrument` + +## Schema + +https://fdc3.finos.org/schemas/1.2/instrument.schema.json + +## Details + +| Property | Type | Required | Example Value | +|-------------|---------|----------|---------------------| +| `type` | string | Yes | `'fdc3.instrument'` | +| `name` | string | No | `'Microsoft'` | +| `id.ticker` | string | No | `'MSFT'` | +| `id.BBG` | string | No | `'MSFT:US'` | +| `id.CUSIP` | string | No | `'594918104'` | +| `id.FDS_ID` | string | No | `'P8R3C2-R'` | +| `id.FIGI` | string | No | `'BBG000BPH459'` | +| `id.ISIN` | string | No | `'US5949181045'` | +| `id.PERMID` | string | No | `'4295907168'` | +| `id.RIC` | string | No | `'MSFT.OQ'` | +| `id.SEDOL` | string | No | `'2588173'` | + +## Example + +```js +const instrument = { + type: 'fdc3.instrument' + name: 'Microsoft', + id: { + ticker: 'MSFT', + RIC: 'MSFT.OQ', + ISIN: 'US5949181045' + } +} + +fdc3.joinChannel('global') +fdc3.broadcast(instrument) +``` + +## See Also + +Other Types +- [InstrumentList](InstrumentList) +- [Position](Position) +- [Portfolio](Portfolio) + +Intents +- [ViewAnalysis](../../intents/ref/ViewAnalysis) +- [ViewChart](../../intents/ref/ViewChart) +- [ViewInstrument](../../intents/ref/ViewInstrument) +- [ViewNews](../../intents/ref/ViewNews) +- [ViewQuote](../../intents/ref/ViewQuote) + +FINOS Financial Objects +- [Instrument](https://fo.finos.org/docs/objects/instrument) \ No newline at end of file diff --git a/website/versioned_docs/version-1.2/context/ref/InstrumentList.md b/website/versioned_docs/version-1.2/context/ref/InstrumentList.md new file mode 100644 index 000000000..b9a4008a8 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/InstrumentList.md @@ -0,0 +1,77 @@ +--- +id: version-1.2-InstrumentList +sidebar_label: InstrumentList +title: InstrumentList +hide_title: true +original_id: InstrumentList +--- +# `InstrumentList` + +A collection of instruments. Use this type for use cases that require not just a single instrument, but multiple (e.g. to populate a watchlist). + +When holding information for each instrument is required, it is recommended to use the [Portfolio](Portfolio) type, though. + +Notes: + +- The instrument list schema does not explicitly include identifiers in the `id` section, as there +is not a common standard for such identifiers. Applications can, however, populate +this part of the contract with custom identifiers if so desired. + +## Type + +`fdc3.instrumentList` + +## Schema + +https://fdc3.finos.org/schemas/1.2/instrumentList.schema.json + +## Details + +| Property | Type | Required | Example Value | +|---------------|--------------|----------|--------------------------------| +| `type` | string | Yes | `'fdc3.instrumentList'` | +| `name` | string | No | `'Interesting instruments...'` | +| `id` | object | No | `{ customId: '5464' }` | +| `instruments` | Instrument[] | Yes | `[instrument1, instrument2]` | + +## Example + +```js +const instruments = { + type: 'fdc3.instrumentList', + instruments: [ + { + type: 'fdc3.instrument', + id: { + ticker: 'AAPL' + } + }, + { + type: 'fdc3.instrument', + id: { + ticker: 'MSFT' + } + }, + ] +} + +fdc3.joinChannel('global') +fdc3.broadcast(instruments) +``` + +## See Also + +Other Types +- [Instrument](Instrument) +- [Position](Position) +- [Portfolio](Portfolio) + +Intents +- [ViewAnalysis](../../intents/ref/ViewAnalysis) +- [ViewChart](../../intents/ref/ViewChart) +- [ViewInstrument](../../intents/ref/ViewInstrument) +- [ViewNews](../../intents/ref/ViewNews) +- [ViewQuote](../../intents/ref/ViewQuote) + +FINOS Financial Objects +- [InstrumentList](https://fo.finos.org/docs/objects/instrumentlist) \ No newline at end of file diff --git a/website/versioned_docs/version-1.2/context/ref/Organization.md b/website/versioned_docs/version-1.2/context/ref/Organization.md new file mode 100644 index 000000000..35ee0ce27 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/Organization.md @@ -0,0 +1,61 @@ +--- +id: version-1.2-Organization +sidebar_label: Organization +title: Organization +hide_title: true +original_id: Organization +--- +# `Organization` + +An entity that can be used when referencing private companies and other organizations where a specific instrument is not available or desired e.g. CRM and News workflows. + +Notes: + +- It is valid to include extra properties and metadata as part of the organization payload, but the minimum requirement +is for at least one specified identifier to be provided. + +## Type + +`fdc3.organization` + +## Schema + +https://fdc3.finos.org/schemas/1.2/organization.schema.json + +## Details + +| Property | Type | Required | Example Value | +|-------------|---------|----------|---------------------------| +| `type` | string | Yes | `'fdc3.organization'` | +| `name` | string | No | `'Cargill, Incorporated'` | +| `id.LEI` | string | No | `'QXZYQNMR4JZ5RIRN4T31'` | +| `id.PERMID` | string | No | `'4296555324'` | +| `id.FDS_ID` | string | No | `'00161G-E'` | + +## Example + +```js +const organization = { + type: 'fdc3.organization' + name: 'Cargill, Incorporated', + id: { + LEI: 'QXZYQNMR4JZ5RIRN4T31', + FDS_ID: '00161G-E' + } +} + + +fdc3.broadcast(organization) +``` + +## See Also + +Other Types +- [Instrument](Instrument) + +Intents +- [ViewNews](../../intents/ref/ViewNews) +- [ViewAnalysis](../../intents/ref/viewAnalysis) + +FINOS Financial Objects +- [Organization](https://fo.finos.org/docs/objects/organization) diff --git a/website/versioned_docs/version-1.2/context/ref/Portfolio.md b/website/versioned_docs/version-1.2/context/ref/Portfolio.md new file mode 100644 index 000000000..562c3e39f --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/Portfolio.md @@ -0,0 +1,99 @@ +--- +id: version-1.2-Portfolio +sidebar_label: Portfolio +title: Portfolio +hide_title: true +original_id: Portfolio +--- +# `Portfolio` + +A financial portfolio made up of multiple positions (holdings) in several instruments. Contrast this +with e.g. the [InstrumentList](InstrumentList) type, which is just a list of instruments. + +This is a good example of how types can be composed and extended with extra properties to define more complex types. + +The [Portfolio](Portfolio) type consists of an array of [Position](Position) types, each of which +refers to a single [Instrument](Instrument) and a holding amount for that instrument. + +Notes: + +- Like all other FDC3 context types, extra properties for the portfolio can be added, the schema just +specifies the minimum contract. + +- The portfolio schema does not explicitly include identifiers in the `id` section, as there +is not a common standard for such identifiers. Applications can, however, populate +this part of the contract with custom identifiers if so desired. + +## Type + +`fdc3.portfolio` + +## Schema + +https://fdc3.finos.org/schemas/1.2/portfolio.schema.json + +## Details + +| Property | Type | Required | Example Value | +|--------------|------------|----------|---------------------------| +| `type` | string | Yes | `'fdc3.portfolio'` | +| `id` | object | No | `{ portfolioId: '7381' }` | +| `name` | string | No | `'My share portfolio'` | +| `positions` | Position[] | Yes | `[position1, position2]` | + +## Example + +```js +const portfolio = { + type: 'fdc3.portfolio', + positions: [ + { + type: 'fdc3.position', + instrument: { + type: 'fdc3.instrument' + id: { + ticker: 'AAPL' + } + }, + holding: 2000000 + }, + { + type: 'fdc3.position', + instrument: { + type: 'fdc3.instrument' + id: { + ticker: 'MSFT' + } + }, + holding: 1500000 + }, + { + type: 'fdc3.position', + instrument: { + type: 'fdc3.instrument' + id: { + ticker: 'IBM' + } + }, + holding: 3000000 + } + ] +} + +fdc3.raiseIntent('ViewAnalysis', portfolio) +``` + +## See Also + +Other Types +- [Instrument](Instrument) +- [InstrumentList](InstrumentList) +- [Position](Position) + +Intents +- [ViewAnalysis](../../intents/ref/ViewAnalysis) +- [ViewChart](../../intents/ref/ViewChart) +- [ViewNews](../../intents/ref/ViewNews) + +FINOS Financial Objects +- [Position](https://fo.finos.org/docs/objects/portfolio) diff --git a/website/versioned_docs/version-1.2/context/ref/Position.md b/website/versioned_docs/version-1.2/context/ref/Position.md new file mode 100644 index 000000000..fcf756826 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/ref/Position.md @@ -0,0 +1,74 @@ +--- +id: version-1.2-Position +sidebar_label: Position +title: Position +hide_title: true +original_id: Position +--- +# `Position` + +A financial position made up of an instrument and a holding in that instrument. This type is a good +example of how new context types can be composed from existing types. + +In this case, the instrument and the holding amount for that instrument are required values. + +The [Position](Position) type goes hand-in-hand with the [Portfolio](Portfolio) type, which represents +multiple holdings in a combination of instruments. + +Notes: + +- Like all other FDC3 context types, extra properties for the position can be added, the schema just +specifies the minimum contract. + +- The position schema does not explicitly include identifiers in the `id` section, as there +is not a common standard for such identifiers. Applications can, however, populate +this part of the contract with custom identifiers if so desired. + +## Type + +`fdc3.position` + +## Schema + +https://fdc3.finos.org/schemas/1.2/position.schema.json + +## Details + +| Property | Type | Required | Example Value | +|--------------|------------|----------|------------------------------------| +| `type` | string | Yes | `'fdc3.position'` | +| `id` | object | No | `{ positionId: '6475' }` | +| `name` | string | No | `'My Apple shares'` | +| `holding` | number | Yes | `2000000` | +| `instrument` | Instrument | Yes | `{ type: 'fdc3.instrument', ... }` | + +## Example + +```js +const position = { + type: 'fdc3.position', + instrument: { + type: 'fdc3.instrument' + id: { + ticker: 'AAPL' + } + }, + holding: 2000000 +} + +fdc3.raiseIntent('ViewChart', position) +``` + +## See Also + +Other Types +- [Instrument](Instrument) +- [Portfolio](Portfolio) + +Intents +- [ViewAnalysis](../../intents/ref/ViewAnalysis) +- [ViewChart](../../intents/ref/ViewChart) +- [ViewNews](../../intents/ref/ViewNews) + +FINOS Financial Objects +- [Position](https://fo.finos.org/docs/objects/position) \ No newline at end of file diff --git a/website/versioned_docs/version-1.2/context/spec.md b/website/versioned_docs/version-1.2/context/spec.md new file mode 100644 index 000000000..5224a30a7 --- /dev/null +++ b/website/versioned_docs/version-1.2/context/spec.md @@ -0,0 +1,269 @@ +--- +id: version-1.2-spec +sidebar_label: Context Data Specification +title: Context Data Specification 1.2 +original_id: spec +--- + +## Introduction + +To interoperate, apps need to exchange commonly recognized context structures that can indicate topic with any number of identifiers or mappings to different systems. + +Exchanging context is the most basic entry point to desktop interoperability. The barriers to adoption for this interaction must be kept as low as possible. + +There are two main use cases for exchanging context data: + +* __Transmitting reference data between applications.__ + The source application will send as many known identifiers as possible, and the target application will try to match the entity based on the identifiers. It may then choose to map to its own internal domain representation for rendering purposes. + + An example of this is sending an instrument or contact, when only an ISIN or email is required to reference the same data in another application. + +* __Transferring information between applications.__ + The source application may have data required to compose a workflow with another application, e.g. a list of contacts that have been selected, or a complex object representing an RFQ request. + + In many such cases there isn't any sensible reference identifiers that can be shared, it is instead the data itself being transferred. + +## Assumptions + +1. Context data objects are identified and routed according to their type, which is unique. +2. Any names, identifiers or extra properties are optional. +3. More complex objects can be composed from simpler objects by defining a new type, e.g a position from an instrument and a holding amount. +4. If multiple pieces of data need to be sent, an embedded array can be used, identified as a collection type, e.g. "contactList" or "portfolio". This allows for additional metadata and data relationships to be expressed. +5. There needs to be a way to reference or look up the structure of well-known context types, e.g. from a directory. + +## Other Standards + +FDC3 recognizes that there are other object definitions for providing context between applications. Most, if not all of these definitions though are platform-specific. FDC3, as a rule, sets out to be platform-agnostic and focused on creating bridges between the various walled gardens on the financial desktop. + +## The Context Interface + +```ts +interface Context { + type: string; + name?: string; + id?: { + [x:string]: string; + }, + [x: string]: any; +} +``` +### Namespacing + +All well-known types at FDC3 level should be prefixed with `fdc3`. For private type definitions, or type definitions issued by other organisations, different namespaces can be used, e.g. `blackrock.fund`, etc. + +### Versioning + +The specification recognises that evolving context data definitions over time, and helping applications to deal with changes to types, are very important. + +It may be as simple as adding an optional `$version` property to types, but it could also be a set of guidelines for adding new properties, without removing or changing existing ones. For example, web technologies like REST or GraphQL do not take a particular opinion about versioning. + +### Identifiers + +Where an identifier is the name of an existing standard, external to FDC3, it is represented in all caps. For example: FIGI, PERMID, CUSIP, ISO-2. When an identifer is a more general concept, it is represented in all lower case. For example: ticker, name, geocode, email. + +All standard identifier names are reserved names. Applications may use their own identifiers ad hoc. For example: +```json +"id": { + "CUSIP":"037833100", + "foo":"bar" +} +``` +The identifier "foo" is proprietary, an application that can use it is free to do so. However, since multiple applications may want to use the "foo" name and may use it to mean different things, there is a need for applications to ensure that their identifiers use naming conventions that will avoid collision. The recommended approach here is to prefix the identifier name with a namespace. For example: +```json +"id": { + "CUSIP":"037833100", + "com.company.foo": "000C7F-E" +} +``` + +## Standard Context Types + +The following are standard FDC3 context types. + __Note:__ The specification for these types are shared with the [FINOS Financial Objects](https://fo.finos.org) definitions, JSON schemas are hosted with FDC3. + +- __fdc3.contact__ + - A person contact that can be engaged with through email, calling, messaging, CMS, etc. + - [Financial Objects Specification](https://fo.finos.org/docs/objects/contact) + - [schema](/schemas/1.2/contact.schema.json) +- __fd3.contactList__ + - A collection of contacts. + - [Financial Objects Specification](https://fo.finos.org/docs/objects/contactlist) + - [schema](/schemas/1.2/contactList.schema.json) +- __fdc3.country__ + - A standard country entity. + - [Financial Objects Specification](https://fo.finos.org/docs/objects/country) + - [schema](/schemas/1.2/country.schema.json) +- __fdc3.instrument__ + - A financial instrument from any asset class. + - [Financial Objects Specification](https://fo.finos.org/docs/objects/instrument) + - [schema](/schemas/1.2/instrument.schema.json) +- __fdc3.instrumentList__ + - A collection of instruments. + - [Financial Objects Specification](https://fo.finos.org/docs/objects/instrumentList) + - [schema](/schemas/1.2/instrumentList.schema.json) +- __fdd3.organization__ + - A standard organization entity. + - [Financial Objects Specification](https://fo.finos.org/docs/objects/organization) + - [schema](/schemas/1.2/organization.schema.json) +- __fdc3.portfolio__ + - A collection of positions. + - [Financial Objects Specification](https://fo.finos.org/docs/objects/portfolio) + - [schema](/schemas/1.2/portfolio.schema.json) +- __fdc3.position__ + - [Financial Objects Specification](https://fo.finos.org/docs/objects/position) + - [schema](/schemas/1.2/position.schema.json) + +__Note:__ The below examples show how the base context data interface can be used to define specific context data objects. It is not the purpose of the specification at this stage to define standard representations for objects. It establishes the framework in which such definitions could be created. + +### Examples + +#### Contact +```json +{ + "type": "fdc3.contact", + "name": "John Smith", + "id":{ + "email": "john.smith@company.com", + } +} +``` + +#### ContactList +```json +{ + "type": "fdc3.contactList", + "name": "client list", + "contacts":[ + { + "type":"fdc3.contact", + "name":"joe", + "id":{ + "email": "joe@company1.com", + } + }, + { + "type":"fdc3.contact", + "name":"jane", + "id":{ + "email": "jane@company2.com", + } + } + ] +} +``` + +#### Country +```json +{ + "type":"fdc3.country", + "name":"the USA", + "id":{ + "ISOALPHA2":"US", + "ISOALPHA3":"USA" + } +} +``` + +#### Instrument +```json +{ + "type" : "fdc3.instrument", + "name" : "Apple", + "id" : + { + "ticker" : "aapl", + "ISIN" : "US0378331005", + "CUSIP" : "037833100", + "FIGI" : "BBG000B9XRY4", + } +} +``` + +#### InstrumentList +```json +{ + "type" : "fdc3.instrumentList", + "name" : "my portfolio", + "instruments" : [ + { + "type" : "fdc3.instrument", + "name" : "Apple", + "id": { + "ticker" : "aapl" + } + }, + { + "type" : "fdc3.instrument", + "name" : "International Business Machines", + "id": { + "ticker" : "ibm" + } + } + ] +} +``` + +#### Organization +```json +{ + "type": "fdc3.organization", + "name": "IBM", + "id": { + "PERMID" : "4295904307", + "LEI" : "VGRQXHF3J8VDLUA7XE92" + } +} +``` + +#### Portfolio +```json +{ + "type":"fdc3.portfolio" + "name":"my portfolio", + "positions":[ + { + "type": "fdc3.position", + "instrument": { + "type" : "fdc3.instrument", + "name" : "Apple", + "id" : + { + "ISIN" : "US0378331005" + } + }, + "holding": 500 + }, + { + "type": "fdc3.position", + "instrument": { + "type" : "fdc3.instrument", + "name" : "IBM", + "id" : + { + "ISIN" : "US4592001014" + } + }, + "holding": 1000 + } + ] +} +``` + + +#### Position +```json +{ + "type": "fdc3.position", + "instrument": { + "type" : "fdc3.instrument", + "name" : "Apple", + "id" : + { + "ISIN" : "US0378331005" + } + }, + "holding": 500 +} +``` + + diff --git a/website/versioned_docs/version-1.2/fdc3-charter.md b/website/versioned_docs/version-1.2/fdc3-charter.md new file mode 100644 index 000000000..70106ea7e --- /dev/null +++ b/website/versioned_docs/version-1.2/fdc3-charter.md @@ -0,0 +1,43 @@ +--- +title: FDC3 Charter +id: version-1.2-fdc3-charter +original_id: fdc3-charter +--- + +## Summary +The mission of the Financial Desktop Connectivity and Collaboration Consortium (FDC3) is to develop specific protocols and taxonomies to advance the ability of desktop applications in financial workflows to interoperate in a plug-and-play fashion, without prior bi-lateral agreements. + +## Scope +Financial desktop applications include any app used in common financial workflows: + +* Traditional native applications implemented in C++, .NET, Java, Python, etc. +* Hybrid web/native applications - stand alone native apps embedding Chromium (e.g. Electron, CEF, NW.js) +* Desktop web applications - platform based apps extending Chromium (e.g. OpenFin, Finsemble, Glue42) +* Common desktop applications not specific to finance, but critical to workflows - such as Excel, Outlook, etc. +* PWAs & Web applications running in a commercial browser + +This standards group is focused specifically on the desktop. Activities of the desktop interoperability group do not include: + +* Defining financial objects - where existing standards are well established +* Interoperability between mobile apps +* Interoperability via REST or other client to server communication + +Note: While these areas are out of scope, compatibility with Mobile and/or REST are still valid points of consideration for the FDC3. + +## Success Criteria +* Commitment from major banks and application vendors to support the standards set out by the FDC3 +* Workflow integrations in the wild leveraging the standards + +## Deliverables +* Define criteria and mechanics for secure communication between apps +* Define key functions that require specific standards for interoperability +* Create an agreed taxonomy for common app “intents” within financial desktop workflows +* Create an agreed taxonomy for common data to be shared across apps within financial desktop workflows +* Provide reference implementations of all standards +* Maintain the above standards and reference implementations + +### Participation +To be successful, the FDC3 is expected to have a critical mass of active participants for its duration. Effective participation in FDC3 means participation in the form of research, authoring, editing, and development activities outside the scope of attending regular meetings. + +### Licensing +The FDC3 will use Apache 2.0 license or similar for all deliverables. diff --git a/website/versioned_docs/version-1.2/fdc3-compliance.md b/website/versioned_docs/version-1.2/fdc3-compliance.md new file mode 100644 index 000000000..945fd441e --- /dev/null +++ b/website/versioned_docs/version-1.2/fdc3-compliance.md @@ -0,0 +1,56 @@ +--- +title: FDC3 Compliance +id: version-1.2-fdc3-compliance +original_id: fdc3-compliance +--- + +FDC3 standards follow the IETF best practices for keywords to Indicate Requirement levels: [RFC 2119](https://tools.ietf.org/html/rfc2119). Documentation should be updated as needed to reflect this. + +In general, the ratified FDC3 specs represent a lowest common denominator interface for interoperability. So, unless a particular item in a spec is marked with keywords such as OPTIONAL, MAY, SHOULD, or SHOULD NOT, it should be treated as REQUIRED. Since FDC3 itself is primarily concerned with establishing the baseline requirements for interoperation, this is consistent with the IETF Guidance: + +>6. **Guidance in the use of these Imperatives** +> +> Imperatives of the type defined in this memo must be used with care +> and sparingly. In particular, they MUST only be used where it is +> actually required for interoperation or to limit behavior which has +> potential for causing harm (e.g., limiting retransmisssions) For +> example, they must not be used to try to impose a particular method +> on implementors where the method is not required for +> interoperability. + +These rules would apply only to standards work within FDC3. Today, this covers API, App Directory, Context Data, and Intents working groups, it does not apply to the Use Cases working group. + +## Personas +FDC3 implementors generally fall into 2 categories: platform providers, and application providers. A platform provider supplies an implementation of the FDC3 API for applications to use. Implicitly, it connects to one or more App Directories. + +An application provider is largely a downstream consumer of FDC3 standards. It MAY use the API, it MAY use Context Data, it MAY use Intents. Application providers are only required to comply with the standards they make use of. + +Depending on persona, implementation compliance with FDC3 will mean different things. + +### Platform Provider +To meet the requirements of FDC3, a platform provider would need to support the following: + +* Connection to 1 or more App Directories meeting the FDC3 App Directory standards +* Provide an API to all applications running in the context of the platform that meets the FDC3 API standards, including: + * Support for FDC3 Context Data and Intents standards + * Support for Intent and Context resolution using a resolver UI +* At least one workflow of one of the use cases marked as Accepted by the Use Cases working group SHOULD be satisfied by the implementation. + +### Application Provider +For application providers FDC3 compliance requires: +* If intents are supported by the application, they SHOULD favor supporting applicable FDC3 defined intents over proprietary ones. +* If FDC3 defined intents are supported, they MUST meet the expected context and behavior defined for the intent. +* If proprietary intents are handled, those intents SHOULD follow the recommended naming conventions in the specification. +* If intents are supported, the application SHOULD use the addIntentListener API to set up a handler. +* If Context Data is supported by the application, they SHOULD favor supporting applicable FDC3 defined Context Data over proprietary ones. +* If FDC3 defined Context Data is supported, it MUST meet the interface defined for the type of Context Data. +* If proprietary Context Data properties are handled, they SHOULD follow any recommended naming conventions in the specification. +* If Context Data is supported, the application SHOULD use the addContextListener API to set up a handler. + +## References +The following specifications and use case references apply to the above: +* [API](api/spec) +* [App Directory](app-directory/spec) +* [Context Data](context/spec) +* [Intents](intents/spec) +* [Use Cases](use-cases/overview) diff --git a/website/versioned_docs/version-1.2/fdc3-intro.md b/website/versioned_docs/version-1.2/fdc3-intro.md new file mode 100644 index 000000000..660340a44 --- /dev/null +++ b/website/versioned_docs/version-1.2/fdc3-intro.md @@ -0,0 +1,51 @@ +--- +title: Welcome to FDC3 +sidebar_label: Introduction +id: version-1.2-fdc3-intro +original_id: fdc3-intro +--- + +FDC3 aims to provide an **open standard for interoperability** between applications on the financial desktop. + +This includes standardized verbs to invoke actions between applications (called "intents"), a standardized data format, a REST-based app directory standard, and standardized API operations. + +## Motivation + +FDC3 codifies standard patterns that application developers have been using for cross-application workflows between web and native applications +in the financial industry. + +According to the [FDC3 Charter](fdc3-charter): +> The mission of FDC3 is to develop specific protocols and taxonomies to advance the ability of desktop applications in financial workflows to interoperate in a plug-and-play fashion, without prior bi-lateral agreements. + +For more information, see [Why FDC3](why-fdc3). +## Specifications + +The standard currently consists of four complementary specifications: + +- [API](api/spec) +- [Intents](intents/spec) +- [Context Data](context/spec) +- [App Directory](app-directory/spec) + +## Use Cases + +From its inception, the standards have been informed by real-world [business use cases](use-cases/overview), which you can view on this website, +and form an important part of FDC3. +## Who is using FDC3? + +FDC3 was launched in October 2017 by [OpenFin](http://www.openfin.co) in collaboration with [major industry participants](/users). It includes representatives from over 40 major banks, buy-side firms, consultancies and financial services platforms. + +## How is FDC3 governed? + +FDC3 is hosted within, and governed by the policies of, the [Fintech Open Source Foundation](http://finos.org/) (FINOS). FINOS is an independent nonprofit organization focused on promoting open innovation within financial services. + +FDC3 uses the Apache 2.0 open source license for all deliverables. + +## Where should I go next? + +- Have a look at the [supported platforms](supported-Platforms) or [common use cases](use-cases/overview). +- Visit FDC3 [on GitHub](https://github.com/finos/FDC3). +- Download and install our [npm package](https://www.npmjs.com/package/@finos/fdc3). +- Try out an FDC3-compliant implementation, e.g. this [browser extension](https://github.com/finos/fdc3-desktop-agent). +- Join us in the [mailing list](fdc3+subscribe@finos.org) or on [Slack](https://app.slack.com/client/T01E7QRQH97/C01R0P7H5LH). +- [Participate](https://github.com/finos/FDC3#getting-involved) in the evolution of the standard. diff --git a/website/versioned_docs/version-1.2/intents/spec.md b/website/versioned_docs/version-1.2/intents/spec.md new file mode 100644 index 000000000..319a5225d --- /dev/null +++ b/website/versioned_docs/version-1.2/intents/spec.md @@ -0,0 +1,60 @@ +--- +id: version-1.2-spec +sidebar_label: Intents Specification +title: Intents Specification 1.2 +original_id: spec +--- + +## Introduction + +FDC3 [Intents](intents-intro) define a standard set of nouns and verbs that can be used to put together common cross-application workflows on the financial desktop. + +### Naming Syntax +* Intent names should be free of non-alphanumeric characters. +* ‘.’ will be used to namespace the intent (see below). +* Intent names should be in UpperCamelCase. + +### Characteristics + +Intents shoulde be: +* Recognizable + * Generally self-evident what the thing is +* Repeatable + * Many instances across the industry +* Stateless + * Workflows should not require callbacks or endpoints to maintain references to each other. Once an Intent is passed to an endpoint - it controls the rest of that workflow. +* Specific + * Terms should not be so open-ended that one endpoint could fulfill the Intent in a completely different way than another +* Distinct + * Granular enough that Intent handlers can communicate key functional differences + +### Namespaces ### +All standard Intent names are reserved. Applications may use their own Intents ad hoc. +However, there is a need for applications to ensure that their Intents avoid collision. The recommended approach here is to use the app name as the noun. For example, the ‘myChart’ App may expose the ‘ViewChart’ intent and the ‘myChart.Foo’ proprietary Intent. + +## Initial Set of Standard Intents ## + +### StartCall + * Expected Context: Contact + * Expected behavior: initiate call with contact(s) +### StartChat + * Expected Context: Contact + * Expected behavior: initiate chat with contact(s) +### ViewChart + * Expected Context: Instrument + * Expected behavior: display a chart for the context +### ViewContact + * Expected Context: Contact + * Expected behavior: display details of a contact +### ViewQuote + * Expected Context: Instrument + * Expected behavior: display pricing for an instrument +### ViewNews + * Expected Context: Instrument, Contact, Organisation, etc. + * Expected behavior: display news for a given context +### ViewInstrument + * Expected Context: Instrument + * Expected behavior: display relevant information for a given instrument +### ViewAnalysis + * Expected Context: Instrument, Organization, etc. + * Expected behavior: Send context to receiving application for displaying analysis diff --git a/website/versioned_docs/version-1.2/supported-platforms.md b/website/versioned_docs/version-1.2/supported-platforms.md new file mode 100644 index 000000000..0792da814 --- /dev/null +++ b/website/versioned_docs/version-1.2/supported-platforms.md @@ -0,0 +1,69 @@ +--- +title: Supported Platforms +id: version-1.2-supported-platforms +original_id: supported-platforms +--- + +As an open standard, FDC3 can be implemented on any platform and in any language. + +All that is required is a "desktop agent" that supports the FDC3 standard, which is responsible for co-ordinating application interactions. + +## Web + +For web applications to be FDC3-enabled, they need to run in the context of an agent that makes the FDC3 API available to the application. This desktop agent is also responsible for lauching and co-ordinating applications. It could be a browser extension, web app, or full-fledged desktop container framework. + +### Installation + +FDC3 offers the [`@finos/fdc3` npm package](https://www.npmjs.com/package/@finos/fdc3) that can by used by web applications to target operations from the [API Specification](api/spec) in a consistent way. Each FDC3-compliant desktop agent that the application runs in, can then provide an implementation of the FDC3 API operations. + + + + +```sh +npm install @finos/fdc3 +``` + + +```sh +yarn add @finos/fdc3 +``` + + + +```sh +pnpm install @finos/fdc3 +``` + + + +### Usage + +```javascript +// declare FDC3-compliant data +const instrument = { + type: 'fdc3.instrument', + id: { + ticker: 'AAPL', + ISIN: 'US0378331005', + FIGI : 'BBG000B9XRY4' + } +} + +// invoke an action in another application, with the required data +const result = await fdc3.raiseIntent('ViewAnalysis', instrument) + +// join the red channel and broadcast data to subscribers +await fdc3.joinChannel('red') +fdc3.broadcast(instrument) + +// set up a listener for incoming data +const listener = fdc3.addContextListener('fdc3.contact', contact => { }) +``` + +For details about the available API operations, see the [API Referennce](api/ref/DesktopAgent). + +## Native + +The FDC3 standard does not define wire formats for communication. Hence, for native applications to be FDC3-enabled, they need to make use of a library (e.g. a DLL in .Net or JAR file in Java) that provides them with an implementation of the FDC3 API. FDC3-enabled native applications are therefore specific to particular desktop container frameworks (or other suitable environments) that provide the necessary libraries. + +Despite this limitation, implementing support for FDC3 in a native application can allow it to interact with a wide variety of FDC3-enabled web applications. diff --git a/website/versioned_docs/version-1.2/why-fdc3.md b/website/versioned_docs/version-1.2/why-fdc3.md new file mode 100644 index 000000000..c5202d7de --- /dev/null +++ b/website/versioned_docs/version-1.2/why-fdc3.md @@ -0,0 +1,18 @@ +--- +id: version-1.2-why-fdc3 +sidebar_label: Why FDC3 +title: Why FDC3 +original_id: why-fdc3 +--- + +## Why look for FDC3-enabled applications? + +You want your business to move fast and use best of breed applications. Application integration has traditionally been a time consuming and costly exercise, meaning that once a set of applications supporting a workflow was established, changing parts of the workflow without very good reason was a no-go. The main goal of FDC3 is to standardize how applications communicate, without having defined inter-application workflows prior to being deployed. Applications that are FDC3 enabled can take part in a workflow on the desktop without any coding or manual integration, allowing you to replace one application with another application serving the same functions to the desktop (in FDC3 terms - supporting the same Intents and Context) + +## Why should I FDC3-enable my applications? + +There is a trend towards breaking up monolithic desktop applications, replacing them with adaptable workflows which involve the collaboration of multiple best-of-breed applications. Still much of the integration on the desktop is done by the actual end-user; copy/paste between applications, exporting/importing CSV files etc. Every application that has manual user input is a candidate for being FDC3-enabled, being able to demonstrate that your application can effectively take part in a workflow (without manual dual-entry or other tedious operations) is a easy route to happier users. Allowing your application to reach out to others is another way of extending the power of your offering; your app might not offer charting, but can let the end-user chart in an FDC3 enabled companion application based on context passed from your own app. + +## Why should my development team look at adopting FDC3? + +Deploying effective end-user workflows with as little development effort as possible, should be the goal for all internal/platform integration development teams. Implementing or developing on a platform that is FDC3 enabled, if done right, results in more bang for the buck. FDC3 is all about (re)usability and low-touch integration, with an [App directory](appd-intro) in place and a platform to develop on, each new enabled app broadens the value of the workflow offering. diff --git a/website/versioned_sidebars/version-1.2-sidebars.json b/website/versioned_sidebars/version-1.2-sidebars.json new file mode 100644 index 000000000..c942d1b46 --- /dev/null +++ b/website/versioned_sidebars/version-1.2-sidebars.json @@ -0,0 +1,87 @@ +{ + "version-1.2-docs": { + "Getting Started": [ + "version-1.2-fdc3-intro", + "version-1.2-supported-platforms", + "version-1.2-why-fdc3", + "version-1.2-fdc3-charter", + "version-1.2-fdc3-compliance" + ], + "API": [ + "version-1.2-api/overview", + "version-1.2-api/spec", + { + "type": "subcategory", + "label": "Reference", + "ids": [ + "version-1.2-api/ref/DesktopAgent", + "version-1.2-api/ref/Channel", + "version-1.2-api/ref/Listener", + "version-1.2-api/ref/Globals", + "version-1.2-api/ref/Types", + "version-1.2-api/ref/Metadata", + "version-1.2-api/ref/Errors" + ] + } + ], + "Intents": [ + "version-1.2-intents/overview", + "version-1.2-intents/spec", + { + "type": "subcategory", + "label": "Reference", + "ids": [ + "version-1.2-intents/ref/StartCall", + "version-1.2-intents/ref/StartChat", + "version-1.2-intents/ref/ViewChart", + "version-1.2-intents/ref/ViewContact", + "version-1.2-intents/ref/ViewQuote", + "version-1.2-intents/ref/ViewNews", + "version-1.2-intents/ref/ViewAnalysis", + "version-1.2-intents/ref/ViewInstrument" + ] + } + ], + "Context Data": [ + "version-1.2-context/overview", + "version-1.2-context/spec", + { + "type": "subcategory", + "label": "Reference", + "ids": [ + "version-1.2-context/ref/Context", + "version-1.2-context/ref/Contact", + "version-1.2-context/ref/ContactList", + "version-1.2-context/ref/Instrument", + "version-1.2-context/ref/InstrumentList", + "version-1.2-context/ref/Organization", + "version-1.2-context/ref/Country", + "version-1.2-context/ref/Position", + "version-1.2-context/ref/Portfolio" + ] + } + ], + "App Directory": [ + "version-1.2-app-directory/overview", + "version-1.2-app-directory/discovery", + "version-1.2-app-directory/usage", + "version-1.2-app-directory/spec" + ] + }, + "version-1.2-use-cases": { + "Use Cases": [ + "version-1.2-use-cases/overview", + "version-1.2-use-cases/uc-1", + "version-1.2-use-cases/uc-2", + "version-1.2-use-cases/uc-3", + "version-1.2-use-cases/uc-4", + "version-1.2-use-cases/uc-5", + "version-1.2-use-cases/uc-9", + "version-1.2-use-cases/uc-10", + "version-1.2-use-cases/uc-13", + "version-1.2-use-cases/uc-15", + "version-1.2-use-cases/uc-16", + "version-1.2-use-cases/uc-17" + ] + } +} diff --git a/website/versions.json b/website/versions.json index a74314cd1..7ed67b571 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,5 @@ [ + "1.2", "1.1", "1.0" ] From 6caff0dde8915a3a7386f8a2a2fd8a5d6b33011b Mon Sep 17 00:00:00 2001 From: Riko Eksteen Date: Fri, 16 Apr 2021 15:49:01 +0100 Subject: [PATCH 2/2] chore: increment npm package version to publish v1.2.0 - change latest standard version in README and tick 1.2 in roadmap - update CHANGELOG --- CHANGELOG.md | 39 ++++++++++++++++++++++----------------- README.md | 4 ++-- package.json | 4 ++-- 3 files changed, 26 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 55811f46c..b6e452863 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] -## [FDC3 Standard 1.2] - 2021-04-16 +## [npm v1.2.0] - 2021-04-19 + +### Added +* ES6 functions for `getInfo()` and `raiseIntentForContext()` ([#268](https://github.com/finos/FDC3/pull/268), [#324](https://github.com/finos/FDC3/pull/324)) +* `fdc3Ready()` utility function that wraps checks for the window.fdc3 global object and new `fdc3Ready` event ([#360](https://github.com/finos/FDC3/pull/360)) +* `compareVersionNumbers()` and `versionIsAtLeast()` utility functions to complement `getInfo()` ([#324](https://github.com/finos/FDC3/pull/324)) + +### Changed +* `addContextListener(contextType, handler)` now supports passing `null` as the context type ([#329](https://github.com/finos/FDC3/pull/329)) +* All other API type changes and additions from the [FDC3 Standard 1.2](https://github.com/finos/FDC3/releases/tag/v1.2) release + +### Deprecated +* `addContextListener(handler)` ([#329](https://github.com/finos/FDC3/pull/329)) +* `IntentResolution.data` ([#341](https://github.com/finos/FDC3/pull/341)) + +## [FDC3 Standard 1.2] - 2021-04-19 ### Added * New `raiseIntentForContext()` method ([#268](https://github.com/finos/FDC3/pull/268)) * New `fdc3Ready` event ([#269](https://github.com/finos/FDC3/pull/269)) @@ -16,10 +31,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * `fdc3.open()` and `fdc3.raiseIntent()` now takes `TargetApp`, which resolves to `string | AppMetadata` ([#272](https://github.com/finos/FDC3/pull/272)) * `AppMetadata` return type can now optionally include `appId` and `version` ([#273](https://github.com/finos/FDC3/pull/273)) * `addContextListener(contextType, handler)` now supports passing `null` as the context type ([#329](https://github.com/finos/FDC3/pull/329)) -* **Deprecated**: - - `addContextListener(handler)` ([#329](https://github.com/finos/FDC3/pull/329)) - - `IntentResolution.data` and `'global'` channel concept ([#341](https://github.com/finos/FDC3/pull/341)) -* Simplify API Reference documentation and add Supported Platforms with info about npm package ([#349](https://github.com/finos/FDC3/pull/349)) +* Simplify API reference documentation and add info about supported platforms, including npm package ([#349](https://github.com/finos/FDC3/pull/349)) + +### Deprecated +* `addContextListener(handler)` ([#329](https://github.com/finos/FDC3/pull/329)) +* `IntentResolution.data` and `'global'` channel concept ([#341](https://github.com/finos/FDC3/pull/341)) ### Fixed * Return type of `getCurrentChannel()` should be `Promise` ([#282](https://github.com/finos/FDC3/pull/282)) @@ -29,17 +45,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Fixed * `Intents` enum should contain `StartChat` not `StartChart` ([#364](https://github.com/finos/FDC3/pull/364)) -## [npm v1.2.0-beta] - 2021-04-14 -### Added -* ES6 functions for `getInfo()` and `raiseIntentForContext()` ([#268](https://github.com/finos/FDC3/pull/268), [#324](https://github.com/finos/FDC3/pull/324)) -* `fdc3Ready()` utility function that wraps checks for the window.fdc3 global object and new fdc3Ready event -* `compareVersionNumbers()` and `versionIsAtLeast()` utility functions to complement `getInfo()` - -### Changed -* `addContextListener(contextType, handler)` now supports passing `null` as the context type ([#329](https://github.com/finos/FDC3/pull/329)) -* **Deprecated**: `addContextListener(handler)` ([#329](https://github.com/finos/FDC3/pull/329)) and `IntentResolution.data` ([#341](https://github.com/finos/FDC3/pull/341)) -* Type expansions that form part of [FDC3 Standard 1.2] - ### Fixed * Return type of `getCurrentChannel()` should be `Promise` ([#282](https://github.com/finos/FDC3/pull/282)) * Missing `leaveCurrentChannel()` export ([#283](https://github.com/finos/FDC3/pull/283)) @@ -120,7 +125,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Errors in DesktopAgent API Reference ([#66](https://github.com/finos/FDC3/pull/66)) [Unreleased]: https://github.com/finos/FDC3/compare/v1.2..HEAD -[npm v1.2.0-beta]: https://github.com/finos/FDC3/compare/v1.1.0..v1.2.0-beta +[npm v1.2.0]: https://github.com/finos/FDC3/compare/v1.1.0..v1.2.0 [FDC3 Standard 1.2]: https://github.com/finos/FDC3/compare/v1.2..v1.1 [npm v1.1.1]: https://github.com/finos/FDC3/compare/v1.1.0..v1.1.1 [npm v1.1.0]: https://github.com/finos/FDC3/compare/v1.1..v1.1.0 diff --git a/README.md b/README.md index 164691e82..e4b163405 100755 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # FDC3 Logo -[![Latest Standard](https://img.shields.io/badge/release-1.1-blue)](https://github.com/finos/fdc3/releases/v1.1) +[![Latest Standard](https://img.shields.io/badge/release-1.2-blue)](https://github.com/finos/fdc3/releases/v1.2) [![npm](https://img.shields.io/npm/v/@finos/fdc3)](https://www.npmjs.com/package/@finos/fdc3) [![FINOS - Released](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-released.svg)](https://finosfoundation.atlassian.net/wiki/display/FINOS/Released) [![GitHub](https://img.shields.io/github/license/finos/fdc3)](https://opensource.org/licenses/Apache-2.0) @@ -108,8 +108,8 @@ Despite this limitation, implementing support for FDC3 in a native application c # Roadmap - [x] Publish versioned NPM packages to ease adoption and implementation of FDC3 APIs. +- [x] Release version 1.2 of the standard with expanded API capabilities. - [ ] Establish a process to accelerate community-contributed context data definitions. -- [ ] Release version 1.2 of the standard with expanded API capabilities. - [ ] Release version 2.0 of the standard with support for app instances, two-way data flow and joining multiple channels. - [ ] Improve the app directory specification, with support for container-agnostic app manifests, and more type metadata around channels and launching apps. - [ ] Introduce a hosted app directory example with sample application definitions. diff --git a/package.json b/package.json index 4253ce253..f71e61726 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@finos/fdc3", - "version": "1.2.0-beta", + "version": "1.2.0", "author": "Fintech Open Source Foundation (FINOS)", "homepage": "https://fdc3.finos.org", "repository": { @@ -8,7 +8,7 @@ "url": "https://github.com/finos/FDC3.git" }, "publishConfig": { - "tag": "next" + "tag": "latest" }, "license": "Apache-2.0", "main": "dist/index.js",