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.
Create A Router
- Enable Advanced Mode
- From the action button, click the Create Router button.
- 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.
- Click Save button.
Update A Router
- Navigate to the router page you would like to edit.
- Next to any of the fields double click to edit or just toggle the swtich.
Delete A Router
- Navigate to the Routers page.
- Click the trashcan button next to the router you wish to delete.
- Click the Yes button to confirm you would actually like to delete this router.
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.
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).
Internally PagerTree uses the sift package to do rule matching. It follows the familiar MongoDB syntax.
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.
The timeBetween operator returns a boolean.
true if the current time is between (inclusive) the time provided,
Make sure to provide the
timezone (default: ‘Etc/UTC’),
timeformat (default: ‘hh:mm a’),
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.
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:
- Navigate to the integration needing to use the routing rule
- Set the destination to be the router
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
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
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.
The automate action will run automations when triggered. Provide the
ids of the automations to run.
The incident action will mark the alert as an incident when triggered. Provide a
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.
The setval action will assign data to the alert. Use the
map attribute to define custom
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.
The stakeholder action will attach stakeholders to the alert when triggered. Provide the
ids of the stakeholders to attach.
The ignore action will place the alert into a
suppressed state and stop routing.
Routing Rules Example Templates
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.
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:
- Navigate to the user needing to use the notification rule
- Set the destination to be the router
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
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:
The repeat action will repeat the above notify actions n
times. You can repeat between 0 and 3 times.
The ignore action will supress sending any notififications to the user when matched.