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.

Collection

A class that represents a collection.

Dashboard ⇐ BasicEmitter

The class that represents a dashboard.

Dataspace

The class that represents a dataspace.

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.

DataModelLink ⇐ BasicEmitter

The class that represents a data model link.

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.

Eid ⇐ BasicEmitter

The class that represents an eid.

Graph

A class that represents a graph.

Highlighting

APIs to process the highlights and present the matching snippets.

Notify

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

RecordViewer

APIs to access the Record Viewer.

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.

Reporting

Provides methods for report generation.

Revisions

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

Search ⇐ BasicEmitter

The class that represents a search.

SearchApp

A class that represents a search app.

SearchSource

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

SirenAPI ⇐ BasicEmitter

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

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.

Functions

getFields() ⇒ Promise<Array<Field>>

Returns fields metadata from the entity.

Typedefs

APIDefinition : Object

The definition of an API as per the scripting interfaces.

DataModelRecordId : Object

Object representing a record

EsRecordId : Object

Id of an Elasticsearch record.

DataModelEntityType : string

Possible types of a Data Model Entity.

CountOptions : Object

Options applied when counting records.

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.

RichDocs : RichDocsConfig | RichDocsConfigBySearch

Configuration for enriching documents.

RichDocsConfig : Object

Configuration for enriching documents. Will be applied documents originating from all searches.

RichDocsConfigBySearch : Object<string, RichDocsConfig>

Configuration for enriching documents by search.

VisScreenshot : Object

A screenshot obtained from a dashboard visualization.

Interfaces

Field

Interface representing a Field.

RelationCondition

The interface representing a relation condition.

HighlightParsingOptions

Options necessary to parse a highlighted string.

HighlightItem

Part of a highlighted string.

When parsing highlights for a string, the string is subdivided into substrings that alternate between highlighted and normal text. Each substring is represented by a HighlightItem object.

Field

Interface representing a Field.

Kind: global interface
Properties

Name Type Description

name

string

The name of the field.

esType

string

The Elasticsearch type of the field.

type

string

The type of the field.

label

string

The label of the field.

description

string

A description of the field.

scripted

boolean

Indicates whether the field is scripted.

searchable

boolean

Indicates whether the field is searchable.

aggregatable

boolean

Indicates whether the field is aggregatable.

primaryKey

boolean

Indicates whether the field is a primary key.

singleValue

boolean

Indicates whether the field can have only one value.

globalSearchEnabled

boolean

(Optional) Indicates whether global search is enabled for the field.

globalSearchBoost

number

(Optional) The boost value for global search.

mainField

boolean

Indicates whether the field is selected as a main field.

RelationCondition

The interface representing a relation condition.

Kind: global interface
Properties

Name Type Description

clause

string

'must'

operator

string

The condition operator such as eq, lte, gte, gt, lt, intersects, contains

domainField

string | undefined

The domain field name of the condition. The value is undefined if this side of the relation is an Entity Identifier.

rangeField

string | undefined

The range field name of the condition. The value is undefined if this side of the relation is an Entity Identifier.

HighlightParsingOptions

Options necessary to parse a highlighted string.

Kind: global interface
Properties

Name Type Description

pre_tags

Array<string>

Tags used to represent the start of a highlight. Only one tag is supported (array of a single element).

post_tags

Array<string>

Tags used to represent the end of a highlight. Only one tag is supported (array of a single element).

HighlightItem

Part of a highlighted string.

When parsing highlights for a string, the string is subdivided into substrings that alternate between highlighted and normal text. Each substring is represented by a HighlightItem object.

Kind: global interface
Properties

Name Type Description

type

'text' | 'highlight'

Whether the item represents normal or highlighted text.

text

string

The text represented by this item.

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) ⇒ Promise<Chart>

Creates an Apex Chart element

Kind: static method of Charts
Returns: Promise<Chart> - Promise to an instance of a Chart object

Parameter Type Description

options

object

ApexChart options.

Charts.getBarChartBasicOptions(options) ⇒ Promise<object>

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

Kind: static method of Charts
Returns: Promise<object> - Promise to the basic options for an ApexChart bar chart

Parameter Type Description

options

object

Apex Chart options

Collection

A class that represents a collection.

Kind: global class

Collection.addCollectionRecords(options) ⇒ Promise<void>

Add records passed via option.recordIds to collection specified via options.collectionId. If options.collectionId is not specified then the method will display a modal where the user can create a new collection or select from existing ones.

Kind: static method of Collection
Throws:

  • EID records are not supported at the moment and can not be added using this method. You can use Graph.addRecordsWithModal instead.

Parameter Type Default Description

options

object

Options for adding records to a collection.

options.recordIds

Array<DataModelRecordId> | Array<DataRecord>

An array of objects representing the records to add.

[options.collectionId]

string

The Id of the collection to which to add records. If not provided, the method will display a modal in which a user can create a new collection or pick an existing one. (optional)

[options.allowCreate]

boolean

true

Setting to false will hide modal functionality for creating a new collection. Defaults to true. (optional)

[options.openAfterAdd]

boolean

false

Setting to true will redirect to the collection page. If true a secondary button will appear in the modal which gives the user the choice to redirect to the collection. Defaults to false. (optional)

Dashboard ⇐ BasicEmitter

The class that represents a dashboard.

Kind: global class
Extends: BasicEmitter

dashboard.getQueryString() ⇒ QueryString

The query string currently applied to the dashboard.

Kind: instance method of Dashboard

dashboard.getSavedQueryString() ⇒ QueryString

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

dashboard.getId() ⇒ string

The dashboard’s ID.

Kind: instance method of Dashboard

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.getSearchSource() ⇒ Promise<SearchSource>

Get the SearchSource associated to this Dashboard. You can use the search source to run queries on the dashboard.

Kind: instance method of Dashboard
Throws:

  • Error If the dashboard is not attached to a data model entity.

dashboard.getFilters() ⇒ Array<Filter>

The filters currently applied to the dashboard.

Kind: instance method of Dashboard

dashboard.getSavedFilters() ⇒ Array<Filter>

The filters saved with the dashboard.

Kind: instance method of Dashboard

dashboard.setFilters(filters) ⇒ this

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

Kind: instance method of Dashboard

Parameter Type

filters

Filter | Array<Filter>

dashboard.addFilters(filters) ⇒ this

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

Kind: instance method of Dashboard

Parameter Type

filters

Filter | Array<Filter>

dashboard.getTime() ⇒

The time currently applied to the dashboard.

Kind: instance method of Dashboard
Returns: a time object with properties from, to and mode. Returns a null value if the time filter is not visible in the dashboard.

dashboard.getSavedTime() ⇒

The time saved with the dashboard.

Kind: instance method of Dashboard
Returns: a time object with properties from, to and mode. Returns a null value if the time is not saved with the dashboard or the time filter is not visible in the dashboard.

dashboard.getVisualizationByTitle(title) ⇒ Array<Visualization>

Gets visualizations by title

Kind: instance method of Dashboard

Parameter Type Description

title

string

title of visualization to return

dashboard.getVisualizationById(title) ⇒ Array<Visualization>

Gets visualizations 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 tree

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

Applies any modification to the dashboard query and filters to the state of the application.

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.openFlyout(flyoutConfig) ⇒ Promise<void>

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

Kind: instance method of Dashboard

Parameter Type Description

flyoutConfig

object

configuration object of the modal

flyoutConfig.Element

object

React element rendered inside the flyout

[flyoutConfig.titleText]

string

title of the flyout

[flyoutConfig.footer]

object

React element rendered inside the footer of the flyout

[flyoutConfig.size]

's' | 'm' | 'l'

Size of the flyout (default: 'm')

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 milliseconds
    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 Dashboard object

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

Dataspace

The class that represents a dataspace.

Kind: global class

dataspace.shortCode ⇒ string

Short code of the dataspace

Kind: instance property of Dataspace

dataspace.title ⇒ string

Title of the dataspace

Kind: instance property of Dataspace

dataspace.description ⇒ string

Description for the dataspace

Kind: instance property of Dataspace

dataspace.colorCode ⇒ string

Colour code of the dataspace. This is in hex format (#000000)

Kind: instance property of Dataspace

dataspace.icon ⇒ string

Icon of the dataspace. This is in the form of FontAwesome CSS classes (e.g. fas fa-search)

Kind: instance property of Dataspace

dataspace.switch()

Switch to the dataspace represented by the dataspace object. This will cause the page to reload, which will interrupt any running scripts.

Kind: instance method of Dataspace

Dataspace.getByShortCode(shortCode) ⇒ Promise<Dataspace>

Fetches a dataspace object with the specified short code.

Kind: static method of Dataspace

Parameter Type Description

shortCode

string

The short code of the dataspace to fetch

Dataspace.getCurrentDataspace() ⇒ Promise<Dataspace>

Fetches a dataspace object which represents the current dataspace.

Kind: static method of Dataspace

Dataspace.getAvailableDataspaces() ⇒ Promise<Array<Dataspace>>

Fetches a list of the available dataspaces that the user can switch to.

Kind: static method of Dataspace
Returns: Promise<Array<Dataspace>> - Objects representing the available dataspaces

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.getIcon() ⇒ Promise<string>

Gets the icon of the data model entity.

Kind: instance method of DataModelEntity

dataModelEntity.getColor() ⇒ Promise<string>

Gets the color of the data model entity.

Kind: instance method of DataModelEntity

dataModelEntity.getIndexPattern() ⇒ Promise<string>

Returns the index pattern of a Search entity.

Kind: instance method of DataModelEntity
Throws:

  • If the entity represents an entity identifier.

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.

Kind: instance method of DataModelEntity
Throws:

  • If the entity represents an entity identifier.

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

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.getRecordHit(record) ⇒ Promise<EsHit>

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

Kind: instance method of DataModelEntity
Throws:

  • If the entity represents an entity identifier.

Parameter Type Description

record

DataRecord

Given record to retrieve its label.

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.openRecordView(record) ⇒ Promise<void>

Opens the record viewer for given record associated to the current data model entity.

Kind: instance method of DataModelEntity

Parameter Type Description

record

DataRecord

Given record to open on the record viewer

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

DataModelLink ⇐ BasicEmitter

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

dataModelLink.on(eventName, instanceId, handler) ⇒ BasicEmitter

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

dataModelLink.off(name, [handler], instanceId) ⇒ BasicEmitter

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)

dataModelLink.removeAllListeners(instanceId) ⇒ BasicEmitter

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)

dataModelLink.emit(eventName, instanceId) ⇒ BasicEmitter

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

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. This can be an _id/_index EsRecordId pair for actual data records or a string value for entity identifiers.

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.getHit() ⇒ Promise<EsHit>

Gets the hit associated to the record.

Kind: instance method of DataRecord
Throws:

  • If the record represents an entity identifier value.

dataRecord.getLabel() ⇒ Promise<string>

Gets the label of the record.

Kind: instance method of DataRecord

dataRecord.getRawFieldValuesArray(field, [options]) ⇒ Promise<Array<unknown>>

Gets the raw values for specified field of the record.

Kind: instance method of DataRecord

Parameter Type Default Description

field

string

The field name to get values for.

[options]

Object

(Optional) Options that affect how values for the field are resolved.

[options.useEr]

boolean

false

(Optional) Whether to also include field values for all equivalent records (requires entity resolution enabled).

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, [options]) ⇒ 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 Default Description

field

string

The field name to get values of.

[options]

Object

(Optional) Options that affect how values for the field are resolved.

[options.useEr]

boolean

false

(Optional) Whether to also include field values for all equivalent records (requires entity resolution enabled).

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, options) ⇒ 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.

options

CountOptions

(Optional) Options for the count operation.

dataRecord.openRecordViewer() ⇒ Promise<void>

Opens a Record Viewer on this record. This will replace the currently viewed record if the Record Viewer is already open.

Kind: instance method of DataRecord

dataRecord.getEquivalentRecords([options]) ⇒ Promise<Array<DataRecord>>

Retrieves equivalent records associated to the current record. The equivalent DataRecords found will only contain fields or _source values defined in richDocs.

Kind: instance method of DataRecord

Parameter Type Default Description

[options]

Object

(Optional) Options that affect how the equivalent records are fetched.

[options.size]

number

10

(Optional) The maximum number of equivalent records to return.

[options.richDocs]

RichDocs

(Optional) Configuration used to determine how to enrich documents retrieved from Elasticsearch.

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

Retrieves the record given its id.

Kind: static method of DataRecord

Parameter Type Description

id

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

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

Graph

A class that represents a graph.

Kind: global class

graph.getId() ⇒ string

Get the id of the graph.

Kind: instance method of Graph

graph.getLabel() ⇒ string

Get the label of the graph.

Kind: instance method of Graph

graph.getCount() ⇒ number

Get the count displayed in the Dashboards page about this graph. This roughly matches the number of records in the graph, excluding Entity Identifiers and ignoring ACL restrictions.

Kind: instance method of Graph

graph.getLastSaveTime() ⇒ Date

Get the time the graph was last saved.

Kind: instance method of Graph

graph.open()

Open the graph in a visualizer on the Dashboard page.

Kind: instance method of Graph

Parameter Type Description

options.newTab

boolean

(Optional) Whether to open the graph in a new browser tab, defaults to false.

Graph.getGraphsWithRecords(options) ⇒ Promise<Array<Graph>>

Returns a list of all graphs that contain a given list of record IDs.

Kind: static method of Graph
Returns: Promise<Array<Graph>> - - An array of graphs containing the relevant record IDs
Throws:

  • EID records are not supported at the moment.

Parameter Type Description

options

object

Options for getting graphs from a list of records

[options.recordIds]

Array<EsHitId> | Array<DataRecord>

An array of records to search by.

[options.containing]

'ALL_RECORDS' | 'ANY_RECORDS'

Return graphs that return either all or any of the record IDs

Graph.getGraphsByLabel(label) ⇒ Promise<Array<Graph>>

Get graph instance by label.

Kind: static method of Graph
Returns: Promise<Array<Graph>> - Returns an array of graph instances found matching the label.

Parameter Type Description

label

string

Graph label to search for.

Graph.addRecordsWithModal(options) ⇒ Promise<(Graph\|undefined)>

Add records passed via option.recordIds to the graph specified by options.graphId. If options.graphId not specified then the method will display a modal where the user can create a new graph or select from existing ones.

Kind: static method of Graph
Returns: Promise<(Graph\|undefined)> - Either a resolved graph instance with added records or undefined when no records could be added, for example, because the user canceled the operation.

Parameter Type Default Description

options

object

Options for adding records to a graph.

options.recordIds

Array<DataModelRecordId> | Array<DataRecord>

An array of objects representing the records to add.

[options.graphId]

string

The Id of the graph to which to add records. If not provided, the method will display a modal in which a user can create a new graph or pick an existing one. (optional)

[options.allowCreate]

boolean

true

Setting to false will hide modal functionality for creating a new graph. Defaults to true. (optional)

[options.openAfterAdd]

boolean

false

Setting to true will redirect to the graph page. If true a secondary button will appear in the modal which gives the user the choice to redirect to the graph. Defaults to false. (optional)

Graph.getGraphById(id) ⇒ Promise<Graph>

Get graph instance by ID.

Kind: static method of Graph
Returns: Promise<Graph> - Resolves with graph matching the id.

Parameter Type Description

id

string

Graph ID to search for.

Highlighting

APIs to process the highlights and present the matching snippets.

Kind: global class

Highlighting.parseString(snippet, options) ⇒ Array<HighlightItem>

Splits a highlighted text snippet into the list of its normal and highlighted parts.

Kind: static method of Highlighting
Throws:

  • If the "pre_tags" or "post_tags" property is defined with either more than one tag or no tag.

Parameter Type Description

snippet

string

The highlighted text snippet to break up into highlighted items.

options

HighlightParsingOptions

(Optional) Options object specifying the highlight tags to use to process the text. If not specified, the default Investigate highlighting tags will be used for parsing.

Example

const items = sirenapi.Highlighting.parseString('some <tag>highlighted</tag> text', {
 pre_tags: ['<tag>'],
 post_tags: ['</tag>']
});

// [
//   { type: 'text', text: 'some ' },
//   { type: 'highlight', text: 'highlighted' },
//   { type: 'text', text: ' text' }
// ]

Highlighting.itemsToReactElement(items) ⇒ JSX.Element

Transforms a list of highlight items into a React element that can be properly displayed in the UI.

Kind: static method of Highlighting

Parameter Type Description

items

Array<HighlightItem>

Highlight items to transform into a React element.

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

RecordViewer

APIs to access the Record Viewer.

Kind: global class

RecordViewer.openRecord(id, dataModelEntity) ⇒ void

Opens the Record Viewer on the record with the specified id. This method translates to sirenapi.DataRecord.getRecordById(<args>).openRecordViewer(), and is provided as a convenience.

Kind: static method of RecordViewer

Parameter Type Description

id

EsRecordId | string

Id of the record to open.

dataModelEntity

DataModelEntity

(Optional) A data model entity to associate to the record.

RecordViewer.close() ⇒ Promise<boolean>

Closes any open Record Viewer.

Kind: static method of RecordViewer
Returns: Promise<boolean> - Whether the record was closed. A record could be prevented from closing, for example, if a user edited the record but didn’t save the changes yet. When prompted about saving changes, the user refused.

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.getInverseRelation() ⇒ Promise<Relation>

Gets the inverse of this relation.

Kind: instance method of Relation

relation.isDirectionPreferred() ⇒ Promise<boolean>

Returns whether this relation has the direction that is preferred between the two entities.

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

Deprecated

Gets the name of the matched field in the source endpoint if the relation has a single condition

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

Deprecated

Gets the name of the matched field in the target endpoint if the relation has a single condition

Kind: instance method of Relation

relation.getConditions() ⇒ Promise<Array<RelationCondition>>

Gets the entire conditions array for the relation.

Kind: instance method of Relation

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

Deprecated

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 with a single condition 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.

Reporting

Provides methods for report generation.

Kind: global class

reporting.render(templateId, data) ⇒ Promise<string>

Renders a report and returns the result as a string.

Kind: instance method 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.renderToElement(templateId, data) ⇒ Promise<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 method 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(content, fileName)

Downloads a string as a file.

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

reporting.downloadBlob(blob, fileName)

Downloads a blob object as a file.

Kind: instance method of Reporting

Parameter Type Description

blob

string

The blob object which will be the contents of the downloaded file.

fileName

string

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

reporting.download(templateId, data, filename)

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

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

Revisions

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

Kind: global class

revisions.reviseRow(entityTableId, hit) ⇒ Promise<void>

Replaces a document with the specified one.

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

Parameter Type Description

entityTableId

string

Id of the entity table that contains the document to change.

hit

Object

The replacement document.

hit._id

String

Id of the document to replace.

hit._index

String

Index of the document to replace.

hit._seq_no

Number

Part of the document versioning information.

hit._primary_term

Number

Part of the document versioning information.

hit._source

Object

Data of the document. This data will replace the original document’s data.

hit._siren_revision.notes

String

A note to store with the document about the edit.

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

SearchApp

A class that represents a search app.

Kind: global class

SearchApp.openSearchModal(searchModalOptions) ⇒ Promise<SearchModalResult>

Opens a search modal, a simplified search app user interface. Invoking the method without arguments or an empty recordIds array will initialize a new search session.

Kind: static method of SearchApp
Returns: Promise<SearchModalResult> - Selected search result hits when confirm button clicked, else undefined if closed.

Parameter Type Description

searchModalOptions

SearchModalOptions

(Optional) Options to initiate a search modal session.

searchModalOptions.recordIds

Array<DataModelRecordId>

(Optional) An array of objects representing the records to open in the modal.

searchModalOptions.modalTitle

string | JSX.Element

(Optional) The modal title.

searchModalOptions.confirmButtonLabel

string

(Optional) Label for the confirm button, confirm button does not render when undefined.

searchModalOptions.showEquivalentResults

boolean

(Optional) Show equivalent entity records when entity resolution enabled.

Example

Awaited return value - { type: 'confirm', globalSearchHits: [{ _id: 1, _index: 'article', _source: {} }] }

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.

Dataspace

Dataspace

The prototype of the Dataspace class.

Visualization

Visualization

The prototype of the Visualization class.

DataRecord

DataRecord

The prototype of the DataRecord class.

DataModelEntity

DataModelEntity

The prototype of the DataModelEntity class.

Relation

Relation

The prototype of the Relation class.

RecordViewer

RecordViewer

The prototype of the RecordViewer class.

Collection

Collection

The prototype of the Collection class.

Highlighting

Highlighting

The prototype of the Highlighting class.

Search

Search

The prototype of the Search class.

SearchApp

SearchApp

The prototype of the SearchApp class.

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 sirenapi 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 custom 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 emitted.

sirenAPI.Revisions ⇒ Revisions

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

sirenAPI.Reporting ⇒ Reporting

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

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.openFlyout(flyoutConfig) ⇒ Promise<void>

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

Kind: instance method of Visualization

Parameter Type Description

flyoutConfig

object

configuration object of the flyout

flyoutConfig.Element

object

React element rendered inside the flyout

[flyoutConfig.titleText]

string

title of the flyout

[flyoutConfig.footer]

object

React element rendered inside the footer of the flyout

[flyoutConfig.size]

's' | 'm' | 'l'

Size of the flyout (default: 'm')

visualization.getDataModelEntity() ⇒ Promise<(DataModelEntity\|undefined)>

Kind: instance method of Visualization
Returns: Promise<(DataModelEntity\|undefined)> - Resolved with the data model entity associated to this visualization if one exists.

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

Visualization.getCurrentVisualizer() ⇒ Visualization

Find the visualization instance currently used as the visualizer and return it.

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

getFields() ⇒ Promise<Array<Field>>

Returns fields metadata from the entity.

Kind: global function
Returns: Promise<Array<Field>> - Returns a promise that resolves with an array of Field objects.
Throws:

  • If the entity represents an entity identifier.

APIDefinition : Object

The definition of an API as per the scripting interfaces.

Kind: global typedef
Properties

Name Type Description

name

string

Function name

DataModelRecordId : Object

Object representing a record

Kind: global typedef
Properties

Name Type Description

_id

string

Record id, assumed to be unique in its own index

_index

string

Name of the index that contains the record

searchId

string

Id of the Entity table to which the record belongs

EsRecordId : Object

Id of an Elasticsearch record.

Kind: global typedef
Properties

Name Type Description

_id

string

Record id, assumed to be unique in its own index

_index

string

Name of the index that contains the record

DataModelEntityType : string

Possible types of a Data Model Entity.

Kind: global typedef
Properties

Name Type Description

SEARCH

string

Identifies a Search in the Data Model

ENTITY_IDENTIFIER

string

Identifies an Entity Identifier in the Data Model

CountOptions : Object

Options applied when counting records.

Kind: global typedef
Properties

Name Type Description

query

Object

(Optional) Elasticsearch query applied when counting records.

cancelPromise

Promise<void>

(Optional) Fulfilling this promise cancels the query and stops script execution.

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 the data model entities associated with the retrieved records.

'QUERY_TARGET' - use the queried data model entity with no overhead.

Default: 'ALL_CONTAINING'.

highlight

HighlightClause | boolean

(Optional) Highlighting to apply in the query.

You can pass true for the default highlighting used by Investigate for the query parameter, or specify your own highlight clause according to the Elasticsearch Query DSL syntax.

You can access the highlighting results using the getHit function.

Also see Highlighting for parsing highlights.

cancelPromise

Promise<void>

(Optional) Fulfilling this promise cancels the query and stops script execution.

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

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

RichDocs : RichDocsConfig | RichDocsConfigBySearch

Configuration for enriching documents.

Kind: global typedef

RichDocsConfig : Object

Configuration for enriching documents. Will be applied documents originating from all searches.

Kind: global typedef
Properties

Name Type Description

[fields]

string | Array<string> | Array<DocValueField>

Fields to include in the document.

[_source]

boolean | string | Array<string> | Object

Source configuration for the document.

[_source.includes]

boolean | string | Array<string>

Fields to include in the source.

[_source.excludes]

boolean | string | Array<string>

Fields to exclude from the source.

[size]

number

Maximum number of documents enrich.

RichDocsConfigBySearch : Object<string, RichDocsConfig>

Configuration for enriching documents by search.

Kind: global typedef

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.