Custom plug-ins

With the plug-in widget, you can customize how your data is processed and displayed.

The plug-in widget needs the next files to run:

• backend.js (JavaScript file run on the server to preprocess your data)
• frontend.js (JavaScript file run on your browser to manipulate and display your data)
• view.html (html file that contains the content of your widget)
• style.css (css file with which you can change the style of your plug-in)
• schema (parameters table to add configurable parameters)

backend.js

The backend.js return an object that contains three functions:

• init(params)
• update(trace)
• finalize(output)

init(params):

This function is run when you initialize your widget on the server

params: key and value map of plug-in parameters

update(trace):

This function is called every time that your widget is reloaded

trace: object that contains the next methods:

• getDiscarded(): byte

  It returns one if all the events of the trace (sequence) are discarded by an ETL filter

• getCaseId(): string

  It returns the trace-id value that is associated to current trace

• getCaseIdIndex(): int

  It returns a dictionary index of trace-id value that is associated to current trace

• get(index): TraceEvent

  It returns the TraceEvent object at the specified index in trace sequence

• size(): long

  It returns the number of events

TraceEvent: event object that contains the next methods

• getDiscarded(): bool

  Return if the current event was discarded by an ETL filter

• getCaseId(): string

  Returns the trace-id value that is associated to current event

• getEventClass(): string

  Returns the class of a trace event (that is, activity)

• getResource(): string

  It returns the associated resource of a trace event

• getRole(): string

  It returns the role of a trace event

• getStartTime(): long

  It returns the start time in milliseconds of current event

• getEndTime(): long

  It returns the end time in milliseconds of current event

• getStringAttributeValue(String fieldId): string

  It returns a string value that is mapped to the corresponding “fieldId” (the name of the mapped custom column) of the current event. A prefix attr-custom- needs to be inserted before the fieldId, for example, var vendor = event.getStringAttributeValue('attr-custom-Vendor');

• getDoubleAttributeValue(String fieldId): double

  It returns a double value that is mapped to the corresponding “fieldId” (the name of the mapped custom column) of the current event. A prefix attr-custom- needs to be inserted before the fieldId, for example, var amount = event.getDoubleAttributeValue('attr-custom-Amount');

finalize(output):

This function is run when your data is processed and used to send the data you want to display to the browser, for example,

...
update: function(trace) {
    this.myVariable = "plugin test";
},
finalize: function(output) {
    output['myIntVariable'] = 8;
    output['myVariable'] = this.myVariable
}
...

Helpers

console: helper object with the purpose of printing messages on console

• log(string): void

  It appends a message to the plug-in output that is evaluated after finalize callback

API: helper object that contains the next methods:

• summaryStatistics(): SummaryStatisticsLite

  It returns a mutable back end summary statistics object instance

• getStringCacheId(string eventFieldId, string fieldValue): string

  It returns a dictionary index of the specified value, or -1 if not found

SummaryStatisticsLite: object to compute and store statistics

• addValue(value): void

  It adds a value to the data

• getSummary() StatisticalSummary

  It returns a StatisticalSummaryValues instance with a report on the current statistics

• getMedian(): double

  It returns the median of the values that were added

• copy(): SummaryStatisticsLite

  It returns a copy of this SummaryStatisticsLite instance with the same internal state

• getN(): long

  It returns the number of available values

• getSecondMoment(): double

  It returns a statistic that is related to the Second Central Moment

• getMax(): double

  It returns the maximum of the values that were added

• getMin(): double

  It returns the minimum of the values that were added

• getMean(): double

  It returns the mean of the values that were added

• getVariance(): double

  It returns the (sample) variance of the available values

• getStandardDeviation(): double

  It returns the standard deviation of the values that were added

• getSum(): double

  It returns the sum of the values that were added

frontend.js

The frontend.js return an object that contains three functions:

• init(context)
• update(data, context)
• resize(size, context)

init(context):

This function is run when you initialize the widget.

The context parameter is an object that contains two properties:

1. element (jQuery object that contains DOM node of your widget)
2. scope (angular context of your widget)

You can alter the DOM element of your widget with jQuery or alter the scope with AngularJS

update(data, context):

This function is run every time that the dashboard is reloaded.

data: object that contains your data that can be bound to the scope to be displayed

context: see the previous section

For example,

update: function(data, context) {
// set your data in scope so you can use it where you need
    context.scope.data = data;
}

Eventually you can manipulate your data by using jQuery or Underscore.js, for example,

update: function(data, context) {
// set your data in scope after transforming it so you can use it where you need
    context.scope.data = _.map(data, function(element) {
      return {
          name: element.id,
          text: element.value
      };
    });
}

resize(size, context):

This function is run every time that the widget is resized.

size: object that contains width and height of your widget

context: see the previous section

External Libraries Available

• AngularJS
• jQuery
• Underscore.js
• Bootstrap
• d3.js
• dc.js
• Cross filter

view.html

The view.html file contains the content of your widget.

To display your data and change HTML elements based on the content without the need to modify the DOM with JavaScript, you can use the next angular helpers:

• Expressions
• Interpolation
• Filters

For example,

frontend.js

init: function(context) {
    context.scope.myVariable = 'Plugin widget test';
    context.scope.myIntVariable = 8;
}

view.html

<!-- the next syntax will print the content of myVariable inside the paragraph -->
<p>{{myVariable}}</p>

<!-- the next paragraph will be displayed only if myIntVariable is greater than 5 and the content will be formatted as a number -->
<p ng-if="myIntVariable > 5">{{myIntVariable | number}}</p>

For more information, see the angular documentation

Advanced Filters

In addition to angular filters, you can use custom filters that are designed specifically to reach every need

formatMeasure: param

Filter to format any kind of value.

params can be one of the next values.

• auto - automatic formatter

• date - date formatter with localization support

• datetime - datetime formatter with localization support

• duration - duration formatter

• number - number formatter with localization support

• text - text formatter

• percentage - percentage formatter

For example,

<!-- will print the date with the format based on your location i.e. 01/01/2018 -->
<p>{{myDateVariable | formatMeasure:'datetime'}}</p>

style.css

The style.cssfile contains the stylesheet for your widget, for example,

p {
    font-size: 14px;
    color: red;
}

Note: The style that is written in this file is only applied to your widget

schema

The schema table contains optional parameters that can be set in the widget options.

The parameter can be either of the next two types:

• string
• dimension