Data Sharing

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

See the JavaScript Intents example on GitHub.

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:

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);

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:

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);

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:

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:

Available since io.Connect Desktop 9.6

To clear all previously saved Intent handlers, use the clearSavedHandlers() method of the Intents API. To remove a saved handler for a specific Intent, use the clearSavedHandler property of the IntentRequest object when raising the Intent:

const intentRequest = {
    name: "ShowChart",
    // Clearing a previously saved handler for this Intent.
    clearSavedHandler: true
};

await io.intents.raise(intentRequest);

// Clearing all saved handlers for all previously raised Intents.
await io.intents.clearSavedHandlers();

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 accepts two required arguments - 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);

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 argument:

// 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.

Available since io.Connect Desktop 9.6

The Intents API provides methods for subscribing for Intent events. All methods return a function you can use to unsubscribe from the respective event.

To get notified when Intent handlers are added or removed, use the onHandlerAdded() and onHandlerRemoved() methods respectively and provide a callback function for handling the event. The callback will receive an IntentHandler object describing the added or removed Intent handler:

const handler = (intentHandler) => {
    console.log(`App "${intentHandler.applicationName}" was registered as an Intent handler.`);
};

const unsubscribe = io.intents.onHandlerAdded(handler);

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