Intents
2.20.0In 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 glue.intents object.
APIobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| resolver | Resolver | An object, through which IntentsResolver API is exposed. |
Methods
allmethod
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. |
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) => 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) => any | The callback that will handle a raised intent. Will be called with an IntentContext if it is provided by the raising application. |
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 glue.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 |
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 |
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 |
IntentRequestobject
Description
Represents a request to raise an intent.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| context | IntentContext | The context type and data that will be provided to the intent implementation's handler. |
||
| handlers | IntentHandler[] | |||
| 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:
|
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
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| intent | string | Name of the raised intent |
Methods
onHandlerAddedmethod
Signature
(callback: (handler: ResolverIntentHandler) => void) => UnsubscribeFunction
Description
Notifies when a ResolverIntentHandler of the current intent is added. Replays the already existing handlers.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (handler: ResolverIntentHandler) => void |
onHandlerRemovedmethod
Signature
(callback: (removedHandler: ResolverIntentHandler) => void) => UnsubscribeFunction
Description
Notifies when a ResolverIntentHandler of the current intent is removed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (removedHandler: ResolverIntentHandler) => void |
sendResponsemethod
Signature
(handler: ResolverIntentHandler) => Promise<InvocationResult<any>>
Description
Sends the chosen handler to the application which raised the intent
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| handler | ResolverIntentHandler |
ResolverIntentHandlerobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| applicationIcon | string | |||
| applicationName | string | |||
| instanceId | string |