Accessing and Using Incident Data in Playbook Execution

LAST UPDATED: MARCH 24, 2025

Incident Data Overview

When configuring an investigation playbook, referencing incident data for dynamic data selection is crucial for executing specific actions effectively. For example, it can be used for:

• Communication: Retrieving the incident number and URL to notify relevant parties.

• Validation: Extracting the top-level domain of an email address to check it against a whitelist.

• Data Enrichment: Extracting IP addresses and sending them to a threat intelligence service to retrieve reputation scores.

• Remediation: Retrieving the username and using it to disable the user account in an identity and access management (IAM) system.

To fully leverage these capabilities in an investigation playbook, users must understand how to retrieve incident data.

Retrieving Incident Data

Incident data is retrieved from different JSON paths depending on the initiating trigger for the playbook execution and whether it is accessed within a codeless playbook.

Main Playbook Execution

Main playbook execution refers to the workflow initiated by the On Playbook Start trigger. Users can retrieve incident data for the main playbook execution at $.DataSource.incident, which contains the complete dataset for the incident.

This data is dynamically retrieved at the time of execution, reflecting the most current state of the incident.

Trigger Execution

Trigger execution refers to workflows initiated by any trigger except On Playbook Start, such as On Incident Change and On Playbook Task Error. Users can retrieve incident data for trigger execution at $.Trigger.incident.

This data is dynamically retrieved at the time of execution.

Codeless Playbooks

Within a codeless playbook, incident data is accessible at the paths $.DataSource.incident and $.Trigger.incident. This data is dynamically retrieved during execution, ensuring it reflects the most up-to-date values.

Incident data, whether retrieved from $.DataSource.incident or $.Trigger.incident, is identical.

Retrieving Incident Data Within a Codeless Playbook

Users can follow the steps below to retrieve incident data from a codeless playbook.

1. Add a codeless playbook task to the On Playbook Start trigger.

   

2. Select the Auto Run checkbox, then click the button to save the task.

   

3. Follow these steps to test the playbook.

4. Click the icon to open the codeless playbook.

   

5. Click the View Draft or Edit button.

   

6. Select the task where incident data needs to be retrieved, then click the UNKNOWN_ATTACHMENT icon.

   

RESULT

The incident data can be retrieved at $.DataSource.incident.

Where Is $.Trigger.incident?

If the codeless playbook task is linked to any trigger except On Playbook Start, and that trigger is activated, $.Trigger.incident will be exposed.

Incident Data Model Field

Regardless of the retrieval path, the structure of incident data remains consistent, containing fields such as Creator, ID, IncidentNo, Owner, SeverityName, and Status.

Below is an example of fields available in the incident data model, excluding event and artifact fields.

{
  "ClosedBy": "",
  "ClosedByID": "",
  "ClosedDate": "",
  "Conclusion": "",
  "Creator": "",
  "CreatorID": "",
  "Description": "",
  "Disposition": "",
  "Dynamic fields": "",
  "ID": "",
  "IncidentEndedOn": "",
  "IncidentNo": "",
  "IncidentSource": "",
  "IncidentTypeID": "",
  "IncidentTypeName": "",
  "LastModified": "",
  "Owner": "",
  "OwnerID": "",
  "OwnerSite": "",
  "OwnerSiteID": "",
  "RawData": "",
  "ReportingDate": "",
  "ReportingDateUTC": "",
  "SeverityID": "",
  "SeverityName": "",
  "SLADueDate": "",
  "Status": "",
  "StatusID": "",
  "TimeZone": "",
  "Title": "",
  "File": [
    {
      "FileDescription": "",
      "FileExtension": "",
      "FileId": "",
      "FileName": "",
      "FileType": ""
    }
  ],
  "Investigation Team": [
    {
      "Access": "",
      "Investigator": ""
    }
  ],
  "Linked Incident": [
    {
      "Date Created": "",
      "Incident Number": "",
      "Incident Type Id": "",
      "Incident Type Name": "",
      "Owner": "",
      "Status": "",
      "Title": ""
    }
  ],
  "Note": [
    {
      "Content": ""
    }
  ],
  "Playbook": [
    {
      "PlaybookName": ""
    }
  ],
  "TacticTechniques": [
    {
      "addedUTCTime": "",
      "IsIncidentTTP": "",
      "TacticID": "",
      "TacticMID": "",
      "TacticName": "",
      "TechniqueId": "",
      "TechniqueMid": "",
      "TechniqueName": ""
    }
  ]
}

When users run the Test Playbook function on a real incident with event data, linked artifacts, and/or additional information added from the incident workspace, the number of incident data fields may differ.

Exposing Additional Fields and Populating with Data

When configuring an investigation playbook, users may notice that incident data fields appear empty (showing null values or empty strings) when used for dynamic data retrieval in playbook tasks.

While users can reference these fields for dynamic data selection, it is easier to validate and use the correct JSON paths when those fields contain actual data rather than being empty or null.

Testing the Playbook to Populate with Real Incident Data

Users can populate these fields with real incident data in the following steps:

Before vs. After Testing the Playbook

Populating the Event and Artifacts Fields

If the tested incident is correlated with an event, it will include an event field containing the raw event data. If the correlated event has linked artifacts, the incident will also include an artifacts field in addition to the event field.