Using the Bloomberg Integration API

This article describes several ways that you might want to use the Bloomberg Integration API.

Create a connection to Bloomberg

A connection enables you to continuously send and receive securities to and from Bloomberg Terminal panels and Launchpad groups.

Check that the Terminal is running and logged in

Before creating a connection, call isBloombergTerminalReady() to verify that the Bloomberg Terminal is running and a user is logged in.

import { isBloombergTerminalReady } from '@openfin/bloomberg';

// Proceed only if the Terminal is running and logged in
const terminalReady = await isBloombergTerminalReady();
if (!terminalReady) {
  return;
}

Create connections

To create a connection, call the create function with the following parameters:

  • source: The name of a Launchpad group that triggers the onChange callback function when its security is changed from within Bloomberg.
  • target: The name of a Launchpad group or panel number (out of the four Terminal panels) whose security is updated by the onChange callback function.
  • onChange: A callback function that is called when the source is changed.
  • onError (optional): A callback function that is called when an error occurs related to the connection.
    To specify all Launchpad groups, use '*' as the value instead of a group name in the source or target parameter.

📘

Note

A terminal panel cannot be used as a source, because it does not trigger an event when its security is changed.

With a panel as a target, the current function is set to DES when it receives a security update.

You can create multiple connections with different combinations of source and target.

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

// Send updates to Terminal panel 1 and ignore group updates
const conn1 = await connect(null, 1, console.log, console.error);

// Send updates to Terminal panel 2 and receive updates from Launchpad group 'A'
const conn2 = await connect('Group-A', 2, console.log, console.error);

// Send updates to Launchpad group 'A' and receive updates from all groups
const conn3 = await connect('*', 'Group-A', console.log, console.error);

// Send updates to all Launchpad groups and receive updates from a custom-named group
const conn4 = await connect('My Group', '*', console.log, console.error);

The connect() function returns a promise that is resolved with a connection object.

Update a security

To update the security of the target, call the setSecurity() function, with a full Bloomberg security string.

// Update the displayed security in Terminal panel 1 to 'TSLA US Equity'
await conn1.setSecurity('TSLA US Equity');

// Update the displayed security in Terminal panel 2 to 'GBP Curncy' using its FIGI
await conn2.setSecurity('BBG0013HFH84 Curncy');

// Providing an incomplete security string throws an error
await conn3.setSecurity('25468PBW5');

When the user changes the security of a source from within the Bloomberg Terminal, the onChange callback is called with the new Bloomberg security string.

// Log console message whenever Launchpad group 'A' security changes
const conn5 = await connect('Group-A', null, (security) => console.log(`New security: ${security}`));

// Group A security is updated to 'TSLA US Equity'; console message logged:
// New security: TSLA US Equity

Close and clean up

When finished with a connection, call its close() method to clean up resources.

await conn1.close();

Handle connection errors

When an error occurs related to a connection, the onError callback function is called, if one was defined when the connection was created. It receives an argument that is an instance of the BloombergApiError class, or of a subclass if the error is relevant to a specific case.

For example, when a connection is created when a Terminal not running or a user is not logged in, a TerminalConnectionError is thrown. As another example, when the app calling the API has not been properly authorized with Bloomberg, an AppNotAuthorizedError is thrown.

In addition to the standard JavaScript error properties, Bloomberg API error objects have user-friendly title and description properties, which you can use to inform the user about the error.

The following example shows how to create a notification in the OpenFin Notification Center.

import { BloombergApiError, connect } from '@openfin/bloomberg';
import { create, NotificationIndicatorType } from 'openfin-notifications';

const handleError = async (error) => {
  if (error! instanceof BloombergApiError) {
    await create({
      title: error.title,
      body: error.description,
      category: 'Failure',
      indicator: {
        type: NotificationIndicatorType.FAILURE,
      },
    });
  }
};

let connection;
try {
  // If Bloomberg Terminal is not running this throws a TerminalConnectionError
  // Error is handled in the catch block and a notification is displayed
  connection = await connect(null, 1, console.log, handleError);
} catch (err) {
  handleError(err);
  return;
}

// Calling setSecurity with an invalid security string results in a 
// BloombergSecurityError being thrown; this is caught by handleError and a notification is displayed
await connection.setSecurity('25468PBW5');

Access the Terminal instance

The OpenFin Bloomberg Integration builds on top of Bloomberg's Terminal Connect API by adding the ability to create connections using OpenFin. You can import the terminal instance to access Terminal Connect API functionality directly. This is useful when you want to update the current function in a Terminal panel, or retrieve the list of Launchpad groups.

import { terminal } from '@openfin/bloomberg/terminal';

// Update Terminal panel 1 to DIS 7 sell ticket 2mm @ 102
await terminal.runFunction('STT', 1, '25468PBW5 Corp', null, '2000 102');
// Output the names of all Launchpad groups to the console
const groups = await terminal.getAllGroups();
groups.forEach((group) => console.log(group.name));

Function examples

The functions demonstrated in the following code example are useful when working with the Bloomberg Integration:

import {
  getInstrumentCodeFromSecurity,
  getSecurityStringFromParts,
  isCusip,
  isEquity,
  isFigi,
  isIsin,
} from '@openfin/bloomberg';

// Returns '25468PBW5'
getInstrumentCodeFromSecurity('25468PBW5 Corp');

// Returns 'TSLA US Equity'
getSecurityStringFromParts('TSLA', 'US');

// Returns 'GBPUSD Curncy'
getSecurityStringFromParts('GBPUSD', null, 'Curncy');

// Returns true
isCusip('25468PBW5');

// Returns false
isCusip('BBG00005J747');

// Returns true
isEquity('TSLA US Equity');

// Returns false
isEquity('GBPUSD Curncy');

// Returns true
isFigi('BBG00005J747');

// Returns false
isFigi('US25468PBW59');

// Returns true
isIsin('US25468PBW59');

// Returns false
isIsin('BBG00005J747');

Did this page help you?