jKQL Scripts (XRay Admin Settings)

The functionality described in this article is available in XRay versions 1.4 and greater. 

jKQL Scripts allow custom processing functionality to be executed.  For those familiar with SQL systems, these are analogous to stored procedures/functions.  With them, data can be loaded from jKQL data store, processed, and written back out to data store and/or returned for display in the user interface.

jKQL Script definitions are kept in jKQL data store.  The definition contains either the complete text for the script, or a URI from which to retrieve the text.  jKQL scripts can be implemented directly using jKQL, or through the user interface. Some examples of the direct implementation of jKQL scripts are shown below. These are defined using the Upsert statement:

Upsert Script Name = 'TestScript', Text = 'var rs = executeJKQL(\'Get number of events for latest year group by eventname\'); setReturnResult(rs);'

Upsert Script Name = 'TestUrl', Url = 'file:/home/me/example.js', Properties = ('FilterField'='STRING', 'FilterValue'='STRING', 'GroupField'='STRING'), Options = ('MaxRawRows'=30000)

To add a script through the user interface, start on the jKQL Scripts tab of Admin Settings.

1. Go to Main Menu > Admin Settings.
2. Select the jKQL Scripts tab.
3. Click Create.
4. In the Script editor, enter the script that you want to save. It will take the form of JavaScript code that interfaces with jKQL. For example:

var startTime = getScriptParam('starttime');
var endTime = getScriptParam('endtime');
var interval = getScriptParam('interval');
var query = "get number of activities fields avg(elapsedtime) as elapsedtime where starttime > '"
    + startTime
    + "'  and starttime <= '"
    + endTime
    + "' group by starttime bucketed by " + interval;
var rsActivities = executeJKQL(query);
for (var arow = 1; arow <= rsActivities.getRowCount(); arow++) {
    var dataset = createDataset();
    dataset.setField(FieldType.DATASET_NAME, 'TestDataset1');
    dataset.setMapFieldKey(FieldType.PROPERTIES, "time", rsActivities.getValue(arow, 1).getBegin()); // starttime
    dataset.setMapFieldKey(FieldType.PROPERTIES, rsActivities.getColumnName(2), rsActivities.getInteger(arow, 2)); // number of rows
    dataset.setMapFieldKey(FieldType.PROPERTIES, rsActivities.getColumnName(3), rsActivities.getTimeInterval(arow, 3)); // average elapsedtime
    upsert(dataset);
}
executeJKQL("gt datasets fields all")

You can even write an entire JavaScript program (that interacts with JKQL) and save it as a script. To learn how to call jKQL from within the JavaScript, refer to the Script section of the jKQL User’s Guide in the XRay section of the Resource Center.

5. In the panel on the right side, enter the name of the script in the jKQL Script Name field, and select the Repository it will use.
6. Use the Time Period parameter to define the timeframe for which you want the query and the script to be applied.
7. Click Save to save the script for future reuse.
8. Use the jKQL Script Parameters area to enter any runtime values for the parameters that you are asking users to enter via the ‘getScriptParam’ function (such as 'starttime'). These parameters are displayed immediately after a script is saved, and whenever a script is run.
9. Click Run. Results are displayed in a Results Viewlet in the Console panel.

Before data can be made available to queries, it must be committed to index files in Solr. Therefore you may experience a delay before results become available. After you run a script, try waiting several minutes, then use a temporary viewlet to query your results (click the Create temporary viewlet button  next to the Console label).

10. Click Close to return to the jKQL Scripts list.

jKQL Create Window

jKQL Scripts List