Core APIs in Siren Investigate
The following classes are available:
- SirenAPI ⇐
BasicEmitter
-
The API for interacting with Siren Investigate, which is exposed at window.sirenapi.
- Dashboard ⇐
BasicEmitter
-
The class that represents a dashboard.
- 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.
- Revisions
-
APIs to facilitate document revisions (Target Search must have revision enabled)
- Search ⇐
BasicEmitter
-
The class that represents a search.
- Chart
-
Class representing a chart object
- Charts
-
Utility class - provides static methods to create charts.
- SearchSource
-
Allows scripts to query data model searches. State of the SearchSource can be modified by the property methods (chainable).
- 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 |
The prototype of the Dashboard class for convenience. |
|
Visualization |
The prototype of the Visualization class for convenience. |
|
Search |
The prototype of the Search class for convenience. |
|
notify |
The utility class that allows scripts to trigger notifications at the top of the screen. |
|
Charts |
The utility Charts class, provides methods to create ApexCharts |
|
es |
-
-
.destroy()
⇒[ 'Promise' ].<void>
-
.setJWTToken(token)
⇒Promise
-
.invokeWebService(groupName, serviceName, params, [options])
⇒Promise
-
.getTimeFilter(time, indexPatternId)
⇒Promise
-
.resolveIdFromCurrentDataspace(id)
⇒Promise
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 |
|
event fired when app state changes, (filter or query was added or removed) |
CUSTOM |
|
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.Revisions
⇒ Revisions
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 |
|
Set to true to enable embedding in the URL. |
displayNavBar |
|
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 |
|
The group name of the webservice. |
|
serviceName |
|
The name of the webservice. |
|
params |
|
JSON data that will be sent to a Web service. |
|
[options] |
|
|
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 with three properties from, to and mode |
indexPatternId |
|
ID of a indexpattern |
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 |
|
id of the saved object |
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 |
|
Name of the event |
|
instanceId |
|
|
ID of the instance ( |
handler |
|
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 |
|
|
[handler] |
|
An optional handler to remove. If no handler is passed, then all are removed. |
instanceId |
|
ID of the instance ( |
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 |
|
ID of the instance ( |
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 |
|
|
instanceId |
|
ID of the instance ( |
[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
-
-
instance
-
.getQueryString()
⇒string
-
.getSavedQueryString()
⇒string
-
.setQueryString(queryString)
⇒this
-
.getTitle()
⇒string
-
.setTitle(title)
⇒this
-
.getDescription()
⇒string
-
.setDescription(description)
⇒this
-
.getFilters()
⇒string
|Array.<string>
-
.getSavedFilters()
⇒string
|Array.<string>
-
.setFilters(filters)
⇒this
-
.addFilters(filters)
⇒this
-
.getVisualizationByTitle(title)
⇒[ 'Array' ].<Visualization>
-
.getDashboardDataModelNodeIndexpattern(focusNodeId)
⇒Promise
-
.applyState()
⇒Promise
-
-
static
-
.fetchDashboardById(dashboardID)
⇒Promise
-
.getCurrentDashboard()
⇒Promise
-
.fetchAllDashboards()
⇒Promise
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 |
|
dashboard.setTitle(title)
⇒ this
Sets the title of the dashboard.
Kind: instance method of Dashboard
Parameter | Type |
---|---|
title |
|
dashboard.setDescription(description)
⇒ this
Sets the description of the dashboard.
Kind: instance method of Dashboard
Parameter | Type |
---|---|
description |
|
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 |
|
dashboard.addFilters(filters)
⇒ this
Specify a filter or array of filters to add to the dashboard.
Kind: instance method of Dashboard
Parameter | Type |
---|---|
filters |
|
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 |
|
title of visualization to return |
dashboard.getVisualizationById(title)
⇒ [ 'Array' ].<Visualization>
Gets visualisations by id
Kind: instance method of Dashboard
Parameter | Type | Description |
---|---|---|
title |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
Name of the event |
|
instanceId |
|
|
ID of the instance ( |
handler |
|
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 |
|
|
[handler] |
|
An optional handler to remove. If no handler is passed, then all are removed. |
instanceId |
|
ID of the instance ( |
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 |
|
ID of the instance ( |
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 |
|
|
instanceId |
|
ID of the instance ( |
[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 |
|
event fired when dashboard autorefresh option is enabled and dashboard was refreshed |
SEARCH_COUNT_CHANGED |
|
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.
Parameter | Type |
---|---|
dashboardID |
|
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 |
|
|
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 |
|
Name of the event |
|
instanceId |
|
|
ID of the instance ( |
handler |
|
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 |
|
|
[handler] |
|
An optional handler to remove. If no handler is passed, then all are removed. |
instanceId |
|
ID of the instance ( |
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 |
|
ID of the instance ( |
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 |
|
|
instanceId |
|
ID of the instance ( |
[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 |
Revisions
APIs to facilitate document revisions (Target Search must have revision enabled)
Kind: global class
revisions.reviseRow
⇒ [ 'Promise' ].<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 |
|
|
row |
|
Document to be revised |
row._id |
|
|
row._seq_no |
|
|
row._primary_term |
|
|
row._source |
|
|
row._siren_revision |
|
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 |
|
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
Returns: BasicEmitter
- this
, for chaining
Parameter | Type | Default | Description |
---|---|---|---|
eventName |
|
Name of the event |
|
instanceId |
|
|
ID of the instance ( |
handler |
|
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 |
|
|
[handler] |
|
An optional handler to remove. If no handler is passed, then all are removed. |
instanceId |
|
ID of the instance ( |
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 |
|
ID of the instance ( |
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 |
|
|
instanceId |
|
ID of the instance ( |
[arg…] |
|
Any number of arguments that will be applied to each handler |
Chart
Class representing a chart object
Kind: global class
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
Charts
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 |
|
Chainable state setter, |
query |
|
Chainable state setter, |
filter |
|
Chainable state setter, |
sort |
|
Chainable state setter, |
highlight |
|
Chainable state setter, |
highlightAll |
|
Chainable state setter, |
aggs |
|
Chainable state setter, |
from |
|
Chainable state setter, |
searchAfter |
|
Chainable state setter, |
size |
|
Chainable state setter, |
source |
|
Chainable state setter, |
version |
|
Chainable state setter, |
seqNoPrimaryTerm |
|
Chainable state setter, |
inject |
|
Chainable state setter, |
searchSource.fetch()
⇒ [ 'Promise' ].<Object>
Fetch response.
Kind: instance method of SearchSource
Returns: [ 'Promise' ].<Object>
- Resolved with an Elasticsearch response for the given SearchSource
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 |
|
Name of the event |
|
instanceId |
|
|
ID of the instance ( |
handler |
|
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 |
|
|
[handler] |
|
An optional handler to remove. If no handler is passed, then all are removed. |
instanceId |
|
ID of the instance ( |
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 |
|
ID of the instance ( |
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 |
|
|
instanceId |
|
ID of the instance ( |
[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 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 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 to report as a red error notification on top of the screen |