• Back to io.Connect Desktop docs
io.Connect Desktop Documentation

API Reference Documentation

  • Back to io.Connect Desktop docs
Press/
  • io.Connect Desktop
  • App Management
  • App Preferences
  • Channels
  • Cookies
  • Displays
  • Hotkeys
  • Intents
  • Interception
  • Interop
  • Layouts
  • Logger
  • Metrics
  • Notifications
  • Pub Sub
  • Search
  • Shared Contexts
  • Themes
  • Windows
  • Workspaces

Intents

6.13.0

The 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

  • all
  • clearSavedHandlers
  • filterHandlers
  • find
  • getIntents
  • onHandlerAdded
  • onHandlerRemoved
  • raise
  • register

allmethod

Signature

() => Promise<Intent[]>

Description

Retrieves all registered Intents.

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 IntentFilter object supplying more criteria for filtering the Intents.

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 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 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 IntentRequest object holding settings for targeting Intent handlers, passing context, app start options and more.

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 true, will enable using the Intents Resolver UI for handling raised Intents. The Intents Resolver UI provides the user with a list of all available apps and running instances which can handle the raised Intent. In case there is only one Intent handler available, it will be automatically selected for handling the raised Intent, without displaying the Intents Resolver UI to the user.

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 filterHandlers() method to resolve if more than one Intent handler is available and the Intents Resolver UI is enabled.

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 true, the previously saved Intent handler for this Intent (if any) will be cleared.

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 "startNew" to start a new instance of the first available Intent handler. Use "reuse" to reuse the first available running instance of an Intent handler. Will fall back to "startNew" if there are no running instances available. Use an object with optional app and instance properties to target specific apps or app instances. The app property accepts an app name, the instance property - an ID of a running app instance. Provide a value for the app property to start a new instance of a specific Intent handler app. Provide a value for the instance property to reuse a specific running instance of an Intent handler. If both app and instance are set, instance will take precedence.

timeout number 90000

Interval in milliseconds to wait for the raise() method to resolve when raising an Intent.

waitUserResponseIndefinitely boolean false

If true, the framework will wait for the user to choose a handler for the raised Intent from the Intents Resolver UI before starting the timeout specified in the timeout property of the Intent request. Otherwise, the timeout will start when the raise() method is invoked.

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 IntentRequest object used for raising the Intent.

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 filterHandlers() method was used to open the Intents Resolver UI.

intent string | IntentRequest

Name of the raised Intent.

version string

Version of the Intents Resolver API.

Methods

  • getTitle
  • onHandlerAdded
  • onHandlerRemoved
  • sendResponse

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 filterHandlers() method and you want to save the Intent handler for that Intent. If the Intents Resolver UI is opened via the raise() method, it isn't necessary to explicitly provide the Intent name here, as specifying an Intent name is mandatory when using the raise() method.

saveHandler boolean false

If true, the chosen Intent handler will be saved as a handler for the raised Intent. If the handler is saved, the next time the same Intent is raised, the Intents Resolver UI won't open and the saved handler will be used automatically.

  • Home
  • Privacy policy
  • Contact Us
  • interop.io
  • Overview
  • API
  • AddIntentListenerRequest
  • Config
  • FilterHandlersResult
  • GetIntentsResult
  • HandlerFilter
  • Intent
  • IntentContext
  • IntentFilter
  • IntentHandler
  • IntentInfo
  • IntentRequest
  • IntentResult
  • Resolver
  • ResolverCaller
  • ResolverIntentHandler
  • SendResolverResponseOptions
Navigate
Go