Intents
6.9.0The Intents API enables you to enhance workflow scenarios where at certain points in the workflow the user must use a specific app, or select an app from a list of available apps, in order to execute a business action. This is achieved by allowing apps to raise requests for other apps to handle predefined actions (Intents). When an Intent is raised, an app (or a running instance of it) that has already been registered as a handler for this Intent (dynamically or via configuration) may be chosen programmatically or by the end user to be started or activated in order to handle the raised Intent. For instance, you may have an app showing client portfolios with financial instruments. When the user clicks on an instrument, you may want to start an app which shows a chart for that instrument. In other cases, you may want to present the user with several options for executing an action or handling data from the current app. The Intents API makes all that possible by enabling apps to register, find and raise Intents.
The Intents API is accessible through the io.intents
object.
APIobject
Description
Intents API.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
resolver | Resolver | API for controlling the Intents Resolver UI app. |
Methods
allmethod
clearSavedHandlersmethod
Signature
() => Promise<void>
Description
Removes all saved Intent handlers for previously raised Intents.
filterHandlersmethod
Signature
(handlerFilter: HandlerFilter) => Promise<FilterHandlersResult>
Description
Filters Intent handlers by specified criteria. If there are more than one valid Intent handlers and the Intents Resolver UI is enabled, it will open and display the available handlers.
Parameters
Name | Type | Required | Description |
---|---|---|---|
handlerFilter | HandlerFilter | Filter for the list of Intent handlers to return. |
findmethod
Signature
(intentFilter?: string | IntentFilter) => Promise<Intent[]>
Description
Retrieves Intents by a specified filter. If no filter is supplied, all available Intents will be retrieved.
Parameters
Name | Type | Required | Description |
---|---|---|---|
intentFilter | string | IntentFilter | Filter for retrieving Intents. Can be the Intent name only, or an |
getIntentsmethod
Signature
(handler: IntentHandler) => Promise<GetIntentsResult>
Description
Retrieves all Intents associated with an Intent handler.
Parameters
Name | Type | Required | Description |
---|---|---|---|
handler | IntentHandler | Intent handler whose Intents to retrieve. |
onHandlerAddedmethod
Signature
(callback: (handler: IntentHandler) => void, intentName: string) => UnsubscribeFunction
Description
Notifies when a handler for an Intent is added. Returns an unsubscribe function.
Available since version io.Connect Desktop 9.6
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (handler: IntentHandler) => void | Callback function for handling the event. Receives an object describing the added Intent handler as an argument. |
|
intentName | string |
onHandlerRemovedmethod
Signature
(callback: (handler: IntentHandler) => void, intentName: string) => UnsubscribeFunction
Description
Notifies when a handler for an Intent is removed. Returns an unsubscribe function.
Available since version io.Connect Desktop 9.6
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (handler: IntentHandler) => void | Callback function for handling the event. Receives an object describing the removed Intent handler as an argument. |
|
intentName | string |
raisemethod
Signature
(request: string | IntentRequest) => Promise<IntentResult>
Description
Raises an intent.
Parameters
Name | Type | Required | Description |
---|---|---|---|
request | string | IntentRequest | The name of the Intent to raise, or an |
registermethod
Signature
(intent: string | AddIntentListenerRequest, handler: (context: IntentContext, caller?: Instance) => any) => Promise<{ unsubscribe: UnsubscribeFunction; }>
Description
Registers an Intent handler. If your app is already registered as an Intent handler through its configuration, use this method to supply a handler for the specified Intent. Otherwise, you can use it to register your app as an Intent handler dynamically at runtime. Dynamically registered Intent handlers share the life span of the respective app instance.
Parameters
Name | Type | Required | Description |
---|---|---|---|
intent | string | AddIntentListenerRequest | The name of the Intent to be handled, or an object specifying the Intent name and additional settings for handling the Intent. |
|
handler | (context: IntentContext, caller?: Instance) => any | The callback that will handle a raised intent. Will be called with an IntentContext if it is provided by the raising application and caller - the Interop Instance which raised the intent |
AddIntentListenerRequestobject
Description
Describes a dynamically registered Intent. Dynamically registered Intent handlers share the life span of the respective app instance.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
contextTypes | string[] | The types of predefined data structures with which the app can work. |
||
description | string | Description for the Intent. |
||
displayName | string | Display name of the Intent. Can be used in context menus or other UI elements to visualize the Intent. |
||
icon | string | Icon for the Intent to be displayed in a UI. |
||
intent | string | Name of the Intent to register. |
||
resultType | string | The type of predefined data structure which the Intent handler returns. |
Configobject
Description
Global settings for the Intents API.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
enableIntentsResolverUI | boolean | true | If |
|
intentsResolverAppName | string | Specify the name of your custom Intents Resolver app to be used for raised Intents. If not provided, the Intents API will use the default Intents Resolver UI app. |
||
methodResponseTimeoutMs | number | 60000 | Interval in milliseconds to wait for a response from the Intents Resolver UI. |
FilterHandlersResultobject
Description
Describes the result returned by the filterHandlers()
method.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
handlers | IntentHandler[] | List of Intent handlers that satisfy the filter criteria. |
GetIntentsResultobject
Description
Describes the result returned by the getIntents()
method.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
intents | IntentInfo[] | List of objects describing the Intents associated with the specified Intent handler. |
HandlerFilterobject
Description
Specifies the criteria for filtering the available Intent handlers when using the filterHandlers()
method.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
applicationNames | string[] | List of app names which will be used as a filter criteria. |
||
contextTypes | string[] | List of context types with which the Intent handlers work to be used as filter criteria. |
||
intent | string | Intent name to be used as a filter criterion. |
||
openResolver | boolean | true | Flag indicating whether the Intents Resolver UI will open to provide the user with the list of valid Intent handlers. |
|
resultType | string | Result type returned by the Intent handlers to be used as a filter criterion. |
||
timeout | number | 90000 | Interval in milliseconds to wait for the |
|
title | string | Title for the search operation that will be provided to the Intents Resolver UI. |
Intentobject
Description
Describes an Intent.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
handlers | IntentHandler[] | Collection of objects describing Intent handler implementations for the Intent. |
||
name | string | Name of the Intent. |
IntentContextobject
Description
Describes the predefined data structure that will be passed to an Intent handler.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
data | { [key: string]: any; } | Data passed as an argument to the Intent handler implementation. |
||
type | string | Type of the predefined data structure. |
IntentFilterobject
Description
Filter for retrieving Intents.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
contextType | string | The type of predefined data structure with which the Intent handler works. |
||
name | string | Name of the Intent to retrieve. |
||
resultType | string | The type of predefined data structure which the Intent handler returns. |
IntentHandlerobject
Description
Describes an Intent handler implementation.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
applicationDescription | string | User-friendly description of the app, as specified in the app configuration. |
||
applicationIcon | string | Icon of the app that has registered the Intent handler, as specified in the app configuration. |
||
applicationName | string | Name of the app that has registered the Intent, as specified in the app configuration. |
||
applicationTitle | string | Title of the app that has registered the Intent, as specified in the app configuration. |
||
contextTypes | string[] | The types of predefined data structures with which the Intent handler works. |
||
displayName | string | Display name of the Intent, as specified in the Intent definition. |
||
instanceId | string | ID of the running app instance. |
||
instanceTitle | string | Title of the app window. |
||
resultType | string | The type of predefined data structure which the Intent handler returns. |
||
type | "app" | "instance" | The type of the Intent handler - an app declared as an Intent handler via its configuration, or a running instance of an app. Dynamically registered Intent handlers are considered running instances. |
IntentInfoobject
Description
Provides additional information about an Intent (e.g., when an Intent is retrieved with the getIntents()
method).
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
contextTypes | string[] | The types of predefined data structures with which the app can work. |
||
description | string | Description for the Intent. |
||
displayName | string | Display name of the Intent. Can be used in context menus or other UI elements to visualize the Intent. |
||
icon | string | Icon for the Intent to be displayed in a UI. |
||
intent | string | Name of the Intent to register. |
||
resultType | string | The type of predefined data structure which the Intent handler returns. |
IntentRequestobject
Description
Describes a request for raising an Intent.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
clearSavedHandler | boolean | false | If |
|
context | IntentContext | Context data that will be provided to the Intent handler. |
||
handlers | IntentHandler[] | Collection of Intent handlers that can be presented to the user via an Intents Resolver UI. If there isn't an Intents Resolver app available (or if the list consists of only one handler), the first member of the collection will be used as an Intent handler. |
||
intent | string | Name of the intent to raise. |
||
options | ApplicationStartOptions | Settings that will be passed to the newly started app instance, if such is to be used as an Intent handler. |
||
target | "startNew" | "reuse" | { app?: string; instance?: string; } | Target for the raised Intent. Use |
||
timeout | number | 90000 | Interval in milliseconds to wait for the |
|
waitUserResponseIndefinitely | boolean | false | If |
IntentResultobject
Description
Describes the result from a raised Intent.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
handler | IntentHandler | The Intent handler implementation used for handling the Intent. |
||
request | IntentRequest | The |
||
result | any | Data returned by the Intent handler implementation. |
Resolverobject
Description
API for controlling the Intents Resolver UI app.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
caller | ResolverCaller | Details about the app instance that opened the Intents Resolver UI. |
||
handlerFilter | HandlerFilter | Criteria for filtering the available Intent handlers. Available only if the |
||
intent | string | IntentRequest | Name of the raised Intent. |
||
version | string | Version of the Intents Resolver API. |
Methods
getTitlemethod
Signature
() => string
Description
Retrieves the title for the search operation. Available only if the filterHandlers()
method was used to open the Intents Resolver UI and the title
property of the HandlerFilter
object was set.
onHandlerAddedmethod
Signature
(callback: (handler: ResolverIntentHandler, intent: IntentInfo) => void) => UnsubscribeFunction
Description
Notifies when a handler for the current Intent is added. Replays already existing handlers.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (handler: ResolverIntentHandler, intent: IntentInfo) => void | Callback function for handling the event. |
onHandlerRemovedmethod
Signature
(callback: (removedHandler: ResolverIntentHandler, intent: IntentInfo) => void) => UnsubscribeFunction
Description
Notifies when a handler for the current Intent is removed.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (removedHandler: ResolverIntentHandler, intent: IntentInfo) => void | Callback function for handling the event. |
sendResponsemethod
Signature
(handler: ResolverIntentHandler, options?: SendResolverResponseOptions) => Promise<InvocationResult<any>>
Description
Sends the chosen Intent handler to the app which raised the Intent.
Parameters
Name | Type | Required | Description |
---|---|---|---|
handler | ResolverIntentHandler | ||
options | SendResolverResponseOptions |
ResolverCallerobject
Description
Describes the app instance that opened the Intents Resolver UI.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
applicationName | string | Name of the app that opened the Intents Resolver UI. |
||
applicationTitle | string | Title of the app that opened the Intents Resolver UI. |
||
id | string | ID of the Interop instance of the app that opened the Intents Resolver UI. |
ResolverIntentHandlerobject
Description
Describes an Intent handler app within the Intents Resolver API.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
applicationIcon | string | Icon of the Intent handler app. |
||
applicationName | string | Name of the Intent handler app. |
||
applicationTitle | string | Title of the Intent handler. |
||
instanceId | string | ID of the Intent handler app instance. |
SendResolverResponseOptionsobject
Description
Options for sending the chosen Intent handler to the app that raised the Intent.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
intent | string | Use this property to supply the name of the Intent when the Intents Resolver UI is opened via the |
||
saveHandler | boolean | false | If |