Calling the JavaScript API directly from your own script

This section explains the advanced information related to loading reports, dashboards, report filters, and dashboard filters.

Example of calling the JavaScript API

You can call the API directly from your own script for following reasons:

• To have more control over the loading of content
• Call reports or dashboards on demand
• Set display options dynamically (based on user input), .

The JavaScript API must be included before any API calls can be made:

<script src="http://localhost/JsAPI" type="text/javascript"></script>

With the version parameter, you can request a specific version of the API:

<script src="http://localhost/JsAPI?version=2.1" type="text/javascript"></script>

If the browser cannot load the API, any calls to load reports or dashboards will fail. To detect whether the API has loaded successfully, check whether the window.yellowfin variable is available:

<script src="http://localhost/JsAPI" type="text/javascript"></script>
<script type="text/javascript">
if (!window.yellowfin) {
   alert('Error loading API');
}
</script>

Parameters for displaying server information and the API version

After loading the API, the following Remedy Smart Reporting server information is made available:

Example of displaying the API version

This example displays the API version:

<script src="http://localhost/JsAPI" type="text/javascript"></script>
<script type="text/javascript">
if (window.yellowfin) {
   alert('Smart Reporting API loaded. Version: ' + yellowfin.apiVersion);
}
</script>

Parameters for loading a report

To load a report, call the yellowfin.loadReport function:

yellowfin.loadReport(options);

Parameters are passed to the function as a JavaScript object. These parameters include a report identifier for the report you are loading, the element ID of the HTML element in which to load the report (or the element itself), and other options that alter the way the report is displayed. The available parameters are:

Examples of loading a report

The following example loads a report into an element that its universal ID specifies, and sets initial display options:

var options = {};
options.reportUUID = 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63';
options.elementId = 'myReport';
options.showFilters = 'false';
options.showSeries = 'false';
options.display = 'chart';
options.fitTableWidth = 'false';
yellowfin.loadReport(options);

The following example loads a report with an anonymous options object:

yellowfin.loadReport({
   reportUUID: 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63',
   elementId: 'myReport',
   showFilters: 'false',
   showSeries: 'false',
   display: 'chart',
   fitTableWidth: 'false'
});

The following example passes the element directly instead of passing its ID:

yellowfin.loadReport({
   reportUUID: 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63',
   element: document.getElementById('myReport')
});

Parameters for loading report filters

To load filters that a report uses, call the yellowfin.reports.loadReportFilters function. To use this function, load the reports sub-API into your page along with the main API:

<script src="http://localhost/JsAPI" type="text/javascript"></script>
<script src="http://localhost/JsAPI?api=reports" type="text/javascript"></script>

Then, call the loadReportFilters function:

yellowfin.reports.loadReportFilters(reportId, callback, arg);

The first argument is the unique identifier for the report, which can be a reportUUID or a reportId. (Use the reportUUID where possible.) The second argument is a callback function that the API calls after the filters for the report are loaded. The first argument to the callback function is the list of filters in the report. The second argument to the callback function is the third argument supplied to the loadReportFilters function (if specified).

The filters object returned as the first argument to the callback function is an array containing any filters used in the report. Each element in the array is an object containing information about that filter. These filter objects contain these parameters:

Examples of loading report filters

The following example loads the report filters and displays them to the user:

function filterCallback(filters) {
 
   for (var i = 0; i < filters.length; i++) {
      alert('Filter ' + filters[i].description + ' (' +
         filters[i].filterUUID + '), display style: ' +
         filters[i].display);
   }
 
}
 
yellowfin.reports.loadReportFilters(
   'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63', filterCallback);

The following example loads the available filters, and then passes them back to the loadReport function to set up initial filter values for the report when it is loaded into the page:

function filterCallback(filters) {
 
   var filterValues = {};
 
   for (var i = 0; i < filters.length; i++) {
 
      if (filters[i].description == 'Country') {
 
         filterValues[filters[i].filterUUID] = 'Australia';
 
      } else if (filters[i].description == 'Start Date') {
 
         filterValues[filters[i].filterUUID] = '2011-01-01';
 
      } else if (filters[i].description == 'Invoiced Amount') {
 
         filterValues[filters[i].filterUUID] = 6400;
 
      }
 
   }
 
   // set up other options to load the report
   var options = {};
   options.reportUUID = 'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63';
   options.elementId = 'myReport';
   // add the filter values
   options.filters = filterValues;
 
   // load the report
   yellowfin.loadReport(options);
 
}
 
yellowfin.reports.loadReportFilters(
   'e5e5aaf3-c3b8-4f9b-8280-e21e4d848e63', filterCallback);

As shown in the previous example, specify simple values for filter values passed to the loadReport function. If the filter is a list style, you can set multiple values by using an array:

filterValues[filterUUID] = ['Australia', 'China', 'Italy'];

If the filter is a between style, set the start and end values by using an array:

filterValues[filterUUID] = [500, 600];

Parameters for loading a dashboard

To load a dashboard, call the yellowfin.loadDash function:

yellowfin.loadDash(options);

Parameters are passed to the function as a JavaScript object. These parameters include:

• An identifier for the dashboard you are loading
• The element ID of the HTML element in which to load the dashboard (or the element itself)
• Other parameters that alter the way the dashboard is displayed

The available parameters are:

clientOrg

Examples of loading dashboards

The following example loads a dashboard into an element specified by its ID and sets initial display options.

var options = {};
options.dashUUID = '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9';
options.elementId = 'myDash';
options.showFilters = 'false';
options.showExport = 'false';
yellowfin.loadDash(options);

The following example loads a dashboard by using an anonymous options object:

yellowfin.loadDash({
   dashUUID: '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9',
   elementId: 'myDash',
   showFilters: 'false',
   showExport: 'false'
});

The following example passes the element directly, rather than just its ID:

yellowfin.loadDash({
   dashUUID: '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9',
   element: document.getElementById('myDash')
});

Parameters for loading dashboard filters

To load filters that a dashboard uses, call the yellowfin.dash.loadDashFilters function. To use this function, load the dashboard sub-API into your page along with the main API:

<script src="http://localhost/JsAPI" type="text/javascript"></script>
<script src="http://localhost/JsAPI?api=dash" type="text/javascript"></script>

Then, call the loadDashFilters function:

yellowfin.dash.loadDashFilters(dashUUID, callback, arg);

The first argument is the unique identifier for the dashboard. The second is a callback function that the API calls after the filters for the dashboard are loaded. The first argument to the callback function is the list of filters in the dashboard. The second argument to the callback function is the third argument supplied to the loadReportFilters function (if specified).

The filters object that is returned as the first argument to the callback function is an array containing any analytical filters used in the dashboard, as well as filter group separators. Each element in the array is an object containing information about that filter or filter group. These objects contain the parameters:

Examples of loading dashboard filters

The following example loads the dashboard filters and displays them to the user:

function filterCallback(filters) {
 
   for (var i = 0; i < filters.length; i++) {
      alert('Filter ' + filters[i].description + ' (' +
         filters[i].key + '), display style: ' +
         filters[i].display);
   }
 
}
 
yellowfin.reports.loadReportFilters(1234, filterCallback);

Use the following function to load the available filters, and then pass them back to the loadDash function to set up initial filter values for the dashboard when it is loaded into the page:

function filterCallback(filters) {
 
   var filterValues = {};
 
   for (var i = 0; i < filters.length; i++) {
 
      if (filters[i].description == 'Country') {
 
         filterValues[filters[i].key] = 'Australia';
 
      } else if (filters[i].description == 'Start Date') {
 
         filterValues[filters[i].key] = '2011-01-01';
 
      } else if (filters[i].description == 'Invoiced Amount') {
 
         filterValues[filters[i].key] = 6400;
 
      }
 
   }
 
   // set up other options to load the dashboard
   var options = {};
   options.dashUUID = '3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9';
   options.elementId = 'myDash';
   // add the filter values
   options.filters = filterValues;
 
   // load the dashboard
   yellowfin.loadDash(options);
 
}
 
yellowfin.dash.loadDashFilters('3b0b6c9a-9dfb-41f0-b85a-eb17bb8aeeb9', filterCallback);

As shown in the previous example, specify simple values for filter values passed to the loadDash function. If the filter is a list style, you can set multiple values by using an array:

filterValues[key] = ['Australia', 'China', 'Italy'];

If the filter is a between style, set the start and end values by using an array:

filterValues[key] = [500, 600];

The options.filters element passed to the loadDash function should contain values keyed by the keys returned from the loadDashFilters function.