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:

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

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:

Parameters for displaying server information and the API version

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

Parameter	Description
yellowfin.apiVersion	The version of the API that the server is using.
yellowfin.baseURL	The base URL used to connect to the API on the server.
yellowfin.serverInfo.releaseVersion	The Remedy Smart Reporting release version running on the server (for example, 6.1).
yellowfin.serverInfo.buildVersion	The Remedy Smart Reporting build version running on the server (for example, 20120601).
yellowfin.serverInfo.javaVersion	The Java version installed on the server.
yellowfin.serverInfo.operatingSystem	The operating system running on the server.
yellowfin.serverInfo.operatingSystemArch	The operating system architecture on the server.
yellowfin.serverInfo.operatingSystemVersion	The operating system version on the server.
yellowfin.serverInfo.schemaVersion	The Remedy Smart Reporting schema version configuration database.

Example of displaying the API version

This example displays the API version:

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:

Parameter	Description
reportUUID	The unique ID identifying the dashboard to load. The reportUUID, reportId, or wsName parameter is required.
reportId	The numeric report ID identifying the report to load. The reportUUID, reportId, or wsName parameter must be present. Note: We recommend using the reportUUID parameter.
wsName	The Web Service name identifying the report to load. The reportUUID, reportId, or wsName parameter must be present. Note: We recommend using the reportUUID parameter.
elementId	The ID of the html element in which to load the report. Either elementId or element must be present.
element	The html element in which to load the report. Either elementId or element must be present.
showTitle	Displays the title bar at the top of the report. The default is true. To omit the title bar at the top of the report, set the parameter to false. All interactive buttons included in the title bar are also omitted.
showInfo	Displays the Info button in the title bar. The default is true. To omit the Info button in the title bar, set the parameter to false.
showFilters	Displays the Filters button in the title bar. The default is true. To omit the Filters button in the title bar, set the parameter to false. Any user-prompt filters are not displayed.
showSections	Displays the Sections button in the title bar (for reports with tabbed or multi-page sections). The default is true. To omit the Sections button in the title bar, set the parameter to false.
showSeries	Displays the Series button in the title bar (for reports with the series selection parameter). The default is true. To omit the Series button in the title bar, set the parameter to false.
showPageLinks	Displays the previous page/next page button in title bar (for reports with multiple pages). The default is true. To omit the previous page/next page button in the title bar, set the parameter to false.
showExport	Displays the Export button in the title bar. The default is true. To omit the Export button in the title bar, set the parameter to false.
height	Overrides the report height. Enter a numeric value. The default value is automatically detected from the dimensions of the enclosing element.
width	Overrides the report width. Enter a numeric value. The default value is automatically detected from the dimensions of the enclosing element.
display	Sets how the report is initially displayed. To display the report initially as a table, set the parameter to table. To display the report initially as a chart, set the parameter to chart. The default is chart. Note: This parameter is ignored for reports that do not have table and chart available.
fitTableWidth	Scales the report table to the width of the enclosing element. The default is true.
canChangeDisplay	Enables users to switch between a chart and table display. The default is true. To omit the buttons that enable users to switch between a chart and table display, set the parameter to false.
filters	An object containing filter values to pass to the report.
username	(Required) The Remedy Smart Reporting user name to authenticate when loading the report. Set this parameter with the password parameter. Setting this parameter avoids the need for users to enter their login details before viewing restricted reports.
password	(Required) The password of the user in Remedy Smart Reporting. Set this parameter with the username parameter to authenticate a particular user when loading the report.
clientOrg	The name of the client org.

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:

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:

Parameter	Description
filterUUID	A unique identifier for the filter.
filterId	A numeric identifier for the filter.
nativeType	The native data type of the filter.
description	The description of the filter.
operator	The operator used with the filter.
display	The display style that the filter uses.
dependencies	Set to true if other filters in the report are dependent on this one.
list	Set to true if the filter is a list style (allows multiple values).
between	Set to true if the filter is a between style (requires a start and end value).
listValues	A list of available options. This property is used if the filter is displayed as a drop-down list.

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:

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:

Parameter	Description
dashUUID	The unique identifier for the dashboard to load. This parameter must be present.
elementId	The ID of the html element in which to load the dashboard. Either elementId or element must be present.
element	The html element in which to load the dashboard. Either elementId or element must be present.
showTitle	Display the title bar at the top of the dashboard. The default value is true. Set the value to false to omit the title bar at the top of the dashboard. All interactive buttons included in the title bar will also be omitted.
showInfo	Display the Info button in the title bar. The default value is true. Set to false to omit the Info button in the title bar.
showFilters	Display the Filters button in the title bar. The default value is true. Set to false to omit the Filters button in the title bar. Any analytical filters will not be displayed.
showExport	Display the Export button in the title bar. The default value is true. Set to false to omit the Export button in the title bar.
height	Set this parameter to a numeric value to override the dashboard height. If the reports in the dashboard require more space, a vertical scrollbar will be added. The default value is automatically set from the dimensions of the reports in the dashboard.
width	Set this parameter to a numeric value to override the dashboard width. Set this to auto to use the full width of the enclosing element. The default value is automatically set from the logged-in user’s preferences or the system configuration setting.
filters	Set this parameter to an object containing filter values to pass to the dashboard.
username	Set this parameter with the password parameter to authenticate as a particular user when loading the dashboard. Authentication avoids the need for users to enter their login details before viewing restricted dashboards.
password	Set this parameter with the username parameter to authenticate as a particular user when loading the dashboard.
clientOrg	The name of the client org.

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:

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:

Parameter	Description
key	A unique key for this filter or filter group.
type	Type of filter. If this object represents a filter group, set this property to FILTERGROUP. Other values indicate a type of analytic filter.
description	The description of the filter or filter group.
groupId	(For filter groups) A numeric identifier for the group.
state	(For filter groups) The state of the filter group. Set to OPEN if the group is currently opened.
display	(For filters) The display style that the filter uses.
dependencies	(For filters) Set to true if other filters in the dashboard are dependent on this one.
list	(For filters) Set to true if the filter is a list style (allows multiple values).
between	(For filters) Set to true if the filter is a between style (requires a start and end value).
listValues	(For filters) If the filter is displayed as a drop-down list, this parameter contains a list of available options.

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:

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'];