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

API Reference Documentation

  • Back to io.Connect Browser docs
Press/
  • io.Connect Browser
  • App Management
  • App Preferences
  • Channels
  • Intents
  • Interop
  • Layouts
  • Notifications
  • Search
  • Shared Contexts
  • Themes
  • Widget
  • Windows
  • Workspaces

Intents

3.5.9

In certain workflow scenarios, your application may need to start (or activate) a specific application. For instance, you may have an application showing client portfolios with financial instruments. When the user clicks on an instrument, you want to start an application 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 application.

The Intents API makes all that possible by enabling applications to register, find and raise Intents.

The Intents API is accessible through the io.intents object.

APIobject

Properties

Property Type Default Required Description
resolver Resolver

An object, which exposes the Intents Resolver API.

Methods

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

allmethod

Signature

() => Promise<Intent[]>

Description

Returns all registered Intent.

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

Searches for registered intents.

Parameters

Name Type Required Description
intentFilter string | IntentFilter

can be the intent name or a IntentFilter filtering criteria.

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, intentName: string) => void) => UnsubscribeFunction

Description

Notifies when a handler for an Intent is added. Returns an unsubscribe function.

Available since io.Connect Browser 3.5

Parameters

Name Type Required Description
callback (handler: IntentHandler, intentName: string) => void

Callback function for handling the event. Receives an object describing the added Intent handler as an argument.

onHandlerRemovedmethod

Signature

(callback: (handler: IntentHandler, intentName: string) => void) => UnsubscribeFunction

Description

Notifies when a handler for an Intent is removed. Returns an unsubscribe function.

Available since io.Connect Browser 3.5

Parameters

Name Type Required Description
callback (handler: IntentHandler, intentName: string) => void

Callback function for handling the event. Receives an object describing the removed Intent handler as an argument.

raisemethod

Signature

(request: string | IntentRequest) => Promise<IntentResult>

Description

Raises an intent, optionally passing context to the intent handlers, and optionally targeting specific intent handlers. If no handlers are matching the targeting conditions the promise will be rejected.

Parameters

Name Type Required Description
request string | IntentRequest

can be the intent's name or an IntentRequest object carrying the intent, and its optional target, context and start options (see "startNew").

registermethod

Signature

(intent: string | AddIntentListenerRequest, handler: (context: IntentContext, caller?: Instance) => any) => Promise<{ unsubscribe: UnsubscribeFunction; }>

Description

If your application is an intent handler use this method to handle incoming intent requests. Please note that when a new instance of your application is started as a result of a raised intent with e.g. startNew your application needs to call register() on startup so that the intent can be resolved. The handler callback will be invoked whenever an intent is raised and your app was selected as an IntentTarget. You can also use this method to register new dynamic intents, that will have the the same lifespan as your application instance.

Parameters

Name Type Required Description
intent string | AddIntentListenerRequest

The intent to be handled. The intent name of an object containing the intent, contextTypes that the intent can handle and a display name.

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

Use to define dynamic intents, that will have the same lifespan as your application instance

Properties

Property Type Default Required Description
contextTypes string[]
description string
displayName string
icon string
intent string
resultType string

Configobject

Properties

Property Type Default Required Description
enableIntentsResolverUI boolean

Whether to use Intents Resolver UI to handle raising an intent. The UI provides the user with a list of all available applications and running instances which can handle the raised intent. Default value: true

intentsResolverAppName string

Specify your custom application name for Intents Resolver UI which will open when io.intents.raise() is invoked. If not provided, Intents API will use the default Intents Resolver UI application to handle raising an intent with multiple handlers

methodResponseTimeoutMs number 60000

Timeout to wait for response from 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 application 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 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

Represents an intent.

Properties

Property Type Default Required Description
handlers IntentHandler[]

The set of IntentHandler that provide an implementation for the intent and can be used to handle an intent request.

name string

The name of the intent, such as "CreateCall".

IntentContextobject

Description

A structure that describes a typed context to be used to raise intents with.

Properties

Property Type Default Required Description
data { [key: string]: any; }

The context data used as an argument by the intent implementation.

type string

The name of a typed, documented data structure such as "Person", "Team", "Instrument", "Order", etc. It is the application developers' job to agree on a protocol to follow.

IntentFilterobject

Description

Specifies the search criteria for the Intent API's find() method.

Properties

Property Type Default Required Description
contextType string

The name of the context type to be used in the lookup.

name string

The name of the intent to be used in the lookup.

resultType string

The type of the intent result to be used in the lookup.

IntentHandlerobject

Description

Represents an implementation of an intent. Each intent handler can offer its own display name - this allows context menus built on the fly to display more user friendly options. For example, if there is an intent with a name "ShowNews", there could be a handler with display name "Show Bloomberg News" and another with display name "Show Reuters News". Handlers can optionally specify the context type they support, where the context type is the name of a typed, documented data structure such as "Person", "Team", "Instrument", "Order", etc. In the example above, both the Bloomberg and Reuters handlers would specify a context type "Instrument" and would expect to be raised with an instrument object conforming to an expected structure from both handlers. An intent handler must not necessarily specify a context type.

Properties

Property Type Default Required Description
applicationDescription string
applicationIcon string
applicationName string

The name of the application which registered this intent implementation, as specified in the application configuration.

applicationTitle string
contextTypes string[]

The context types this handler supports.

displayName string

The human-readable name of the intent handler, as specified in the intent definition.

instanceId string

The id of the running application instance.

instanceTitle string

The window's title of the running application instance.

resultType string

Result type may be a type name, the string "channel" (which indicates that the app will return a channel) or a string indicating a channel that returns a specific type, e.g. "channel<fdc3.instrument>"

type "app" | "instance"

The type of the handler. "app" - An application that has declared itself as an implementor of the intent inside of its application definition. "instance" - A running instance of an application that can handle the intent. Also includes dynamically added intents using addIntentListener().

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[]
description string
displayName string
icon string
intent string
resultType string

IntentRequestobject

Description

Represents a request to raise 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

The context type and data that will be provided to the intent implementation's handler.

handlers IntentHandler[]

List of Intent Handlers which will be provided to the user via Intents Resolver UI. If the Resolver is disabled or there's only one handler in the array, raise() will resolve with the first application or instance in the collection.

intent string

The name of the intent to be raised.

options ApplicationStartOptions

Start up options that will be used when a new instance of an application needs to be started to handle the intent request.

target "startNew" | "reuse" | { app?: string; instance?: string; }

Тhe target of the raised intent. Valid values are: startNew - will start a new instance of an application that can handle the intent. reuse - a running instance of an application will handle the intent. { app: "AppName" } - will start a new instance of the "AppName" application (iff it can handle it) that will handle the intent. { instance: "i-123-1" } - the running application instance with instanceId "i-123-1" will handle the intent (iff it can handle it).

timeout number : 90000

Timeout to wait for 'raise' method to resolve.

waitUserResponseIndefinitely boolean : false

Whether to wait for the Intents Resolver UI to choose a handler for the raised intent. If set to true, the timer starts after there's a chosen handler from the user. Otherwise, the start point is the beginning of the raise invocation.

IntentResultobject

Description

The result of a raised intent.

Properties

Property Type Default Required Description
handler IntentHandler

The intent implementation that handled the intent.

request IntentRequest

The arguments that were used to raise the intent with.

result any

The data returned by the intent implementation when handling the intent.

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

(response: ResolverIntentHandler, options?: SendResolverResponseOptions) => Promise<InvocationResult<any>>

Description

Sends the chosen Intent handler to the app which raised the Intent.

Parameters

Name Type Required Description
response ResolverIntentHandler

The Intent handler that will be sent to the app which raised the Intent.

options SendResolverResponseOptions

Options for sending the Intent handler to the app that raised the Intent.

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