Splunk® IT Service Intelligence

Event Analytics Manual

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.
Last modified on 28 April, 2023
Use the Notable Event Actions SDK  

This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.11.0, 4.11.1, 4.11.2, 4.11.3, 4.11.4, 4.11.5, 4.11.6, 4.12.0 Cloud only, 4.12.1 Cloud only, 4.12.2 Cloud only, 4.13.0, 4.13.1, 4.13.2, 4.13.3, 4.14.0 Cloud only, 4.14.1 Cloud only, 4.14.2 Cloud only, 4.15.0, 4.15.1, 4.15.2, 4.15.3, 4.16.0 Cloud only, 4.17.0, 4.17.1, 4.18.0, 4.18.1, 4.19.0, 4.19.1

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters