Intents

JavaScript

Registering Intents

Intents are registered either through the application configuration file, or dynamically at runtime. User defined application files are usually located in the %LocalAppData%\Tick42\UserData\<ENV-REG>\apps folder, where <ENV-REG> should be replaced by the environment and region of your Glue42 Enterprise copy (e.g., T42-DEMO). Intents are configured under the intents top-level key of the application configuration file.

It is possible for several applications to register an Intent with the same name, which is useful when several applications perform the same action or work with the same data structure. This allows for easy replacement of applications. You may have an old app that has registered an Intent called "ShowChart" which you want to replace with a new app. Your new app only needs to register the same Intent (you can either remove the old app or leave it as an additional option for the users who prefer it). No changes to the calling application are necessary - when it raises the "ShowChart" Intent, the new app will be called.

Use the intents top-level key in the application configuration file to define an Intent:

"intents": [
    {
        "name": "ShowChart",
        "displayName": "BBG Instrument Chart",
        "contexts": ["Instrument"]
    }
]
  • name - Required. The name of the Intent;
  • displayName - Optional human readable name of the Intent. Used in context menus to visualize the Intent;
  • contexts - Optional array of types of predefined data structures with which the application works;

The Intents API is accessible through glue.intents.

Finding Intents

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:

const intents = await glue.intents.find("ShowChart");

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

  • name - name of the Intent to look for;
  • contextType - context type (pre-defined data structure - e.g., "Instrument") with which the Intent handler works;

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

Raising 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 an IntentRequest is intent which must specify the name of the Intent to be raised.

Targeting Intent Handlers

When raising an Intent, optionally target one or more IntentHandler objects using the target property of the IntentRequest object:

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

  • "startNew" - will start a new instance of the first available Intent handler;
  • "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;
  • { app?: string, instance?: string} - an object with optional app and instance properties. The app property accepts an application name, the instance property - an ID of a running application instance. Provide a value for the app property to start a new instance of a specific Intent handler application. The application 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. 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 an Intent handler application that has defined the Intent in its configuration is available. If the Intent has been registered dynamically, the default value is "reuse".

The IntentHandler object has a type property which shows whether the Intent handler is an application that will be started (type: "app"), or an already running instance of an Intent handler (type: "instance").

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

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 application.
            selectedClientID: 1 
        }
    },
    // Specify application 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 application, use the addIntentListener() method. It has two required parameters - an Intent name and a context handler definition: 14

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

glue.intents.addIntentListener("ShowChart", contextHandler);

Registering Intents at Runtime

To register an Intent at runtime, use the addIntentListener() 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.
    };
};

glue.intents.addIntentListener(intent, contextHandler);

Note that when you register an Intent only at runtime (the Intent is not defined in the application configuration file), your application must be running in order to handle the Intent and it will always be of type "instance". If your application is not running when this Intent is raised, it will not be available as a possible Intent handler.

Reference

Reference