Modify episode fields through the REST API

In addition to modifying episode fields directly within Episode Review in IT Service Intelligence (ITSI), you can also use the REST API to make changes to episode fields. The ITSI Event Management Interface encapsulates CRUD operations on Event Analytics objects, including episodes, aggregation policies, and correlation searches. For the full reference, see Event Management Interface in the REST API Reference manual.

Update the severity of an episode

The following example changes an episode's severity to 6 (Critical):

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/{episode_id}/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"severity": "6"}' 

The request returns the ID of the updated episode.

Default episode severity codes:

• 1 - Info
• 2 - Normal
• 3 - Low
• 4 - Medium
• 5 - High
• 6 - Critical

The severity codes are controlled by $SPLUNK_HOME/etc/apps/SA-ITOA/default/itsi_notable_event_severity.conf. For more information about what each severity means and how to customize the file, see Customize episode severities in ITSI.

Update the assignee of an episode

The following example changes an episode's assignee to "Jeff":

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/{episode_id}/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"owner": "Jeff"}' 

The request returns the ID of the updated episode.

Update the status of an episode

The following example changes an episode's status to 2 (In Progress):

curl -k -u admin:password https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/{episode_id}/?is_partial_data=1 -X POST -H "Content-Type:application/json" -d '{"status": "2"}' 

The request returns the ID of the updated episode.

Default episode status codes:

• 1 - New
• 2 - In Progress
• 3 - Pending
• 4 - Resolved
• 5 - Closed

The status codes are controlled by $SPLUNK_HOME/etc/apps/SA-ITOA/default/itsi_notable_event_status.conf. For more information about what each status means and how to customize the file, see Customize episode statuses in ITSI.

Update episode fields and send events to the Rules Engine

When an API call is made to notable_event_group, only values in the in the itsi_notable_group_user collection are updated. If these updated fields need to be processed by the Rules Engine, send an episode event to the itsi_tracked_alerts index.

The following example shows how to make a request to update episode fields and send an event to the rules engine:

curl -k -u admin:5up3rn0va https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group/{episode_id}?episode_update_policy_id={policy_id} -X POST -H "Content-Type:application/json" -d '{"_key":"<episode_id>","status":"3","itsi_policy_id":"<itsi_policy_id>"}' 

You can update the status, severity, or owner fields with this API. Once updated, an event can be sent to the Rules Engine to trigger corresponding actions based on your changes.

Close and break an episode

To break an episode through the REST API, you must send a breaking event to the itsi_tracked_alerts index:

curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/SA-ITOA/event_management_interface/notable_event_group?break_group_policy_id={policy_id} -X POST --data '{"_key":"{episode_id}","status":"5","title":"splunkd_access","description":"None","severity":"1","owner":"unassigned"}' --header "Content-Type: application/json"

Ensure that the data payload has all the required field:

• _key
• status
• title
• description
• severity
• owner

The REST call updates the episode status to Closed in the itsi_notable_group_user KV store collection and sends a breaking event to the itsi_tracked_alerts index. Upon receiving the breaking event, the Rules Engine breaks the episode and marks it as inactive in the itsi_notable_group_system KV store collection. Any new event grouped by that aggregation policy is added to a new episode.

The "Closed" status value, which is 5 by default, is defined in $SPLUNK_HOME/etc/apps/SA-ITOA/default/itsi_notable_event_status.conf. If you update this value, you must also update the REST API body with the correct status value.