Core APIs in Siren Investigate

The following classes are available:

SirenAPIBasicEmitter

The API for interacting with Siren Investigate, which is exposed at window.sirenapi.

DashboardBasicEmitter

The class that represents a dashboard.

VisualizationBasicEmitter

The class that represents a visualization.

Instances of this class will also expose methods registered by visualizations. These methods vary per visualization type. See Visualization APIs in Siren section.

SearchBasicEmitter

The class that represents a search.

BasicEmitter

A basic event emitter class that is used by sirenAPI. It calls handlers synchronously and implements a chainable API.

Notify

A class that allows scripts to trigger notifications at the top of the screen

SirenAPI ⇐ BasicEmitter

The API for interacting with Siren Investigate, which is exposed at window.sirenapi.

Kind: global class
Extends: BasicEmitter
Version: 1.0.0
Properties

Name Type Description

version

The version of the API.

Dashboard

Dashboard

The prototype of the Dashboard class for convenience.

Visualization

Visualization

The prototype of the Visualization class for convenience.

Search

Search

The prototype of the Search class for convenience.

notify

Notify

The utility class that allows scripts to trigger notifications at the top of the screen.

es

The Elasticsearch client.


sirenAPI.EVENTS

Return a map of events that can be registered on sirenspi object

Kind: instance property of SirenAPI
Properties

Name Type Description

APP_STATE_CHANGED

number

event fired when app state changes, (filter or query was added or removed)

CUSTOM

number

reserved for passing cutom events, visualization can emit any custom event this way

Example

Event returned in handler on APP_STATE_CHANGED has no extra parameters.
Event returned in handler on CUSTOM has custom parameters, depends on what was passed when it was emmited.

sirenAPI.destroy()Promise

Clean all resources allocated by sirenapi

Kind: instance method of SirenAPI
Returns: Promise - - Resolved with undefined


sirenAPI.generateShortUrl(shareAsEmbed, displayNavBar)Promise

Generates a short URL for the current state.

Kind: instance method of SirenAPI
Returns: Promise - - Resolved with the short URL.

Parameter Type Description

shareAsEmbed

Boolean

Set to true to enable embedding in the URL.

displayNavBar

Boolean

Set to true to display the Investigate navigation bar when embedding is enabled in the URL.


sirenAPI.setJWTToken(token)Promise

Validates a JWT token and stores it in the Investigate session cookie.

Kind: instance method of SirenAPI
Returns: Promise - - Resolved with true if token authentication was successful, an Error otherwise.

Parameter Description

token

A valid JWT token.


sirenAPI.invokeWebService(groupName, serviceName, params, [options])Promise

Calls a Web service.

Kind: instance method of SirenAPI
Returns: Promise - Resolved with data that is returned by a Web service. Depending on the passed options, it can return the actual results or the invocation id. Rejects when a user does not have the permissions to invoke a service.

Parameter Type Default Description

groupName

String

The group name of the webservice.

serviceName

String

The name of the webservice.

params

JSON

JSON data that will be sent to a Web service.

[options]

JSON

{storeData: false, returnData: true }

Options to indicate how the call should be invoked.


sirenAPI.getTimeFilter(time, indexPatternId)Promise

Utility method to convert a time into a time range filter.

Kind: instance method of SirenAPI
Returns: Promise - Resolved with time range filter on a time field from a given index pattern.

Parameter Type Description

time

object

object with three properties from, to and mode

indexPatternId

String

ID of a indexpattern


sirenAPI.on(eventName, instanceId, handler)BasicEmitter

Add an event handler

Kind: instance method of SirenAPI
Overrides: on
Returns: BasicEmitter - - this, for chaining

Parameter Type Default Description

eventName

string

Name of the event

instanceId

string

"global"

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

handler

function

Handler for the event


sirenAPI.off(name, [handler], instanceId)BasicEmitter

Remove an event handler.

Kind: instance method of SirenAPI
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

name

string

[handler]

function

An optional handler to remove. If no handler is passed, then all are removed.

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


sirenAPI.removeAllListeners(instanceId)BasicEmitter

If instanceId is specified, remove all event handlers bound to given instanceId Otherwise remove all the listeners.

Kind: instance method of SirenAPI
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


sirenAPI.emit(eventName, instanceId)BasicEmitter

Emit an event and all arguments to all listeners for an event name.

Kind: instance method of SirenAPI
Overrides: emit
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

eventName

string

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

[arg…​]

\*

Any number of arguments that will be applied to each handler


Dashboard ⇐ BasicEmitter

The class that represents a dashboard.

Kind: global class
Extends: BasicEmitter


new Dashboard()

Create a new dashboard.


dashboard.getQueryString()string

The dashboard’s current query string.

Kind: instance method of Dashboard


dashboard.getSavedQueryString()string

The dashboard’s saved query string.

Kind: instance method of Dashboard


dashboard.setQueryString(queryString)this

Sets the dashboard’s query string.

Kind: instance method of Dashboard

Parameter Type

queryString

string


dashboard.getTitle()string

The dashboard’s title.

Kind: instance method of Dashboard


dashboard.setTitle(title)this

Sets the title of the dashboard.

Kind: instance method of Dashboard

Parameter Type

title

string


dashboard.getDescription()string

The dashboard’s description.

Kind: instance method of Dashboard


dashboard.setDescription(description)this

Sets the description of the dashboard.

Kind: instance method of Dashboard

Parameter Type

description

string


dashboard.getFilters()string | Array.<string>

The filters currently applied to the dashboard.

Kind: instance method of Dashboard


dashboard.getSavedFilters()string | Array.<string>

The filters saved with dashboard currently applied to the dashboard.

Kind: instance method of Dashboard


dashboard.setFilters(filters)this

Specify a filter or array of filters to replace in the dashboard.

Kind: instance method of Dashboard

Parameter Type

filters

string | Array.<string>


dashboard.addFilters(filters)this

Specify a filter or array of filters to add to the dashboard.

Kind: instance method of Dashboard

Parameter Type

filters

string | Array.<string>


dashboard.getTime()

Gets current dashboard time

Kind: instance method of Dashboard
Returns: time as object with three properties from, to and mode


dashboard.getSavedTime()

Gets dashboards saved time

Kind: instance method of Dashboard
Returns: time as object with three properties from, to and mode or null


dashboard.getVisualizationByTitle(title)Array.<Visualization>

Gets visualisations by title

Kind: instance method of Dashboard

Parameter Type Description

title

string

title of visualization to return


dashboard.getVisualizationById(title)Array.<Visualization>

Gets visualisations by id

Kind: instance method of Dashboard

Parameter Type Description

title

string

id of visualization to return


dashboard.getDashboardDataModelSearchByTitle(title)Promise

Gets a dashboard data model search by title This method returns an array as the same search could be associated more than one data model nodeId

Kind: instance method of Dashboard
Returns: Promise - - Resolved with {Array}

Parameter Type Description

title

String

title of the search from dashboard datamodel


dashboard.getDashboardDataModelSearchByNodeId(nodeid)Promise

Gets a search by node id

Kind: instance method of Dashboard
Returns: Promise - - Resolved with {Search}

Parameter Type Description

nodeid

String

nodeid of a search from dashboard datamodel


dashboard.getDashboardDataModelNodeIndexpattern(focusNodeId)Promise

Gets an index for particular search in the Dashboard datamodel. We assume that it is a current dashboard on view

Kind: instance method of Dashboard
Returns: Promise - - Resolved with an elasticsearch index pattern as a string

Parameter Type Description

focusNodeId

String

nodeid of a node from dashboard datamodel


dashboard.getDashboardDataModelNodeQuery(focusNodeId)Promise

Gets a query to fetch documents present on a dashboard for particular search in the Dashboard datamodel We assume that it is a current dashboard on view On Dashboard 360 there could be multiple searches in the model and there is a different query behind each search which depends on Data model settings and the position of the search in the datamodel

Kind: instance method of Dashboard
Returns: Promise - - Resolved with a query as a JSON object

Parameter Type Description

focusNodeId

String

nodeid of a node from dashboard datamodel


dashboard.applyState()Promise

Apply current dashboard state replacing the state of the application. Example: if dashboard has query or filters these will be sync back to to the application search bar and filter bar replacing the current values.

Kind: instance method of Dashboard
Returns: Promise - - Resolves with this


dashboard.on(eventName, instanceId, handler)BasicEmitter

Add an event handler

Kind: instance method of Dashboard
Overrides: on
Returns: BasicEmitter - - this, for chaining

Parameter Type Default Description

eventName

string

Name of the event

instanceId

string

"global"

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

handler

function

Handler for the event


dashboard.off(name, [handler], instanceId)BasicEmitter

Remove an event handler.

Kind: instance method of Dashboard
Overrides: off
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

name

string

[handler]

function

An optional handler to remove. If no handler is passed, then all are removed.

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


dashboard.removeAllListeners(instanceId)BasicEmitter

If instanceId is specified, remove all event handlers bound to given instanceId Otherwise remove all the listeners.

Kind: instance method of Dashboard
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


dashboard.emit(eventName, instanceId)BasicEmitter

Emit an event and all arguments to all listeners for an event name.

Kind: instance method of Dashboard
Overrides: emit
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

eventName

string

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

[arg…​]

\*

Any number of arguments that will be applied to each handler


Dashboard.EVENTS

Return a map of events that can be registered on dashboard object

Kind: static property of Dashboard
Properties

Name Type Description

DASH_AUTOREFRESHED

number

event fired when dashboard autorefresh option is enabled and dashboard was refreshed

SEARCH_COUNT_CHANGED

number

event fired when count on any search associated with the dashboard changes

Example

Event returned when dashboard emits DASH_AUTOREFRESHED has a data parameter in the following form
{
  refreshInterval: {
    value: {integer} - autorefresh time in miliseconds
    display: {string} - a human readable string describing the value
  }
}

Event returned when dashboard emits SEARCH_COUNT_CHANGED has an extra parameter in the following form
{
  node: {
    id: {string}
  },
  search: {
    id: {string}
  },
  count: {number}
}

Dashboard.fetchDashboardById(dashboardID)Promise

Fetch the saved dashboard with id dashboardID.

Kind: static method of Dashboard
Returns: Promise - - Resolved with an array of Dashboard objects

Parameter Type

dashboardID

string


Dashboard.getCurrentDashboard()Promise

Fetches a Dashboard object which represents a state of the current dashboard.

Kind: static method of Dashboard
Returns: Promise - - Resolved with Dashboard object


Dashboard.fetchAllDashboards()Promise

Fetches an array of Dashboard objects for all saved dashboards.

Kind: static method of Dashboard
Returns: Promise - - Resolved with an array of Dashboard objects


Visualization ⇐ BasicEmitter

The class that represents a visualization.

Instances of this class will also expose methods registered by visualizations. These methods vary per visualization type. See Visualization APIs in Siren section.

Kind: global class
Extends: BasicEmitter
Properties

Name Description

id

id of associated object in investigate

panelIndex

index of the panel containing the visualization on dashboard

title

title of associated object in investigate

type

type of associated object in investigate

description

description of associated object in investigate


visualization.waitUntilLoaded(timeout)

Resolves when visualization reported status ready on the dashboard

Kind: instance method of Visualization

Parameter Type Default Description

timeout

integer

5000

default 5000 ms


visualization.on(eventName, instanceId, handler)BasicEmitter

Add an event handler

Kind: instance method of Visualization
Overrides: on
Returns: BasicEmitter - - this, for chaining

Parameter Type Default Description

eventName

string

Name of the event

instanceId

string

"global"

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

handler

function

Handler for the event


visualization.off(name, [handler], instanceId)BasicEmitter

Remove an event handler.

Kind: instance method of Visualization
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

name

string

[handler]

function

An optional handler to remove. If no handler is passed, then all are removed.

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


visualization.removeAllListeners(instanceId)BasicEmitter

If instanceId is specified, remove all event handlers bound to given instanceId Otherwise remove all the listeners.

Kind: instance method of Visualization
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


visualization.emit(eventName, instanceId)BasicEmitter

Emit an event and all arguments to all listeners for an event name.

Kind: instance method of Visualization
Overrides: emit
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

eventName

string

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

[arg…​]

\*

Any number of arguments that will be applied to each handler


Visualization.get(id, panelIndex, title, type, description)Visualization

For given id-panelIndex combination finds a registered visualization instance and returns it. If not found, creates a new instance and returns it.

Kind: static method of Visualization
Returns: Visualization - - A visualization instance

Parameter Description

id

id of associated object in investigate

panelIndex

index of the panel containing the visualization on dashboard

title

title of associated object in investigate

type

type of associated object in investigate

description

description of associated object in investigate


Search ⇐ BasicEmitter

The class that represents a search.

Kind: global class
Extends: BasicEmitter
Properties

Name Type Description

id

id of associated object in investigate

title

title of associated object in investigate

nodeid

id of associated node id in Dashboard datamodel

indexPatternId

id of indexpattern associated with the search

isMain

boolean

indicated if the search is a main search in in Dashboard datamodel


search.on(eventName, instanceId, handler)BasicEmitter

Add an event handler

Kind: instance method of Search
Returns: BasicEmitter - - this, for chaining

Parameter Type Default Description

eventName

string

Name of the event

instanceId

string

"global"

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

handler

function

Handler for the event


search.off(name, [handler], instanceId)BasicEmitter

Remove an event handler.

Kind: instance method of Search
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

name

string

[handler]

function

An optional handler to remove. If no handler is passed, then all are removed.

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


search.removeAllListeners(instanceId)BasicEmitter

If instanceId is specified, remove all event handlers bound to given instanceId Otherwise remove all the listeners.

Kind: instance method of Search
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


search.emit(eventName, instanceId)BasicEmitter

Emit an event and all arguments to all listeners for an event name.

Kind: instance method of Search
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

eventName

string

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

[arg…​]

\*

Any number of arguments that will be applied to each handler


BasicEmitter

A basic event emitter class that is used by sirenAPI. It calls handlers synchronously and implements a chainable API.

Kind: global class


basicEmitter.on(eventName, instanceId, handler)BasicEmitter

Add an event handler

Kind: instance method of BasicEmitter
Returns: BasicEmitter - - this, for chaining

Parameter Type Default Description

eventName

string

Name of the event

instanceId

string

"global"

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

handler

function

Handler for the event


basicEmitter.off(name, [handler], instanceId)BasicEmitter

Remove an event handler.

Kind: instance method of BasicEmitter
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

name

string

[handler]

function

An optional handler to remove. If no handler is passed, then all are removed.

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


basicEmitter.removeAllListeners(instanceId)BasicEmitter

If instanceId is specified, remove all event handlers bound to given instanceId Otherwise remove all the listeners.

Kind: instance method of BasicEmitter
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)


basicEmitter.emit(eventName, instanceId)BasicEmitter

Emit an event and all arguments to all listeners for an event name.

Kind: instance method of BasicEmitter
Returns: BasicEmitter - - this, for chaining

Parameter Type Description

eventName

string

instanceId

string

ID of the instance (dashboard id for dashboard, visualization id - panel id for visualization)

[arg…​]

\*

Any number of arguments that will be applied to each handler


Notify

A class that allows scripts to trigger notifications at the top of the screen

Kind: global class


notify.info(error)

Kind: instance method of Notify

Parameter Type Description

error

Error | String

error to report as a blue info notification on top of the screen


notify.warning(error)

Kind: instance method of Notify

Parameter Type Description

error

Error | String

error to report as a yellow warning notification on top of the screen


notify.error(error)

Kind: instance method of Notify

Parameter Type Description

error

Error | String

error to report as a red error notification on top of the screen