From 0ea9ab01c8a836ee841446377d0d38ad0b76f146 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 22 Sep 2021 12:26:19 +0100 Subject: [PATCH 1/4] Improve the raiseIntent documentation - add missing information and examples to the docs entry for raiseIntent and TS docs for same - add missing information and examples to the docs entry for raiseIntentForCOntext and TS docs for same - move resolvers section in spec to co-locate with raiseIntent - remove comments about versioning intents from spec as no functionality for doing so is defined --- docs/api/ref/DesktopAgent.md | 28 +++++++++++++++++----------- docs/api/spec.md | 19 +++++++++++++------ src/api/DesktopAgent.ts | 36 ++++++++++++++++++++++++++++++------ 3 files changed, 60 insertions(+), 23 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index c4a8eb0b6..f1a931eff 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -376,21 +376,23 @@ await fdc3.open('myApp', context); ```ts raiseIntent(intent: string, context: Context, app?: TargetApp): Promise; ``` -Raises a specific intent against a target app. +Raises a specific intent for resolution against apps registered with the desktop agent. -The desktop agent will resolve the correct app to target based on the provided intent name and context data. +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. A list of valid target applications can be retrieved via [`findIntent`](DesktopAgent#findintent). -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. +Returns an `IntentResolution` object with details of the app that was selected to respond 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 +// raise an intent for resolution by the desktop agent +// a resolver UI will be displayed if more than one application can resolve the intent +await fdc3.raiseIntent("StartChat", context); + +// or 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 @@ -411,12 +413,12 @@ await fdc3.raiseIntent("StartChat", context, appIntent.apps[0]); raiseIntentForContext(context: Context, app?: TargetApp): Promise; ``` -Finds and raises an intent against a target app based purely on context data. +Finds and raises an intent against apps registered with the desktop agent based purely on the type of the context data. -The desktop agent will resolve the correct app to target based on the provided context. +The desktop agent will first resolve to a specific intent based on the provided context, displaying a resolver UI if more than one intent is available for specified context. It will then resolve to a specific app to handle the selected intent and specified context. +Alternatively, the specific app to target can also be provided, in which case the resolver should only offer intents supported by the specified application. -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. +Using `raiseIntentForContext` 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 both the intent and target app. Returns an `IntentResolution` object with a handle to the app that responded to the selected intent. @@ -425,7 +427,11 @@ If a target app for the intent cannot be found with the criteria provided, an `E #### Example ```js +// Display a resolver UI for the user to select an Intent and application to resolve it const intentResolution = await fdc3.raiseIntentForContext(context); + +// Resolve against all intents registered by a specific target app for the specified context +await fdc3.raiseIntentForContext(context, targetAppMetadata); ``` #### See also diff --git a/docs/api/spec.md b/docs/api/spec.md index 248054fa7..3a9e45d88 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -163,7 +163,19 @@ catch (er){ } ``` -##### Upgrading to a Remote API Connection +#### 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) and then invoke the Intent on a specific target application, e.g.: + +```js +//Find apps to resolve an intent to start a chat with a given contact +const appIntent = await fdc3.findIntent("StartChat", context); +//use the returned AppIntent object to target one of the returned chat apps by name +await fdc3.raiseIntent("StartChat", context, appIntent.apps[0].name); +//or by using the full AppMetadata object +await fdc3.raiseIntent("StartChat", context, appIntent.apps[0]); +``` + +#### 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 @@ -182,8 +194,6 @@ Intents represent a contract with expected behavior if an app asserts that it su 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. @@ -200,9 +210,6 @@ if (fdc3.getInfo && versionIsAtLeast(fdc3.getInfo(), '1.2')) { } ``` -## 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. diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index 5decc8c56..9270caf0e 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -114,22 +114,46 @@ export interface DesktopAgent { broadcast(context: Context): void; /** - * Raises an intent to the desktop agent to resolve. + * Raises a specific intent for resolution against apps registered with the desktop agent. + * + * 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. A list of valid target applications can be retrieved via `findIntent`. + * + * Returns an `IntentResolution` object with details of the app that was selected to respond 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` enumeration is returned. + * * ```javascript - * //Find apps to resolve an intent to start a chat with a given contact + * // raise an intent for resolution by the desktop agent + * // a resolver UI will be displayed if more than one application can resolve the intent + * await fdc3.raiseIntent("StartChat", context); + * // or find apps to resolve an intent to start a chat with a given contact * const appIntent = await fdc3.findIntent("StartChat", context); - * //use the returned AppIntent object to target one of the returned chat apps with the context + * // use the returned AppIntent object to target one of the returned chat apps by name * await fdc3.raiseIntent("StartChat", context, appIntent.apps[0].name); - * //or use one of the AppMetadata objects returned in the AppIntent object's 'apps' array - * await fdc3.raiseIntent("StartChat", context, appMetadata); + * // or use one of the AppMetadata objects returned in the AppIntent object's 'apps' array + * await fdc3.raiseIntent("StartChat", context, appIntent.apps[0]); * ``` */ raiseIntent(intent: string, context: Context, app?: TargetApp): Promise; /** - * Raises a context to the desktop agent to resolve with one of the possible Intents for that context. + * Finds and raises an intent against apps registered with the desktop agent based purely on the type of the context data. + * + * The desktop agent will first resolve to a specific intent based on the provided context, displaying a resolver UI if more than one intent is available for specified context. It will then resolve to a specific app to handle the selected intent and specified context. + * Alternatively, the specific app to target can also be provided, in which case the resolver should only offer intents supported by the specified application. + * + * Using `raiseIntentForContext` 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 both 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` enumeration is returned. + * * ```javascript + * // Resolve against all intents registered for the specified context * await fdc3.raiseIntentForContext(context); + * // Resolve against all intents registered by a specific target app for the specified context + * await fdc3.raiseIntentForContext(context, targetAppMetadata); * ``` */ raiseIntentForContext(context: Context, app?: TargetApp): Promise; From 787ba983dbbaaf74246ba45870ba5325fe16448b Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 23 Sep 2021 11:33:57 +0100 Subject: [PATCH 2/4] Apply suggestions from code review a resolver UI *should* be shown if multiple apps match the intent and context --- docs/api/ref/DesktopAgent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index f1a931eff..5c7466fd3 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -378,7 +378,7 @@ raiseIntent(intent: string, context: Context, app?: TargetApp): Promise Date: Fri, 8 Oct 2021 11:29:02 +0100 Subject: [PATCH 3/4] Adjusting wording to acknowledge methods of resolving intents other than a resolver UI --- docs/api/ref/DesktopAgent.md | 9 +++++---- docs/api/spec.md | 2 +- src/api/DesktopAgent.ts | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 5c7466fd3..2538612f3 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -378,7 +378,7 @@ raiseIntent(intent: string, context: Context, app?: TargetApp): Promise Date: Fri, 8 Oct 2021 12:24:14 +0100 Subject: [PATCH 4/4] prettier --- src/api/DesktopAgent.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index dfa324529..6b449a6f6 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -148,7 +148,7 @@ export interface DesktopAgent { /** * Finds and raises an intent against apps registered with the desktop agent based purely on the type of the context data. * - * The desktop agent SHOULD first resolve to a specific intent based on the provided context if more than one intent is available for the specified context. This MAY be achieved by displaying a resolver UI. It SHOULD then resolve to a specific app to handle the selected intent and specified context. + * The desktop agent SHOULD first resolve to a specific intent based on the provided context if more than one intent is available for the specified context. This MAY be achieved by displaying a resolver UI. It SHOULD then resolve to a specific app to handle the selected intent and specified context. * Alternatively, the specific app to target can also be provided, in which case the resolver should only offer intents supported by the specified application. * * Using `raiseIntentForContext` 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 both the intent and target app.