CEvents API

The CEvents API is an object interface used to encapsulate data as it flows through Moogsoft Enterprise. A CEvent object contains status and data, and methods to access and manipulate that data. The data contained in the CEvent object depends on the type specified in the object, which include LAM events, alerts, Situations, thread entries, and invitations.

This API uses the following methods.

contains

Checks whether the CEvent object contains the given key.

Request arguments

Name

Type

Description

key

String

Name of a potential key in the CEvent object.

Return parameter

Type

Description

Boolean

Returns true if the provided key exists in the CEvent object, or false if it was not.

Request example

var custom_info = event.contains("custom_info") ? event.getCustomInfo() : {};

evaluateFilter

Allows an event/alert/Situation to be easily evaluated against a filter.

Request arguments

Name

Type

Description

filter

String

An SQL-like filter for events, alerts or Situations.

Return parameter

Type

Description

Boolean

Whether the filter matches the event, alert or Situation.

Returns true if the filter matches the event, alert or Situation.

Returns false if the filter has a correct syntax but doesn't match the event, alert or Situation.

Returns null if the filter syntax is incorrect.

Request example

var is_matching = situation.evaluateFilter("description LIKE 'Created Situation'");

forward(this)

Forwards the CEvent down the chain configured in the moog_farmd.conf (using the process_output_of configuration). The usual way of calling this is CEvent.forward(this) where this is the Moobot that is processing the CEvent object. This method also sends the CEvent object to any Moolet listening via event_handlers.

Request arguments

Name

Type

Description

moobot

NativeObject

The instance of the Moobot which is handling the CEvent object, usually the variable named this.

Return parameter

None.

forward(target,....)

Takes any number of target Moolet names as strings and forwards the CEvent to each of them. For example CEvent.forward("moolet1") or CEvent.forward("moolet1", "moolet2").

Request arguments

Name

Type

Description

targets

Stringvarargs

One or more Moolet names as strings.

Return parameter

None.

Request examples

You can forward alerts or Situations to other Moolets such as clustering algorithms programmatically using this function.

Example request to forward an alert to Alert Enricher:

alert.forward("AlertEnricher");

Example request to forward a Situation to Situation Manager Labeler:

situation.forward("SituationMgrLabeller");

getActionDetails

A utility helper method that retrieves the entire alert or Situation contained in the payload of a CEvent. The format of the details varies depending on what the action type is, and may be empty.

Request arguments

None

Return parameter

Type

Description

JS NativeObject

Whole of the alert or Situation contained in the payload of the CEvent, as a NativeObject ready for use in the Javascript for a Moobot.

getCorrelationInfo

Returns the correlation information for a Situation, which lists all of the services which are interested in this Situation. This method only applies to CEvent objects that contain Situation thread entries from the Collaborate tab in a Situation Room. For other correlation information, use the MoogDb v2 method getSigCorrelationInfo.

Request arguments

None

Return parameter

Type

Description

NativeObject

An object which contains the sig_id, service_name, external_id and properties for all the correlation info for the Situation. sig_correlation_info is a one to many relationship of sigs to services.

getCustomInfo

A helper method provided to retrieve the whole custom_info object for an alert or Situation.

Request arguments

None

Return parameter

Type

Description

JS NativeObject

Whole custom_info map for an alert or Situation as a NativeObject ready for use in the Javascript for a Moobot.

Bot.getType

Returns the internal name of the Moobot that is running the code.

Request arguments

None.

Return parameter

Type

Description

Enumerated type

Can be one of the following:

Request example

Example request if the following code is put into the Alert Builder Moobot:

logger.warning("This moobot is a: " + Bot.getType());

When Moogfarmd is started, the log line shows:

[AlertBuilder.js:65] +|This moobot is a: CAlertBuilder|+

getSummaryData

Returns a summary of information about a system, such as the number of alerts or the service count bundled up as key/value pairs.

Request arguments

None.

Return parameter

Type

Description

JS NativeObject

The summary of information about a system:

  • summary.alert_count - number

  • summary.service_count - number

  • summary.sig_summaries - map (contains "categories" and "queues")

  • summary.sig_summaries.categories - (array of objects)

  • summary.sig_summaries.queues - (array of objects)

Categories and queues contain the following:

  • summary.sigs_down - number

  • summary.sigs_up - number

  • summary.total_events - number

  • summary.total_sigs - number

Request example

If a Moolet is configured to listen to the 'Summary' event type as follows:

events.onEvent("summary", constants.eventType("Summary")).listen();

Then you can define a function can be defined to extract data out of the summary event object as follows:

function summary(summary)
{
var info = summary.getSummaryData();
logger.warning("Summary data: Events: "+info.total_events + " Situations: " + info.open_sigs);
}

getTopic

Returns the topic that the data was received on, for example "alerts" or "Situations".

Request arguments

None.

Return parameter

Type

Description

String

Name of the topic that the data came from or relates to, such as "Situations" or "alerts".

payload

Retrieves the whole data payload that was sent in the CEvent object. In most cases the data contained in the payload is going to represent either a Situation or an alert, and as such will have key/value pairs which match the data columns for each.

Request arguments

None.

Return parameter

Type

Description

CMooMsg

Enum value specifying the type of data that the Event contains and/or which topic the data was received on from the bus.

Examples

Request example

Example CEvent payload request:

logger.warning(cevent.payload().getData());

Response example

Example CEvent payload response:

{active=true, competencies=[], contact_num=, department=null, description=Online, email=, fullname=cyber, groupname=End-User, invitations=[], joined=1516963803, only_ldap=0, photo=-1, primary_group=1, profile_image=null, realms=[DB], roles=[1, 3, 4, 5], session_expiry=null, status=1, teams=[], timezone=SYSTEM, uid=6, username=cyber}

set

Inserts or updates a value in the CEvent object. This call does no transformation of values. All values specified must match the underlying value type in the CEvent.The custom_info value is a JSON string. If using .set() to change the value of custom_info, the JS object must be stringified first. Use setCustomInfo() to update custom_info.

Request arguments

Name

Type

Description

key

String

Key to insert or change a value at.

value

String or Number

New value to store against the key.

Return parameter

Type

Description

Boolean

Indicates whether or not the value was successfully changed: true = success, false = fail.

setCustomInfo

Sets the whole custom_info object for an alert or Situation.

Request arguments

Name

Type

Description

customInfo

NativeObject

The whole custom_info object to set for an alert or Situation.

Return parameter

None.

setCustomInfoValue

Sets a value of a specific property within custom_info to the supplied value. This can be used to change existing values, or create new ones.

Request arguments

Name

Type

Description

field

String

Dot-formatted field within the custom_info of the reference alert or Situation to update.

value

String, Integer, Boolean, Object, or Map

String, integer, Boolean, object, or map value to replace the value stored in the custom_info field.

Return parameter

Type

Description

Boolean

Indicates if the operation was successful: true = success, false = fail.

Request examples

You can use this method to add or replace specific keys within alert or Situation custom_info.

Example request to set a custom_info value in an alert:

alert.setCustomInfoValue("key1.my_new_key", "my_new_value");
var result = moogdb.updateAlert(alert);

Example request to set a custom_info value in a Situation:

situation.setCustomInfoValue("fieldA.fieldB", {"my_new_map_key1":"my_new_map_value1"});
var result = moogdb.updateSituation(situation);

setTopic

Sets or updates the topic value in the payload of the CEvent object.

Request arguments

Name

Type

Description

topic

String

Name of a topic to set or update in the payload data.

Return parameter

None.

Request example

Example request to close an alert in a non-standalone Moolet:

moogdb.closeAlert(alert.value("alert_id"));
alert.setTopic("alerts.close");
alert.forward(this);

stringValue

Retrieves a value from inside the payload which matches the provided key as a string value.

Request arguments

Name

Type

Description

key

String

Key for a value stored in the payload which will be used to fetch the data.

Return parameter

Type

Description

String

Value from the payload that was stored alongside the key, or null if no value was found for the provided key, converted to string format.

type

Retrieves the type stored on the CEvent, this value indicates type of information in the payload and/or which topic the data came from.

Request arguments

None.

Return parameter

Type

Description

EBotEvent

Enum value specifying the type of data that the Event contains and/or which topic the data was received on from the bus.

value

Retrieves a value from inside the payload which matches the provided key. Objects such as custom_info are stored as JSON strings, not native objects. To return custom_info as a native JS object, use the getCustomInfo call instead.

Request arguments

Name

Type

Description

key

String

Key for a value stored in the payload which will be used to fetch the data.

Return parameter

Type

Description

String, Number or Boolean

Value from the payload that was stored alongside the key, or null if no value was found to for the provided key. Values are returned in their native stored format, that is, as a string, number, or Boolean. Native JS objects such as custom_info are stored in CEvent objects as JSON strings, and are returned as such by this method.