Splunk® IT Service Intelligence

Administration Manual

Acrobat logo Download manual as PDF


Splunk IT Service Intelligence version 4.0.x reached its End of Life on January 19, 2021. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see Plan an upgrade of IT Service Intelligence.
This documentation does not apply to the most recent version of ITSI. Click here for the latest version.
Acrobat logo Download topic as PDF

Notable Event Actions SDK reference

A new, refactored version of the Notable Event Actions SDK, called the ITSI Event Management SDK, is available on GitHub here. This documentation pertains to the legacy Notable Event Actions SDK that continues to be packaged with ITSI. Scripts based on the legacy SDK will continue to work, however, it is recommended to eventually port your scripts to use the new SDK because only the new SDK will be updated going forward.

The Notable Events Action SDK contains two main modules.

  • custom_event_action_base
  • eventing

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

Use the eventing module to work with 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.

class custom_event_action_base.CustomEventActionBase(settings, logger)

Import the custom_event_action_base module when you want to consume the output of your modalert. In your script, inherit your class from the CustomEventActionBase class. Use the get_event() method to work on the event that triggered your script.

Parameter Type Description
settings basestring or dict 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 CustomEventActionBase instance.
Return type
CustomEventActionBase.

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_event_id(notable_data)

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

Parameter Type Description
notable_data basestring Notable event object from which the event_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.
Return type
basestring.

get_config()

Gets the configuration based on the settings.

Returns
The configuration that comes with the settings.
Return type
Configuration.

get_event()

Gets the events 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 events.

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 dict type object until all received events are returned.
Return type
dict.

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 operate on 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.

create_comment(event_id, comment)

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

Parameter Type Description
event_id basestring An event ID.
comment basestring A comment to add to the event.
Raises
Type Error - Raised when the event_id or comment are empty strings.
Returns
The event ID, the comment ID, and the comment.
Return type
dict.

create_tag(*args)

Create a tag, given an event ID.

Parameter Type Description
event_id basestring An event 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 event_id or tag_value is an empty string.
Returns
The event ID, the new tag, and the the tag ID.
Return type
dict.

delete_all_comments(event_id)

Delete all of the comments associated with an event, given the event ID.

Parameter Type Description
event_id basestring An event ID.
Raises
Type Error - Raised when the event_id is an empty string.
Returns
Nothing.

delete_all_tags(event_id)

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

Parameter Type Description
event_id basestring An event ID.
Raises
Type Error - Raised when the event_id is an empty string.
Returns
Nothing.

delete_comment(comment_id)

Delete the comment associated with the comment ID.

Parameter Type Description
comment_id basestring The ID of the comment to delete.
Raises
Type Error - Raised when the comment_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(event_ids, ticket_system, ticket_id)

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

Parameter Type Description
event_ids basestring or list A comma separated string of event IDs, or a list of event IDs.
ticket_system basestring The name of an external ticket system.
ticket_id basestring The external ticket ID.
Raises
Type Error - Raised when the event_ids is not of type basestring or of type list.
Value Error - Raised when the event_ids is an empty string or list.
Returns
The event IDs of successful and failed deletions.
Return type
dict.

get_all_comments(event_id)

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

Parameter Type Description
event_id basestring An event ID.
Raises
Type Error - Raised when the event_id is an empty string.
Returns
All of the comments corresponding to the event ID.
Return type
list.

get_all_tags(event_id)

Get all of the tags, given an event ID.

Parameter Type Description
event_id basestring An event ID.
Raises
Type Error - Raised when event_id is an empty string.
Returns
All of the existing tags for a given event.
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 events or event IDs.

Parameter Type Description
events list of dicts Each dict in the list represents an event that was sent by Splunk as an outcome of a Custom Action. The get_event() method in the CustomEventActionBase class generates such an item.
event_ids basestring or list A unique ID for 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 dict 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 dict in the list represents an event that was sent by Splunk as an outcome of a Custom Action. The get_event() method in the CustomEventActionBase class generates such an item.
event_ids basestring or list A unique ID for 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 dict 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 dict in the list represents an event that was sent by ITSI as an outcome of a Custom Action. The get_event() method in the CustomEventActionBase class generates such an event.
event_ids basestring / list A unique ID for 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 dict 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.

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 event individually.

Parameter Type Description
blob list / dict A list of dicts containing event IDs and the severity, status, and/or owner that they should be updated to.
split_by basestring If the event_ids in blob is of type basestring, then it is split into a list of event IDs. By default, ',' separates the event IDs.
**kwargs dict A dict with the keys earliest_time and latest_time with corresponding values.
Raises
Key Error - Raised when the event_ids key is missing from the blob dict.
Type Error - Raised when blob is neither of type list nor of type dict.
Value Error - Raised when blob is empty.
Returns
The event ID schemas with updated fields, in the order of input.
Return type
dict.

update_comment(*args)

Update a comment, given a comment ID and an event ID. Duplicate comments are not allowed for any given event.

Parameter Type Description
event_id basestring An event ID.
comment_id basestring The ID of the comment to update.
comment basestring The new value for the comment.
Raises
Type Error - Raised when the event_id or comment_id is an empty string.
Returns
The committed comment value.
Return type
dict.

update_owner(*args, **kwargs)

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

Parameter Type Description
event_ids basestring or list A comma separated string of event IDs or a list of event IDs.
owner basestring The owner of the event.
split_by basestring If the 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 dict with the keys earliest_time and latest_time with corresponding values.
Raises
Type Error - Raised when event_ids is neither of type basestring nor of type list.
Value Error - Raised when event_ids is an empty list, or when owner is not a valid string.
Returns
The event ID schemas with updated owners, in the order of input.
Return type
dict.

update_severity(*args, **kwargs)

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

Parameter Type Description
event_ids basestring or list A comma separated string of event IDs, or a list of event IDs
severity basestring One of the supported severity values
split_by basestring If the 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 dict with the keys earliest_time and latest_time with corresponding values.
Raises
Type Error - Raised when event_ids is neither of type basestring nor of type list.
Value Error - Raised when event_ids is an empty list, or when severity is not a valid string.
Returns
The event ID schemas with updated severities, in the order of input.
Return type
dict.

update_status(*args, **kwargs)

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

Parameter Type Description
event_ids basestring or list A comma separated string of event IDs, or a list of event IDs
status basestring One of the supported statuses
split_by basestring If the 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 dict with the keys earliest_time and latest_time with corresponding values.
Raises
Type Error - Raised when event_ids is neither of type basestring nor of type list.
Value Error - Raised when event_ids is an empty list, or when status is not a valid string.
Returns
The event ID schemas with updated statuses, in the order of input.
Return type
dict.

update_tag(*args)

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

Parameter Type Description
event_id basestring An event ID.
tag_id basestring The tag ID.
tag_value basestring The new value for the tag.
Raises
Type Error - Raised when the event_id or tag_id are empty strings.
Returns
The committed value.
Return type
dict.

update_ticket_info(*args, **kwargs)

Update events with external ticket information, given a list of event IDs.

Parameter Type Description
event_ids basestring or list A comma separated string of event IDs, or a list of event 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 dict of additional parameters to add to the ticket information.
Raises
Type Error - Raised when the event_ids is not of type basestring or of type list.
Value Error - Raised when the event_ids is an empty string or list.
Returns
The event IDs of successful and failed updates.
Return type
dict.

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

Import this class to operate on an ITSI Event Group.

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

add_drilldown(self, group_id, drilldown)

Adds drilldown to a notable event group.

Parameter Type Description
group_id basestring The ID of the group 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 dict with link and name.
Returns
Return dict which holds updated keys.
Return type
dict.

update_drilldown(self, group_id, drilldown)

Updates a drilldown for a notable event group.

Parameter Type Description
group_id basestring The ID of the group who owns the drilldown that is updated.
drilldown dict The drilldown that is updated.
Raises
Value Error - Raised when drilldown data is not dict with link and name.
Returns
Return dict which holds updated keys.
Return type
dict.

delete_drilldown(self, group_id, drilldown)

Deletes a drilldown for a notable event group.

Parameter Type Description
group_id basestring The ID of the group who owns the drilldown that is deleted.
drilldown dict The drilldown that is deleted.
Raises
Value Error - Raised when drilldown data is not dict with link and name.
Returns
Return dict which holds updated keys.
Return type
dict.
Last modified on 04 April, 2019
PREVIOUS
Use the Notable Event Actions SDK 		  NEXT
Notable event aggregation policies overview for ITSI

This documentation applies to the following versions of Splunk® IT Service Intelligence: 4.0.0, 4.0.1, 4.0.2, 4.0.3, 4.0.4, 4.1.0, 4.1.1, 4.1.2, 4.1.5

Was this documentation topic helpful?

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