Intents

Overview

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

See the JavaScript Intents example on GitHub.

Finding Intents

To find all registered Intents, use the all() method:

const allIntents = await io.intents.all();

To get a collection of all Intents that fit certain criteria, use the find() method:

// The `find()` method resolves with a list of `Intent` objects.
const intents = await io.intents.find("ShowChart");
const showChartIntent = intents[0];

The find() method accepts a string or an IntentFilter object as an optional argument. The IntentFilter object has the following properties:

Property Type Description
name string Name of the Intent for which to search.
contextType string The type of pre-defined data structure with which the Intent handler works.
resultType string The type of pre-defined data structure which the Intent handler returns.

If no filter is supplied, find() returns all registered Intents.

Available since io.Connect Desktop 9.2

To get all Intents for a specific Intent handler, use the getIntents() method and pass an IntentHandler object as a required argument:

const intents = await io.intents.find("ShowChart");
const handler = intents[0].handlers[0];

const result = await io.intents.getIntents(handler);
// The `getIntents()` method resolves with an object with an `intents` property holding a list of `IntentInfo` objects.
result.intents.forEach(console.log);

Raising Intents

To raise an Intent, use the raise() method:

await io.intents.raise("ShowChart");

The raise() method accepts an Intent name as a string or an IntentRequest object as a required argument. The only required property of the IntentRequest object is intent which must specify the name of the Intent to be raised.

The IntentRequest object has the following properties:

Property Type Description
context object Context data that will be provided to the Intent handler.
handlers object[] 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 object ApplicationStartOptions object that will be passed to a 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 Interval in milliseconds to wait for the raise() method to resolve when raising an Intent. Defaults to 90000.
waitUserResponseIndefinitely boolean 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. Defaults to false.

Filtering Intent Handlers

Available since io.Connect Desktop 9.2

To retrieve available Intent handlers based on a specified criteria, use the filterHandlers() method and provide a HandlerFilter object as a required argument. The HandlerFilter object allows you to specify whether the Intents Resolver UI app will open when there are more than one available Intent handlers in order to display them to the user:

const filter = {
    intent: "ShowChart",
    openResolver: false
};

const result = await io.intents.filterHandlers(filter);

// The `filterHandlers()` method resolves with an object with a `handlers` property holding a list of `IntentHandler` objects.
result.handlers.forEach(console.log);

Targeting Intent Handlers

To target which apps or running instances will handle a raised Intent, you can use the handlers and/or target properties of the IntentRequest object.

  • using the target property:

The target property allows you to specify whether a new instance of an Intent handler app is to be started, or an already running instance is to be reused for handling the Intent.

The following example demonstrates using the target property of the IntentRequest object:

const filter = { intent: "ShowChart" };
const result = await io.intents.filterHandlers(filter);
const intentHandler = result.handlers[0];

const intentRequest = {
    intent: "ShowChart",
    target: { app: intentHandler.applicationName }
};

await io.intents.raise(intentRequest);

The target property of the IntentRequest object accepts the following values:

Value Description
"reuse" Will reuse the first available running instance of an Intent handler or will fall back to "startNew" if there are no running instances available.
"startNew" Will start a new instance of the first available Intent handler.
{ app?: string, instance?: string } An object with optional app and instance properties. 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. The app name is available in the applicationName property of the IntentHandler object. Provide a value for the instance property to reuse a specific running instance of an Intent handler. The ID of an Intent handler instance is available in the instanceId property of the IntentHandler object. If both app and instance are set, instance will take precedence. Using this targeting option gives you full control over the choice of an appropriate Intent handler.

The default value for the target property is "startNew" when the Intent has been defined in an app definition. If the Intent has been registered dynamically, the default value is "reuse".

To determine whether an Intent handler is an app or an already running instance, use the type property of the IntentHandler object, which will be set to "app" or "instance" respectively.

⚠️ Note that in order for the running Intent handler instance to be registered as type "instance", the app must use the register() method in its code to handle context updates (see Handling Context Updates) or to register an Intent at runtime (see Registering Intents at Runtime). Otherwise, the running Intent handler instance will be of type "app".

  • using the handlers property:

The handlers property allows you to pass directly an array of IntentHandler objects to be used for handling the Intent and provides more flexibility when targeting Intent handlers. For instance, you can filter them by context type or result type before attaching them to the Intent request:

const filter = { intent: "ShowChart" };
const result = await io.intents.filterHandlers(filter);
// Filtering the handlers by context type.
const handlers = result.handlers.filter(handler => handler.contextTypes.includes("Instrument"));

const intentRequest = {
    intent: "ShowChart",
    handlers
};

await io.intents.raise(intentRequest);
  • using a combination of both properties:

When using the target and handlers properties of the IntentRequest object in a combination, you must take into consideration that the target property takes precedence over the handlers property.

The following table demonstrates what the resulting behavior would be for various combinations between the target and handlers properties:

Value/App/Instance for target Apps/Instances for handlers Targeted Intent Handler
undefined App-A, App-B New instance of App-A
undefined App-A, App-B, Instance-A, Instance-B Reuse Instance-A
"reuse" App-A, App-B New instance of App-A
"reuse" App-A, App-B, Instance-A, Instance-B Reuse Instance-A
"startNew" App-A, App-B New instance of App-A
"startNew" App-A, App-B, Instance-A, Instance-B New instance of App-A
{ app: "App-A" } App-A, App-B New instance of App-A
{ app: "App-A" } App-A, App-B, Instance-A, Instance-B New instance of App-A
{ app: "App-A" } App-B, Instance-A, Instance-B New instance of App-A
{ instance: "Instance-B" } App-A, App-B, Instance-A, Instance-B Reuse Instance-B
{ instance: "Instance-B" } App-A, App-B, Instance-A Reuse Instance-B if such is found within the io.Connect framework and it's registered as an Intent handler, otherwise - throw an error.

Context

Passing Initial Context

To pass initial context to the Intent handler, use the context property of the IntentRequest object. It accepts an IntentContext object as a value:

const intentRequest = {
    intent: "ShowChart",
    target: "startNew",
    context: {
        type: "Instrument",
        data: {
            // Context for the started app.
            RIC: "MSFT"
        }
    },
    // Specify app start options for the Intent handler.
    options: {
        width: 300,
        height: 200
    }
};

await io.intents.raise(intentRequest);

The type property of the IntentContext object is required and specifies the structure of the context object. The data property is the actual data to be passed to the Intent handler.

The options property of the IntentRequest object is used to pass custom ApplicationStartOptions to the Intent handler.

Handling Context Updates

To handle the context data passed when an Intent is raised and targeted at your app, use the register() method. It has two required parameters - an Intent name and a context handler definition:

const intentName = "ShowChart";

// Context handler definition.
function contextHandler (context) {
    // Check the context type.
    const contextType = context.type;

    if (contextType === "Instrument") {
        // Extract the context data.
        const data = context.data;
        // App-specific logic for handling the new context data.
    };
};

await io.intents.register(intentName, contextHandler);

Registering Intents at Runtime

To register an Intent at runtime, use the register() method. Besides an Intent name, this method also accepts an object describing an Intent as a first required parameter:

// Intent definition.
const intent = {
    intent: "ShowChart",
    contextTypes: ["Instrument"],
    displayName: "Fidessa Instrument Chart",
    icon: "https://example.com/resources/icon.ico"
};

// Context handler.
function contextHandler (context) {
    // Check the context type.
    const contextType = context.type;

    if (contextType === "Instrument") {
        // Extract the context data.
        const data = context.data;
        // App-specific logic for handling the new context data.
    };
};

await io.intents.register(intent, contextHandler);

⚠️ Note that when you register an Intent only at runtime (the Intent isn't defined in an app definition), your app must be running in order to handle the Intent, and it will always be of type "instance". If your app isn't running when this Intent is raised, it won't be available as a possible Intent handler.

Reference

For a complete list of the available Intents API methods and properties, see the Intents API Reference Documentation.