diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 37ab9de8d..f7b52efdd 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -382,21 +382,26 @@ 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 type. If you wish to raise an Intent without a context, use the `fdc3.nothing` context type. This type exists so that apps can explicitly declare support for raising an intent without context. +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, a method for resolving the intent to a target app, such as presenting the user with a resolver UI allowing them to pick an app, SHOULD be provided. +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). +If you wish to raise an Intent without a context, use the `fdc3.nothing` context type. This type exists so that apps can explicitly declare support for raising an intent without context. -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 may be displayed, or another method of resolving the intent to a + target applied, 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 @@ -420,13 +425,12 @@ await fdc3.raiseIntent("StartChat", {type: "fdc3.nothing"}); 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 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 any method of resolution SHOULD only consider 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. @@ -435,7 +439,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 bae4f2997..5c0a9b309 100644 --- a/docs/api/spec.md +++ b/docs/api/spec.md @@ -165,7 +165,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 (for example, by displaying a resolver UI allowing the user to pick the desired App for the intent) or by the app calling App handling the resolution itself (by using the `findIntents` API) and then invoking 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 @@ -184,8 +196,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. @@ -202,9 +212,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 both an Intent and App for a context) 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 8140e6ec6..6b449a6f6 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -120,14 +120,25 @@ 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]); * //Raise an intent without a context by using the null context type * await fdc3.raiseIntent("StartChat", {type: "fdc3.nothing"}); * ``` @@ -135,9 +146,22 @@ export interface DesktopAgent { 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 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. + * + * 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;