Skip to main content

Create Data Alerts using API

Introduction​

In Holistics, you can set up a system that sends you automatic notifications when data meets certain criteria, allowing you to make timely and strategic business decisions. This concept is called Data Alert.

Holistics offers a set of public API endpoints allowing clients to work with Data Alert. This tutorial shows you how to programmatically create these data alerts using the API.

The Use Case​

Assuming you are an e-commerce company that wants to track the number and status of orders placed on your platform. You can set up data alerts that trigger notifications when certain conditions are met, such as:

  1. A number of orders placed in a specific time period exceed a certain threshold.
  2. A certain percentage of orders are canceled or marked as "canceled".

You can receive these alerts through email or Slack, and use this information to quickly respond to any issues or to make informed decisions about adjusting inventory or shipping processes.

Let's walk through how we can create a data alert to track your number of orders using Holistics API.

High-level Approach​

We will use the API to create email data alerts. Specifically, we'll send a POST request to Holistics create data alert API.

Before that, we need to prepare the following:

  • A dashboard widget with relevant report
  • Holistics API Key: We need to setup the API key. Refer to the Getting Started guide for setup instructions.

How to Create a Data Alert via API​

Step 1: Preparing the Dashboard Widget​

You will need to create a dashboard widget containing the data of interest to you. In this example, I used this simple report that counts the total number of orders.

Dashboard widget example

Step 2: Making the API Call​

We'll be using the following endpoint:

POST https://secure.holistics.io/api/v2/data_alerts

There are some notable configuration options in this request:

  • schedule: Specify how frequently the email schedule should be
  • viz_conditions: Specify what alert condition should be checked on the report result. By configuring this, we can customize the alert for each alerting use case.
  • dest: Specify configurations regarding the alert delivery destination, e.g. the recipients' information.
  • dynamic_filter_presets: Specify what dynamic filters should be applied to the report. By configuring this, we can customize the report for each recipient.

Below is a sample request body. Refer to Holistics API docs for more information on these fields.

Sample request body

Dest field​

  • dest: Specify configurations regarding recipients' information
    • title (string): Note that Holistics support dynamic variables in email title. For example, the title Sales report for {{$today}} sent on 29/09/2021 will be rendered as Sales report for 2021-09-29 Wed.
    • type: This tells Holistics you want to receive notification via email: EmailDest or Slack: SlackDest

Viz conditions​

  • viz_conditions: Coming to the core of the alert, the condition to set data alert

    • field_path: This is used to extract from a specific data model

      • field_name: field name of the field in the data model you want to apply the condition.
      • model_id: The id of the data model associated with the field_name
      • You can get the field_name and model_id by following these steps:
        • From the widget id, use Get a dashboard widget (include_report=true) then extract query_report.viz_settings.fields, you can find the field you want to add condition then extract path_hash to get model_id and field_name

    • aggregation: The aggregation that will be applied on the field when processing the condition.

    • transformation: The transformation that will be applied on the field when processing the condition.

    • condition: be applied on the Data Modeling layer to filter your data.

    • Example: you have a field id and want to check whether the number of it is greater than 35000

      {
        "field_path": {
          "field_name": "id",
          "model_id": 1
        },
        "aggregation": "count",
        "transformation": null,
        "condition": {
          "operator": "greater_than",
          "modifier": null,
          "values": [35000]
        }
      }

Schedule​

schedule: This field is used to specify the schedule for your email schedule.

repeat (string): You will need to input a crontab expression to let Holistics know how frequently you want your email schedule to run.

Dashboard Filters​

dynamic-filter-presets is where you define your filter presets.

dynamic_filter_id: To get your filter_id, send a request to Dashboards#Get API to get the dashboard info.

preset_conditions: Let's go through our example to better illustrate this field.

We want to set a value for the filter by setting a preset condition. A preset condition consists of an operator and a list of values. Holistics supports various operators.

In this case, we want to use operator is and set values to customer_id. By this, we mean the filter's default value equals exactly to customer_id.

Finally, we also want to set up another dynamic filter preset to filter data to the whole of last week. Fortunately, Holistics allows a list of dynamic filter presets. For the Date Range filter, we similarly want to use operator is and set values to "last 7 days".

Our final dynamic_filter_presets object will look like this:

dynamic_filter_presets = [
  {
    "dynamic_filter_id": MY_CUSTOMER_FILTER_ID,
    "preset_condition": {
      "operator": "is",
      "values": [
        customer_id
      ]
    }
  },
  {
    "dynamic_filter_id": MY_DATE_RANGE_FILTER_ID,
    "preset_condition": {
      "operator": "is",
      "values": [
        "last 7 days"
      ]
    }
  }
]

Step 3: Verify to see if your data alert is created​

The request should now be ready. After sending it to Holistics, the server will respond with a HTTP status response code to indicate whether the request was successful / failed.

Lastly, be sure to head over to the Holistics page to see if your data alert is created.

Data alert confirmation

Example Script​

An example script to send requests written in Ruby is available here:

# install the neccessary dependencies for this script to work
require "bundler/inline"
require "net/http"
require "json"

gemfile do
  source "https://rubygems.org"
  gem "net-http"
end

# this the Holisitics API endpoint that we need to send our POST request to
DATA_ALERT_ENDPOINT = URI("https://secure.holistics.io/api/v2/data_alerts")

# Step 1: Create a POST request to the endpoint below
request = Net::HTTP::Post.new(DATA_ALERT_ENDPOINT)

# Step 2: Provide your authentication information
request["X-Holistics-Key"] = "mysecretAPIkey"

# Step 2.1: This line helps the system know that we are sending a JSON request
request.content_type = "application/json"

# Step 3: Provide information for your data alert in the request body
request.body = {
  "data_alert": {
    "title": "Tracking number of orders",
    "source_id": 41,
    "source_type": "DashboardWidget",
    # Conditions for the Alert to be Triggered
    "viz_conditions": [
      {
        "field_path": {
          "field_name": "id",
          "model_id": 12
        },
        "aggregation": "count",
        "transformation": null,
        "condition": {
          "operator": "greater_than",
          "modifier": null,
          "values": [35000]
        }
      }
    ],
    # Destination for the Alert
    "dest": {
      "type": "EmailDest",
      "title": "The number of orders has just exceeded than 35000",
      "recipients": [
        "[email protected]"
      ],
      "options": {
        "body_text": null
      }
    },
    # Schedule for the Alert to be Triggered
    "schedule": {
      # Repeat Everyday at 7:00 AM
      "repeat": "0 7 * * *",
      "paused": false
    },
    # Dynamic Filter Presets for the Alert
    "dynamic_filter_presets": [
      {
        "preset_condition": {
          "operator": "is",
          "modifier": null,
          "values": ["VN", "SG"],
        },
        "dynamic_filter_id": 1
      },
      {
        "preset_condition": {
          "operator": "is",
          "modifier": null,
          "values": [
              "Male"
          ],
        },
        "dynamic_filter_id": 2
      }
    ]
  }
}.to_json

# Step 4: Send the request to Holistics!
response = Net::HTTP.start(
  DATA_ALERT_ENDPOINT.hostname,
  DATA_ALERT_ENDPOINT.port,
  :use_ssl => DATA_ALERT_ENDPOINT.scheme == "https",
) do |https|
  https.request(request)
end

# Optional: Output the result into the terminal
puts [response.code,response.message].join(' ')
Let us know what you think about this document :)