Intents

Available since Glue42 Enterprise 3.9

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

See the JavaScript Intents example on GitHub.

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

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

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

// The `find()` method returns an array of `Intent` objects.
const intents = await glue.intents.find("ShowChart");
const showChartIntent = intents[0];

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

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

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

await glue.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:

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 intents = await glue.intents.find("ShowChart");
const showChartIntent = intents[0];
const intentHandler = showChartIntent.handlers[0];

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

await glue.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 configuration. 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 intents = await glue.intents.find("ShowChart");
const showChartIntent = intents[0];
// Filtering the handlers by context type.
const handlers = showChartIntent.handlers.filter(handler => handler.contextTypes.includes("Instrument"));

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

await glue.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:

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 glue.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:

// 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;
        // Аpplication specific logic for handling the new context data.
    };
};

await glue.intents.register("ShowChart", 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 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;
        // Аpplication specific logic for handling the new context data.
    };
};

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

Note that when you register an Intent only at runtime (the Intent isn't defined in an app configuration), 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.

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