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 Refinitiv 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 | 37833100 | 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 a proprietary standard owned by Refinitiv. It is used to identify instruments used in Refinitiv's products, such as Eikon, and Elektron |
| PermID | 8590932301 | It is an open standard from Refinitiv. 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 programmatically 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 a database and would like to use App Studio - Web SDK to retrieve 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 retrieve real-time data.
This article demonstrates how to use this plug-in. It also explains the structures of request and response messages.
Prerequisite
To follow the 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.
--symbology-plug-in/request.png)
- 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.
--symbology-plug-in/response1.png)
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.
--symbology-plug-in/response2.png)
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>
