Bloomberg integration v2

The OpenFin integration API for Bloomberg Terminal Connect enables interoperability between OpenFin apps that you write and the Bloomberg Terminal.
It takes full advantage of the OpenFin Interop API implementation of context and intents.

Version 2 replaces version 1 of the connector, reflecting significant changes in the API offered by Bloomberg Terminal Connect.
Version 2 is recommended for all new development.
If you need information about the previous Bloomberg integration, refer to Bloomberg integration v1.2.

The updated Bloomberg API connector makes it getting going straightforward, but with many options to tailor the connector to your needs.

This new version uses the latest version of Bloomberg’s Terminal Connect API to provide rich integration with a Bloomberg Terminal.
It supports several FDC3 contexts and intents out of the box, allowing your OpenFin applications to stay in sync with content in Bloomberg through context sharing or allowing workflows to flow from your OpenFin applications to your Bloomberg Terminal using intents.

The connector also makes it straightforward to make requests to the Terminal Connect API GraphQL endpoints directly from your OpenFin apps.
The connector includes Typescript definitions for common Terminal Connect API requests to enable you to build strongly typed applications that integrate with the Bloomberg Terminal.

Prerequisites

• OpenFin
  • Minimum recommended runtime version 20.91.62.4
• Bloomberg
  • Terminal Connect API key (contact your Bloomberg account manager for more information about getting an API key)
  • Terminal running locally and user logged in

Install

The updated Bloomberg connector consists of two assets:

• An NPM package that you install for development

• A signed executable .NET adapter package that can be delivered from the OpenFin CDN or self-hosted within your network

First, add the @openfin/bloomberg NPM package as a dependency for your app:

npm install @openfin/bloomberg

Use the connector

Initialize

When the connect function is first run, the client-side API downloads and launches the .NET adapter package in the background, which is an intermediary between the client-side API and Bloomberg’s Terminal Connect API.
To facilitate this process, you must configure some aspects of the application.

Configure API security

The Bloomberg API Connector requires permission to use the System.downloadAsset and System.launchExternalProcess secured APIs.
Be sure to declare the following permissions in your app’s manifest:

...
"permissions": { 
  "System": {
    "downloadAsset": true,
    "launchExternalProcess": true
  }
},
...

Note

The location of the permissions object depends on whether your app uses Platform API.
See Declaring APIs in an application manifest file for more information.

In addition, when running on OpenFin runtime v20 or later, the desktop owner must also allow your application to use this secured API in desktop owner settings. However, this is not required during development if your application is running from localhost, so there is no need to configure desktop owner settings.

Self-host the adapter

Corporate firewalls might prevent access to OpenFin’s CDN, in which case, the Bloomberg connector cannot download the required adapter package.
To remedy this, you can self-host the adapter package by downloading the relevant package and hosting it within the corporate network.

Adapter packages for the Bloomberg Connector can be downloaded from OpenFin’s Versions page,
Check the Bloomberg Connector Versions table on the Integrations tab.

When self-hosting the adapter package, you must make any app that uses the Bloomberg connector aware of the alternate adapter package location by declaring it as an appAsset in your app’s manifest:

...
"appAssets": [{
  "alias": "bloomberg-adapter",
  "src": "ADAPTER_PACKAGE_URL",
  "target": "OpenFin.Bloomberg.exe",
  "version": "ADAPTER_PACKAGE_VERSION"
  }]
...

Note that you should do the following:

• Ensure that the alias and target values match those in the example above.

• Replace "ADAPTER_PACKAGE_URL" for the src property with the URL where your app can download the adapter package from. Including the package version in the URL is recommended to avoid version conflicts.

• Replace "ADAPTER_PACKAGE_VERSION" for the version property with the NPM package version your app is using.

Caution

Do not mix package versions!

The version of the self-hosted adapter package declared in appAssets must match the NPM package version used by the app.
If it does not, an error is thrown when the app attempts to use the Bloomberg Connector.

To avoid conflicts, ensure that the hosted URL contains the version of the adapter package and take care when upgrading NPM dependencies: if the @openfin/bloomberg package is upgraded, you must also update appAssets to match.

Connect to the Bloomberg Terminal

Under the hood, Bloomberg’s Terminal Connect API is a web service accessed using an API key, which Bloomberg provides you.
In order that the connector can make requests to the Terminal Connect API, you must provide your API key when calling the connect function.
If the default interoperability features are sufficient for your needs, you need only provide your API key, and the OpenFin connector does the rest:

    import { connect} from "@openfin/bloomberg";
    const apiKey = "BLOOMBERG_API_KEY";
    const bbgConnection = await connect(apiKey);

(Replace “API_KEY” with your Terminal Connect API key.)

You can also specify various parameters to configure how the integration works when connecting. You can disable or customize the interoperability integrations and specify what groups should be included in interoperability context sharing.
If all you want to do is directly call Bloomberg Terminal Connect APIs, you only need to specify your API key and disable the interoperability options.
See Advanced configuration for more options for tailoring the connector’s behavior.

Disconnect

When the connection is no longer needed, be sure to call the disconnect function to clean up resources:

await bbgConnection.disconnect();

Launchpad groups

By default, the connector listens to all Launchpad groups and broadcasts an fdc3.instrument object whenever a group’s security changes.

You can change this behavior to listen only to specific groups or disable the broadcasting of context altogether, by providing appropriate configuration options.
See Advanced configuration for information on how to configure this behavior.

Share contexts

By default, the connector listens for incoming standard FDC3 context types and executes the relevant function in the Terminal.
Thus, your applications and your Bloomberg Terminal can show information about the same instrument, contact, or organization without users needing to rekey data.

The connector supports FDC3 Instrument properties that contain full Bloomberg security strings or FIGIs.
If only a ticker ID is present in a context object, the connector assumes the ticker represents a US equity.
An exception to this rule is that if the context type has an FDC3 market property that includes a BBG key indicating which exchange the equity belongs to, then the connector looks up the instrument ticker against that exchange.

If you share an fdc3.contact object with the Terminal, it issues a BIO command for the contact.

If you send an fdc3.organization object to the Terminal, it searches for that organization, displaying any relevant information.

This functionality is overridable and extendable.
You can map FDC3 context types to different mnemonics or custom context types to your chosen mnemonics.
See Advanced configuration for information on configuring this behavior.

Use intents

The OpenFin Bloomberg connector includes support for several FDC3 intents out of the box.
The default configuration maps intents to Bloomberg mnemonics depending on the intent and the context within it.
For example, any application connected to your Interop Broker that raises a ViewChart intent can automatically have an appropriate mnemonic sent to the Terminal without you having to write custom mappings.
In addition, the default configuration accepts fdc3.nothing contexts supplied with supported intents, meaning that the relevant mnemonic function is loaded in the Terminal without changing the current security.

Of course, if you want fine-grain control over this, you can supply your own mappings to override the defaults that we provide or even register custom intents and contexts.
This capability is useful if you use custom context types or intents beyond the standard FDC3 ones.

The following sections describe default intents, which are then summarized in a table for quick reference.

Start chats

We support StartChat and ViewChat using an fdc3.contact, which opens an Instant Bloomberg (IB) chat with that contact by issuing the IB mnemonic.
The connector uses the email address within the contact context object to identify the relevant IB chat user.

Explore analyses

You can use a ViewAnalysis intent containing an fdc3.instrument context.
The analysis opened in the terminal depends on the type of instrument in the context.
For example, if you raise a ViewAnalysis intent with a fixed income security (Corp/Govt/Mtge/Muni/Pfd) as the instrument, the connector issues a YAS mnemonic to show a yield and spread analysis in the Terminal.
In contrast, if you supply equity-related securities (Equity/Index), the connector issues the FA mnemonic to show an equity analysis; if you supply any other value, the connector issues an ANR mnemonic.

View charts

In version 1 of the OpenFin Bloomberg connector, the ViewChart intent supported only the fdc3.instrument context; it is also supported in version 2.
If you supply an instrument context with the ViewChart intent, the connector issues a GIP mnemonic to the Terminal.

However, FDC3 2.0 also supports an fdc3.chart context type, which can be used to specify numerous parameters such as date range, multiple instruments, and chart style.
Using this context type issues an appropriate mnemonic, as detailed below.

You can use the following options in an fdc3.chart context to control the chart that is opened:

• instruments: Update the security loaded in the Terminal

• range: When set, historic chart mnemonics are used; otherwise, intraday mnemonics are used

• style: When set with a value from the list below, the corresponding chart mnemonics are used (historic/intraday respectively, depending on whether range was supplied).

  • “line”: GP/GIP

  • “bar”: GPO/IGPO

  • “candle”: GPC/IGPC (default)

• interval: When set with a value from the list below, historic charts (non-intraday) are presented with the appropriate interval

  • “daily”

  • “weekly”

  • “monthly”

  • “quarterly”

  • “yearly”

View contacts

The ViewContact intent instructs the Terminal to open a BIO page for the supplied contact fdc3.contact context.

View news

The ViewNews intent displays company news for the security specified in the supplied fdc3.instrument context via a CN mnemonic.

View profiles

Depending on the type of context passed with the ViewProfile intent, the terminal either shows a BIO page for a fdc3.contact or searches for an organization specified in an fdc3.organization context.

View quotes

The ViewQuote intent shows all quotes in the Terminal for the security specified in the supplied fdc3.instrument context via an ALLQ mnemonic.

View research

The ViewResearch intent displays research results in the Terminal for the security specified in the supplied fdc3.instrument context via a BRC mnemonic.

Summary of default mappings

Context

Intents

When connecting, you can override these default mappings or provide custom mappings as described in Advanced configuration section.

Execute Terminal Connect API functions

You can run custom Terminal Connect API GraphQL queries directly from your OpenFin application by specifying a query and the endpoint to submit the query to.
The endpoint is either ‘Local’ or ‘Remote’, depending on the query you want to run.
The Bloomberg GraphQL documentation on your terminal gives you details on the query format and advice on which endpoint to use for different queries.

For example, to execute a GraphQL mutation that runs the DES mnemonic in Terminal panel zero and updates the security to RIO LN Equity, do the following:

    import { TerminalConnectApiTypes } from "@openfin/bloomberg";

    // Use the appropriate return type from TerminalConnectApiTypes when calling the executeApiRequest function
    const result =
      await bbgConnection.executeApiRequest<TerminalConnectApiTypes.RunFunctionInPanelResult>(`
        mutation {
          runFunctionInPanel(input: {
            mnemonic: "DES",
            panel: ZERO,
            security1: "RIO LN Equity"
          }) {
            ... on Result {
              succeeded
              details
            }
            ... on Error {
              errorCategory
              errorMessage
            }
          }
        }`,
        "local"
      );

    // Output results to the console
    console.log(result.runFunctionInPanel);

Note the following:

• Use the relevant type from the TerminalConnectApiTypes namespace exported by the connector API. In this case, the GraphQL mutation is runFunctionInPanel, which corresponds to the RunFunctionInPanelResult type.

• The Bloomberg Terminal Connect API documentation indicates that the runFunctionInPanel mutation must be sent to the local web socket, so "local" is the second parameter to the executeApiRequest function.

• Providing "... on Error" with errorCategory and errorMessage in the GraphQL mutation ensures that the connector API throws a TerminalConnectRequestError error in the event that the mutation results in an error.

Advanced configuration

The OpenFin Bloomberg connector is designed to get you up and running using standard FDC3 contexts and intents while also allowing you to issue GraphQL queries with minimal configuration.
However, when you call the connect function, you can override and customize any default capabilities.

The connect function accepts an optional BloombergConnectionConfig object.
It provides options to completely disable the interoperability features through the Boolean interopDisabled property, as well as the ability to specify what groups the connector listens to in the Terminal through the groups property.

To disable interoperability, set the interopDisabled property of the connection configuration object to false:

    import { connect } from "@openfin/bloomberg";

    const config: BloombergConnectionConfig = {
      interopDisabled: true,
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);

If you want to change the default behavior so that context is broadcast only when Launchpad group A is updated, then set the groups property of the connection configuration object:

    import { connect } from "@openfin/bloomberg";

    const config: BloombergConnectionConfig = {
      groups: ["Group-A"],
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);

Configure custom actions

The actions property of the BloombergConnectionConfig object allows you to specify which incoming context types and intents are handled by the connector and what resultant actions are taken in the Terminal.

The following examples show how you can use the actions property to specify what happens on the Terminal for various contexts or intents.

Disable behavior for a specific context type

If you wanted to override the default behavior for handling fdc3.contact contexts so that nothing happens on the Terminal, you could use the following configuration when connecting:

    import { BloombergConnectionConfig, connect } from "@openfin/bloomberg";
    import * as fdc3 from "@finos/fdc3";

    const config: BloombergConnectionConfig = {
      actions: {
        // Override the default contact context action with a handler that returns null
        contexts: [[fdc3.ContextTypes.Contact, () => null]],
      },
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);

Specify what action to take when context is received

If you wanted to replace the default behavior for when an fdc3.instrument context is received, or specify behavior for a custom context, you can specify the context type and function that implements the behavior using the following approach:

    import {
      BloombergConnectionConfig,
      BloombergGroupUpdate,
      connect,
      getSecurityFromInstrumentContext
    } from "@openfin/bloomberg";
    import * as fdc3 from "@finos/fdc3";

    const config: BloombergConnectionConfig = {
      actions: {
        contexts: [
          [
            fdc3.ContextTypes.Instrument,
            (context) => {
              // Use the getSecurityFromInstrumentContext utility function to extract the security string from the context
              const security = getSecurityFromInstrumentContext(context);
              if (!security) {
                return;
              }

              // Return a BloombergGroupUpdate object that updates Launchpad group A with the security
              return {
                group: "Group-A",
                security,
              } as BloombergGroupUpdate;
            },
          ],
        ],
      },
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);

Note the use of the getSecurityFromInstrumentContext function, which is useful in extracting a Bloomberg security string from an Instrument context object.

If you want to configure the connector to run a mnemonic against a particular tab in the Bloomberg Terminal when an fdc3.instrument context is received from OpenFin, then you could use the following options:

    import {
      BloombergConnectionConfig,
      BloombergTerminalFunction,
      connect,
      getSecurityFromInstrumentContext
    } from "@openfin/bloomberg";
    import * as fdc3 from "@finos/fdc3";

    const config: BloombergConnectionConfig = {
      actions: {
        contexts: [
          [
            fdc3.ContextTypes.Instrument,
            (context) => {
              // Use the getSecurityFromInstrumentContext utility function to extract the security string from the context
              const security = getSecurityFromInstrumentContext(context);
              if (!security) {
                return;
              }

              // Return a BloombergTerminalFunction object that runs the GP function in the desired tab
              return {
                mnemonic: "GP",
                securities: [security],
                target: "myChart",
              } as BloombergTerminalFunction;
            },
          ],
        ],
      },
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);

Custom intent behavior

If you wanted to replace the behavior for when a ViewInstrument intent is received by the connector, so that both the panel and group are updated to show the security, you can use the intents property of the actions object to specify the intent name; for each context type that it supports, specify a function that returns the instructions to run on the Terminal:

    import {
      BloombergConnectionConfig,
      BloombergGroupUpdate,
      BloombergTerminalFunction,
      connect,
      getSecurityFromInstrumentContext
    } from "@openfin/bloomberg";
    import * as fdc3 from "@finos/fdc3";

    const config: BloombergConnectionConfig = {
      actions: {
        intents: [
          [
            "ViewInstrument",
            [
              [
                fdc3.ContextTypes.Instrument,
                (context) => {
                  const security = getSecurityFromInstrumentContext(context);
                  return security
                    ? ({
                        mnemonic: "DES",
                        securities: [security],
                        target: 0,
                      } as BloombergTerminalFunction)
                    : undefined;
                },
              ],
              [
                fdc3.ContextTypes.Instrument,
                (context) => {
                  const security = getSecurityFromInstrumentContext(context);
                  return security
                    ? ({
                        group: "Group-A",
                        security,
                      } as BloombergGroupUpdate)
                    : undefined;
                },
              ],
            ],
          ],
        ],
      },
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);

Observe context changes

You can specify a function to run whenever context changes, by using the onContextChanged property of the BloombergConnectionConfig object.
Doing so allows you to observe what contexts are being processed by the connector.

    import { BloombergConnectionConfig, connect } from "@openfin/bloomberg";

    const config: BloombergConnectionConfig = {
      onContextChanged: (context) => console.log(context)
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);

Handle errors

You can specify an error handler via the onError property of the BloombergConnectionConfig object.
Doing so allows you to observe any issues the connector encounters when interfacing with the Bloomberg Terminal or processing context or intents.

    import { BloombergConnectionConfig, connect } from "@openfin/bloomberg";

    const config: BloombergConnectionConfig = {
      onError: (error) => console.log(error)
    };
    const bbgConnection = await connect("BLOOMBERG_API_KEY", config);