Notable Event Actions SDK reference

The Notable Events Action SDK contains three main modules.

• custom_group_action_base
• eventing
• grouping

Use the custom_group_action_base module when you want to consume the output of your moderator alerts (modalert).

Use the eventing module to get information about your events in ITSI. This module must reside on the same host where ITSI is installed. All classes in this module inherit from the EventBase class. This base class tracks the session key, username, password, and logger info.

Use the grouping module to operate on your episodes in ITSI. This module must reside on the same host where ITSI is installed.

class custom_group_action_base.CustomGroupActionBase(settings,logger)

Import the custom_group_action_base module when you want to consume the output of your modalert. In your script, inherit your class from the CustomGroupActionBase class. Use the get_group() method to work on the episode that triggered your script.

Parameter	Type	Description
settings	basestring or dictionary	Incoming parameters passed to the script using stdin.
logger	logger	The logger instance of the inherited class.

Raises

Type Error - Raised when settings is not a serialized JSON string.

Returns

A CustomGroupActionBase instance.

Return type

CustomGroupActionBase.

execute()

Implement this method to configure the actions to take based on the alert output. Derived classes must implement this method.

Raises

Not Implemented Error - Raised when the execute() method is not implemented in the derived class.

extract_group_or_event_id(notable_data)

Use this method to get the ID of the event or episode that triggered the action.

Parameter	Type	Description
notable_data	basestring	Notable event or episode object from which the event_ID or itsi_group_id is extracted.

Raises

Type Error - Raised if notable_data is of type None.

Exception - Raised if notable_data is not JSON type data.

Returns

The event_id or itsi_group_id.

Return type

basestring.

get_config()

Gets the configuration based on the settings.

Returns

The configuration that comes with the settings.

Return type

Configuration.

get_group()

Gets the episode that triggered the custom action. This method relies on get_results_file() and expects the returned file path to be a .csv.gz format.

The method is implemented as a generator because there can be thousands of episodes.

Raises

Value Error - Raised when there is not a valid .csv.gz results file. It prints out what file format was returned instead.

Returns

A dictionary type object until all received episodes are returned.

Return type

dictionary

get_results_file()

Gets the results file, which is where results are temporarily stored.

Raises

Attribute Error - Raised when no results file is returned.

Returns

The results file.

Return type

Results file.

get_session_key()

Gets the Splunk session key.

Raises

Attribute Error - Raised when no session key is returned.

Returns

The session key.

Return type

basestring.

class eventing.EventMeta(*args)

Import this class to get information about ITSI events, such as status, owner, and severities.

Parameter	Type	Description
session_key	basestring	The session key that is given by splunkd when you log in. If you do not have a session key, pass in None, but you will need to provide username and password credentials.
username	basestring	Your username.
password	basestring	Your password.
logger	logger	A place to log actions in an existing logger. If you do not have a logger, then the ITSI logger is used.

Raises

Type Error - Raised when the session_key is not a basestring type or when the session_key is not valid.

Value Error - Raised when the session_key is a zero-length string, or when the username and password are empty strings and the session_key is of type None.

Returns

An EventMeta instance.

Return type

EventMeta.

get_all_owners()

Get all valid owner values for a notable event.

Returns

A list of all configured owners.

Return type

list.

get_all_severities()

Get all severity values for a notable event.

Returns

A list of all configured severities.

Return type

list.

get_all_statuses()

Get all status values for a notable event.

Returns

A list of all configured statuses.

Return type

list.

class eventing.Event(session_key, *args, **kwargs)

Import this class to get information about ITSI events.

Parameter	Type	Description
session_key	basestring	The session key that is given by splunkd when you log in. If you do not have a session key, pass in None, but you will need to provide username and password credentials.
username	basestring	Your username.
password	basestring	Your password.
logger	logger	A place to log actions in an existing logger. If you do not have a logger, then the ITSI logger is used.

Raises

Type Error - Raised when the session_key is not a basestring type or when the session_key is not valid.

Value Error - Raised when the session_key is a zero-length string, or when the username and password are empty strings and the session_key is of type None.

Returns

An Event instance.

Return type

Event.

get_owner(*args, **kwargs)

Return the owners, given a list of events or event IDs.

Parameter	Type	Description
events	list of dictionaries	Each dictionary in the list represents an event that was sent by Splunk as an outcome of a custom action. The get_event() method in the CustomGroupActionBase class generates such an item.
event_ids	basestring or list	The unique ID of an event.
split_by	basestring	If event_ids is of type basestring, then it is split into a list of event IDs. By default, ',' separates the event IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when events is not of type basestring or of type list.

Value Error - Raised when both events and event_ids are of type None.

Returns

The event IDs and corresponding owners.

Return type

list of tuples.

get_status(*args, **kwargs)

Return the statuses, given a list of events or event IDs.

Parameter	Type	Description
events	list of dicts	Each dictionary in the list represents an event that was sent by Splunk as an outcome of a custom action. The get_event() method in the CustomGroupActionBase class generates such an item.
event_ids	basestring or list	The unique ID of an event.
split_by	basestring	If event_ids is of type basestring, then it is split into a list of event IDs. By default, ',' separates the event IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when events is not of type list.

Value Error - Raised when both events and event_ids are of type None.

Returns

The event IDs and corresponding statuses.

Return type

list of tuples.

get_severity(*args, **kwargs)

Return the severities, given a list of events or event IDs.

Parameter	Type	Description
events	list of dicts	Each dictionary in the list represents an event that was sent by ITSI as an outcome of a custom action. The get_event() method in the CustomGroupActionBase class generates such an event.
event_ids	basestring / list	The unique ID of an event.
split_by	basestring	If event_ids is of type basestring, then it is split into a list of event IDs. By default, ',' separates the event IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when events is not of type basestring or of type list.

Value Error - Raised when both events and event_ids are of type None.

Returns

The event IDs and corresponding severities.

Return type

list of tuples.

class grouping.GroupMeta(*args)

Import this class to get information about ITSI episodes, such as all available statuses, owners, and severities.

Parameter	Type	Description
session_key	basestring	The session key that is given by splunkd when you log in. If you do not have a session key, pass in None, but you will need to provide username and password credentials.
username	basestring	Your username.
password	basestring	Your password.
logger	logger	A place to log actions in an existing logger. If you do not have a logger, then the ITSI logger is used.

Raises

Type Error - Raised when the session_key is not a basestring type or when the session_key is not valid.

Value Error - Raised when the session_key is a zero-length string, or when the username and password are empty strings and the session_key is of type None.

Returns

An GroupMeta instance.

Return type

GroupMeta.

get_all_owners()

Get all valid owner values for an episode.

Returns

A list of all configured owners.

Return type

list.

get_all_severities()

Get all severity values for an episode.

Returns

A list of all configured severities.

Return type

list.

get_all_statuses()

Get all status values for an episode.

Returns

A list of all configured statuses.

Return type

list.

class grouping.EventGroup(session_key, *args, **kwargs)

Import this class to operate on ITSI episodes.

Parameter	Type	Description
session_key	basestring	The session key that is given by splunkd when you log in. If you do not have a session key, pass in None, but you will need to provide username and password credentials.
username	basestring	Your username.
password	basestring	Your password.
logger	logger	A place to log actions in an existing logger. If you do not have a logger, then the ITSI logger is used.

Raises

Type Error - Raised when the session_key is not a basestring type or when the session_key is not valid.

Value Error - Raised when the session_key is a zero-length string, or when the username and password are empty strings and the session_key is of type None.

Returns

An EventGroup instance.

Return type

EventGroup.

create_comment(group_id, comment)

Add a new comment, given an episode ID. Duplicate comments are not allowed for any given episode.

Parameter	Type	Description
group_id	basestring	An episode ID.
comment	basestring	A comment to add to the episode.

Raises

Type Error - Raised when the group_id or comment are empty strings.

Returns

The episode ID, the comment ID, and the comment.

Return type

dictionary

create_tag(*args)

Create a tag, given an episode ID.

Parameter	Type	Description
group_id	basestring	An episode ID.
tag_value	basestring	New value for the tag.
raise_exceptions	bool	Raise an exception. By default this value is False

Raises

Type Error - Raised when the group_id or tag_value is an empty string.

Returns

The episode ID, the new tag, and the the tag ID.

Return type

dictionary.

delete_all_tags(group_id)

Delete all of the tags associated with an episode, given an episode ID.

Parameter	Type	Description
group_id	basestring	An episode ID.

Raises

Type Error - Raised when the group_id is an empty string.

Returns

Nothing.

delete_tag(tag_id)

Delete the tag value, given a tag ID.

Parameter	Type	Description
tag_id	basestring	The ID of the tag to be retrieved.

Raises

Type Error - Raised when the tag_id is an empty string.

Returns

Nothing.

delete_ticket_info(group_ids, ticket_system, ticket_id)

Delete external ticket information, given a list of episode IDs.

Parameter	Type	Description
group_ids	basestring or list	A comma-separated string of episode IDs, or a list of episode IDs.
ticket_system	basestring	The name of an external ticket system.
ticket_id	basestring	The external ticket ID.

Raises

Type Error - Raised when group_ids is not of type basestring or of type list.

Value Error - Raised when group_ids is an empty string or list.

Returns

The episode IDs of successful and failed deletions.

Return type

dictionary.

get_all_comments(group_id)

Get all of the comments associated with an episode, given an episode ID.

Parameter	Type	Description
group_id	basestring	An episode ID.

Raises

Type Error - Raised when the group_id is an empty string.

Returns

All of the comments corresponding to the episode ID.

Return type

list.

get_all_tags(group_id)

Get all of the tags, given an episode ID.

Parameter	Type	Description
group_id	basestring	An episode ID.

Raises

Type Error - Raised when group_id is an empty string.

Returns

All of the existing tags for a given episode.

Return type

list.

get_comment(comment_id)

Get the comment, given a comment ID.

Parameter	Type	Description
comment_id	basestring	The ID of the comment to get.

Raises

Type Error - Raised when the comment_id is an empty string.

Returns

The comment corresponding to the ID.

Return type

basestring.

get_owner(*args, **kwargs)

Return the owners, given a list of episodes or episode IDs.

Parameter	Type	Description
groups	list of dicts	Each dictionary in the list represents an episode that was sent by Splunk as an outcome of a custom action. The get_group() method in the CustomGroupActionBase class generates such an item.
group_ids	basestring or list	The unique ID of an episode.
split_by	basestring	If group_ids is of type basestring, then it is split into a list of episode IDs. By default, ',' separates the episode IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when groups is not of type basestring or of type list.

Value Error - Raised when both groups and group_ids are of type None.

Returns

The episode IDs and corresponding owners.

Return type

list of tuples.

get_status(*args, **kwargs)

Return the statuses, given a list of episodes or episode IDs.

Parameter	Type	Description
groups	list of dicts	Each dictionary in the list represents an episode that was sent by Splunk as an outcome of a custom action. The get_group() method in the CustomGroupActionBase class generates such an item.
group_ids	basestring or list	The unique ID of an episode.
split_by	basestring	If group_ids is of type basestring, then it is split into a list of episodes IDs. By default, ',' separates the episode IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when groups is not of type list.

Value Error - Raised when both groups and groups_ids are of type None.

Returns

The episode IDs and corresponding statuses.

Return type

list of tuples.

get_severity(*args, **kwargs)

Return the severities, given a list of episodes or episode IDs.

Parameter	Type	Description
groups	list of dicts	Each dictionary in the list represents an episode that was sent by ITSI as an outcome of a custom action. The get_group() method in the CustomGroupActionBase class generates such an episode.
group_ids	basestring / list	The unique ID of an episode.
split_by	basestring	If group_ids is of type basestring, then it is split into a list of episode IDs. By default, ',' separates the episode IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when groups is not of type basestring or of type list.

Value Error - Raised when both groups and group_ids are of type None.

Returns

The episode IDs and corresponding severities.

Return type

list of tuples.

get_tag(tag_id)

Get the value of a tag, given a tag ID.

Parameter	Type	Description
tag_id	basestring	The ID of the tag to be retrieved.

Raises

Type Error - Raised when the tag_id is an empty string.

Returns

The tag value corresponding to the tag ID.

Return type

basestring.

update(*args, **kwargs)

Update the status, severity, and owner of each episode individually.

Parameter	Type	Description
blob	list / dict	A list of dicts containing episode IDs and the severity, status, and/or owner that they should be updated to.
split_by	basestring	If the group_ids in blob is of type basestring, then it is split into a list of episode IDs. By default, ',' separates the episode IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Key Error - Raised when the group_ids key is missing from the blob dictionary.

Type Error - Raised when blob is neither of type list nor of type dictionary.

Value Error - Raised when blob is empty.

Returns

The episode ID schemas with updated fields, in the order of input.

Return type

dictionary.

update_owner(*args, **kwargs)

Update the owner of each episode, given a list of episode IDs.

Parameter	Type	Description
group_ids	basestring or list	A comma-separated string of episode IDs or a list of episode IDs.
owner	basestring	The owner of the episode.
split_by	basestring	If the group_ids is of type basestring, then it is split into a list of episode IDs. By default, ',' separates the episode IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when group_ids is neither of type basestring nor of type list.

Value Error - Raised when group_ids is an empty list, or when owner is not a valid string.

Returns

The episode ID schemas with updated owners, in the order of input.

Return type

dictionary.

update_severity(*args, **kwargs)

Update the severity value of each episode, given a list of episode IDs.

Parameter	Type	Description
group_ids	basestring or list	A comma-separated string of episode IDs, or a list of episode IDs.
severity	basestring	One of the supported severity values.
split_by	basestring	If the group_ids is of type basestring, then it is split into a list of episode IDs. By default, ',' separates the episode IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when group_ids is neither of type basestring nor of type list.

Value Error - Raised when group_ids is an empty list, or when severity is not a valid string.

Returns

The episode ID schemas with updated severities, in the order of input.

Return type

dictionary.

update_status(*args, **kwargs)

Update the status of each episode, given a list of episode IDs.

Parameter	Type	Description
group_ids	basestring or list	A comma-separated string of episode IDs, or a list of episode IDs.
status	basestring	One of the supported statuses.
split_by	basestring	If the group_ids is of type basestring, then it is split into a list of episode IDs. By default, ',' separates the episode IDs.
**kwargs	dict	A dictionary with the keys earliest_time and latest_time with corresponding values.

Raises

Type Error - Raised when group_ids is neither of type basestring nor of type list.

Value Error - Raised when group_ids is an empty list, or when status is not a valid string.

Returns

The episode ID schemas with updated statuses, in the order of input.

Return type

dictionary.

update_tag(*args)

Update the tag, given an episode ID and a tag ID.

Parameter	Type	Description
group_id	basestring	An episode ID.
tag_id	basestring	The tag ID.
tag_value	basestring	The new value for the tag.

Raises

Type Error - Raised when the group_id or tag_id are empty strings.

Returns

The committed value.

Return type

dictionary.

update_ticket_info(*args, **kwargs)

Update episodes with external ticket information, given a list of episode IDs.

Parameter	Type	Description
group_ids	basestring or list	A comma-separated string of episode IDs, or a list of episode IDs.
ticket_system	basestring	The name of an external ticket system.
ticket_id	basestring	The external ticket ID.
ticket_url	basestring	The URL to reach the external ticket.
**kwargs	dict	A dictionary of additional parameters to add to the ticket information.

Raises

Type Error - Raised when the group_ids is not of type basestring or of type list.

Value Error - Raised when the group_ids is an empty string or list.

Returns

The episode IDs of successful and failed updates.

Return type

dictionary.

add_drilldown(self, group_id, drilldown)

Adds drilldown to an episode.

Parameter	Type	Description
group_id	basestring	The ID of the episode where add_drilldown is operated on.
drilldown	dict	The drilldown data that is added.

Raises

Attribute Error - Raised when the group_id not available.

Value Error - Raised when drilldown data is not a dictionary with link and name.

Returns

Return dictionary which holds updated keys.

Return type

dictionary.

update_drilldown(self, group_id, drilldown)

Updates a drilldown for an episode.

Parameter	Type	Description
group_id	basestring	The ID of the episode that owns the updated drill down.
drilldown	dict	The drilldown that is updated.

Raises

Value Error - Raised when drilldown data is not a dictionary with link and name.

Returns

Return dictionary which holds updated keys.

Return type

dictionary.

delete_drilldown(self, group_id, drilldown)

Deletes a drilldown for an episode.

Parameter	Type	Description
group_id	basestring	The ID of the episode that owns the deleted drill down.
drilldown	dict	The drilldown that is deleted.

Raises

Value Error - Raised when drilldown data is not a dictionary with link and name.

Returns

Return dictionary which holds updated keys.

Return type

dictionary.