Configuring FireHydrant incident data export
Note: Data exports are only available for Enterprise-level FireHydrant accounts. A FireHydrant owner role is required to configure the data export integration.
Overview
The data export feature can be used to incorporate granular FireHydrant incident data into your organization's custom reports and data pipelines. After installing this integration, you will be able to retrieve data periodically exported by FireHydrant in CSV format from the FireHydrant API.
How it works
- First, you'll need to enable the Data Exports on the Integrations page. This instructs our system to start generating nightly exports of your account's activity. See the next section for setup instructions.
- Once enabled, it typically takes 24 hours to generate the first reports (usually happens overnight).
- Once your first reports are generated, you will use the export requests API endpoint to make a request to our system, which will return all of the nightly exports that have been generated, as well as links to retrieve them.
- These links are populated with temporary access tokens expiring 5 minutes after the request. If the token expires, you will need to remake the same API call above to refresh the links with new tokens.
- You will be able to access your CSV reports via the returned links.
- All reports are expunged after 30 days, so for example if today is April 1st, any reports returned from 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.
Installing the data export integration
To begin generating data, first install the Data Export integration from the Integrations section of FireHydrant.
Generating data exports
Once configured, the data will automatically be exported in CSV format on a daily cadence.
Retrieving data exports
Retrieving exported data is a two-step process. First, retrieve a list of all the export requests that are new since you last checked for data:
GET <api host>/v1/integrations/data_export/export_requests?status=completed&newer_than=<datetime of earliest export to consider>
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
.
This will return a list of exports, each of which will have a url field that can be used to fetch the raw exported data. A handy way to cleanly display the response JSON is by using jq
. For example, to see all report exports generated for April 2023 and beyond, and display visually in terminal:
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
- The URLs for each report contain temporary access tokens and expire after 5 minutes. If you need to access those reports after expiration, you will need to remake the API call above.
- The
newer_than
parameter in the API call specifies all new reports generated after that date, not all new incidents after that date. To fetch that data, we recommend using the incidents API endpoint. - Data exports are expunged from the platform after 30 days. So for example, if today is April 1st, then all exports dated March 1st and prior will have been expunged. Clicking on those links will result in a
404
. - Incident data is intentionally overlapped between exports to ensure that 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. 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.
Name | Type | Description |
---|---|---|
id | String | The unique identifier for this incident. |
account_id | String | The id for the account that owns this incident |
organization_id | String | The id for the organization that owns this incident |
created_at | DateTime | The utc date and time when this incident was created |
updated_at | DateTime | The utc date and time when this incident was last directly updated |
number | String | The incident number for this incident. |
name | String | The name/title of this incident. |
severity | String | The currently assigned severity. |
priority | String | The currently assigned priority. |
started_at | DateTime | The time at which the incident started. |
detected_at | DateTime | The time at which the incident entered the detected milestone. |
acknowledged_at | DateTime | The time at which the incident entered the acknowledged milestone. |
investigating_at | DateTime | The time at which the incident entered the investigating milestone. |
identified_at | DateTime | The time at which the incident entered the identified milestone. |
mitigated_at | DateTime | The time at which the incident entered the mitigated milestone. |
resolved_at | DateTime | The time at which the incident entered the resolved milestone. |
retrospective_started_at | DateTime | The time at which the incident entered the retrospective_started milestone. |
retrospective_completed_at | DateTime | The time at which the incident entered the retrospective_completed milestone. |
opened_at | DateTime | The time at which the incident was opened. |
started_by | String | The actor that opened the incident. |
active_duration | String | ISO 8601 Duration that the incident has been or was active. |
text/csv+incident_role_assignment-20220525
Entities representing incident role assignments
Name | Type | Description |
---|---|---|
id | String | The unique identifier for this incident. |
account_id | String | The id for the account that owns this incident |
organization_id | String | The id for the organization that owns this incident |
created_at | DateTime | The utc date and time when this incident was created |
updated_at | DateTime | The utc date and time when this incident was last directly updated |
status | String | Is the role assignment currently active (assigned) |
incident_role_id | String | Unique identifier for the role. |
incident_role_name | String | Name of the role. |
incident_id | String | Unique identifier for the associated incident. |
assigned_user_id | String | Unique identifier for the assigned user. |
assigned_user_name | String | Name of the assigned user. |
text/csv+incident_event-20220525
Entities representing the stream of events related to an incident.
Name | Type | Description |
---|---|---|
id | String | The unique identifier for this incident. |
account_id | String | The id for the account that owns this incident |
organization_id | String | The id for the organization that owns this incident |
created_at | DateTime | The utc date and time when this incident was created |
updated_at | DateTime | The utc date and time when this incident was last directly updated |
incident_id | String | Unique identifier of the associated incident. |
created_by_name | String | Name of the actor that cause the event. |
type | String | The type of event |
event_details_schema | String | JSON-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_details | String | JSON-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.
Name | Type | Description |
---|---|---|
id | String | The unique identifier for this incident. |
account_id | String | The id for the account that owns this incident |
organization_id | String | The id for the organization that owns this incident |
created_at | DateTime | The utc date and time when this incident was created |
updated_at | DateTime | The utc date and time when this incident was last directly updated |
incident_id | String | Unique identifier of the associated incident. |
impacted_id | String | The unique identifier for the impacted component |
impacted_type | String | The type of the component (e.g. service , functionality , or environment ) |
impacted_slug | String | The slug of the component |
condition_name | String | The condition it was marked as. |
text/csv+retrospective-20220525
Entities representing incident retrospectives
Name | Type | Description |
---|---|---|
id | String | The unique identifier for this incident. |
account_id | String | The id for the account that owns this incident |
organization_id | String | The id for the organization that owns this incident |
created_at | DateTime | The utc date and time when this incident was created |
updated_at | DateTime | The utc date and time when this incident was last directly updated |
name | String | Name/title of the retrospective. |
summary | String | Longer description of the retrospective. |
tags | String | JSON-encoded array of tags. |
incident_id | String | Id of associated incident. |
additional_details | String | Freeform information about the retrospective. |
questions | String | JSON 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."
}
}
}