
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.
- Type Error - Raised when
- Returns
- A
CustomEventActionBase
instance.
- A
- 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.
- Not Implemented Error - Raised when the
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.
- Type Error - Raised if
- Returns
- The
event_id
.
- The
- 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 thesession_key
is not valid. - Value Error - Raised when the
session_key
is a zero-length string, or when theusername
andpassword
are empty strings and thesession_key
is of type None.
- Type Error - Raised when the
- Returns
- An
EventMeta
instance.
- An
- 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 thesession_key
is not valid. - Value Error - Raised when the
session_key
is a zero-length string, or when theusername
andpassword
are empty strings and thesession_key
is of type None.
- Type Error - Raised when the
- Returns
- An
Event
instance.
- An
- 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
orcomment
are empty strings.
- Type Error - Raised when the
- 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
ortag_value
is an empty string.
- Type Error - Raised when the
- 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.
- Type Error - Raised when the
- 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.
- Type Error - Raised when the
- 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.
- Type Error - Raised when the
- 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.
- Type Error - Raised when the
- 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.
- Type Error - Raised when the
- 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.
- Type Error - Raised when the
- 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.
- Type Error - Raised when
- 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.
- Type Error - Raised when the
- 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
andevent_ids
are of type None.
- Type Error - Raised when
- 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
andevent_ids
are of type None.
- Type Error - Raised when
- 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
andevent_ids
are of type None.
- Type Error - Raised when
- 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.
- Type Error - Raised when the
- 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 theblob
dict. - Type Error - Raised when
blob
is neither of type list nor of type dict. - Value Error - Raised when
blob
is empty.
- Key Error - Raised when the
- 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
orcomment_id
is an empty string.
- Type Error - Raised when the
- 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 whenowner
is not a valid string.
- Type Error - Raised when
- 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 whenseverity
is not a valid string.
- Type Error - Raised when
- 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 whenstatus
is not a valid string.
- Type Error - Raised when
- 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
ortag_id
are empty strings.
- Type Error - Raised when the
- 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.
- Type Error - Raised when the
- 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 thesession_key
is not valid. - Value Error - Raised when the
session_key
is a zero-length string, or when theusername
andpassword
are empty strings and thesession_key
is of type None.
- Type Error - Raised when the
- Returns
- An
EventGroup
instance.
- An
- 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.
- Attribute Error - Raised when the
- 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.
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
Feedback submitted, thanks!