Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

AppD consolidated update PR #668

Merged
merged 62 commits into from
May 27, 2022
Merged
Changes from 21 commits
Commits
Show all changes
62 commits
Select commit Hold shift + click to select a range
a282c2a
Defining a term for a single appD record
kriswest Apr 4, 2022
baa33e1
changelog
kriswest Apr 4, 2022
7445769
Move latest work on appD to /v2/ urls and restore /v1/ urls to 1.2 st…
kriswest Apr 19, 2022
bcd732d
Adds appD /v2/ API paths and fixes some html issues in the appD spec
kriswest Apr 19, 2022
cb9aa60
remove appD v1 search API example
kriswest Apr 20, 2022
fc81042
Merge pull request #666 from finos/553-appd-backwards-compatibility
kriswest Apr 20, 2022
19df580
adding moreInfo field to application record and applying formats to f…
kriswest Apr 20, 2022
3417d3a
changelog
kriswest Apr 20, 2022
0fc35a8
changelog
kriswest Apr 20, 2022
b8b62c2
Merge branch 'Appd-consolidated-update-branch' into AppD-more-info
kriswest Apr 20, 2022
116903c
adding lang tag to specify primary language of application and appD r…
kriswest Apr 20, 2022
fb201ed
adding localizedVersions field to appD application record schema to s…
kriswest Apr 21, 2022
a67dfed
changelog
kriswest Apr 21, 2022
a4589be
Introducing launch details for native application types and adjusting…
kriswest Apr 21, 2022
44bcf2f
making details field required, fixing description of citrix alias
kriswest Apr 21, 2022
2dac483
Improving documentation of application types
kriswest Apr 21, 2022
7fb7f30
Apply suggestions from code review
kriswest Apr 22, 2022
3976d29
Merge pull request #670 from finos/AppD-lang-and-translations
kriswest Apr 22, 2022
3dad413
Merge branch 'Appd-consolidated-update-branch' into AppD-more-info
kriswest Apr 22, 2022
a30c023
Merge pull request #669 from finos/AppD-more-info
kriswest Apr 22, 2022
26ff4ed
Merge branch 'Appd-consolidated-update-branch' into 560-appD-record-term
kriswest Apr 22, 2022
784f9b5
Merge pull request #658 from ChartIQ/560-appD-record-term
kriswest Apr 22, 2022
f92df72
adding categories field to appD and suggested list of categoreis
kriswest Apr 22, 2022
5b21431
add allocations, tca, research and trading system categories to sugge…
kriswest Apr 22, 2022
8362832
Merge pull request #570 from ChartIQ/555-558-improve-AppD-overview
kriswest Apr 22, 2022
fe849b7
Merge branch 'Appd-consolidated-update-branch' into App-categories
kriswest Apr 22, 2022
349ae03
Merge branch 'Appd-consolidated-update-branch' into AppD-vendor-agnos…
kriswest Apr 22, 2022
6cc60fd
add statement on alignment with other standards, changes appd images …
kriswest Apr 22, 2022
29e3fe5
changelog
kriswest Apr 22, 2022
d5ef18c
changelog
kriswest Apr 22, 2022
f9aec0c
changelog
kriswest Apr 22, 2022
4644aae
improve category list rendering
kriswest Apr 25, 2022
52e0741
improve rendering of type list
kriswest Apr 25, 2022
de1dde9
add app type and clarify that web type MUST be supported, other type…
kriswest Apr 25, 2022
8ace2ed
Update docs/app-directory/overview.md
kriswest May 3, 2022
91ca024
adding 'other' category
kriswest May 5, 2022
8753a65
Merge pull request #673 from finos/App-categories
kriswest May 5, 2022
7a85f5a
Merge branch 'Appd-consolidated-update-branch' into Appd-better-align…
kriswest May 5, 2022
b385d8c
Merge pull request #675 from finos/Appd-better-align-with-web-applica…
kriswest May 5, 2022
70eded6
Merge branch 'Appd-consolidated-update-branch' into AppD-vendor-agnos…
kriswest May 5, 2022
e850c35
add an endpoint for retrieving all apps from an appD (a primary use c…
kriswest May 5, 2022
9400bce
build
kriswest May 5, 2022
a9e10e3
Merge pull request #694 from finos/565-list-all-apps-in-appd
kriswest May 5, 2022
6386ec3
removing appD create application endpoint
kriswest May 6, 2022
ef3f6ea
changelog
kriswest May 6, 2022
84fc359
removing appD search application endpoint
kriswest May 6, 2022
a53ae89
changelog
kriswest May 6, 2022
673151a
Add note that implementations MAY extend beyond the standardized AppD…
kriswest May 16, 2022
54f1853
Merge pull request #695 from finos/566-remove-appd-create-fn
kriswest May 16, 2022
1339c60
Merge pull request #720 from finos/566-remove-appd-create-fn
kriswest May 16, 2022
4fb38f8
Merge branch 'Appd-consolidated-update-branch' into 370-remove-appd-s…
kriswest May 16, 2022
70d33c2
Merge branch 'Appd-consolidated-update-branch' into 370-remove-appd-s…
kriswest May 16, 2022
b668e06
Merge branch 'Appd-consolidated-update-branch' into AppD-vendor-agnos…
kriswest May 16, 2022
704603b
Merge pull request #696 from finos/370-remove-appd-search-endpoint
kriswest May 16, 2022
a89f21f
Merge branch 'Appd-consolidated-update-branch' into AppD-vendor-agnos…
kriswest May 16, 2022
310b45f
Merge pull request #671 from finos/AppD-vendor-agnostic-native-apps
kriswest May 16, 2022
9332132
Merge branch 'master' into Appd-consolidated-update-branch
kriswest May 16, 2022
0c82f7f
Merge branch 'master' into Appd-consolidated-update-branch
kriswest May 18, 2022
b63f0ba
Merge branch 'master' into Appd-consolidated-update-branch
kriswest May 20, 2022
ee2741a
correct type on FDC3Workbech appD examples
kriswest May 20, 2022
67fe65a
Apply suggestions from code review
kriswest May 25, 2022
f946a5a
Merge branch 'master' into Appd-consolidated-update-branch
kriswest May 27, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -20,10 +20,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
* `IntentResolution` now requires the name of the intent raised to included, allowing it to be used to determine the intent raised via `fdc3.raiseIntentForContext()`. ([#507](https://github.com/finos/FDC3/pull/507))
* A Trademarks page was added to acknowledge trademarks used within the Standard not owned by FINOS or the Linux Foundation ([#534](https://github.com/finos/FDC3/pull/534))
* Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
* Add `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
* Added `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
kriswest marked this conversation as resolved.
Show resolved Hide resolved
* Added a definition for "app directory record" to the FDC3 glossary to be used to refer to a single appD record ([#658](https://github.com/finos/FDC3/pull/658))
* 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 ([#666](https://github.com/finos/FDC3/pull/666))
* Added `lang` field to appD application records to specify the primary language of an app and its appD record. ([#670](https://github.com/finos/FDC3/pull/670))
* Added `localizedVersions` field to appD application records to support localized versions of descriptive fields in the app records andalternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670))
* Added a `moreInfo` URL field to AppD application records to enable linking to a web page with more information on an app ([#669](https://github.com/finos/FDC3/pull/669))
* Added `lang` field to AppD application records to specify the primary language of an app and its appD record. ([#670](https://github.com/finos/FDC3/pull/670))
* Added `localizedVersions` field to AppD application records to support localized versions of descriptive fields in the app records and alternative launch details for localized versions of the applications themselves. ([#670](https://github.com/finos/FDC3/pull/670))

### Changed
* Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))
74 changes: 66 additions & 8 deletions docs/app-directory/overview.md
Original file line number Diff line number Diff line change
@@ -7,18 +7,76 @@ hide_title: true

# App Directory Overview

The FDC3 App Directory provides trusted identity for financial desktop apps. This identity can be used to prevent spoofing and man-in-the-middle attacks when apps communicate with one another and exchange data. The App Directory also enables service discovery. Apps are registered with a declaration of the intents and context data that can be used when interoperating.
An application directory (appD) is a structured repository of information about apps that can be used in an FDC3-enabled desktop. In other words, it’s a convenient way of storing and managing metadata about apps in your ecosystem.

## Core features
The application metadata stored in appD records may include: the app name, type, details about how to run the application, its icons, publisher, support contact details and so on. It may also include links to or embed manifest formats defined elsewhere, such as proprietary manifests for launching the app in a container product or a Web Application Manifest (as [defined by the W3C](https://www.w3.org/TR/appmanifest/)).

All this information is readily available in one place and can be used both to populate a launcher or app catalog UI for your users, and by the desktop agent managing the apps on your desktop. In fact, if your desktop platform supports the FDC3 standard, appD is the primary way that the FDC3 desktop agent implementation should receive the details about apps available to run on your desktop. Conversely, if an app is not listed in appD, the desktop agent can’t ensure its participation in context sharing or use it to resolve intents.

## Advantages

Using appD offers many advantages both for the financial institutions running an FDC3-enabled desktop container and for vendors that provide FDC3-compliant apps:


### For the user


#### Easier to find app info

Your appD is the one place to collect all the information about apps. The more apps you have, the more you’ll appreciate the convenience of not having to chase down details about each. This is particularly important for large institutions with multiple desks.


#### Human readable

AppD has two types of users. One is the desktop agent, but the other is humans administrating and using the smart desktop at your organization. Hence, an appD contains information about apps in both machine- and human-readable forms. For example, it includes both unique identifiers for apps that are used to refer to them in code and human-friendly app names, icons, descriptions and tooltips necessary to populate a launcher menu or app catalog user interface for your users.


#### Apps are discoverable

For large institutions, it can be difficult to keep track of all the apps (developed both in-house and by vendors), since a typical desktop could have many. Users can search appD to discover the apps they need. An app might already reside on their system or be available to them over the internet, but if they don’t have a way to search the apps available to them, they won’t be able to find it. An appD provides a way for users to discover the apps they need.

An appD makes it possible to discover info about apps that reside on various domains, not just the one domain the appD itself is hosted on. In addition, you can find details about how to launch the apps in multiple, diverse environments. This is a different use-case to, for example, the [W3C's Web App Manifest](https://www.w3.org/TR/appmanifest/), which is hosted on the same domain as the app, is limited to web apps, and is generally used to 'install' an app that the user has already accessed.


#### Updating apps

Typically, software evolves over time. The app versions you are running today will not be the same ones you need tomorrow. Therefore, you will need to upgrade apps periodically. Very few people look forward to upgrading, but appD and web deployment can make it easier for you. To roll out a new version of your app, either update the existing entry for it in appD or add a new entry for that version (allowing users to select the version they will use).


#### Agent-agnostic

As a part of the FDC3 standard, appD isn't tied to any specific vendor. This is important, as it allows you more flexibility in that you are not tied to any specific container or desktop agent implementation. If at any point you want to switch to a different desktop agent, the process won’t be prohibitively difficult. The existing appD will work without any additional effort from you, as long as your new desktop agent is also FDC3-compliant. This is in contrast with proprietary solutions, where you would have to produce a new configuration and integration for every application.

AppD reduces fragmentation in the market and allows end-users more flexibility in what applications can be included in their desktop.


#### Intent resolution

AppD provides information to the Desktop Agent on which applications can handle particular [intents](../intents/overview) and the context types they support as input to them. This allows the Desktop Agent to implement an [intent resolver](../api/spec#resolvers) that can launch applications and pass the intent and context to them to operate on, supporting workflows between applications that didn't require prior bilateral agreements between the application providers.


### For an Application Provider

Until now, we've looked at appD from the perspective of a desktop owner and user. But appD also offers advantages to vendors who develop apps for the financial services desktop.


#### Apps work well together out of the box

When your customers add your FDC3-compliant app to their desktop via an appD record accurately describing it, you can be sure that your app will interoperate with other apps that follow the FDC3 standard. You don’t have to do anything special, or arrange a bilateral agreement with anyone else. The benefit of the open standard is that any app that follows it will work well with any other compliant app.


#### Easy updates

As a vendor, you prefer for all your customers to run your latest software. However, many customers will postpone upgrades, sometimes for a long time, because upgrading can be a pain. An advantage of a vendor-hosted appD is that the configuration of an app can be updated at any time and, if your customers need to choose when to upgrade, multiple versions of it can be made available, each with their own configuration. By making it easier for customers to update, you can drive better adoption.


### For the industry

By hosting our own appD we can easily combine applications from various providers into one cohesive directory. Alternatively, we can connect to directories from multiple providers (in standardized format) and provide a single view over them. This reduces fragmentation in the market, allows end-users more flexibility in what apps to include in their smart desktop, and obviates the need for vendors to provide application details in diverse formats or for their customers to work out these details for themselves.

- Provide verification of identity for an application running on a desktop - whether it is Native, Web, or Hybrid.
- Resolve human readable names for applications to the location of and instructions for launching
- Serve as a repository for application metadata supporting discoverability by intent, context, and other workflow driven facets.

## Sections to review

- [Application Directory Discovery](discovery.md) describes how to resolve the location of the Application Directory using an application identifier.
- [Application Directory Usage](usage.md) provides a simple view on how application directories can be used. This also includes links to a reference implementation.
- [Application Directory specification](spec.md) is the interface definition required to support a compatible application directory.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC 2119](https://tools.ietf.org/id/draft-faltstrom-uri-11.html#RFC2119) [RFC2119].
- [Application Directory specification](spec.md) is the interface definition required to support a compatible application directory.
4 changes: 3 additions & 1 deletion docs/fdc3-glossary.md
Original file line number Diff line number Diff line change
@@ -6,9 +6,11 @@ sidebar_label: Glossary
For the purposes of this Standard, the following definitions apply. Other terms are defined when first used, at which place they appear in bold and italic type. Terms explicitly defined in this Standard are not to be presumed to refer implicitly to similar terms defined elsewhere. Terms not defined are assumed to be well-known in the financial services or software industries.


- **app directory**: A repository of application metadata supporting discovery, for example via name or intent, and retrieval of metadata necessary to launch an application.
- **app**: Shorthand for application.
- **app directory**: A repository of application metadata supporting discovery, for example via name or intent, and retrieval of metadata necessary to launch an application.
- **app directory record**: Metadata relating to a single application, encoded in JSON.
- **appD**: Shorthand for app directory.
- **appD record**: Shorthand for app directory record.
- **application**: Any endpoint on the desktop that is registered with/known by a Desktop Agent, launchable by a Desktop Agent, addressable by a Desktop Agent or otherwise able to interact with the Desktop Agent.
- **application, hybrid**: Any web application running within the context of a standalone native application that embeds a web view, typically based on Chromium.
- **application, native**: A non-web-based application; i.e., one that runs outside the context of web browser, web view or web container. A user-written program—typically implemented in a language such as C++, C#, Java, or Python, rather than JavaScript or TypeScript.
18 changes: 15 additions & 3 deletions src/app-directory/specification/appd.yaml
Original file line number Diff line number Diff line change
@@ -448,7 +448,7 @@ components:
lang:
type: string
pattern: '^[a-z]{2}(-[a-zA-Z0-9]{2,8}){0,1}$'
description: a language tag that specifies the primary language of both application and it's AppD entry, as defined by IETF RFC 5646.
description: a language tag that specifies the primary language of both application and its AppD entry, as defined by IETF RFC 5646.
description:
type: string
description: >-
@@ -463,10 +463,16 @@ components:
$ref: '#/components/schemas/AppImage'
contactEmail:
type: string
format: email
description: Optional e-mail to receive queries about the application
supportEmail:
type: string
format: email
description: Optional e-mail to receive support requests for the application
moreInfo:
type: string
format: uri
description: Optional URL that provides more infomation about the application
publisher:
type: string
description: >-
@@ -581,9 +587,11 @@ components:
$ref: '#/components/schemas/AppImage'
contactEmail:
type: string
format: email
description: Optional e-mail to receive queries about the application
supportEmail:
type: string
format: email
description: Optional e-mail to receive support requests for the application
publisher:
type: string
@@ -649,6 +657,7 @@ components:
properties:
src:
type: string
format: uri
description: Icon URL
size:
type: string
@@ -661,12 +670,14 @@ components:
properties:
icon:
type: string
format: uri
description: Icon URL
AppImage:
description: App Image holder
properties:
url:
type: string
format: uri
description: App Image URL
Intent:
description: >-
@@ -788,8 +799,8 @@ components:
properties:
url:
type: string
formt: uri
description: Application start URL.
format: uri
description: Application URL.
additionalProperties: false
HostManifests:
type: object
@@ -834,6 +845,7 @@ components:
tooltip: FDC3 logo
contactEmail: fdc3@finos.org
supportEmail: fdc3-maintainers@finos.org
moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists
publisher: FDC3
intents: [{
name: ViewChart,
18 changes: 15 additions & 3 deletions website/static/schemas/next/app-directory.yaml
Original file line number Diff line number Diff line change
@@ -448,7 +448,7 @@ components:
lang:
type: string
pattern: '^[a-z]{2}(-[a-zA-Z0-9]{2,8}){0,1}$'
description: a language tag that specifies the primary language of both application and it's AppD entry, as defined by IETF RFC 5646.
description: a language tag that specifies the primary language of both application and its AppD entry, as defined by IETF RFC 5646.
description:
type: string
description: >-
@@ -463,10 +463,16 @@ components:
$ref: '#/components/schemas/AppImage'
contactEmail:
type: string
format: email
description: Optional e-mail to receive queries about the application
supportEmail:
type: string
format: email
description: Optional e-mail to receive support requests for the application
moreInfo:
type: string
format: uri
description: Optional URL that provides more infomation about the application
publisher:
type: string
description: >-
@@ -581,9 +587,11 @@ components:
$ref: '#/components/schemas/AppImage'
contactEmail:
type: string
format: email
description: Optional e-mail to receive queries about the application
supportEmail:
type: string
format: email
description: Optional e-mail to receive support requests for the application
publisher:
type: string
@@ -649,6 +657,7 @@ components:
properties:
src:
type: string
format: uri
description: Icon URL
size:
type: string
@@ -661,12 +670,14 @@ components:
properties:
icon:
type: string
format: uri
description: Icon URL
AppImage:
description: App Image holder
properties:
url:
type: string
format: uri
description: App Image URL
Intent:
description: >-
@@ -788,8 +799,8 @@ components:
properties:
url:
type: string
formt: uri
description: Application start URL.
format: uri
description: Application URL.
additionalProperties: false
HostManifests:
type: object
@@ -834,6 +845,7 @@ components:
tooltip: FDC3 logo
contactEmail: fdc3@finos.org
supportEmail: fdc3-maintainers@finos.org
moreInfo: https://fdc3.finos.org #update to point to implementations page when it exists
publisher: FDC3
intents: [{
name: ViewChart,