An application directory (appD)
An enterprise can have a huge number of applications, and your smart desktop needs to keep track of them. Specifically, it needs to know the name, the type of the app, how to launch it, and lots of other info. This info is useful both for the smart desktop users and for the container and desktop agent.
The FDC3 Standard 2.0 defines a format for organizing all this data and an API for retrieving it. The standard is known as the Application Directory, or appD. Finsemble uses the record format from this standard for its internal configuration of apps and can connect to external app directories to browse or import apps. You will almost certainly add appD records for both your own applications and those published by other firms to your Finsemble desktop.
You can add Application Directory records in the appD 2.0 format to the finsemble.apps array in Finsemble's configuration, either by using the SDD, or by adding them to the public/configs/application/apps.json file in your project, or dynamically via the Config Client API.
note
Previous versions of Finsemble used the appD 1.2 format, which we still support for backwards compatibility. 1.2 format records should be added to the finsemble.appd Object in Finsemble's configuration in the public/configs/application/appd.json file. They will be automatically upgraded to the 2.0 format and moved to the finsemble.apps array.
For more info about appD, see it's FDC3 documentation and its full specification in OpenAPI v3.0 format.
AppD format
{
/**
* A unique application identifier (key). This can be any string and doesn't
* necessarily need to describe the app. It should NOT include a @
* character because this string is used to fully qualify appIds by appending the
* @ and the host name of the app directory server, (making them similar to
* email addresses.
* @type String
*/
"appId": "X39A765",
/**
* The name of the application. A legacy property used to group different
* versions of the same app. There might be multiple instances with
* the same name. Don't confuse it with the display name of the
* app, which is specified in `title`.
* @type String
*/
"name": "MyApp",
/**
* The display name that represents the application in
* user interfaces such as a Launcher menu or the FDC3 Intent Resolver.
* @type String
*/
"title": "My app's display name",
/**
* The technology type that you use to launch and run the application.
* Each application type implies a particular set of launch details that
* you need to provide.
* Valid values include: "web", "native", "citrix", "onelineNative" and
* "other".
* @type String
*/
"type": "web",
/**
* The type-specific launch details of the application. These *could* be
* duplicated by or overridden by details provided in the hostManifests
* object. You must specify sub-properties of details for all app types
* apart from "other" (when you rely on the hostManifest instead).
* @type Object
*/
"details": {
/**
* Application launch URL. Required for the web and onelineNative types.
* @type String
*/
"url": "http://myapp.com/myapp.html",
/**
* The path on disk from which a native application is launched.
* Required for the native type.
* @type String
*/
"path": "C:\\path\\to\\my\\application.exe",
/**
* An alias applied to a particular application and used to launch it.
* Required for the Citrix app type, but you can also use it with native
* applications in Finsemble where you launch them from an App Asset.
* @type String
*/
"alias": "myAppsAlias",
/**
* Arguments that you should pass on the command line to launch a native
* app in the expected configuration.
* Used with the native, Citrix, and onlineNative app types.
*/
"arguments":
},
/**
* Version of the application.
* @type String
*/
"version": "1.0.0",
/**
* Icons that represent the application. This can be a single icon, or a set
* of icons of different sizes.
* @type Array<Icon>
*/
"icons": [
{
/** Url to retrieve the icon from
* @type String */
"src": "http://myapp.com/icons/myapp.png",
/** Optional dimensions in the form `<height>x<width>`
* @type String */
"size": "256x256",
/** Optional image mime type. May be inferred from the URL if not present
* @type String */
"type": "image/png"
}
],
/**
* Metadata that describes how the application uses FDC3 APIs.
* This metadata serves multiple purposes:
* - It supports intent resolution by a desktop agent, by declaring what
* intents an app listens for.
* - You can use it for example in an app catalog UI, to find apps that
* 'interoperate with' other apps.
* - It provides a standard location to document how the app interacts with
* user channels, app channels, and intents, for use by other app
* developers and desktop assemblers.
* @type Array<object>
*/
"interop": {
"intents": {
/** Details of the intents that the app can resolve. Used to support
* Intent resolution and the spawning of apps to resolve intents. */
"listensFor": {
/** Intent name */
"ViewChart": {
/** A filter stating that this app only handles intents for *these*
* context types.
* @type Array<String> */
"contexts": ["fdc3.instrument"],
/** Optional declaration of the result type returned by the intent
* handler. May be used to resolve fdc3.findIntent calls that
* request a specific return type.
* @type String */
"resultType": "fdc3.chart"
}
},
/** Details of the intents that the app raises. Used to help find apps
* that will interoperate with this app and to document API interactions
* for other app developers. */
"raises": {
/** Intent name mapped to an array of context type names that it can
* be raised with. Use the Intent name "any" to represent use of the
* `fdc3.raiseIntentForContext` function. */
"ViewNews": ["fdc3.instrument"],
}
},
/** Details of the app's use of context types on User channels. */
"userChannels": {
/** Array of context types that the app will broadcast onto User channels. */
"broadcasts": ["fdc3.instrument"],
/** Array of context types that the app will listen for or respond to
* on User channels. */
"listensFor": ["fdc3.instrument"]
},
/** Details of named channels used by the app, and the context types used
* in conjunction with each. */
"appChannels": [{
/** The name of the App channel */
"name": "MyAppsChannel",
/** Description of the purpose of the channel and the app's interaction
with it. */
"description": "Description of interactions that the app has with the channel",
/** Array of context types that the app will broadcast onto the channel. */
"broadcasts": ["fdc3.instrument"],
/** Array of context types that the app will listen for or respond to
* on the channel. */
"listensFor": ["fdc3.instrument"]
}]
},
/**
* A mapping from desktop agent name to a specific application manifest object
* or URI from which that manifest can be retrieved. Use the key "Finsemble"
* for the Finsemble-specific manifest.
*
* In the example we show only the most important fields. See
* https://documentation.finsemble.com/docs/reference/ConfigReference for all
* configuration possibilities)
*
* @type Object
*/
"hostManifests": {
"Finsemble": {
/** Default size and position settings for the app's window.*/
"window": {
"width": 800,
"height": 600,
"left": "center",
"right": "center"
},
/** Properties that control how other parts of the desktop should handle
* the application, such as whether to show it in a launcher menu. */
"foreign": {
"components": {
"App Launcher": {
"launchableByUser": true
}
}
},
/** Properties associated with how Finsemble manages this application.*/
"component": {
/**
* The url of a JavaScript preload to be loaded into the app.
*/
"preload": "http://myapp.com/preload.js"
},
/** Properties that affect how the application interacts with interop,
* such as those controlling selectConnect features.*/
"interop": {
"selectConnect": [{
"autoAssociate": {
"allChildren": true
}
}]
}
}
},
/* The following properties in this file are all optional, but you should
* provide them to enhance the user's experience when reviewing the app in a
* launcher, application catalog or app directory browser. */
/**
* Tooltip description for use in a launcher UI. Typically limited to
* a single line of copy.
* @type String
*/
"tooltip": "Short description of My App",
/**
* Full description of the application for use in a launcher UI or
* App Directory browser UI. Typically 1-2 paragraphs.
* @type String
*/
"description": "A full description of My App including all the details I would expect to share with users through an app directory or catalog interface.",
/**
* Language tag that specifies the primary language of both the app and its appD
* entry. Provides pronunciation hints to screen readers.
* @type String
*/
"lang": "en-US",
/**
* Array of string categories that describe the application. You can
* use it to organize an App Directory for browsing purposes.
* We recommend that AppD record authors use lower-case and, where possible,
* select categories from the list defined in the FDC3 Standards's documentation:
* @type Array<String>
*/
"categories": ["market data", "visualisation", "productivity"],
/**
* Who to contact for more information about the app.
* @type String
*/
"contactEmail": "info@myapp.com",
/**
* Who to contact for support on used the app.
* @type String
*/
"supportEmail": "support@myapp.com",
/**
* URL that provides more information about the application.
* @type String
*/
"moreInfo": "https://www.myapp.com",
/**
* The name of the firm that publishes the application.
* @type String
*/
"publisher": "My Company, inc.",
/**
* Optional screenshots to show the user when looking at a description
* of the app.
* @type Array<Screenshot>
*/
"screenshots": [
{
/** Url to retrieve the screenshot from
* @type String */
"src": "http://myapp.com/screenshots/myapp_example.png",
/** Optional dimensions in the form `<height>x<width>`
* @type String */
"size": "1024x768",
/** Optional image mime type. May be inferred from the URL if not present
* @type String */
"type": "image/png",
/**
* Optional caption for the image.
* @type String */
"label": "Description of whats show in the screenshot"
}
],
/**
* Finsemble-specific metadata that you can use to automatically update AppD records
* on startup.
* @type Object
*/
"metadata": {
/** If explicitly true and an appDUrl is set, Finsemble automatically updates the appD record during startup.
* @type Boolean */
"autoUpdate": true,
/** The appDUrl must be a valid URL to retrieve an updated copy of this
* appD record
* @type String */
"appDUrl": "https://host.domain.com/api/appd/v2/X39A765",
/** The ISO formatted date and time string at which the appD record was
* last retrieved from the appDUrl. Finsemble sets this automatically.
* @type String */
"retrievedAt": "2023-01-11T00:00:00.000Z"
}
}
See also
Add an app to your smart desktop
Augmenting FDC3: selectConnect
Integrating FDC3-compliant apps into a workflow using the FDC3 workbench