Examples and Ideas

A starting point to get you familiar with the options and power of the VividChart API

Warning: The following information is designed to cover the environment within our chart script. The Filter and Chart Object are not guaranteed to be present in other environments, however, the other variables are.

The Filter

The filter is an object with 2 key/pairs representing the active filter being used. filter.title contains the title that the filter was named when it was created. A possible use for this is to change chart options based on the filter.

Warning: filter.title is not available with dynamic filters and instead always contains an empty string.

Example: Sometimes you could use some dynamism in your filters. A common use case could be needing only the Top X of a given field or having more targeted needs based on filter. In this example we will be showing you how you can create a filter called 'Top 3' and limit it to only the most relevant data for this filter while still leaving the full range of data for other filters.

var vividChart = new VividChart(chart);
vividChart.setType('donut');
// if our filter title is 'Top 3' set our record limit to 3
if (filter.title === 'Top 3') {
    vividChart.option('record_limit', 3);
}
chartData = vividChart.getData();

Sucess! We've limited the chart to 3 data points for only this filter.

The filter also contains the conditions for the query being applied to the chart in filter.conditions. You can also use this in any custom scripts available.

Tips: The conditions can be split up for easier use. Dynamic filters do have conditions variables and if you are having trouble imagining them you can use gs.info to better visualize the data.

Example: Imagine you have a pie that groups by category. But you also filter by category. You don't want your pie to have only one slice. Wouldn't it be nice if you can change the grouping IF you filter by category?

A chart not being fully utilized

var vividChart = new VividChart(chart);
vividChart.setType('pie');
// get a string containing the left part of the conditions. This is assuming category is the first condition
var filterGroup = filter.conditions.split('=')[0];
// if that is category, set the chart to group by priority instead
if (filterGroup === 'category') {
    vividChart.option('group_by', 'priority');
}
chartData = vividChart.getData();

Now we are getting useful data no matter which filter we use!

The Chart Object

The chart object is a JavaScript object containing all the choices and selections entered during chart creation. If you select a certain condition or table of group by it's in there using the same format our options method uses.

Example: Imagine you want fixed conditions on a chart. Things you don't want your chart builder to worry about selecting in the condition builder. "All Active Tickets This Year". The user may want more conditions, but needs their "pool of available records" to be smaller than just "all".

// the encoded query that is the default condition to be applied to all conditions. In this case, all active tickets this year
var defaultConditions = "active=true^sys_created_onONLast 12 months@javascript:gs.beginningOfLast12Months()@javascript:gs.endOfLast12Months()"
var vividChart = new VividChart(chart);
vividChart.setType('half donut');
// add the conditions specified by the chart and the default conditions
var newConditions = chart.conditions + '^' + defaultConditions;
// set the charts conditions to be the new combined encoded query
vividChart.option('conditions', newConditions);
chartData = vividChart.getData();

Tips: Always use the option method to change chart conditions. Changing conditions using the chart object will not be guaranteed to take effect.

Other Variables to use

While those are the variables specifically available inside the VividCharts chart script environment, there are plenty of cool things you can do regardless of environment. Here is just a very small number of things to give a general idea of all the possibilities the VividChart API can do!

System Properties

There are many useful things you can use system properties. Now with the VividChart API you can easily combine system properties and VividCharts to make some truly stellar data visualizations.

Example: You want a chart to behave differently in a dev environment than a prod one.

// get the instance name
var instanceName = gs.getProperty('instance_name');
var vividChart = new VividChart(chart);
vividChart.setType('arc score');
// if we are in an instance named 'MyCompanyDev'
if (instanceName === 'MyCompanyDev') {
    // do something
}
chartData = vividChart.getData();

Using GS

There are tons of cool stuff you can do mixing the GS system and the VividCharts API. These are just 2 examples, but the possibilities are vast.

Example: Some users need specialized data compared to others, but still need the same general structure. To prevent having to make many different dashboards for different users, just add conditionals based off the user to dynamic filters to ensure they get only their relevant information.

// get the user
var userObject = gs.getUser();
var vividChart = new VividChart(chart);
// if user is a member of Top Priority Troubleshooters, restrict the data to only priority 1 data
if (userObject.isMemberOf('Top Priority Troubleshooters')) {
    // add only priority 1 to the list of conditions
    var newConditions = chart.conditions + '^' + "priority=1";
    vividChart.option('conditions', newConditions); 
}
vividChart.setType('score list');
chartData = vividChart.getData();

Example: A chart contains super sensitive data that you don't want to leave your corporate office. By utilizing session information we can restrict all access to the charts to a specific public IP to ensure if anyone tried to access this data from home, no results would be returned ensuring the chart information never leaves the office.

Tips: This is a perfect example of utilizing the properties of dashboards with dynamic filters. As the data is collected at the time of viewing the collection script will be run to compare IP addresses when a user attempts to use the dashboard. Be aware though that these scripts are run on collection so non-dynamic dashboards (who collect their data earlier and present cached data) might not be appropriate for this example.

// this would of course use a real ip address instead of a stand in
var companyIP = 'xxx.xxx.xxx.xxx';
// get the users ip
var session = gs.getSession();
var sessionIP = session.getClientIP();
var vividChart = new VividChart(chart);
vividChart.setType('half donut');
// if the ip addresses don't match, set the limit to 0 (no data returned)
if (sessionIP !== companyIP) {
    vividChart.option('record_limit', 0);
}
chartData = vividChart.getData();

The view from the specified ip address

Uh oh, someone tried to access this from an unapproved location

Other Methods

This is just a small sample of all the different variables and properties you can use with our Chart API to give you a small taste of what can be accomplished. In general if a scoped application can run it, you can probably use it! The world is your playground!

Parting Words

Keep in mind this is just the foundations of what's to come so keep your eyes on this space for new and exciting additions to the VividCharts API and we look forward to seeing all the cool and exiting charts you create!