FDC3 Standard 2.1

v2.1 of the FDC3 standard, consisting of:

• Desktop Agent API 2.1
• App Directory API 2.1
• Intents 2.1
• Context Data 2.1
• Agent Bridging 2.1

Release highlights

Agent Bridging

• A new 5th Part to the FDC3 Standard that provides a wire protocol that allows Desktop Agents to collaborate via a 'Bridge', enabling interop for apps managed by those Desktop Agents to span across them and across different devices, for the same user.

API

• Added MalformedContext errors to be returned when something other than a context is passed to an FDC3 function.
• Added a recommendation that apps add their context or intent listeners via the API within 15 seconds of launch, and that Desktop Agents MUST allow at least a 15 second timeout for them to do so.
• Deprecated the IntentMetadata.displayName field in favor of using intent names for display (which are required to be recognizable) as it can be set differently for each application in the appD.
• Clarified description of the behavior of IntentResolution.getResult() when the intent handler returned void (which is not an error).

App Directory

• OpenAPI spec converted from YAML to JSON Schema.
• Added error examples to the OpenAPI spec.
• Corrected the appD interop.appChannels metadata to use an id field to identify channels, rather than name.
• Deprecated the name field in AppD records, to match the deprecation of API signatures and metadata objects using name.
• Deprecated interop.intents.listensFor[].displayName field in favor of using intent names for display (which are required to be recognizable) as it can be set differently for each application in the appD.
• Deprecated the customConfig field in an AppD record due to the lack of a standard API to retrieve it. To be replaced with an applicationConfig element with a Desktop Agent API call to retrieve it in a future version (see #1006 for more details).
• Deprecated the customConfig element of an Intent configuration due to a lack of documented use cases.
• Corrected bad example URLs in the App Directory overview/discovery page in the current and past versions as they did not agree with the paths provided in the API specification and OpenAPI schema.

Context Data

• Added a description of the standards use of JSON Schema to define context types and Bridging messages.
• Docs for standardized Context types was added to their JSON Schema files and TypeScript interfaces generated from them, so that they may act as a 'single source of truth' for Context definitions.
• Updated definition of the fdc3.instrument context type to include optional market identifiers
• New context types added:
  • fdc3.action - context type representing an action (an FDC3 intent and context) that might be performed - to be attached to messages or other objects.
  • fdc3.chat.message - context type representing a chat message with addressing details.
  • fdc3.chat.room - context type representing a chat room.
  • fdc3.chat.searchCriteria - context type representing a search for chat messages.
  • fdc3.message - context type representing the content of a message to send (usually a chat message) - now used as part of fdc3.chat.initSettings.
  • fdc3.transactionResult - A context type representing the result of a transaction initiated via FDC3.
  • Added @experimental fdc3.order, fdc3.orderList, fdc3.product, fdc3.trade & fdc3.tradeList context types.

Intents

• CreateInteraction - To be used when a user wants to record an interaction into a CRM.
• ViewChat - to be used when a user wants to open an existing chat room.
• ViewMessages - to be used when a user wants to search and see a list of messages.
• StartChat - Updated to recommend that a reference to the chat room is returned as an IntentResult

See the CHANGELOG.md for full details.

FDC3 Standard 2.0

v2.0 of the FDC3 standard, consisting of:

• Desktop Agent API 2.0
• App Directory API 2.0
• Intents 2.0
• Context Data 2.0

Release highlights

Formal specification

• Significantly improved both the structure and content of the Standard's documentation (including merging the overview and specification pages for each part of the standard, ensuring the docs are DRY)
• Introduced abstract, glossary, references and trademarks pages.
• Consolidated compliance information for each part of the standard and both 'personas' (Platform providers and Application providers).
• Documented existing deprecation and versioning policies and new experimental features policy.
• Create a Community page to showcase support for and uptake of the FDC3 Standard.

API

• Added the ability to return data or a channel from a raised intent, via the addition of an IntentHandler type and a getResult() to IntentResolution.
• All DesktopAgent and Channel API functions are now async for consistency, changing the return type of the broadcast, addIntentListener, addContextListener and getInfo functions.
• Added support for targetting of intents at specific app instances via an instanceId (and optional instanceMetadata) field to AppIdentifier and AppMetadata and a new `findInstances() function.
• Added a new recommended set of user channel definitions to promote consistency between Desktop Agents (in anticipation of Desktop Agent implementations communicating with each other in future).
• Added the optional exposure of originating app metadata to messages received.
• Added a getAppMetdata() function to the desktop agent that can be used to retrieve the full AppMetadata for an AppIdentifier and reduced types such as IntentResolution.source and ContextMetadata.source from AppMetadata to AppIdentifier to clarify what fields a developer can rely on and that they should manually retrieve the full AppMetadata when they need it for display purposes.
• Clarified descriptions of expected behaviour of many functions including raiseIntent, addContextListener and joinChannel
• Clarified how the broadcast of 'composed' types should be handled so that apps can respond to the sub-types (broadcast each subtype that you expect other apps to respond to, then the composed type).
• Replaced 'System channels' to 'User channels' to better reflect their usage and reduce developer confusion about the difference between User channels and App Channels.
• Adjusted wording in API spec and documentation to acknowledge the possibility of methods of intent resolution other than a resolver UI.
• The joinChannel, getCurrentChannel and leaveCurrentChannel` functions have been made optional for FDC3 API compliance (as equivalent functionality is usually implemented by a Desktop Agent via a selector UI on the window chrome.
• open, raiseIntent and raiseIntentForContext function signatures that make use of the app name have been deprecated in favour of using AppIdentifier (which is a new parent of AppMetadata that clarifies required fields for API call parameters)
• Removed details of the 'global' channel that was deprecated in FDC3 1.2.

App Directory

• Reconfirmed the role appD in FDC3 and its description via a re-written AppD overview page.
• Added /v2/ paths to the AppD's specification, allowing a single implementation to support serving both FDC3 v1.2 and v2.0 application records, enabling simpler migration.
• App Directory endpoint for creating applications was removed as these will often be implementation dependent and should not be required for compliance.
• App Directory endpoint for searching applications was removed as searches over multiple app directories are better implemented by retrieving all the records and searching over the resulting combined dataset.
• Changes to app directory records:
  • Improved container independence of appD records by adding support for including or referencing multiple container or web app manifests for each app by removing the manifestType and manifest properties and replacing them with the new type (required), details and hostManifests properties.
  • Added better support for native applications in appD via the new type and details fields.
  • Added an interop field to AppD application records, replacing the intents field, to more fully describe an app's use of FDC3 and enable search for apps that 'interoperate' with a selected app
  • images field was replaced with screenshots to better align the application record with web application manifest and match its format to that used by icons
  • Added a moreInfo URL field to AppD application records to enable linking to a web page with more information on an app.
  • Added lang field to AppD application records to specify the primary language of an app and its appD record.
  • Added localizedVersions field to AppD application records to support localized versions of descriptive fields in the app records
  • Added categories field and recommended categories list to AppD application records to enable category based browsing of AppDs

Intents

• Extended Intent Naming conventions to support intents that return or interact with data.
• Added new intent definitions:
  • ViewResearch: see the latest research on a particular stock.
  • ViewProfile: supersedes the ViewContact intent and allows the viewing of profiles for different entity types (e.g. organisations).
  • ViewInteractions: see the latest interactions (calls, meetings, conferences, roadshows) on a particular stock or with an individual or organization.
  • ViewOrders: see the order history of an individual, an institution or of a particular instrument.
  • StartEmail: initiate an email with a contact or list of contacts.
• Deprecated the ViewContact intent, which is superseded by ViewProfile.

Contexts

• Added support for raiseIntent without a context via the addition of the fdc3.nothing context type (#375)
• Added new context types representing:
  • a range of time: `fdc3.timerange.
  • a currency: fdc3.currency.
  • the price and value of a holding fdc3.valuation.
  • a chart fdc3.chart.
  • parameters for the initialization of a chat conversation fdc3.chat.initSettings.
  • parameters for the initialization of an email to a contact or list of contacts fdc3.email
• Extended recommended field type conventions for contexts to include types for ids, times, dates, currency codes and country codes.
  • The fdc3.country context type was updated to comply with the recommended field name for country codes (COUNTRY_ISOALPHA2).
  • Updated definition of the Position context type to support negative (short) positions

See the CHANGELOG.md for full details.

npm v1.2.0

v1.2.0 release of the @finos/fdc3 npm package, corresponding with the FDC3 Standard v1.2.

Release highlights

New ES6 Imports

The new methods from the FDC3 1.2 Standard, raiseIntentForContext() and getInfo(), can now be imported:

import { raiseIntentForContext, getInfo } from '@finos/fdc3'

const info = getInfo()
console.log('FDC3 version: ' + info.fdc3Version)

await raiseIntentForContext({
  type: 'fdc3.instrument',
  id: {
    ticker: 'AAPL'
  }
})

New utility functions

• The fdc3Ready() function wraps waiting for the window.fdc3 global and the new fdc3Ready event:

import { fdc3Ready, joinChannel, broadcast } from '@finos/fdc3'

await fdc3Ready(1000) // specify the amount of milliseconds to wait before a timeout error

await joinChannel('blue')

broadcast({
  type: 'fdc3.contact',
  id: {
    email: '[email protected]'
  }
})

• The compareVersionNumbers() and versionIsAtLeast() functions can be used together with getInfo() for version checking:

import * as fdc3 from '@finos/fdc3'

const info = fdc3.getInfo()

if (fdc3.versionIsAtLeast(info, 1.2)) {
  console.log('Version is >= 1.2')
}

🚀 New Features

• ES6 functions for getInfo() and raiseIntentForContext() (#268, #324)
• fdc3Ready() utility function that wraps checks for the window.fdc3 global object and new fdc3Ready event (#360)
• compareVersionNumbers() and versionIsAtLeast() utility functions to complement getInfo() (#324)

💅 Enhancements

• addContextListener(contextType, handler) now supports passing null as the context type (#329)
• All other API type changes and additions from the FDC3 Standard 1.2 release

👎 Deprecated

• addContextListener(handler) (#329)
• IntentResolution.data (#341)

See CHANGELOG.md for more details.

FDC3 Standard 1.2

v1.2 of the FDC3 standard, consisting of:

• API 1.2 [Specification] [Overview]
• Intents 1.2 [Specification] [Overview]
• Context Data 1.2 [Specification] [Overview]
• App Directory 1.2 [Specification] [Overview]

Release highlights

Raising an intent for a context type

The new raiseIntentForContext() method allows an application to start just with an FDC3 context data type, and then ask the desktop agent to raise an appropriate intent for that type.

This is similar to calling findIntentsByContext(), followed by raiseIntent(), but an application doesn't have to select from the available intents itself, or ask the user to. It allows the desktop agent to look up all matching intents and apps, and then use its own resolution logic (which could include an agent-provided selection dialog).

Example

const instrument = {
  type: 'fdc3.instrument',
  id: {
    ticker: 'AAPL'
  }
}

await fdc3.raiseIntentForContext(instrument)

fdc3Ready event

Knowing when the window.fdc3 global object will be initialised and set by the current desktop agent was a challenge in earlier versions of FDC3. The 1.2 API specification adds the concept of a global fdc3Ready event that applications can listen for to know when the FDC3 desktop environment has been initialised, and the window.fdc3 global object is available for use:

Example

if (window.fdc3) {
  action()
} else {
  window.addEventListener('fdc3Ready', action)
}

Specifying metadata for target applications

In FDC3 1.0 and 1.1, the open() and raiseIntent() methods accepts can target specific applications by specifying a string application identifier.

In FDC3 1.2, these methods (along with the new raiseIntentForContext() method) will now also accept the AppMetadata interface to help workflows to be even more targeted, and desktop agents to better identify target applications.

In addition, the AppMetadata interface has been expanded to optionally include appId and version.

Example

const target: TargetApp = {
  name: 'MyApp',
  version: '2.5'
}

await fdc3.open(target)

Obtain information about the current FDC3 environment

A new getInfo() method has been added to FDC3 that returns metadata about the FDC3 implementation that is currently being used, which includes the FDC3 version, as well as (optionally) the provider name and version.

Example

const info = fdc3.getInfo()
console.log('FDC3 version: ' + info.fdc3Version)

🚀 New Features

• New raiseIntentForContext() method (#268)
• New fdc3Ready event (#269)
• New getInfo() method that returns implementation metadata (#324)

💅 Enhancements

• fdc3.open() and fdc3.raiseIntent() now takes TargetApp, which resolves to string | AppMetadata (#272)
• AppMetadata return type can now optionally include appId and version (#273)
• addContextListener(contextType, handler) now supports passing null as the context type (#329)
• Simplify API reference documentation and add info about supported platforms, including npm package (#349)

👎 Deprecated

• addContextListener(handler) (#329)
• IntentResolution.data and 'global' channel concept (#341)

🐛 Bug Fixes

• Return type of getCurrentChannel() should be Promise<Channel | null> (#282)
• leaveCurrentChannel() is missing from DesktopAgent interface (#283)

See the CHANGELOG.md for full details.

npm v1.2.0-beta

Beta package to coincide with the upcoming release of the FDC3 1.2 Standard.

Included in this release:

• Updated TypeScript typings to match the 1.2 API specification, including correct typings for getCurrentChannel() and leaveCurrentChannel(), support for TargetApp in open and raiseIntent, and addContextListener(contextType, handler) accepting null for the contextType argument
• New exported ES6 functions: getInfo(), raiseIntentForContext()
• New exported fdc3Ready() utility function that wraps checks for the window.fdc3 global object and new fdc3Ready event
• New exported compareVersionNumbers() and versionIsAtLeast() utility functions for use together with getInfo()
• Marked IntentResolution.data and addContextListener(handler) as deprecated

npm v1.1.1

🐛 Bug Fix

• Intents enum should contain StartChat not StartChart (#364)

See CHANGELOG.md for more details.

npm v1.1.0

The first official release of the @finos/fdc3 npm package, corresponding with the FDC3 Standard v1.1.

Release highlights

API Typings

This release includes TypeScript typings for the FDC3 [DesktopAgent] interface and related types, as well as the window.fdc3 global object, e.g:

import { DesktopAgent, Channel } from '@finos/fdc3'

let channel: Channel;

async function fdc3Action() {
  channel = await window.fdc3.getOrCreateChannel('red');

  // use channel
}

ES6 Imports

The npm package also exposes the FDC3 API operations as ES6 functions that can be imported directly into your code, e.g.:

import { raiseIntent } from '@finos/fdc3'

const instrument = {
  type: 'fdc3.instrument',
  id: {
    ticker: 'AAPL'
  }
};

await raiseIntent('ViewAnalysis', instrument);

These functions will reject or throw appropriately if window.fdc3 is not defined when they are called.

Context Types

The package also includes generated TypeScript types for all standardised FDC3 Context Types, e.g.:

import { Contact } from '@finos/fdc3'

const contact: Contact = {
  type: 'fdc3.contact',
  id: {
    email: '[email protected]
  },
  name: 'Joe Bloggs'
};

Also included is a Convert helper object for generating for converting from raw JSON to the relevant type, e.g.:

import { Convert } from '@finos/fdc3'

const json = '{ "type": "fdc3.contact", "id": { "email": "[email protected]" }, "name": "Joe Bloggs" }';

const contact = Convert.toContact(json);

The typings and conversion helper were generated with QuickType.

Enums for Intents and Context Types

The included Intents and ContextTypes enums provide named constants for the specific intents and context types that have been standardised as part of FDC3 1.1, so that strings don't have to be used:

import { ContextTypes, Intents, raiseIntent } from '@finos/fdc3'

const instrument = {
  type: ContextTypes.Instrument,
  id: {
    ticker: 'AAPL'
  }
}

await raiseIntent(Intents.ViewNews, instrument);

🚀 New Features

• Build an npm package with exported TypeScript typings for API, Context Data and window.fdc3 global (#252)
• Export helper enums for names of standardised Intents and ContextTypes (#264)
• Export API operations as ES6 functions that can be directly imported (#266)
• Check for the existence of window.fdc3 in ES6 functions, and reject or throw if not defined (#356)

🐛 Bug Fix

• Return type of getCurrentChannel() should be Promise<Channel> (#222)

See CHANGELOG.md for more details.

FDC3 Standard 1.1

v1.1 of the FDC3 standard, consisting of:

• API 1.1 [Specification] [Reference]
• Intents 1.1 [Specification] [Reference]
• Context Data 1.1 [Specification] [Reference]
• App Directory 1.1 [Specification] [OpenAPI Reference]
• Use Cases 1.1 [Overview]

Release higlights

New Channels API

A brand new Channels API, which supports linking applications together through context shared on dedicated channels.

Applications can join and leave channels, which affects the scope of the top-level fdc3.broadcast and fdc3.addContextListener operations.

The channel membership for an app can also be found through the top-level fdc3.getCurrentChannel operation and current context of a channel can be retrieved with the new Channel.getCurrentContext operation on the Channel class.

Context Filtering

The addContextListener and getCurrentContext operations now both support filtering for a specific type of context, e.g.:

const contactListener = fdc3.addContextListener('fdc3.contact', context => {
	// handle contacts
});

New Context Data Types

The first official FDC3 context data types have been standardised, in collaboration with the FINOS
Financial Objects Program.
These types were previously given as examples, and have been adopted by the community.

They are:

• fdc3.contact
• fdc3.contactList
• fdc3.country
• fdc3.instrument
• fdc3.instrumentList
• fdc3.organization
• fdc3.portfolio
• fdc3.position

Published Schemas

Officially versioned public schemas for the FDC3 standards are now published on the FDC3 website, e.g.:

• https://fdc3.finos.org/schemas/1.1/context.schema.json and
• https://fdc3.finos.org/schemas/1.1/app-directory.yaml.

This aids validation and code generation for consuming applications.

Reference Documentation

There is now a reference section for both Intents and Context Data, to go along with the API Reference.

🚀 New Features

• JSON Schema definitions for agreed context types (#119)
• API entry point for web - window.fdc3 (#139)
• Use Case 17 (#153)
• Channels API (#154)
• Type filtering support for getCurrentContext (#161)
• Publish versioned JSON schemas to FDC3 website (#170)
• Intent Reference and Context Data Reference documentation (#172)

💅 Enhancements

• Remove FactSet-specific examples from docs (#88)
• Apply FINOS branding, styles and logos to the website (#96)
• Expand AppMetadata interface with more application properties (#157)
• Restructure some docs (#190)

🐛 Bug Fixes

• Several typos and broken links in docs
• Various security vulnerabilities

See CHANGELOG.md for more details.

FDC3 Standard 1.0

First official release of FDC3 at https://fdc3.finos.org, consisting of:

• API Specification 1.0
• Intents Specification 1.0
• Context Data Specification 1.0
• App Directory Specification 1.0
• Use Cases 1.0

Release highlights

Founded on real-world business use cases

The FDC3 Use Case Working Group, bringing together domain experts from across the financial industry, has defined 15 real-world business use cases to help inform and drive the formation of the FDC3 standard.

Standardised API operations

The API specification 1.0 defines a set of standard API operations for all participating applications, encapsulated by the DesktopAgent interface:

interface DesktopAgent {
  open(name: string, context?: Context): Promise<void>;
  broadcast(context: Context): void;
  findIntent(intent: string, context?: Context): Promise<AppIntent>;
  findIntentsByContext(context: Context): Promise<Array<AppIntent>>;
  raiseIntent(intent: string, context: Context, target?: string): Promise<IntentResolution>;
  addContextListener(handler: ContextHandler): Listener;
  addIntentListener(intent: string, handler: ContextHandler): Listener;
}

Here, Context signifies data matching the [Context Data Specification], and intent signifies the name of a standardised or custom intent.

Standardised Intents

The Intents Specification 1.0 defines intents as predefined nouns or verbs that can be used to stitch together cross-application workflows on the financial desktop.

It also standardises an initial set of global well-known intents:

• StartCall
• StartChat
• ViewChart
• ViewContact
• ViewQuote
• ViewNews
• ViewInstrument
• ViewAnalysis

Standardised Context Data envelope

The Context Data Specification 1.0 defines that any data exchanged as part of interoperability workflows are only required to have a unique type property, used for identification and routing. Any names, identifiers or extra properties are optional.

This is represented by the Context interface as follows:

interface Context {
    type: string;
    name?: string;
    id?: {
        [x:string]: string;
    },
    [x: string]: any;
}

Standardised App Directory schema (OpenAPI 3.0)

The App Directory Specification 1.0 standardises a REST-based OpenAPI 3.0 schema for defining and referencing applications.

This includes the ability to create, address by id and list all applications defined according to the following representation:

{
  "appId": "string",
  "name": "string",
  "manifest": "string",
  "manifestType": "string",
  "version": "string",
  "title": "string",
  "tooltip": "string",
  "description": "string",
  "images": [
    {
      "url": "string"
    }
  ],
  "contactEmail": "string",
  "supportEmail": "string",
  "publisher": "string",
  "icons": [
    {
      "icon": "string"
    }
  ],
  "customConfig": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "intents": [
    {
      "name": "string",
      "displayName": "string",
      "contexts": [
        "string"
      ],
      "customConfig": {}
    }
  ]
}

The intents section links the API, Intents and Context Data specifications together, by defining a way for an application to declare the intents and context data types it supports, which is key to interoperability workflows in FDC3 1.0.

🚀 New Features

• Documentation website (generated with Docusaurus) and content from old separate FDC3 repos (#5)
• FDC3 feature icons on website landing page (#57)
• Participant showcase on website landing page (#67)

💅 Enhancements

• General cleanup of spelling, grammar and punctuation (#34)
• Use cases callout on website landing page (#54)
• Proofreading of docs (#62)

🐛 Bug Fixes

• Remove unnecessary dates from use case file names (#41)
• Header colouring on responsive website (#56)
• Workflow numbers in Use Case 1 (#60)
• Examples in Intent Overview (#65)
• Errors in DesktopAgent API Reference (#66)

See CHANGELOG.md for more details.