Skip to content
HappyOrNot Documentation

Alerts

Alerts are triggered based on a survey’s alert specifications. If responses given in defined time window meet the criteria of the alert specification, then an alert is triggered. Alert specifications can be edited in the web UI.

Alerts can be fetched for a folder and optionally also for any child folders.

Summary of available resource patterns

CodeURL
GET/v1/folders/:key/alerts

Alert

JSON presentation of alert.

Properties
NameDescription
keyThe identifier of the alert
alertTypeA string representing the alert’s type. Possible values are: negative, indexThreshold and feedbackCount. More alert types might be added in the future without increasing api version.
surveyThe survey that has the alert specification for this alert. Survey’s results are monitored and alerts are triggered based on the alert specification that has been configured for the survey. Only a subset of a full Survey-object properties are provided here.
alertSpecificationThe alert specification of this alert. Alert specifications are configured for folders using the web UI. Alerts that have same alert specification are occurances of same alert being triggered over time. Survey’s results are monitored and alerts are triggered based on the alert specification. This value is useful for grouping alerts.
beginTimePoint of time when alert was opened/triggered. Timestamp with survey’s timezone.
endTimeoptional Point of time when alert was closed. Missing if alert is still open. Timestamp with survey’s timezone.
parameters

Alert parameters. Parameters are a combination of the alert specification parameters and the actual calculated values that triggered the alert.

Some of the parameters are present only for certain alert types. Alert types that have the parameter are listed below the parameter description.

Alert specification’s parameters (configuration values) included in each alert:

negative

true or false. Specifies if this alert was configured to be triggered by negative feedback.

negative | indexThreshold | feedbackCount

windowMin

Minutes. The time window of responses used to evaluate alert conditions

negative | indexThreshold | feedbackCount

threshold

The threshold that needs to be reached for alert to be triggered. Semantics depend on the alert type

negative | feedbackCount

countThreshold

Additional response count threshold.

negative | feedbackCount

thresholdType

String under | over

indexThreshold

responseFilter

Index array. Indexes are from 0 (Very Unhappy) to 3 (Very Happy) for 4 scale and from 0 (Very Unhappy) to 4 (Very Happy) for 5 scale. Responses not in the filter are ignored for this alert.

feedbackCount

responses

count How many responses were given during time window.

negative | indexThreshold | feedbackCount

actual

Actual value of the configured limit/threshold that was exceeded to trigger this alert. Semantics depend on the alert type.

negative | indexThreshold

negativeResponses

count Amount of negative responses during the time window.

negative

Example JSON objects

Index threshold alert

Alert is triggered when the index has been above or below a certain value over a specified time window

{
  "key": 91236,
  "alertType": "indexThreshold",
  "beginTime": "2018-07-18T10:00:00.000-07:00",
  "endTime": "2018-07-23T16:15:00.000-07:00",
  "parameters": {
    "negative": true,
    "windowMin": 30,
    "responses": 13,
    "actual": 80,
    "threshold": 90,
    "thresholdType": "under"
  },
  "alertSpecification": {
    "key": 8125
  },
  "survey": {
    "key": 10,
    "question": {
      "key": 312,
      "name": "How clean are our toilets today?",
      "locale": "en-US"
    },
    "folder": {
      "key": 2,
      "name": "West entrance bathroom"
    },
    "timezone": "America/Dawson_Creek"
  }
}
Negative alert

Alert-triggering negative criteria are the set percentage of negative responses (dark and light red) and the associated time window (available window ranges are 15, 30, 60, 120, 140 minutes)

{
  "key": 91234,
  "alertType": "negative",
  "beginTime": "2018-07-19T12:15:00.000-07:00",
  "endTime": "2018-07-19T13:15:00.000-07:00",
  "parameters": {
    "negative": true,
    "windowMin": 15,
    "responses": 100,
    "actual": 44,
    "negativeResponses": 44,
    "threshold": 33,
    "countThreshold": 10
  },
  "alertSpecification": {
    "key": 8123
  },
  "survey": {
    "key": 10,
    "question": {
      "key": 312,
      "name": "How clean are our toilets today?",
      "locale": "en-US"
    },
    "folder": {
      "key": 2,
      "name": "West entrance bathroom"
    },
    "timezone": "America/Dawson_Creek"
  }
}
Feedback count alert

Alert is triggered when a specified limit of a certain type of feedback, or any combination of feedback, is met during a specified time window

{
  "key": 91235,
  "alertType": "feedbackCount",
  "beginTime": "2018-07-19T14:00:00.000-07:00",
  "endTime": "2018-07-20T15:15:00.000-07:00",
  "parameters": {
    "negative": false,
    "windowMin": 15,
    "responses": 131,
    "countThreshold": 120,
    "responseFilter": [0, 1]
  },
  "alertSpecification": {
    "key": 8124
  },
  "survey": {
    "key": 10,
    "question": {
      "key": 312,
      "name": "How clean are our toilets today?",
      "locale": "en-US"
    },
    "folder": {
      "key": 2,
      "name": "West entrance bathroom"
    },
    "timezone": "America/Dawson_Creek"
  }
}

GET /v1/folders/:key/alerts

Retrieves alert history of a folder.

Parameters

All the alerts that have been in open state between date_start and date_end are returned. Note that also alerts opened before date_start or closed after date_end will be included if their open period intersects with the given date range.

NameDescription
keyrequired, identifier of folder
child_foldersoptional, true or false

When true, returns also alerts for child folders.

date_startoptional, timestamp

Alerts with equal or later endTime timestamp than the date_start are included as well as all alerts with no endTime.

date_endoptional, timestamp

Alerts with beginTime timestamp lower than the date_end are included.

local_date_startoptional, timestamp without timezone

ISO8601-standard timestamp without timezone: yyyy-MM-ddTHH:mm:ss.SSS

Works like date_start, but uses survey’s time zone when comparing to alert’s endTime and startTime.

Local date range is useful to:

  • Request alerts for certain local time (e.g. 3 pm) without having to know the time zone of the survey.
  • Request alerts for meaningful time periods, like full day, week or a month. E.g. local_date_start=2018-03-01T00:00:00.000&local_date_end=2018-04-01T00:00:00.000
  • Request alerts for a day, week or a month period of a folder with child folders that contain surveys in different time zones.

Local date range is alternative to date_start and date_end. It is not allowed to mix them or specify both ranges at the same time.

local_date_startoptional, timestamp without timezone

ISO8601-standard timestamp without timezone: yyyy-MM-ddTHH:mm:ss.SSS

Works similar to date_end, but uses survey’s time zone when comparing to alert’s startTime and endTime.

Examples

GET /v1/folders/2/alerts?date_start=2018-07-19T13:00:00.000-07:00&date_end=2018-07-19T14:30:00.000-07:00
{
  "meta": {},
  "data": [
    {
      "key": 91236,
      "alertType": "indexThreshold",
      "beginTime": "2018-07-18T10:00:00.000-07:00",
      "endTime": "2018-07-23T16:15:00.000-07:00",
      "parameters": {
        "negative": true,
        "windowMin": 30,
        "responses": 13,
        "actual": 80,
        "threshold": 90,
        "thresholdType": "under"
      },
      "alertSpecification": {
        "key": 8125
      },
      "survey": {
        "key": 10,
        "question": {
          "key": 312,
          "name": "How clean are our toilets today?",
          "locale": "en-US"
        },
        "folder": {
          "key": 2,
          "name": "West entrance bathroom"
        },
        "timezone": "America/Dawson_Creek"
      }
    },
    {
      "key": 91235,
      "alertType": "feedbackCount",
      "beginTime": "2018-07-19T14:00:00.000-07:00",
      "endTime": "2018-07-20T15:15:00.000-07:00",
      "parameters": {
        "negative": false,
        "windowMin": 15,
        "responses": 131,
        "countThreshold": 120,
        "responseFilter": [0, 1]
      },
      "alertSpecification": {
        "key": 8124
      },
      "survey": {
        "key": 10,
        "question": {
          "key": 312,
          "name": "How clean are our toilets today?",
          "locale": "en-US"
        },
        "folder": {
          "key": 2,
          "name": "West entrance bathroom"
        },
        "timezone": "America/Dawson_Creek"
      }
    }
  ]
}
GET /v1/folders/2/alerts?child_folders=true
{
  "meta": {
    "moreResultsAfter": "2017-05-20T14:00:00.000Z"
  },
  "data": [{
    // ... circa 10000 alert objects ...
  }]
}
GET /v1/folders/2/alerts?child_folders=true?local_date_start=2018-03-21T00:00:00.000&local_date_end=2018-03-22T00:00:00.000

{
  "meta": {},
  "data": [{
    // ... all alerts that were open during local date 2018-03-21 for folder 2 or its child folders according to each survey's own time zone ...
  }]
}
Result
NameDescription
SuccessA single JSON object that contains meta and data keys. The data key contains list of Alert objects. The meta key contains paging information, if the response does not contain all the results.

If there are so many alerts that some of them do not fit in the same HTTP response, the response will contain the alerts with the earliest beginTime timestamps. The maximum number of alerts returned in a single response is 10 000. Inside the meta key will be a moreResultsAfter key that will give you the timestamp from which to request more alerts with this same endpoint. This way you can retrieve any amount of alerts in several “pages”.

ErrorHTTP status code 404 when no folder is found.