App Studio - Web SDK (JET 2) : Symbology Plug-in

Introduction

In the financial world, both securities industry professionals and investors require unique identifiers to locate each trading instrument. There are multiple types of identifiers are in use. The most commonly used are:

  • Ticker symbol
  • CUSIP (Committee on Uniform Securities Identification Procedures)
  • ISIN (International Securities Identification Number)
  • SEDOL (Stock Exchange Daily Official List)
  • RIC (Reuters Instrument Code)
  • PermID (Permanent Identifier)

These types use different formats and are each managed, distributed, and used by different organizations. For example:

ISIN is an international standard maintained by the International Standardard Organization (ISO). The ISIN code is a 12-character alpha-numerical code, such as US0378331005. The first two characters are the country code (such as the "US"). The remaining ten numeric characters are the National Securites Identying Number and the single check-digit.

RIC is a ticker-like code used and maintained by Thomson Reuters to identify financial instruments, such as AAPL.O. The RIC is made up primarily of the ticker symbol, optionally followed by a period with the exchange code.

The following table represents the sample codes and summarizes the usage scope of each type.

Type Code Scope
ISIN US0378331005  It is an international standard used worldwide.
SEDOL 2046251 It is a national standard used in the United Kingdom and Ireland
CUSIP 037833100 It is an American national standard used to identify a North American financial security
Ticker AAPL It is an abbreviation used to uniquely identify a particular stock on a particular market. The formatting convention is specific to each stock exchange
RIC AAPL.OQ It is proprietary standard owned by Thomson Reuters. It is used to identify instruments used in Thomson Reuters' products, such Eikon, and Elektron
PermID  8590932301 It is an open standard from Thomson Reuters. It provides comprehensive identification across a wide variety of entity types including organizations, instruments, funds, issuers and people

To use App Studio - Web SDK to retrieve real-time, timeseries, or fundamental data, a RIC is required. Fortunately, App Studio - Web SDK provides a symbology plug-in used to programatically map instrument identifiers among various types.

Symbology Plug-in Overview

JET 2 has a symbology plug-in (jet-plugin-symbology) which provides a functionality to map security identifiers among various types, such as RIC, ISIN, CUSIP, SEDOL, ticker, and PermId. It uses a simple request and response mechanism. The request contains a list of instruments to be mapped and the response returns the mapped results.

The common use case is that users maintain the list of instruments in SEDOL in database and would like to use App Studio - Web SDK to retreive real-time data for those instruments. Therefore, users can use the symbology plug-in to map those SEDOL codes to RIC codes and then use RIC codes with quotes plug-in in App Studio - Web SDK to retieve real-time data.

This article demontrates how to use this plug-in. It also explains the structures of request and response messages.

Prerequisite

To follow steps in this article, you must have a basic understanding of HTML and JavaScript.

To download and use JET 2 API, please refer to the developer portal.

How to use symbology plug-in

This section explains steps to initialize and use this plug-in. In this article, JET 2 libraries are installed in JET2 directory.

1. Add web component library

JET 2 API uses a web component technology which defines a set of web platform APIs allowing developers to create new custom, reusable, encapsulated HTML tags in web pages and web apps.

To support this technology, JET 2 provides a polyfills javacript library (JET2\webcomponentsjs\webcomponents-lite.min.js) which is a set of library built on top of the web components specifications. It allows developers to use the web components standard across all modern web browsers.

Therefore, the first step to use JET 2 is loading the web components polyfills javascript library.

<script src="JET2/webcomponentsjs/webcomponents-lite.min.js"></script>

2. Import <jet-app> and <jet-plugin-symbology> elements

JET 2 API defines new custom and resuable HTML elements, such as <jet-app>, <jet-quote>, and <jet-plugin-symbology> by using Polymer. Polymer is an open-source project led by a team of front-end developers working within the Chrome organization at Google. It provides a lightweight library that helps you take full advantage of Web Components.

To use the symbology plug-in, two custom HTML elements: <jet-app> and <jet-plugin-symbology> are required. To use those elements, the application must import the /jet-app/jet-app.html and /jet-plugin-symbology/jet-plugin-symbology.html files into the application by using the following code.

<link rel="import" href="JET2/jet-app/jet-app.html" />
<link rel="import" href="JET2/jet-plugin-symbology/jet-plugin-symbology.html" />

<jet-app> is defined in /jet-app/jet-app.html and <jet-plugin-symbology> is defined in /jet-plugin-symbology/jet-plugin-symbology.html.

3. Add <jet-app> and <jet-plugin-symbology> elements

After importing those HTML files, the application can use those custom elements by adding the <jet-app> and <jet-plugin-symbology> elements into the body of HTML file.

<jet-app>
   <jet-plugin-symbology></jet-plugin-symbology>
</jet-app>
<pre id="output"/>

<jet-app> is used to initialize JET API and generate events for the application. <jet-plugin-symbology> is used to add symbology feature to JET API.

We also added the <pre id=”output”/>  element after the <jet-app> to display the result on the browser.

4. Add an event listener for the plugin-symbology-loaded event

Then, the application can use the <jet-app> element to add event listeners to receive JET API events, such as jet-load, jet-unload, and jet-plugin-symbology-loaded.

<script type="text/javascript">
var app = document.querySelector("jet-app");
app.addEventListener("jet-plugin-symbology-loaded", function (e) {
    console.log("jet-plugin-symbology-loaded");
});
</script>

The above code retrieves the \ element from the document and calls thr addEventListener method on that element to register a callback function for the jet-plugin-symbology-loaded event. The jet-plugin-symbology-loaded event will be fired when the JET symbology plug-in is loaded and ready to be used. After receiving the event, it prints text to the JavaScript console.

5. Submitting the request

After the symbology plug-in is loaded, the application can send the request to map symbols by calling JET.Data.Symbology.request(…) method. This method accepts a request object with the following properties.

  • symbols (Required): This is an array of strings. It contains a list of symbols for mapping
  • from (Required): This is a string. It defines the identifier type in the symbols property. It could be "RIC", "ISIN", "CUSIP", "SEDOL", or "ticker"
  • to (Optional): This is an array of strings. Each string defines the identifier types to map to. It could be "RIC", "ISIN", "CUSIP", "SEDOL", "ticker", or "OAPermID". If it is not defined, the response will contain all matched identifier’s types
  • limit (Optional): This is an integer. The default value is 100. This limits the number of matched symbols returned in the response for each identifier type
  • bestMatchOnly (Optional): This is a Boolean. The default value is false. It is used to indicate if the response contains only the best matched symbol. Otherwise, it will return all matched symbols

This method returns a promise object accepting the resolve and reject callbacks.

var app = document.querySelector("jet-app");
app.addEventListener("jet-plugin-symbology-loaded", function (e) {
    console.log("jet-plugin-symbology-loaded");
    var promise = JET.Data.Symbology.request({ "from": "RIC", "symbols": ["IBM.N", "TRI.N"] });
        });

The above code creates a request for mapping IBM.N and TRI.N from RIC to all supported identifier types.

6. Implement and register the resolve and the failure callbacks

JET.Data.Symbology.request(…) method returns a promise object. The promise object is used for asynchronous computations which a value is not necessarily known when the promise is created. It allows users to associate handlers with an asynchronous action's eventual success value or failure reason.

Promise.then(…) method is used to register the function handlers for the success and failure cases. Both function handlers have one argument. For the success case, the argument is a returned object. For the failure case, the argument is a string of the failure reason.

promise.then(function (value) {
                console.log(value);
                document.getElementById("output").innerText = JSON.stringify(value, null, 2);
               }, function (reason) {
                console.log("Failure: "+reason);
                document.getElementById("output").innerText = "Failure: " + reason;
           });

7. The success callback

For simplicity, the success callback will print the response to the JavaScript console, convert the response to JSON string and then show the string in the <pre id="output"/> element.

function (value) {
                console.log(value);
                document.getElementById("output").innerText = JSON.stringify(value, null, 2);
               }

If the request is successful, the response will contain an array of mappedSymbols. The size of mappedSymbols is equal the number of items in the symbols property in the request.

Each mappedSymbols object contains the mapped instruments according to the instrument types specified in the request message. In this example, because the 'to' and 'bestMatchOnly' parameters aren’t defined in the request message, the response will contain mapped instruments for all supported instrument types including the best match for each instrument type.

The following is the output in JSON format.

{
  "mappedSymbols": [
    {
      "CUSIPs": [
        "459200101"
      ],
      "ISINs": [
        "US4592001014"
      ],
      "OAPermIDs": [
        "4295904307"
      ],
      "RICs": [
        "IBM.N"
      ],
      "SEDOLs": [
        "2005973"
      ],
      "bestMatch": {
        "CUSIP": "459200101",
        "ISIN": "US4592001014",
        "OAPermID": "4295904307",
        "RIC": "IBM.N",
        "SEDOL": "2005973",
        "ticker": "IBM"
      },
      "symbol": "IBM.N",
      "tickers": [
        "IBM"
      ]
    },
    {
      "CUSIPs": [
        "884903105"
      ],
      "ISINs": [
        "CA8849031056"
      ],
      "OAPermIDs": [
        "4295861160"
      ],
      "RICs": [
        "TRI.N"
      ],
      "SEDOLs": [
        "2126067"
      ],
      "bestMatch": {
        "CUSIP": "884903105",
        "ISIN": "CA8849031056",
        "OAPermID": "4295861160",
        "RIC": "TRI.N",
        "SEDOL": "2126067",
        "ticker": "TRI"
      },
      "symbol": "TRI.N",
      "tickers": [
        "TRI"
      ]
    }
  ]
}

The identifier's types ("CUSIPs","ISINs","SEDOLs", "tickers", "RICs", "OAPermIDs", ) in the response are array because, for some cases, it could be one to many mappings.

For example, an ISIN, such as CA8849031056, can be mapped to multiple RIC, SEDOL, and ticker codes. The reason is that ISIN represents a financial instrument whereas other codes, such as RIC, represent a financial instrument on a specific market or currency. For instance, CA8849031056 represents ISIN code for Thomson Reuters stock which can be mapped to several RIC codes, such as TRI.TO and TRI.N.

TRI.TO represents Thomson Reuters Stock traded in Toronto Stock Exchange while TRI.N represents Thomson Reuters Stock traded in New York Stock Exchange.

{
  "mappedSymbols": [
    {
      "CUSIPs": [
        "884903105"
      ],
      "ISINs": [
        "CA8849031056"
      ],
      "OAPermIDs": [
        "4295861160"
      ],
      "RICs": [
        "TRI.TO",
        "TRI",
        "TRI.N",
        "TRI.CCP",
        "TRI.TH"
      ],
      "SEDOLs": [
        "2889371",
        "2126067",
        "5964208",
        "BJ055S0"
      ],
      "bestMatch": {
        "CUSIP": "884903105",
        "ISIN": "CA8849031056",
        "OAPermID": "4295861160",
        "RIC": "TRI.TO",
        "SEDOL": "2889371",
        "primaryRIC": "TRI.TO",
        "ticker": "TRI"
      },
      "primaryRICs": [
        "TRI.TO"
      ],
      "symbol": "CA8849031056",
      "tickers": [
        "TRI",
        "TOC"
      ]
    }
  ]
}

On the other hand, if the instruments are invalid, the response will contain the error messages, as shown below.

{
  "mappedSymbols": [
    {
      "bestMatch": {
        "error": "No best match available"
      },
      "error": "Unknown symbol",
      "symbol": "WRONG1.N"
    },
    {
      "bestMatch": {
        "error": "No best match available"
      },
      "error": "Unknown symbol",
      "symbol": "WRONG2.N"
    }
  ]
}

8. The failure callback

For simplicity, the failure callback also prints the response to the JavaScript console and shows it in the <pre id="output"/> element.

function (reason) {
                console.log("Failure: "+reason);
                document.getElementById("output").innerText = "Failure: " + reason;
           }

If the request is failed, the failure callback will be executed. The parameter passed to this callback is the reason of failure.

For example, if the invalid identifier type is defined in the request message, the request can't be made and the failure callback will be called.

var promise = JET.Data.Symbology.request({ "from": "rics", "symbols": ["IBM.N", "TRI.N"] });

"rics" is an invalid identifier type so the failure callback fuction will be called with the following text.

Failure: Unable to get symbology data from container.

Summary

JET 2 provides a jet-plugin-symbology plug-in for mapping security identifiers among various standards, such as RIC, ISIN, CUSIP, SEDOL, ticker, and OAPermId. It uses the web component technology which is reusable, maintainable, and platform independent.

The application can easily use this plug-in by importing and adding <jet-app> and <jet-plugin-symbology> elements into the HTML page. The application can be notified when the plug-in is ready to be used by adding an event listener to receive the jet-plugin-symbology-loaded event. Then, the JET.Data.Symbology.request(…) method can be called to send the request. This method returns the promise object so the application can use this promise object to register the function handlers for the success and rejection cases.

Example Code

The following shows the full example code.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
    <script src="JET2/webcomponentsjs/webcomponents-lite.min.js"></script>
    <link rel="import" href="JET2/jet-app/jet-app.html" />
    <link rel="import" href="JET2/jet-plugin-symbology/jet-plugin-symbology.html" />
</head>
<body>
    <jet-app>
        <jet-plugin-symbology></jet-plugin-symbology>
    </jet-app>
    <pre id="output"/>
    <script type="text/javascript">
        var app = document.querySelector("jet-app");
        app.addEventListener("jet-plugin-symbology-loaded", function (e) {
            console.log("jet-plugin-symbology-loaded");
            var promise = JET.Data.Symbology.request({ "from": "RIC", "symbols": ["IBM.N", "TRI.N"] });
            promise.then(function (value) {
                console.log(value);
                document.getElementById("output").innerText = JSON.stringify(value, null, 2); 
               }, function (reason) {
                console.log("Failure: "+reason);
                document.getElementById("output").innerText = "Failure: " + reason;
           });
        });
    </script>
</body>
</html>

References

  1. Web Componens
  2. Web Components Polyfills
  3. Polymer Project
  4. Promise Object
  5. App Studio - Web SDK Quick Start
  6. Wiki: International Securities Identification Number
  7. Wiki: Reuters Instrument Code
  8. PermID