Eikon Side by Side Interoperability API


Quick Start

Introduction

Eikon's Side by Side (SxS) API enables developers to build applications along side of the Eikon desktop to create a seamless workflow to send and receive information inside the Refinitiv Eikon Desktop. The goal of this Quick Start tutorial is to prepare the Eikon Developer with an environment to execute SxS API calls to communicate with the Eikon desktop. Specifically, instructions enabling developers to launch apps within the Eikon desktop as well as creating links between these apps and an external application.

Table of Contents

Prerequisites

Prior to communication, a SxS proxy needs to be enabled to allow external applications on the local machine to connect into Eikon. This is a server side configuration that is enabled by default by Refinitiv for all users running Eikon 4.0.36 or higher. If you have an older version of Eikon please contact us through the Q&A section and we can provide information on how to update your account. In addition, in order for a SxS application to run beside an instance of Eikon, that application must be registered.

All registered SxS applications must generate an API Key and a Product ID to communicate with Eikon. We strongly recommend you keep these hidden within your application. Use the API Key Generator app in Eikon to generate the API Key and Product ID; this is found in the Search Tools section of the App Library. If you have any questions during set-up, please make a comment in the Q&A section.

Your Application

Your application can be an installed desktop app, or it can run in the browser. Side by Side supports all technologies that can send http requests and create websocket connections.

Creating a Development Environment

For demonstration purposes, the following testing utilities will be used to illustrate the different capabilities offered within the SxS API:

  • Postman -- a simple tool to execute our SxS HTTP requests. To send commands to the Eikon desktop, the Postman utility provides the ability to issue SxS HTTP requests from an external application sitting on the same desktop. Basic instructions will be outlined to execute our requests. Feel free to browse the Postman tutorials and guides at your leisure for additional features.
  • Simple WebSocket Client -- constructs Web Socket requests and handles responses The SxS API provides the ability to link and share context between Eikon apps and external applications. Eikon's Linking Service allows the ability to propagate context information across all apps that are linked. That is, changing information in one app will send the updated context to all linked apps. Context information includes properties such as the RIC and any parameters associated with that app. All context changes will be communicated through a Web Socket connection. Follow the instructions within the above links to download and install these utilities.

Note: Any client software tools that support similar functionality outlined above can be used in place so long as each can perform the basic operations outlined within this guide.

Eikon Environment Setup

To verify we can connect and communicate with Eikon, we must ensure the SxS service is running and we can successfully ping the server. To achieve this:

  1. Start Eikon and Login
  2. Launch the Postman utility

Using Postman, we will be issuing the following GET command http://127.0.0.1:<**port**>/ping. The port number is typically 9000. However, if 9000 is in use, the SxS server will incrementally attempt to use the next available port upon startup, i.e. 9001, 9002, etc. We will assume port 9000 will be used. To test our connection, perform the following steps:

  1. Ensure GET is selected
  2. Enter the command to ping the SxS server: http://127.0.0.1:9000/ping
  3. Click SEND

Within Postman, you will see the response of 9000 upon success. This will confirm the SxS Proxy is active and available within Eikon. All subsequent requests will be sent using the URL: http://127.0.0.1:9000/sxs/v1/. Refer to the Troubleshooting section if you are unable to ping the Eikon SxS server.

Establishing a SxS session-handshake

Prior to communicating with Eikon, we must first establish a session. The session is a generated token that is created within Eikon and returned to the client. The token is necessary when we want to issue commands to Eikon. To generate a session token, we are required to submit a handshake request. The following JSON object is used: { "command": "handshake", "productId": "", "apiKey": ""} Within Postman:

  1. Select the POST option
  2. Use the URL: http://127.0.0.1:9000/sxs/v1
  3. Select Body
  4. Ensure raw data is selected and the type of data should be set to (JSON (application/json)
  5. Cut and paste the above JSON object and use your registered application key (appKey) and Product ID. 
  6. Click on SEND Note: For the remainder of this Quick Start, all settings above will be the same with the exception of the JSON object specification.
    	
            
{


    "command": "handshake", 


    "productId": "<Your Product ID>", 


    "appKey": "<Your appkey>"


}

If the request is successful, SxS will display a prompt within Eikon to permission the user.

Clicking on Allow will successfully permission the user and SxS will return a session token. Otherwise, no session token will be provided within the response.

Note: The permission dialog will appear only once for the user. The dialog will not appear in subsequent attempts to establishing a session with the Eikon desktop using the same key.

Launching a Quote App

To launch a Quote app within Eikon, the following JSON object is used:

    	
            
{


    "command": "launch", 


    "sessionToken": "", 


    "appId": "Quote Object"


}

Within Postman:

  • Cut and paste the above JSON object.
  • Replace the token... with the one returned from the above handshake
  • Click on SEND

Within Eikon, a new Quote App was launched:

Launching a News App

To launch a News app within Eikon and specifying the news item context, the following JSON object is used:

    	
            
{ 


    "command": "launch", 


    "sessionToken": "", 


    "appId": "News", 


    "context": {


         "entities": [{ 


             "RIC": "TRI.TO" 


             }] 


    }


}

Within Postman:

  • Cut and paste the above JSON object.
  • Replace the token... with the one returned from the above handshake
  • Click on SEND

Within Eikon, we have launched a News App that has loaded some data based on our request. In addition, the SxS service returned an instanceId which will be used to initiate a link between the external SxS and this Eikon News app:

Linking and sharing context information

In order to link and share information between a SxS application and Eikon, we need to establish a WebSocket channel.

Using the WebSocket client tool we setup above, use the following URL and click on Open: ws://localhost:9000/sxs/v1/notifications?sessionToken=

The status will change to OPENED indicating a successful channel has been established.

Linking from a SxS App to an Eikon App

External apps can link to Eikon apps they have launched and wish to continually pass context. To link to an Eikon app, you will need the session token, command, and the target app instance ID. The instance ID was returned when the external app was launched within Eikon. For example, to link the news object we launched above:

Within Eikon, we can see a link was created and the Eikon News app is now acting as a receiver of context information from our SxS application.

Updating SxS Context

To simulate changing the RIC within our application, we can update the context to be broadcast to all connected Eikon apps:

After updating the context, the change was broadcast to all linked Eikon apps. In our case, we are only linked to the News app:

Linking from an Eikon App to a SxS App

As with normal linking between Eikon apps, linking can seamlessly work with external SxS applications. From The Quote app we launched above, select the link option to view the list of available apps within the pulldown menu:

As we hover over the SxS link, a show event will be broadcast to the SxS application. As we release the hover, a hide event will be sent.

Select the SxS link above. The selection will immediately generate a linked event to our SxS applcation.

Updating Eikon Context

Change the context from the Quote app by changing the RIC to "JPY=". Changing context will generate a context event within the SxS application:

Troubleshooting

You can use this section to help you identify and resolve basic problems you may be experiencing when using the SxS service within Eikon.

Unable to ping SxS

Unable to retrieve a session token

  • Confirm your AppKey The session token is returned only if the AppKey is valid. Ensure you have received a valid key for your registered application.
  • Allow the SxS application
  • The first time the SxS application is used within your instance of Eikon, a confirmation dialog is presented to the user to allow the use. Once allowed, the session token is returned.
  • You may have Disallowed during confirmation In the event where a dialog was presented, disallowing the app will not return a session key. Ensure you enable the application in the API Key Generator.

 

For any other issues or to verify your setup, use the Q&A section. 

References

For more information, refer to the Developer Guide.