CSV Data Export

πŸ“˜

Note:

Data exports are only available for Enterprise-level FireHydrant accounts.

Overview

The data export feature can incorporate granular FireHydrant incident data into your organization's custom reports and data pipelines. After installing this integration, you can retrieve data periodically exported by FireHydrant in CSV format from the FireHydrant API.

How it works

Data export tile on the integrations page

Data export tile on the integrations page

  1. First, navigate to the Integrations page and enable the Data Exports. This instructs our system to generate nightly exports of your account's activity. There are no other prerequisites besides requiring Owner permissions to access integrations.
  2. Once enabled, generating the first reports typically takes 24 hours (usually happens overnight).
  3. Once your first reports are generated, you will use the export requests API endpoint to request data, which will return all generated nightly exports and links to retrieve them.
    • These links are populated with temporary access tokens expiring 5 minutes after the request. If the token expires, you must remake the same API call above to refresh the links with new tokens.
  4. You will be able to access your CSV reports via the returned links.
  5. All reports are expunged after 30 days, so for example, if today is April 1st, any reports returned prior to March 2nd will have been cleared, even if the URLs are returned. Accessing those URLs will result in a 404 status.

πŸ“˜

Note:

Each night's reports will report on new activity since the last report, with some overlap to prevent lost data. Upon first activating this integration, the first reports will not include all historical data in the system, only activity from the time the exports were enabled.

Using the data export integration

Once configured, the data will automatically be exported in CSV format daily. Retrieving exported data is a two-step process.

  1. First, retrieve a list of all the export requests that are new since you last checked for data.
    1. The newer_than parameter in the API call specifies all reports, not incidents, generated after that date. We recommend the incidents API endpoint to fetch data by incident dates.
curl --request GET \
  --url 'https://api.firehydrant.io/v1/integrations/data_export/export_requests?newer_than=2023-04-01T00%3A00%3A00' \
  --header 'Authorization: TOKEN_HERE' \
  --header 'Content-Type: application/json' | jq

{
  "data": [
    {
      "id": "a9fc8336-b3d0-4bc0-8d74-29f3c7508576",
      "created_at": "2023-04-02T10:11:01.492Z",
      "window_starts_at": "2023-03-30T07:35:24.116Z",
      "window_ends_at": "2023-03-31T07:35:24.116Z",
      "source": "text/csv+incident-20220525",
      "status": "completed",
      "url": "https://storage.googleapis.com/fh-data-export-production/?GoogleAccessId=REDACTED&Expires=1705619519&Signature=REDACTED"
    },
    ...

πŸ“˜

Note:

When inserting datetimes into the URL, you will need to URL-encode the colons to %3A. For example, 2022-11-22T00:00:00 turns into 2022-11-22T00%3A00%3A00.

  1. The request to the /data_export/export_requests endpoint will return a list of exports, each with a url field that can be used to fetch the raw exported data, as well as a source field to inform you what sort of data it is. For more information, see the next section on export data format.
    1. The URLs for each report contain temporary access tokens and expire after 5 minutes. If you need to access those reports after expiration, you must remake the API call above.
    2. Data exports are expunged from the platform after 30 days. So, for example, if today is April 1st, all exports dated March 1st and prior will have been expunged. Accessing those URLs will result in a 404.
    3. Incident data is intentionally overlapped between exports to ensure no incident data is missed. You will need to deduplicate redundant data as part of data pre-processing.

For additional details, see the data export API documentation.

Export data format

The following is the data dictionary for exported data. The headings (e.g., text/csv+incident-20220525 are the source types for each type of data report. Some of the field types that store duration use ISO 8061 format. For details on the specification, see this resource on ISO 8601 duration encoding.

All formats are in text/csv.

text/csv+incident-20220525

These items represent incidents in FireHydrant.

NameTypeDescription
idStringThe unique identifier for this incident.
account_idStringThe id for the account that owns this incident
organization_idStringThe id for the organization that owns this incident
created_atDateTimeThe utc date and time when this incident was created
updated_atDateTimeThe utc date and time when this incident was last directly updated
numberStringThe incident number for this incident.
nameStringThe name/title of this incident.
severityStringThe currently assigned severity.
priorityStringThe currently assigned priority.
started_atDateTimeThe time at which the incident started.
detected_atDateTimeThe time at which the incident entered the detected milestone.
acknowledged_atDateTimeThe time at which the incident entered the acknowledged milestone.
investigating_atDateTimeThe time at which the incident entered the investigating milestone.
identified_atDateTimeThe time at which the incident entered the identified milestone.
mitigated_atDateTimeThe time at which the incident entered the mitigated milestone.
resolved_atDateTimeThe time at which the incident entered the resolved milestone.
retrospective_started_atDateTimeThe time at which the incident entered the retrospective_started milestone.
retrospective_completed_atDateTimeThe time at which the incident entered the retrospective_completed milestone.
opened_atDateTimeThe time at which the incident was opened.
started_byStringThe actor that opened the incident.
active_durationStringISO 8601 Duration that the incident has been or was active.

text/csv+incident_role_assignment-20220525

Entities representing incident role assignments

NameTypeDescription
idStringThe unique identifier for this incident.
account_idStringThe id for the account that owns this incident
organization_idStringThe id for the organization that owns this incident
created_atDateTimeThe utc date and time when this incident was created
updated_atDateTimeThe utc date and time when this incident was last directly updated
statusStringIs the role assignment currently active (assigned)
incident_role_idStringUnique identifier for the role.
incident_role_nameStringName of the role.
incident_idStringUnique identifier for the associated incident.
assigned_user_idStringUnique identifier for the assigned user.
assigned_user_nameStringName of the assigned user.

text/csv+incident_event-20220525

Entities representing the stream of events related to an incident.

NameTypeDescription
idStringThe unique identifier for this incident.
account_idStringThe id for the account that owns this incident
organization_idStringThe id for the organization that owns this incident
created_atDateTimeThe utc date and time when this incident was created
updated_atDateTimeThe utc date and time when this incident was last directly updated
incident_idStringUnique identifier of the associated incident.
created_by_nameStringName of the actor that cause the event.
typeStringThe type of event
event_details_schemaStringJSON-encoded JSONSchema of the details of the event. The event_details field should conform to this schema and the schema has descriptive comments about the embedded fields.
event_detailsStringJSON-encoded object containing the details for this event based on it's type.

text/csv+incident_impact-20220525

Entities representing the impacted components during the incident.

NameTypeDescription
idStringThe unique identifier for this incident.
account_idStringThe id for the account that owns this incident
organization_idStringThe id for the organization that owns this incident
created_atDateTimeThe utc date and time when this incident was created
updated_atDateTimeThe utc date and time when this incident was last directly updated
incident_idStringUnique identifier of the associated incident.
impacted_idStringThe unique identifier for the impacted component
impacted_typeStringThe type of the component (e.g. service, functionality, or environment)
impacted_slugStringThe slug of the component
condition_nameStringThe condition it was marked as.

text/csv+retrospective-20220525

Entities representing incident retrospectives

NameTypeDescription
idStringThe unique identifier for this incident.
account_idStringThe id for the account that owns this incident
organization_idStringThe id for the organization that owns this incident
created_atDateTimeThe utc date and time when this incident was created
updated_atDateTimeThe utc date and time when this incident was last directly updated
nameStringName/title of the retrospective.
summaryStringLonger description of the retrospective.
tagsStringJSON-encoded array of tags.
incident_idStringId of associated incident.
additional_detailsStringFreeform information about the retrospective.
questionsStringJSON array containing question responses with question title, body, and unique question type id. Responses with the same type id are logically responses to the same question even if the title varies.

Incident Event Details Schemata

Type: IncidentStatus

{
  "type": "object",
  "properties": {
    "new_status": {
      "type": [
        "string"
      ],
      "$comment": "The status the incident is moving to."
    }
  }
}

Type: BulkMilestoneUpdate

{
  "type": "object",
  "properties": {
    "original_milestone": {
      "type": [
        "string"
      ],
      "$comment": "The name of the milestone prior to this update"
    },
    "current_milestone": {
      "type": [
        "string"
      ],
      "$comment": "The name of the milestone due to this update"
    }
  }
}

Type: ImpactUpdate

{
  "type": "object",
  "properties": {
    "update_type": {
      "type": [
        "string"
      ],
      "$comment": "Whether this event represents an addition, removal, update, or no-op."
    },
    "impacted_type": {
      "type": [
        "string"
      ],
      "$comment": "The type of the item for which impact was updated"
    },
    "impacted_id": {
      "type": [
        "string"
      ],
      "$comment": "The id of the item for which impact was updated"
    },
    "old_condition_name": {
      "type": [
        "string",
        "null"
      ],
      "$comment": "The name of the previous condition before this update"
    },
    "new_condition_name": {
      "type": [
        "string",
        "null"
      ],
      "$comment": "The name of the condition set in this update"
    }
  }
}

Type: GeneralUpdate

{
  "type": "object",
  "properties": {
    "description": {
      "type": [
        "string"
      ],
      "$comment": "Description of the event"
    }
  }
}

Type: Note

{
  "type": "object",
  "properties": {
    "body": {
      "type": [
        "string"
      ],
      "$comment": "The content of the note."
    }
  }
}

Type: RoleUpdate

{
  "type": "object",
  "properties": {
    "role_assignment_id": {
      "type": [
        "string"
      ],
      "$comment": "Id of role assignment. See the incident role assignment docs."
    },
    "incident_role_name": {
      "type": [
        "string"
      ],
      "$comment": "Name of the role refrenced in this update."
    },
    "operation": {
      "type": [
        "string"
      ],
      "$comment": "Type of operation performed in this update."
    },
    "assigned_user_id": {
      "type": [
        "string"
      ],
      "$comment": "Id of user (un)assigned in this update."
    },
    "assigned_user_name": {
      "type": [
        "string"
      ],
      "$comment": "Name of user (un)assigned in this update."
    }
  }
}

Type: ChatMessage

{
  "type": "object",
  "properties": {
    "chat_user_id": {
      "type": [
        "string"
      ],
      "$comment": "The chat-provider user id of the user who sent the message."
    }
  }
}

Type: AddTaskList

{
  "type": "object",
  "properties": {
    "task_list_id": {
      "type": [
        "string"
      ],
      "$comment": "ID of task list"
    },
    "task_list_name": {
      "type": [
        "string"
      ],
      "$comment": "Name of task list"
    }
  }
}

Type: RunbookAttachment

{
  "type": "object",
  "properties": {
    "runbook_id": {
      "type": [
        "string"
      ],
      "$comment": "Id of the runbook that was attached."
    },
    "runbook_name": {
      "type": [
        "string"
      ],
      "$comment": "Name of the runbook that was attached."
    }
  }
}

Type: RunbookStepExecutionUpdate

{
  "type": "object",
  "properties": {
    "description": {
      "type": [
        "string"
      ],
      "$comment": "A description of the update"
    },
    "step_execution_id": {
      "type": [
        "string"
      ],
      "$comment": "Unique ID for this invocation of the step."
    },
    "step_id": {
      "type": [
        "string"
      ],
      "$comment": "Id of the step."
    },
    "step_name": {
      "type": [
        "string"
      ],
      "$comment": "Name of the step."
    }
  }
}

Type: TaskUpdate

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": [
        "string"
      ],
      "$comment": "Unique id of the task being updated"
    },
    "task_summary": {
      "type": [
        "string"
      ],
      "$comment": "Summary of the task being updated"
    },
    "task_description": {
      "type": [
        "string"
      ],
      "$comment": "Description of the task being updated"
    },
    "operation": {
      "type": [
        "string"
      ],
      "$comment": "Type of of update"
    },
    "new_state": {
      "type": [
        "string"
      ],
      "$comment": "New state of the task after this update"
    }
  }
}

Type: TeamAssignment

{
  "type": "object",
  "properties": {
    "team_id": {
      "type": [
        "string"
      ],
      "$comment": "Unique id of the team being being assigned"
    },
    "team_name": {
      "type": [
        "string"
      ],
      "$comment": "Name of the team being being assigned"
    }
  }
}

Type: TicketUpdate

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": [
        "string"
      ],
      "$comment": "Unique id of the task being updated"
    },
    "ticket_type": {
      "type": [
        "string"
      ],
      "$comment": "Type of ticket, eg incident, task, etc"
    },
    "ticket_provider_id": {
      "type": [
        "string",
        "null"
      ],
      "$comment": "Id of ticket in non-firehydrant ticketing provider (eg Jira) if the ticket is synced."
    }
  }
}

Type: GenericResourceChange

{
  "type": "object",
  "properties": {
    "operation": {
      "type": [
        "string"
      ],
      "$comment": "Nature of operation."
    },
    "resource_type": {
      "type": [
        "string"
      ],
      "$comment": "Type of resource changed."
    },
    "resource_id": {
      "type": [
        "string"
      ],
      "$comment": "Unique id of the resource changed."
    },
    "fields": {
      "type": [
        "object"
      ],
      "$comment": "Object containing changed fields."
    }
  }
}