Overview

Routers are objects that can dynamically route alerts and notifications based on conditions. Make sure to check out the routing rules example video and the notification rules example video for an easy to follow guide on getting setup.

Management

Note: Routers require Administrator permissions and the Pro pricing plan.

Create A Router

  1. Enable Advanced Mode
  2. Navigate to the Routers page.
  3. In the upper right hand corner, click the Create Router button. Create Stakeholder Button
  4. Provide the following:
    • Name - The name of the router (ex: “Dev Alerts Router”)
    • Type - Select the type. This can be “Routing Rules” which are generally connected as alert filters connected to integrations, or “Notification Rules” which are rules specifying how users should be notified and are attached to users.
    • Default Destination - (only applicable to “Routing Rules”) - The default destination to send the alert if no rules match.
  5. Click Save button. Create Router Form

Update A Router

  1. Navigate to the router page you would like to edit.
  2. Next to any of the fields double click to edit or just toggle the swtich. Modify Router Attributes

Delete A Router

Note: Deleteing a router that is being used by another object (integration, user, ext.) could have unintended consequences. Make sure other ojects are not using this router before deleting it.
  1. Navigate to the Routers page.
  2. Click the trashcan button next to the router you wish to delete. Click Trashcan Button
  3. Click the Yes button to confirm you would actually like to delete this router. Confirm Delete

Formats

Rules

All routers use YAML as the format. The root element should always be rules (array). Each rule has a match condition (object) and a actions (array). See the routing rules and notification rules sections for examples.

Please Note: When rules are evaluated, they will be evaluated in order. Only the first matching rule will be used.

Data

When routers are matching rules they are given access to data. Namely you are given access to the alert in context, and a special field always which is always true (especially useful for catch all rules). Additionally, if the alert has a source log, you will be given access to the log and log_parsed.

Operators

Internally PagerTree uses the sift package to do rule matching. It follows the familiar MongoDB syntax.

There are 2 special functions $day and $timeBetween that are supplimental. See below for documentation.

$day

The day operator returns the current ISO day of the week (1 Monday, 7 Sunday). You can then use other operators to match the current day.

Make sure to provide the timezone parameter, if not it will default to Etc/UTC. You can use any of the momentjs timezones.

$timeBetween

The timeBetween operator returns a boolean. true if the current time is between (inclusive) the time provided, false otherwise.

Make sure to provide the timezone (default: ‘Etc/UTC’), timeformat (default: ‘hh:mm a’), starttime, and endtime parameters.

Routing Rules

With routing rules, you can perform complex routing and actions on alerts. Routing rules are processed after the integration has transformed the 3rd party data into an alert, but before the alert has been assigned to the team. The diagram below shows the high level workflow for alerts and how they move within the PagerTree system.

High Level Alert Workflow Highlighting Routing Rules

Connecting the Integration

As a last step to using a router in a production setup, make sure to connect your integrations that should use the routing rules. You can do this by:

  1. Navigate to the integration needing to use the routing rule
  2. Set the destination to be the router Point integrations to Router Rules

Routing Rules Example Video

For a quick overview on how to setup an example routing rule, watch the video below:

Routing Rules Actions

With routers you can perform many actions on alerts. Actions include:

  • aggregate - Aggregate alerts based on field(s)
  • assign - Assign the alert to a team, user, schedule, or another router
  • automate - Run an automation
  • incident - Mark the alert as an incident
  • setval - Set a value on the alert
  • escalate - Create a sudo-escalation process
  • stakeholder - Attach a stakeholder to the alert
  • ignore - Suppress the alert

Aggregate

The aggregate function will aggregate alerts by the specified by properties for timeout time. All subsequent alerts that arrive will be added as a child to the first alert. They can be found in the children tab of the UI and will show a status of suppressed. After the timeout elapses (since the first alert), it will then route the alert to the receiver.

Assign

The assign function will assign the alert to a team, user, schedule, or another router (can only go 10 routers deep). This is useful for dynamic routing based on conditions.

Automate

The automate action will run automations when triggered. Provide the ids of the automations to run.

Incident

The incident action will mark the alert as an incident when triggered. Provide a severity and message. Severity can be any of the following: SEV-1|SEV-2|SEV-3|SEV-4|SEV-5. If the severity is none of the previous, it will default to SEV-5. Use the handlebars boolean to indicate you would like to use handlebars substitution.

Here is an example using handlebars:

SetVal

The setval action will assign data to the alert. Use the map attribute to define custom title, description, tags, or urgency. Use the handlebars boolean to indicate you would like to use handlebars substitution.

Here is an example using handlebars:

Escalate

The escalate action will create a sudo escalation setup. The receivers can be multiple users and/or teams, this is equivalent to having multiple attendees for an on-call layer, essentially fanning out notifications. However, important to note, that once the cycle gets to a rule where the receivers are not all users, it will completely transfer control of the alert, similar to the Handoff or Multi-Team Routing functionality.

Stakeholder

The stakeholder action will attach stakeholders to the alert when triggered. Provide the ids of the stakeholders to attach.

Ignore

The ignore action will place the alert into a suppressed state and stop routing.

Routing Rules Example Templates

Notification Rules

With notification rules, you can perform custom notification sequences. Notification rules are processed after PagerTree has selected the User to notify, but before default notification channels are used. The diagram below shows the high level workflow for alerts and how they move within the PagerTree system.

High Level Alert Workflow Highlighting Notification Rules

Connecting the User

As a last step to using a router in a production setup, make sure to connect your users that should use the notification rules. You can do this by:

  1. Navigate to the user needing to use the notification rule
  2. Set the destination to be the router Point User to Notification Rules

Notification Rules Example Video

For a quick overview on how to setup an example notification rule, watch the video below:

Notification Rules Actions

With notification rules, you can perform custom notification sequences. Actions include:

  • notify - Notify on specified channels
  • repeat - Repeat the notification sequence
  • ignore - Suppress notifications from being sent

Notify

The notify action will notify the user on specified channels then wait for a timeout for next instructions. Possible values for the channels parameter are:

  • push
  • email
  • sms
  • voice
  • slack

Repeat

The repeat action will repeat the above notify actions n times. You can repeat between 0 and 3 times.

Ignore

The ignore action will supress sending any notififications to the user when matched.

Notification Rules Example Templates