AboutSupportDeveloper GuideVersion 36.122.80.4

The Interop Client API is broken up into two groups:

Content Facing APIs - For Application Developers putting Views into a Platform Window, who care about Context. These are APIs that send out and receive the Context data that flows between applications. Think of this as the Water in the Interop Pipes.

Context Grouping APIs - For Platform Developers, to add and remove Views to and from Context Groups. These APIs are utilized under-the-hood in Platforms, so they don't need to be used to participate in Interop. These are the APIs that decide which entities the context data flows between. Think of these as the valves or pipes that control the flow of Context Data for Interop.


All APIs are available at the fin.me.interop namespace.


You only need 2 things to participate in Interop Context Grouping:


Constructor

Returned by Interop.connectSync Interop.connectSync.


Interop methods intended for Views

Context Groups API

Intents API

Interop methods intended for Windows

Hierarchy

  • Base
    • InteropClient

Accessors

  • get me(): Identity
  • Provides access to the OpenFin representation of the current code context (usually a document such as a View or Window), as well as to the current Interop context.

    Useful for debugging in the devtools console, where this will intelligently type itself based on the context in which the devtools panel was opened.

    Returns Identity

Methods

  • Add a context handler for incoming context. If an entity is part of a context group, and then sets its context handler, it will receive all of its declared contexts.

    Parameters

    • handler: ContextHandler

      Handler for incoming context.

    • Optional contextType: string

      The type of context you wish to handle.

    Returns Promise<{
        unsubscribe: (() => void);
    }>

    Example

    function handleIncomingContext(contextInfo) {
    const { type, id } = contextInfo;
    switch (type) {
    case 'instrument':
    handleInstrumentContext(contextInfo);
    break;
    case 'country':
    handleCountryContext(contextInfo);
    break;

    default:
    break;
    }
    }


    function handleInstrumentContext(contextInfo) {
    const { type, id } = contextInfo;
    console.log('contextInfo for instrument', contextInfo)
    }

    function handleCountryContext(contextInfo) {
    const { type, id } = contextInfo;
    console.log('contextInfo for country', contextInfo)
    }

    fin.me.interop.addContextHandler(handleIncomingContext);

    We are also testing the ability to add a context handler for specific contexts. If you would like to use this, please make sure you add your context handlers at the top level of your application, on a page that does not navigate/reload/re-render, to avoid memory leaks. This feature is experimental:

    function handleInstrumentContext(contextInfo) {
    const { type, id } = contextInfo;
    console.log('contextInfo for instrument', contextInfo)
    }

    function handleCountryContext(contextInfo) {
    const { type, id } = contextInfo;
    console.log('contextInfo for country', contextInfo)
    }


    fin.me.interop.addContextHandler(handleInstrumentContext, 'instrument')
    fin.me.interop.addContextHandler(handleCountryContext, 'country')
  • Sends an intent to the Interop Broker to resolve.

    Type Parameters

    • T = unknown

    Parameters

    • intent: Intent<IntentMetadata<any>>

      The combination of an action and a context that is passed to an application for resolution.

    Returns Promise<T>

    Example

    // View wants to fire an Intent after a user clicks on a ticker
    tickerElement.on('click', (element) => {
    const ticker = element.innerText;
    const intent = {
    name: 'ViewChart',
    context: {type: 'fdc3.instrument', id: { ticker }}
    }

    fin.me.interop.fireIntent(intent);
    })
  • Sends a Context that will be resolved to an Intent by the Interop Broker. This context accepts a metadata property.

    Type Parameters

    • T = unknown

    Parameters

    Returns Promise<T>

    Remarks

    To resolve this info, the function handleFiredIntentByContext is meant to be overridden in the Interop Broker. The format for the response will be determined by the App Provider overriding the function.

    Example

    tickerElement.on('click', (element) => {
    const ticker = element.innerText;

    const context = {
    type: 'fdc3.instrument',
    id: {
    ticker
    }
    }

    const intentResolution = await fin.me.interop.fireIntentForContext(context);
    })
  • Gets all clients for a context group.

    Parameters

    • contextGroupId: string

      The id of context group you wish to get clients for.

    Returns Promise<ClientIdentity[]>

    Remarks

    This is primarily used for platform windows. Views within a platform should not have to use this API.

    Returns the Interop-Broker-defined context groups available for an entity to join.

    Example

    fin.me.interop.getAllClientsInContextGroup('red')
    .then(clientsInContextGroup => {
    console.log(clientsInContextGroup)
    })
  • Returns the Interop-Broker-defined context groups available for an entity to join. Used by Platform Windows.

    Returns Promise<ContextGroupInfo[]>

    Example

    fin.me.interop.getContextGroups()
    .then(contextGroups => {
    contextGroups.forEach(contextGroup => {
    console.log(contextGroup.displayMetadata.name)
    console.log(contextGroup.displayMetadata.color)
    })
    })
  • Gets the last context of the Context Group currently subscribed to. It takes an optional Context Type and returns the last context of that type.

    Parameters

    • Optional contextType: string

    Returns Promise<Context>

    Example

    await fin.me.interop.joinContextGroup('yellow');
    await fin.me.interop.setContext({ type: 'instrument', id: { ticker: 'FOO' }});
    const currentContext = await fin.me.interop.getCurrentContext();

    // with a specific context
    await fin.me.interop.joinContextGroup('yellow');
    await fin.me.interop.setContext({ type: 'country', id: { ISOALPHA3: 'US' }});
    await fin.me.interop.setContext({ type: 'instrument', id: { ticker: 'FOO' }});
    const currentContext = await fin.me.interop.getCurrentContext('country');
  • Gets display info for a context group

    Parameters

    • contextGroupId: string

      The id of context group you wish to get display info for.

    Returns Promise<undefined | ContextGroupInfo>

    Remarks

    Used by Platform Windows.

    Example

    fin.me.interop.getInfoForContextGroup('red')
    .then(contextGroupInfo => {
    console.log(contextGroupInfo.displayMetadata.name)
    console.log(contextGroupInfo.displayMetadata.color)
    })
  • Get information for a particular Intent from the Interop Broker.

    Type Parameters

    • T = unknown

    Parameters

    Returns Promise<T>

    Remarks

    To resolve this info, the function handleInfoForIntent is meant to be overridden in the Interop Broker. The format for the response will be determined by the App Provider overriding the function.

    Example

    const intentInfo = await fin.me.interop.getInfoForIntent('ViewChart');
    
  • Get information from the Interop Broker on all Intents that are meant to handle a particular context.

    Type Parameters

    • T = unknown

    Parameters

    Returns Promise<T>

    Remarks

    To resolve this info, the function handleInfoForIntentsByContext is meant to be overridden in the Interop Broker. The format for the response will be determined by the App Provider overriding the function.

    Example

    tickerElement.on('click', (element) => {
    const ticker = element.innerText;

    const context = {
    type: 'fdc3.instrument',
    id: {
    ticker
    }
    }

    const intentsInfo = await fin.me.interop.getInfoForIntentByContext(context);
    })
  • Join all Interop Clients at the given identity to context group contextGroupId. If no target is specified, it adds the sender to the context group.

    Parameters

    • contextGroupId: string

      Id of the context group.

    • Optional target: Identity

      Identity of the entity you wish to join to a context group.

    Returns Promise<void>

    Remarks

    Because multiple Channel connections/Interop Clients can potentially exist at a uuid/name combo, we currently join all Channel connections/Interop Clients at the given identity to the context group. If an endpointId is provided (which is unlikely, unless the call is coming from an external adapter), then we only join that single connection to the context group. For all intents and purposes, there will only be 1 connection present in Platform and Browser implmentations, so this point is more-or-less moot. Used by Platform Windows.

    Example

    joinViewToContextGroup = async (contextGroupId, view) => {
    await fin.me.interop.joinContextGroup(contextGroupId, view);
    }

    getLastFocusedView()
    .then(lastFocusedViewIdentity => {
    joinViewToContextGroup('red', lastFocusedViewIdentity)
    })
  • Join the current entity to session context group sessionContextGroupId and return a sessionContextGroup instance. If the sessionContextGroup doesn't exist, one will get created.

    Parameters

    • sessionContextGroupId: string

      Id of the context group.

    Returns Promise<SessionContextGroup>

    Remarks

    Session Context Groups do not persist between runs and aren't present on snapshots.

    Example

    Say we want to have a Session Context Group that holds UI theme information for all apps to consume:

    My color-picker View:

        const themeSessionContextGroup = await fin.me.interop.joinSessionContextGroup('theme');

    const myColorPickerElement = document.getElementById('color-palette-picker');
    myColorPickerElement.addEventListener('change', event => {
    themeSessionContextGroup.setContext({ type: 'color-palette', selection: event.value });
    });

    In other views:

        const themeSessionContextGroup = await fin.me.interop.joinSessionContextGroup('theme');

    const changeColorPalette = ({ selection }) => {
    // change the color palette to the selection
    };

    // If the context is already set by the time the handler was set, the handler will get invoked immediately with the current context.
    themeSessionContextGroup.addContextHandler(changeColorPalette, 'color-palette');
  • Register a listener that is called when the Interop Client has been disconnected from the Interop Broker. Only one listener per Interop Client can be set.

    Returns Promise<void>

    Example

    const listener = (event) => {
    const { type, topic, brokerName} = event;
    console.log(`Disconnected from Interop Broker ${brokerName} `);
    }

    await fin.me.interop.onDisconnection(listener);
  • Adds an intent handler for incoming intents. The last intent sent of the name subscribed to will be received.

    Parameters

    • handler: IntentHandler

      Registered function meant to handle a specific intent type.

    • intentName: string

      The name of an intent.

    • Optional options: any

    Returns Promise<{
        unsubscribe: (() => Promise<void>);
    }>

    Example

    const intentHandler = (intent) => {
    const { context } = intent;
    myViewChartHandler(context);
    };

    const subscription = await fin.me.interop.registerIntentHandler(intentHandler, 'ViewChart');

    function myAppCloseSequence() {
    // to unsubscribe the handler, simply call:
    subscription.unsubscribe();
    }
  • Removes the specified target from a context group. If no target is specified, it removes the sender from their context group. Used by Platform Windows.

    Parameters

    • Optional target: Identity

      Identity of the entity you wish to join to a context group.

    Returns Promise<void>

    Example

    removeViewFromContextGroup = async (view) => {
    await fin.me.interop.removeFromContextGroup(view);
    }

    getLastFocusedView()
    .then(lastFocusedViewIdentity => {
    removeViewFromContextGroup(lastFocusedViewIdentity)
    })
  • Sets a context for the context group of the current entity.

    Parameters

    • context: Context

      New context to set.

    Returns Promise<void>

    Remarks

    The entity must be part of a context group in order set a context.

    Example

    setInstrumentContext = async (ticker) => {
    fin.me.interop.setContext({type: 'instrument', id: {ticker}})
    }

    // The user clicks an instrument of interest. We want to set that Instrument context so that the rest of our workflow updates with information for that instrument
    instrumentElement.on('click', (evt) => {
    setInstrumentContext(evt.ticker)
    })