Help & DocumentationJavaScript Charting External HostingHow to Host your own JavaScript charts

How to Host your own JavaScript charts

This article describes how to host your JavaScript charts on your own website and pull data from Metric Insights.

1. Architecture Overview

Below is a diagram that shows the sequence of events used in accessing data in Metric Insights from your website.

First, you make a "gettoken" API call (Step 1, 2) to Metric Insights from your website. In this call you supply a username and shared secret information such as "application_id" and "application_key". This call returns a short lived token (3, 4). Your website then uses that token to access data from Metric Insights in a "report_data" API call (5, 6). You typically do that directly from your JavaScript chart.

Architecture Overview

2. Configure Metric Insights for access

To enable access to your website you must first configure Metric Insights with the certain security measures such as shared secret information and a whitelist of external hosts that are cleared for access.

2.1. External Applications

From the Admin Menu, choose External Applications

2.2. Add External Application

Choose Add New External Application button.

2.3. Add External Application

Give your external application a name.

2.4. Add Cross Domain Access

To give your external website access to Metric Insights, you need to select Cross Domain Access. Click "Yes" for Cross Domain Access radio button. Once you do that, the screen will show you a Cross Domain Origin section with a button to Add New Cross Domain Origin. Click this button to add Cross Domain Origin.

2.5. Add Cross Domain Origin

Add the name of your website. This is the fully qualified domain name (FQDN) including the protocol. I.e., include the http(s):// for your website domain. Click Save when done.

2.6. Save External Application access configuration

Back on the External Application Editor, enable the external application by clicking on the Enabled radio button at the top of the screen. Then click the Save button at the bottom of the screen to save.

2.7. Get Credentials

On the External Application Editor click on the Show Credentials button to get the shared secret information that will be used by your website to securely get data from Metric Insights. Once you click on that button, the button label toggles to say Hide Credentials. The shared secret information that displays includes the Application Id and the Application Key. When done, click the same button which is now labeled Hide Credentials.

3. External website

Now you are ready to access Metric Insights data from your website. You just need to add the code to your website to fetch the data from Metric Insights.

In general, fetching the data is a two step process.

  1. First you make a "get token" API call to get a token that gives you secure access to the data.
  2. Then you make a "get data" API call using this token to get the data.

Once complete, you can then chart your data, or do anything else you want with the data.

3.1. Get Token API call

Get the secure token from Metric Insights.

To get the secure token, you make a "get token" API call to Metric Insights. You supply the "application_id" and "application_key" generated in the above steps when configuring external access for Metric Insights. You also supply an existing User via "user".  The token value is then returned.  

You typically make this call from your server and not your client (web browser). Your server will then embed the returned value of the token in the HTML/JavaScript it sends to the web browser.

Below is an example of the API call using curl at unix command line.

Request:

curl --data "application_id=ABC&application_key=XYZ&user=admin" https://yourinstance.metricinsights.com/api/get_token

Response:

<?xml version="1.0" encoding="utf-8"?>
<response><token>cjiSZ2ZYKxQfSxVXsGdk6a0JsE5e5hvydXS4RdZFyBUcjvJf1c</token><expires>2014-01-02 14:37:15</expires></response>

Below is an example of the API call using curl at unix command line.

Request:

curl --header "Accept:application/json" --data "application_id=ABC&application_key=XYZ&user=admin" https://yourinstance.metricinsights.com/api/get_token

Response:

{"token":"UClCUUKxUlkdbhE1cHLz3kyjbIZYVh9eB34A5Q21Y3FPqKGSJs","expires":"2014-01-02 14:46:08"}

3.2. Get Report Data API call

Get the report data from Metric Insights.

In your JavaScript code make a "get report data" API call to Metric Insights, using the token you obtained in the previous step. Typically, your server will embed the value of the token in the HTML/JavaScript it sends to the web browser. This is the token value the server obtained in the previous step.

The API call is done within the instantiation of the MI.Chart JavaScript object. An example is listed here.

var insightCharts = new MI.Chart({
   "url":"https://yourinstance.metricinsights.com/api/report_data?report=4", "token":"UClCUUKxUlkdbhE1cHLz3kyjbIZYVh9eB34A5Q21Y3FPqKGSJs"
});

Other variations of invoking the API call to fetch report data from Metric Insights are listed here. This includes specifying the pivot table, the Dimension value and/or the specific chart.

/api/report_data?report=6&pivot=10
/api/report_data?report=7&chart=12
/api/report_data?report=8&Dimension_value=3&chart=8

3.3. Chart your data

Once your code gets the data from Metric Insights, then within the render function of the Metric Insights JavaScript object you can chart your data.

insightChart.render = function() {
// chart your data
};

Your JavaScript code can access the Metric Insights data via several JavaScript function calls, as listed here.

var chartProperties = insightChart.getCustomVars();
var xLabels = insightChart.getXLabels();
var yLabels = insightChart.getYLabels();
var xTitle = insightChart.getXTitle();
var yTitle = insightChart.getYTitle();
var data = insightChart..getDataset();
var dataD3 = insightChart.getDatasetForD3();
var dataGoogle = insightChart.getDatasetForGoogle()
var reportName = insightChart.getReportName();
var chartName = insightChart.getChartName();

An alternate approach to rendering your JavaScript chart within the render callback method of the MI.Chart function, is to do repeated retries on isDataReady call. This is shown here.

insightChart.render = function() {};
if (!insightChart.isDataReady) {
	setTimeout(function() {
		myChartingFunction(); // Contains your charting code
	}, 500);
	return false;
}

3.4. Example of External hosting of JavaScript chart

Here is an example of your JavaScript Charting source code hosted on your external website. It makes a call to Metric Insights to get the data using the short lived token, and then charts the data.

3.5. Another Example of External hosting of JavaScript chart

Here is another example of your JavaScript Charting source code hosted on your external website. It makes a call to Metric Insights to get the data using the short lived token, and then charts the data. It uses the alternate approach of the JavaScript isDataReady call to chart.

Another Example of External hosting of JavaScript chart

0 Comments

Add your comment

E-Mail me when someone replies to this comment