Core APIs in Siren Investigate

The following classes are available:

ActionRegistry

A registry to store custom actions that are registered from plug-ins for Siren Investigate.

BasicEmitter

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

Chart

Class representing a chart object

Charts

Utility class - provides static methods to create charts.

DashboardBasicEmitter

The class that represents a dashboard.

DataModelLinkBasicEmitter

The class that represents a data model link.

EidBasicEmitter

The class that represents an eid.

Notify

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

Revisions

APIs to facilitate document editing (Target Search must have editing enabled)

SearchBasicEmitter

The class that represents a search.

SearchSource

Allows scripts to query data model searches. State of the SearchSource can be modified by the property methods (chainable).

SirenAPIBasicEmitter

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

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.

Reporting

Provides methods for report generation.

DataRecord

A class that represents either an actual data record or a virtual "entity identifier". The record is associated to a list of data model entities, which interpret the data as a data model-enabled node able to connect to other nodes through relations.

Relation

A class that represents a relation connecting two data model entities. Relations can be used to retrieve new records linked to some known record.

DataModelEntity

A class representing a data model entity, such as a Search or an Entity identifier. It contains the field definitions necessary to extract, interpret and format the data stored in the records. It also allows users to extract records satisfying an input query.

Typedefs

APIDefinition : Object

The definition of an API as per the scripting interfaces.

QueryOptions : Object

Options applied when querying a data model entity for records.

Order : Object

Order specification applied when retrieving records.

DataModelEntitiesSpecs : string

Specifies how retrieved records should implicitly associate to data model entities.

VisScreenshot : Object

A screenshot obtained from a dashboard visualization.

ActionRegistry

A registry to store custom actions that are registered from plug-ins for Siren Investigate.

Kind: global class


new ActionRegistry(supportedVersions)

Creates an instance of the action registry.

Parameter Type Description

supportedVersions

Array<string>

A list of Siren API versions supported


actionRegistry.register(version, uuid, actionName, action)

Registers an action against an action name.

Kind: instance method of ActionRegistry

Parameter Type Description

version

string

Siren API version

uuid

string

a unique id, preferably a UUID, against which the actions are registered

actionName

string

name of the action

action

function

call back function mapped to the action name


actionRegistry.getActions(version, uuid)Object

Returns a object with all action names mapped to the registered actions.

Kind: instance method of ActionRegistry
Returns: Object - an object of all action names mapped to actions

Parameter Type Description

version

string

Siren API version

uuid

string

the id under which the actions are registered


actionRegistry.getActionByName(version, uuid, actionName)function

Returns a registed action based on its action name.

Kind: instance method of ActionRegistry
Returns: function - the registered action

Parameter Type Description

version

string

Siren API version

uuid

string

the id under which the actions are registered

actionName

string

name of the registered action


actionRegistry.registerInterfaceForType(version, type, InterfaceClass)

Register the interface class based on which the APIs are registered on the action registry.

Kind: instance method of ActionRegistry

Parameter Type Description

version

string

Siren API version

type

string

the name of the plug-in

InterfaceClass

any

A javascript class to describe the exposed methods


actionRegistry.getActionDefinitionsForType(version, type)Array<APIDefinition>

Get a list of API definitions as per the scripting interface of a plug-in.

Kind: instance method of ActionRegistry
Returns: Array<APIDefinition> - Array of API definitions

Parameter Type Description

version

string

Siren API version

type

string

the name of the plug-in


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


Chart

Class representing a chart object

Kind: global class


chart.render()

Render the chart

Kind: instance method of Chart


chart.getHtmlElement()

Get the htmlWrapper element of a chart. Example: The wrapped html can be then attached to the panel in Scripted Panel visualization

Kind: instance method of Chart


chart.getRenderStatus()

Get the render status of a chart

Kind: instance method of Chart


chart.destroy()

Destroy a chart and all associated dom elements

Kind: instance method of Chart


Charts

Utility class - provides static methods to create charts.

Kind: global class


Charts.createApexChart(options)Chart

Creates an Apex Chart element

Kind: static method of Charts
Returns: Chart - instance of Chart object

Parameter Type Description

options

object

ApexChart options.


Charts.getBarChartBasicOptions(options)JSON

Returns a basic configuration for a bar chart. The passed options will override the default ones.

Kind: static method of Charts
Returns: JSON - basic options for ApexChart bar chart

Parameter Type Description

options

object

Apex Chart options


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.getDashboardDataModelRootSearch()Promise

Gets the dashboard data model root Search

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


dashboard.getDashboardDataModelTree()Promise

Gets the dashboard data model root Search

Kind: instance method of Dashboard
Returns: Promise - Resolved with {Array<Search | Eid | DataModelLink>}


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.open(options)Promise

Open the browser with this dashboard with state applied.

Kind: instance method of Dashboard
Returns: Promise - Resolves once the dashboard is open.

Parameter Type Description

options

object

currently only one option is available, options.timeout - to specify how long to wait (in milliseconds) for dashboard to be loaded before rejecting


dashboard.openModal(modalConfig)Promise<void>

Renders a modal with react element as its content on the dashboard.

Kind: instance method of Dashboard

Parameter Type Description

modalConfig

object

configuration object of the modal

modalConfig.Element

object

React element rendered inside the modal

modalConfig.primaryBtnText

string

text displayed on primary button

modalConfig.onPrimaryClick

function

callback called when primary button is clicked

[modalConfig.secondaryBtnText]

string

text displayed on secondary button

[modalConfig.onSecondaryClick]

function

callback called when secondary button is clicked

[modalConfig.cancelBtnText]

string

text displayed on secondary button

[modalConfig.onCancel]

function

callback called when cancel button is clicked

[modalConfig.titleText]

string

title of the modal


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
Overrides: removeAllListeners
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


The class that represents a data model link.

Kind: global class
Extends: BasicEmitter
Properties

Name Description

id

id of associated object in investigate

inverseId

id of the inverse object in investigate

linkId

id of associated link id in Dashboard datamodel

id1

id of the starting node

id2

id of the ending node


Add an event handler

Kind: instance method of DataModelLink
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


Remove an event handler.

Kind: instance method of DataModelLink
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)


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

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

Parameter Type Description

instanceId

string

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


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

Kind: instance method of DataModelLink
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


Eid ⇐ BasicEmitter

The class that represents an eid.

Kind: global class
Extends: BasicEmitter
Properties

Name Description

id

id of associated object in investigate

title

title of associated object in investigate

nodeid

id of associated node id in Dashboard datamodel


eid.on(eventName, instanceId, handler)BasicEmitter

Add an event handler

Kind: instance method of Eid
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


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

Remove an event handler.

Kind: instance method of Eid
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)


eid.removeAllListeners(instanceId)BasicEmitter

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

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

Parameter Type Description

instanceId

string

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


eid.emit(eventName, instanceId)BasicEmitter

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

Kind: instance method of Eid
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


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


Revisions

APIs to facilitate document editing (Target Search must have editing enabled)

Kind: global class


revisions.reviseRowPromise<void>

Replaces a document with the specified one

Kind: instance property of Revisions
Returns: Promise<void> - A promise which gets resolved upon completion

Parameter Type Description

savedSearchId

string

row

Object

Document to be revised

row._id

String

row._seq_no

Number

row._primary_term

Number

row._source

Object

row._siren_revision

Object


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

isMain

boolean

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


search.getSearchSource()SearchSource

Get SearchSource behind this Search

Kind: instance method of Search


search.on(eventName, instanceId, handler)BasicEmitter

Add an event handler

Kind: instance method of Search
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


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

Remove an event handler.

Kind: instance method of Search
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)


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
Overrides: removeAllListeners
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
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


SearchSource

Allows scripts to query data model searches. State of the SearchSource can be modified by the property methods (chainable).

Kind: global class
Properties

Name Type Description

type

function

Chainable state setter, (value) => this

query

function

Chainable state setter, (value) => this

filter

function

Chainable state setter, (value) => this

sort

function

Chainable state setter, (value) => this

highlight

function

Chainable state setter, (value) => this

highlightAll

function

Chainable state setter, (value) => this

aggs

function

Chainable state setter, (value) => this

from

function

Chainable state setter, (value) => this

searchAfter

function

Chainable state setter, (value) => this

size

function

Chainable state setter, (value) => this

source

function

Chainable state setter, (value) => this

version

function

Chainable state setter, (value) => this

seqNoPrimaryTerm

function

Chainable state setter, (value) => this

inject

function

Chainable state setter, (value) => this


searchSource.getDataModelEntity()Promise<DataModelEntity>

Returns the DataModelEntity associated to this search source.

Kind: instance method of SearchSource
Returns: Promise<DataModelEntity> - Resolved with the data model entity associated to this search source.


searchSource.fetch()Promise<EsSearchResponse>

Fetch response for current search source parameters.

Kind: instance method of SearchSource
Returns: Promise<EsSearchResponse> - Resolved with an Elasticsearch response for the given SearchSource


searchSource.getSearchRequest()Promise<EsSearchRequest>

Translates current search parameters into a search request. The request can be manipulated by users before being used for a search. The returned object can be used with sirenapi.es.search().

Kind: instance method of SearchSource
Returns: Promise<EsSearchRequest> - Resolved with the Elasticsearch search request for current search source parameters.
Example

const request = await searchSource.getSearchRequest();
const response = await sirenapi.es.search(request);

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.

Charts

Charts

The utility Charts class, provides methods to create ApexCharts

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.RevisionsRevisions

Kind: instance property of SirenAPI
Returns: Revisions - API to revise documents


sirenAPI.ReportingReporting

Kind: instance property of SirenAPI
Returns: Reporting - API to invoke reporting generation methods.


sirenAPI.destroy()Promise<void>

Clean all resources allocated by sirenapi

Kind: instance method of SirenAPI
Returns: Promise<void> - 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, searchId)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

searchId

String

ID of a search


sirenAPI.resolveIdFromCurrentDataspace(id)Promise

Utility method to resolve object ID to current dataspace

Kind: instance method of SirenAPI
Returns: Promise - Resolved promise with the migrated saved object id

Parameter Type Description

id

string

id of the saved object


sirenAPI.importScriptById(id)Promise

Imports the contents of another script. An imported script must declare contents to be exported using one or more context.export({ <contents> }) calls.

Kind: instance method of SirenAPI
Returns: Promise - Promise to the exported content of the loaded script
Throws:

  • If the script could not be found.

Parameter Type Description

id

string

id of the script to load

Example
Script with id "myId":

context.export({ myVar: 123 });

Importer script:

async function asyncWrapper() {
  const { myVar } = await sirenapi.importScriptById('myId');
  console.log(myVar); // Prints 123
}

sirenAPI.importScriptByTitle(title)Promise

Imports the contents of another script. An imported script must declare contents to be exported using one or more context.export({ <contents> }) calls.

Kind: instance method of SirenAPI
Returns: Promise - Promise to the exported content of the loaded script
Throws:

  • If the script could not be found.

  • If multiple scripts with the same title were found.

Parameter Type Description

title

string

title of the script to load

Example
Script with title "My script":

context.export({ myVar: 123 });

Importer script:

async function asyncWrapper() {
  const { myVar } = await sirenapi.importScriptByTitle('My script');
  console.log(myVar); // Prints 123
}

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
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)


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
Overrides: removeAllListeners
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


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.openModal(modalConfig)Promise<void>

Renders a modal with react element as its content on the visualization.

Kind: instance method of Visualization

Parameter Type Description

modalConfig

object

configuration object of the modal

modalConfig.Element

object

React element rendered inside the modal

modalConfig.primaryBtnText

string

text displayed on primary button

modalConfig.onPrimaryClick

function

callback called when primary button is clicked

[modalConfig.secondaryBtnText]

string

text displayed on secondary button

[modalConfig.onSecondaryClick]

function

callback called when secondary button is clicked

[modalConfig.cancelBtnText]

string

text displayed on secondary button

[modalConfig.onCancel]

function

callback called when cancel button is clicked

[modalConfig.titleText]

string

title of the modal


visualization.getDataModelEntity()Promise<DataModelEntity>

Convenience shorthand for this.getSearchSource().getDataModelEntity().

Kind: instance method of Visualization
Returns: Promise<DataModelEntity> - Resolved with the data model entity associated to this visualization.


visualization.getSearchSource()

Returns the search source used by the visualization. The search source can be used to search for related data.

Kind: instance method of Visualization


visualization.getLastRequest()EsSearchRequest | undefined

Returns the last raw request made by this visualization. The request body can be modified to search for related data.

NOTE: Only simple visualizations that retrieve data using a single request will expose this information. This includes histograms, pie charts and all other visualizations that expose the "Request" and "Response" properties under the caret-like ^ icon in the lower-left corner of their panel. Other complex visualizations will not expose this information.

Kind: instance method of Visualization
Returns: EsSearchRequest | undefined - The last request made by this visualization, or undefined if no request was made yet.


visualization.getLastResponse()EsSearchResponse | undefined

Returns the last response returned to this visualization.

NOTE: The same remark in getLastRequest applies here.

Kind: instance method of Visualization
Returns: EsSearchResponse | undefined - The last response returned to this visualization, or undefined if the response was not received yet or the request errored out.


visualization.getScreenshot([options])Promise<(VisScreenshot\|undefined)>

Makes a screenshot of the visualization as a png image.

Kind: instance method of Visualization
Returns: Promise<(VisScreenshot\|undefined)> - Resolves to a VisScreenshot object or undefined if the screenshot could not be acquired.

Parameter Type Default Description

[options]

object

(Optional) Supports options from html2canvas.

[options.title]

boolean

true

(Optional) Whether the screenshot should have the visualization name as title in the upper-left corner of the image. Defaults to true.

[options.scale]

number

window.devicePixelRatio

(Optional) The scale to use for rendering. Defaults to the browser’s device pixel ratio.


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
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)


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
Overrides: removeAllListeners
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, type, title, 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

type

type of associated object in investigate

title

title of associated object in investigate

description

description of associated object in investigate


Reporting

Provides methods for report generation.

Kind: global class


reporting.renderPromise<string>

Renders a report and returns the result as a string.

Kind: instance property of Reporting
Returns: Promise<string> - the result of the rendering as a string.

Parameter Type Description

templateId

string

The identifier of a reporting template.

data

Object

An object containing the data to be passed to the template.


reporting.renderToElementPromise<string>

Renders a report and wraps the resulting string as the inner HTML of a JSX element without performing any kind of sanitization.

Kind: instance property of Reporting
Returns: Promise<string> - a JSX element containing the report as its inner HTML.

Parameter Type Description

templateId

string

The identifier of a reporting template.

data

Object

An object containing the data to be passed to the template.


reporting.downloadString

Downloads a string as a file.

Kind: instance property of Reporting

Parameter Type Description

content

string

The string which will be included in the downloaded file.

fileName

string

The downloaded file’s name, including its file extension.

type

string

The media type (MIME type) indicating the format of the file.


reporting.download

Renders a report and triggers the download of the resulting file as an attachment.

Kind: instance property of Reporting

Parameter Type Description

templateId

string

The identifier of a reporting template.

data

Object

An object containing the data to be passed to the template.

filename

string

The name of the target file.


DataRecord

A class that represents either an actual data record or a virtual "entity identifier". The record is associated to a list of data model entities, which interpret the data as a data model-enabled node able to connect to other nodes through relations.

Kind: global class


dataRecord.getId()Promise<(EsRecordId\|string)>

Gets the id of the record.

Kind: instance method of DataRecord


dataRecord.getDataModelEntities()Promise<Array<DataModelEntity>>

Gets the data model entities associated to the record.

Kind: instance method of DataRecord


dataRecord.getLabel()Promise<string>

Gets the label of the record.

Kind: instance method of DataRecord


dataRecord.getRawFieldValuesArray(field)Promise<Array<unknown>>

Gets the raw values for specified field of the record.

Kind: instance method of DataRecord

Parameter Type Description

field

string

The field name to get values for.


dataRecord.getFirstRawFieldValue(field)Promise<(unknown\|null)>

Gets the first raw value for specified field of the record, or null if there is no value for the field.

Kind: instance method of DataRecord
See: getRawFieldValuesArray

Parameter Type Description

field

string

The field name to get values for.


dataRecord.getFormattedFieldValuesArray(field)Promise<Array<string>>

Gets the formatted values for specified field of the record. For example, raw dates will be formatted to be user-readable.

Kind: instance method of DataRecord

Parameter Type Description

field

string

The field name to get values of.


dataRecord.getFirstFormattedFieldValue(field)Promise<(string\|null)>

Gets the first formatted value for specified field of the record, or null if there is no value for the field.

Kind: instance method of DataRecord
See: getFormattedFieldValuesArray

Parameter Type Description

field

string

The field name to get values of.


dataRecord.getReactElementsFromFieldValuesArray(field)Promise<Array<JSX.Element>>

Converts HTML snippets stored in a given field into React elements. The HTML snippets are properly sanitized before being rendered, so this function can be used safely. The HTML snippet is always wrapped in a <div> element.

Kind: instance method of DataRecord

Parameter Type Description

field

string

The field name to get values for.


dataRecord.getReactElementFromFirstFieldValue(field)Promise<(JSX.Element\|null)>

Converts the first HTML snippet stored in a given field into a React element. Returns null if there is no value for the field.

Kind: instance method of DataRecord
See: getReactElementsFromFieldValuesArray

Parameter Type Description

field

string

The field name to get values for.


dataRecord.getOutgoingRelations()Promise<Array<Relation>>

Gets the outgoing relations based on associated data model entities.

Kind: instance method of DataRecord


dataRecord.getLinkedRecords(relation, options)Promise<Array<DataRecord>>

Gets the linked records associated to the current record.

Kind: instance method of DataRecord

Parameter Type Description

relation

Relation

The relation to use in searching for linked items.

options

QueryOptions

(Optional) Options for the query operation.


dataRecord.getLinkedRecordsCount(relation)Promise<number>

Gets the total count of linked records associated to the current record.

Kind: instance method of DataRecord

Parameter Type Description

relation

Relation

The relation to use in searching for linked items.


DataRecord.getRecordById(id, dataModelEntities)Promise<DataRecord>

Retrieves the record given its id.

Kind: static method of DataRecord

Parameter Type Description

id

string

The id of the required record.

dataModelEntities

Array<DataModelEntity>

(Optional) Known list of data model entities to associate to the record. These input data model entities must be known to contain the record.


DataRecord.fetchDataModelEntities(records, dataModelEntities)Promise<DataRecord>

Retrieves the list of data model entities associated to the given list of records.

Kind: static method of DataRecord

Parameter Type Description

records

Array<DataRecord>

The list of records to fetch associated data model entities for.

dataModelEntities

DataModelEntitiesSpecs

(Optional) The specification for the data model entities to associate.


Relation

A class that represents a relation connecting two data model entities. Relations can be used to retrieve new records linked to some known record.

Kind: global class


relation.getId()Promise<string>

Gets the id of the relation.

Kind: instance method of Relation


relation.getLabel()Promise<string>

Gets the label of the relation.

Kind: instance method of Relation


relation.getSourceDataModelEntity()Promise<DataModelEntity>

Gets the data model entity used as source endpoint of the relation.

Kind: instance method of Relation


relation.getSourceField()Promise<(string\|null)>

Gets the name of the matched field in the source endpoint (or null if the relation source is an Entity Identifier).

Kind: instance method of Relation


relation.getTargetDataModelEntity()Promise<DataModelEntity>

Gets the data model entity used as target endpoint of the relation.

Kind: instance method of Relation


relation.getTargetField()Promise<(string\|null)>

Gets the name of the matched field in the target endpoint (or null if the relation target is an Entity Identifier).

Kind: instance method of Relation


Relation.getRelationByEndpoints(sourceDataModelEntity, sourceField, targetDataModelEntity, targetField)Promise<Relation>

Retrieves a relation given its endpoints. The order in which the endpoints are specified determines the direction of the returned relation. The specified endpoints must match an existing relation in the data model, otherwise an exception will be thrown.

Kind: static method of Relation

Parameter Type Description

sourceDataModelEntity

DataModelEntity

The data model entity used as source of relation,

sourceField

string | null

The field name of relation’s source (null if eid used as the source).

targetDataModelEntity

DataModelEntity

The data model entity used as target of relation.

targetField

string | null

The field name of relation’s target (null if eid used as the target).


Relation.getRelationsByLabel(label)Promise<Array<Relation>>

Retrieves all relations with the given label.

Kind: static method of Relation

Parameter Type Description

label

string

The label of the relations to retrieve.


Relation.getOutgoingRelationsFromDataModelEntities(dataModelEntities)Promise<Array<Relation>>

Returns all relations that have as source any element in the input list of data model entities.

Kind: static method of Relation

Parameter Type Description

dataModelEntities

Array<DataModelEntity>

The list of data model entities that are source of the returned relations.


DataModelEntity

A class representing a data model entity, such as a Search or an Entity identifier. It contains the field definitions necessary to extract, interpret and format the data stored in the records. It also allows users to extract records satisfying an input query.

Kind: global class


dataModelEntity.getId()Promise<string>

Gets the id of the data model entity.

Kind: instance method of DataModelEntity


dataModelEntity.getType()Promise<DataModelEntityType>

Gets the type of the data model entity.

Kind: instance method of DataModelEntity


dataModelEntity.getLabel()Promise<string>

Gets the label of the data model entity.

Kind: instance method of DataModelEntity


dataModelEntity.getIndexPattern()Promise<string>

Returns the index pattern of a Search entity. Throws an error if the entity represents an Entity identifier.

Kind: instance method of DataModelEntity


dataModelEntity.getTimeFieldName()Promise<(string\|undefined)>

Returns the name of the time field of a Search entity, or undefined if the entity has no time field. Throws an error if the entity represents an Entity identifier.

Kind: instance method of DataModelEntity


dataModelEntity.getRoot()Promise<DataModelEntity>

Gets the root entity for the current data model entity if any, otherwise returns itself.

Kind: instance method of DataModelEntity


dataModelEntity.getParent()Promise<DataModelEntity>

Gets the parent entity for the current data model entity if any.

Kind: instance method of DataModelEntity


dataModelEntity.getChildren()Promise<DataModelEntity>

Gets the list of child entities associated to the current data model entity.

Kind: instance method of DataModelEntity


dataModelEntity.getRecordLabel(record)Promise<string>

Gets the label for given record associated to the current data model entity.

Kind: instance method of DataModelEntity

Parameter Type Description

record

DataRecord

Given record to retrieve its label


dataModelEntity.getRecordFormattedFieldValues(record, field)Promise<Array<string>>

Gets the values for the specified field in the input record. The returned values are expressed in a user-readable format.

Kind: instance method of DataModelEntity

Parameter Type Description

record

DataRecord

The record to retrieve values from.

field

string

The field name to retrieve values for.


dataModelEntity.getOutgoingRelations()Promise<Array<Relation>>

Gets the list of all outgoing relations associated to the current data model entity.

Kind: instance method of DataModelEntity


dataModelEntity.getOutgoingRelationsByLabel(label)Promise<Array<Relation>>

Gets the list of outgoing relations associated to the current data model entity based on given label.

Kind: instance method of DataModelEntity

Parameter Type Description

label

string

The label to match in returned relations. (Case insensitive)


dataModelEntity.getRecords(options)Promise<Array<DataRecord>>

Queries the current data model entity for records.

Kind: instance method of DataModelEntity

Parameter Type Description

options

QueryOptions

(Optional) Additional search request options.


dataModelEntity.getRecordRawFieldValues(record, field)Promise<Array<unknown>>

Gets the raw values for the specified field in the input record.

Kind: instance method of DataModelEntity

Parameter Type Description

record

DataRecord

Given record to retrieve its field values

field

string

The field name to retrieve its values from the record


DataModelEntity.getDataModelEntitiesByLabel(label)Promise<Array<DataModelEntity>>

Returns a list of Data Model Entities matching the specified label. The match is case insensitive.

Kind: static method of DataModelEntity

Parameter Type Description

label

string

Label of the Data Model Entities to return.


DataModelEntity.getDataModelEntityById(id)Promise<DataModelEntity>

Returns the Data Model Entity matching the specified saved object id.

Typing saved object ids explicitly in a script is discouraged. Ids are opaque and dataspace-specific, so a script with explicit ids inside wouldn’t work when cloned to a different dataspace. Prefer using method getDataModelEntitiesByLabel if possible.

Kind: static method of DataModelEntity

Parameter Type Description

id

string

Id of the Data Model Entity to return.


DataModelEntity.getDataModelEntitiesByPath(labelsPath)Promise<Array<DataModelEntity>>

Fetches the Data Model Entities in the hierarchical sub-tree identified by a path of Data Model Entity labels (case insensitive).

Kind: static method of DataModelEntity

Parameter Type Description

labelsPath

Array<string>

Sequence of Data Model Entity labels identifying the sub-tree to list.

Example

//           Criminal              Boat
//         /                     /
//  Person               Vehicle - Airplane
//         \                     \
//           Witness               Car

const allEntities = await DataModelEntity.getDataModelEntitiesByPath([]); // All the data model entities

const personEntities = await DataModelEntity.getDataModelEntitiesByPath(['person']); // [Person, Criminal, Witness]
const vehicleEntities = await DataModelEntity.getDataModelEntitiesByPath(['vehicle']); // [Vehicle, Boat, Airplane, Car]

const criminalEntities = await DataModelEntity.getDataModelEntitiesByPath(['person', 'criminal']); // [Criminal]

APIDefinition : Object

The definition of an API as per the scripting interfaces.

Kind: global typedef
Properties

Name Type Description

name

string

Function name


QueryOptions : Object

Options applied when querying a data model entity for records.

Kind: global typedef
Properties

Name Type Description

query

Object

(Optional) Elasticsearch query applied for records retrieval.

size

number

(Optional) The maximum number of records retrieved. Default: 10

from

number

(Optional) Index of the record to start retrieval from. The value can’t exceed 10,000. Default: 0

orderBy

Order

(Optional) Order in which the linked records will be returned. Records discarded due to the limit property will be the ones at the end of the ordered list.

setDataModelEntities

DataModelEntitiesSpecs | 'QUERY_TARGET'

(Optional) Specifies which data model entities will be associated to the retrieved records. Default: 'ALL_CONTAINING'. 'QUERY_TARGET' - use the queried data model entity, with no overhead.


Order : Object

Order specification applied when retrieving records.

Kind: global typedef
Properties

Name Type Description

field

string

Field to sort on

order

'asc' | 'desc'

Sorting direction


DataModelEntitiesSpecs : string

Specifies how retrieved records should implicitly associate to data model entities.

Kind: global typedef
Properties

Name Type Description

ALL_CONTAINING

string

Resolve to all data model entities that contain the input record.


VisScreenshot : Object

A screenshot obtained from a dashboard visualization.

Kind: global typedef
Properties

Name Type Description

title

string

The title of the screenshot.

imgSrc

string

The screenshot image data, in data URL format.

width

number

The screenshot’s width.

height

number

The screenshot’s height.