Imagine connecting your Uptrends account to the Operations management system your organization is using. Feeding Uptrends alert data into your existing incident management processes creates a seamless integration of Uptrends' external monitoring into the day-to-day procedures your teams are already using.

If your DevOps software isn't already listed in our predefined integration types, you can use the custom integration option to build the integration yourself. The key to building a successful integration is knowing what kind of message the other system is expecting. The third party's API documentation will tell you which URL to use, and which content should be posted to that URL. The content is usually JSON-formatted and contains the different fields that have a particular meaning and importance in that system.

Building the right message content

In order to fill in relevant content for those fields in each outgoing alert message, the message body you define will contain so-called system variables. When you refer to a system variable in your message content, it will be replaced by the appropriate content when an actual alert is generated. This allows you to write message definitions that are completely tuned to the other system's expectations.

Let's look at an example. An obvious piece of information that should probably be part of any alert message is a plain text description of the error that was detected by Uptrends. If the system you want to connect to expects that kind of value in a field called "errordescription", your JSON-formatted message could contain:

{ "errordescription": "{{@alert.description}}" }

In Uptrends' system variables, the text description of the error that triggers an alert is available in the {{@alert.description}} variable, so you simply put that variable right where you need it in your message. All available system variables are listed below. Note how all system variables are named {{@...}}:

Variable Description Example value
@alert.alertGuid Unique id of this alert cbfc7769-edb2-46a7-89d0-1e1b1fb0815b
@alert.type The type of this alert message: Alert: a new error was detected. Ok: the original error has been resolved. Reminder: the original error is still ongoing. Alert | Ok | Reminder
@alert.timestampUtc The date and time of the alert, expressed in UTC time, and formatted as ISO 8601. 2018-11-08T16:26:58
@alert.timestamp The same date and time as @alert.timestampUtc, but in the timezone of your account. Also formatted as ISO 8601. 2018-11-08T10:26:58
@alert.firstErrorUtc The date and time of the original error that triggered this alert, expressed in UTC time, and formatted as ISO 8601. 2018-11-08T16:21:58
@alert.firstError The same date and time as @alert.firstErrorUtc, but in the timezone of your account. Also formatted as ISO 8601. 2018-11-08T10:21:58
@alert.description Text description of the error that triggered this alert DNS expected result not found
@alert.firstErrorCheckUrl The URL of a deep link that takes you to the details of the error that triggered this alert. https://app.uptrends.com/Report/ProbeLog/Check/30833627687
@incident.key Unique id of the incident this alert belongs to. An error alert and an Ok alert share the same incident key. ba8ffcb7-5de0-489e-b649-f00f0b447e80-0-30099055746
@monitor.monitorGuid The unique id of the monitor in your account that triggered this alert 849b2046-213d-43ad-9efc-5af1faaeb222
@monitor.name The name of the monitor in your account that triggered this alert GalacticResorts.com - DNS
@monitor.notes Any custom notes that were filled in the monitor settings Please check Amazon Route53 DNS entries
@monitor.url The URL or network address this monitor is checking. https://galacticresorts.com
@monitor.dashboardUrl The URL of a deep link that takes you to the dashboard for this monitor. https://app.uptrends.com/Probe/Dashboard?probeGuids=fe1ad4a2-57c1-49db-af16-ff3a6beaa8d4
@monitor.editUrl The URL of a deep link that takes you to the settings for this monitor. https://app.uptrends.com/Report/Probe?probeGuid=fe1ad4a2-57c1-49db-af16-ff3a6beaa8d4
@account.accountId Your Uptrends account id 299840

Checking an integration using test messages

Once you've created or modified a customized integration, it's useful to test it first before using it in production. The customization tab in the integration editor has a button titled "Send test message" that allows you to send a test message to the third party system using the HTTP step(s) you've created. When you use this test function, you can select which alert type (an Error alert, an OK alert or a Reminder alert) should be used for this particular test message. You can fill in any other appropriate values if necessary, and the remaining data (which would normally be relevant monitor data and alert data) will be filled with fictious values.

Once the message has been generated and sent out to the third party system or API, the full message content, as well as the server's response code and content will be displayed. You can expand the request headers and content and the response headers and content, to inspect the outgoing and incoming traffic that was involved in sending this test message.