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 |
|---|---|---|
| String | Name of a potential key in the CEvent object. |
Return parameter
Type | Description |
|---|---|
Boolean | Returns |
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 |
|---|---|---|
| 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 Returns Returns |
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 |
|---|---|---|
| NativeObject | The instance of the Moobot which is handling the CEvent object, usually the variable named |
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 |
|---|---|---|
| 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:
Categories and queues contain the following:
|
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 |
|---|---|---|
| String | Key to insert or change a value at. |
| String or Number | New value to store against the key. |
Return parameter
Type | Description |
|---|---|
Boolean | Indicates whether or not the value was successfully changed: |
setCustomInfo
Sets the whole custom_info object for an alert or Situation.
Request arguments
Name | Type | Description |
|---|---|---|
| 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 |
|---|---|---|
| String | Dot-formatted field within the custom_info of the reference alert or Situation to update. |
| 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: |
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 |
|---|---|---|
| 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 |
|---|---|---|
| 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 |
|---|---|---|
| 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. |