Add additional properties to AppMetadata type

[sean-ciq]

Enhancement Request

Use Case:

An application developer, in a situation where more than one App Directory exists and the names of applications are not unique, needs more information about applications returned from findIntent() or findIntentsByContext() to successfully raise an intent to a specified target. We recommend bringing in fields from the AppD application definition that differentiate different apps with the same name:

• appId: the fully qualified appID differentiates based on version and the appDirectory and hence should be globally unique
• version: the value that differentiates different copies of an app within a single app directory

Workflow Description

1. Application calls findIntent() or findIntentsByContext()
2. Application receives a response containing a list of AppIntent objects, themselves containing an AppMetadata object for each application that details are being returned on.
3. AppMetadata objects contain values that can uniquely identify each app (given that multiple AppD's may be in use, each of which could contain multi[le versions of an application with a single name value).

Workflow Examples

1. User clicks on a contact
2. UI displays the available applications.
3. There are multiple applications available with the name "Messenger"
4. The user selects any "Messenger" from the UI
5. Instead of passing a name value, the application passes an AppMetadata object containing an appId value or name and version, uniquely identifying the app
6. Desired app version is launched.

Additional Information

Note the following definitions in the AppD specification for an application record:

name: 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.
version: 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)

Integrating additional properties defined in the App D specification provides an additional way for applications to determine and specify intent targets. The argument for returning the entire AppMetadata object from findIntents() & findIntentsByContext() and others is based upon deference to the application. If an application receives a list of available apps, there is currently no identifier other than the name property. This inability to properly identify other applications by one or more properties breaks down when:

• there are multiple app directories
• there are multiple versions of an app within the app directory

Proposed Additions

Current AppMetadata interface:

interface AppMetadata {
  name: string;
  title?: string;
  tooltip?: string;
  description?: string;
  icons?: Array<string>;
  images?: Array<string>;
}

New interface:

interface AppMetadata {
  name: string;
  appId?: string;
  version?: string;
  title?: string;
  tooltip?: string;
  description?: string;
  icons?: Array<string>;
  images?: Array<string>;
}

[rikoe]

@sean-ciq we discussed and voted on this this during the 1.1 time frame - we don't want the full app metadata exposed through the JS API, as a lot of it is hidden or unnecessary information for FDC3-enabled apps themselves. If the additional properties are needed by a framework implementation, they can be obtained by using the AppD REST API.

Could you elaborate on the use case for adding all of these properties to the JS API?

Also, it is worth pointing out that there is nothing in the spec preventing a framework from providing these values on the return object, we just didn't want to mandate it via the API spec.

[rikoe]

The other issue raised by this is that target in raiseIntent can now have multiple ambiguous meanings, which is not the intention of the original API as I understand it.

[kriswest]

@rikoe one of the issues we've run into is that the desktop agent can work with more than one AppD and an AppD can have more than one application with the same name value (but different version value). When this happens, target (which relates to name in the spec) is insufficient to specify the specific app you want as the target.

The AppD spec does deal with this however, via the AppId field, which is the only unique identifier for an app (see: https://fdc3.finos.org/docs/1.0/appd-discovery#application-identifier). By not supporting the appId field, the desktop agent is both unable to return AppMetadata objects which uniquely identify apps from the findIntent(sByContext) API calls or to specify targets in raiseIntent that uniquely identify the target - meaning you have to use a resolver UI (which was not the point of raiseIntent with a target).

Personally, I don't think that the proposed change to raiseintent means that it can now have multiple ambiguous meanings. It's still trying to specify a target application whether you specify a string or AppMetadata Object - it's just been allowed to specify that target in more than one format (in part for backwards comparability with 1.1). Another approace would have been to support passing in an appId, but that would require a new parameter for differentiation. It seems easier and more flexible to accept AppMetadata as you can detect it by its structure (if (typeof target=="object" && target.appId), you can allow the desktop agent some latitude in how it uses it (e.g. use appId if present, or name + version or just name), and any customisations in a Desktop Agent implementations's own AppMetadata objects (as returned by findIntents for example) can pass through (rather than the developer having to reference one of the fields from it as at present).

As for the other fields - supporting them as optional parameters allows resolver UIs etc. to make use of them. It didn't seem excessive to us to expose that (nor does it make it a requirement as they are optional in the proposal). However, we appreciate that this issue was already reviewed and voted on and will happily respect that - but we feel that at least the appId and perhaps version fields are essential for the above use case when Desktop Agent and AppD are used together.

[nkolba]

@sean-ciq @kriswest @rikoe

In AppD, there is the concept of name spacing the app name / id with the app directory identifier to produce a fully qualified name for the app. E.g. [email protected]. This is definitely a bit vague and in need of some clarification & updating now that we have stronger use cases in this area. In general, app.name being a relative name and app.appId being fully qualified seems to make sense and be in line with the spec. This means that a Desktop Agent should return and handle fully qualified names when it is handling multiple app directories.

WRT app versions. Is there a reason that these couldn't be differentiated by name?

[kriswest]

If we look at the (AppD) definitions of appId, name and version in the current spec:

• appId (required): The unique application identifier located within a specific application directory instance.
• name (required): 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.
• version (optional): 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)

We can see that appId should be unique across the specific appD instance (and globally unique once fully qualified with the appD server name), while name is unique apart from different versions of the same app (meaning that the appId should probably contain something derived from, or at least mapping to, the version) details. However, it differentiates version, it will need the appIds it uses to be more than just the name + a qualifying domain for them to be unique among different versions. Hence, we can't simply derive appId from name + appD address. It follows that we need to be able to process the appId through the desktop agent APIs in order to select a target application (resulting in the above proposal to extend AppMetadata and to accept it to define an application target).

[sean-ciq]

Hence, we can't simply derive appId from name + appD address.

I concur with Kris on this. There would need to be the additional properties of version or even perhaps manifest might be a solution here.

[nicholasdgoodman]

👍 on this this thread.

i think the very strong example here is on fdc3.open(name), since fdc3.raiseIntent(... , target) has the "easy out" of stating that implementers can simply use an app picker UI to resolve any ambiguities.

What the spec never explicitly states (and probably should) that the name argument on open and the name field in the AppDirectory entry are one-and-the-same.

But as others have mentioned, since the latter may be ambiguous or duplicated, then opening an application by name is potentially problematic. An overload of .open(...) which takes a metadata object with enough information to uniquely identify an entry seems required here.

[sean-ciq]

This issue has been updated per the WG meeting on 9/24/2020