Bloomberg integration v2
Integrate your OpenFin solution with the Bloomberg Terminal.
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
andtarget
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
Context type | Terminal function (mnemonic) |
---|---|
fdc3.instrument | DES |
fdc3.contact | BIO |
fdc3.organization | SEAR |
Intents
Intent name | Context type | Terminal function (mnemonic) |
---|---|---|
StartChat | fdc3.contact | IB |
ViewAnalysis | fdc3.instrument | Equities: FA ; Fixed income: YAS ; Everything else: ANR |
ViewChart | fdc3.instrument | GIP |
ViewChar t | fdc3.chart | (see View charts above) |
ViewChat | fdc3.contact | IB |
ViewContact | fdc3.contact | BIO |
ViewInstrument | fdc3.instrument | DES |
ViewNews | fdc3.instrument | CN |
ViewProfile | fdc3.contact | BIO |
ViewProfile | fdc3.organization | SEAR |
ViewQuote | fdc3.instrument | ALLQ |
ViewResearch | fdc3.instrument | BRC |
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 theexecuteApiRequest
function. -
Providing "... on Error" with
errorCategory
anderrorMessage
in the GraphQL mutation ensures that the connector API throws aTerminalConnectRequestError
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);
Updated 6 months ago