AlertMagic - Configuring your Alert Management System

Introduction

Setting up your Alert Management System should be a quick task. Because every customer is different, we don't automate this part. Fortunately, this is a simple exercise for most Alert Management Systems.

• Supported Alert Management Systems
• General configuration
• Configuring LogicMonitor
• Configuring Cisco Meraki
• Configuring Microsoft Azure

Supported Alert Management Systems

Any Alert Management System is supported providing it:

• Supports HTTPS using TLS 1.2
• Can emit JSON webhooks
• Can use Basic Auth for webhook security

General configuration

URL

If you are self-hosting or using our test system, you will have been given a different URL. However, for most Deployments, the URL will be:

• pdl-alertmagic-production.azurewebsites.net/api/notify

Authentication

You should configure Basic Authentication, using a username and password. You can view these when configuring your Deployment. You should not need to store these anywhere other than in your Alert Management System, and they can easily be re-generated if required.

Headers

AlertMagic will ignore any custom headers that you set.

Method

You should use the POST HTTP method. All other methods will be ignored.

Message payloads

Message payloads must present a single, valid JSON object. The payload should send AlertMagic information relating to your alert. The following examples are deliberately simple - it is likely that your final template is about 100 lines long and may even contain nested objects and arrays.

A simple payload that AlertMagic receives might look like this:

{
    "AlertType": "Device",
    "AlertId": 1234567890,
    "AlertRef": "Alert1234567890",
    "DeviceName": "ACME-Router-01",
    "AlertStatus": "Critical",
    "Metric": "CPU%",
    "Value": 99.900
}

In order for this to work, you will probably need to configure some sort of alert template in your Alert Management System. These templates are unlikely to be valid JSON until the tokens are replaced. For example, the template for the message above might look like one of these examples:

Example payload template 1

{
    "AlertType": "{{AlertType}}",
    "AlertId": {{Id}},
    "AlertRef": "{{Aref}}",
    "DeviceName": "{{DisplayName}}",
    "AlertStatus": "{{Level}}",
    "Metric": "{{MetricName}}",
    "Value": {{AlertValue}}
}

Example payload template 2

{
    "AlertType": "${type}",
    "AlertId": ${id},
    "AlertRef": "${ref}",
    "DeviceName": "${dev_name}",
    "AlertStatus": "${a_level_short}",
    "Metric": "${measurement_name}",
    "Value": ${measurement_value}
}

Example payload template 3

{
    "AlertType": "##ALERTTYPE##",
    "AlertId": ##ALERTID##,
    "AlertRef": "##ALERTREF##",
    "DeviceName": "##DEVICENAME##",
    "AlertStatus": "##STATUS##",
    "Metric": "##METRIC##",
    "Value": ##VALUE##
}

Configuring LogicMonitor

To configure LogicMonitor, you will need access to the Settings tab. Go to the "Integrations" section and create a new "Custom HTTP Delivery" Integration. The following example will get you up-and-running and you can refine it later!

Basic information

Set up the following basic information, substituting the username and password you obtained when creating your Alert Management System:

For the JSON, insert the following, adding lines for any custom or auto properties, as required:

{
	"internalId": "##INTERNALID##",
	"alertId": "##ALERTID##",
	"alertStatus": "##ALERTSTATUS##",
	"dataPoint": "##DATAPOINT##",
	"dataSource": "##DataSource##",
	"date": "##DATE##",
	"dsDescription": "##DSDESCRIPTION##",
	"dsIDescription": "##DSIDESCRIPTION##",
	"dpDescription": "##DPDESCRIPTION##",
	"group": "##GROUP##",
	"host": "##HOST##",
	"hostDescription": "##HOSTDESCRIPTION##",
	"deviceUrl": "##DEVICEURL##",
	"instance": "##INSTANCE##",
	"level": "##LEVEL##",
	"start": "##START##",
	"startEpoch": "##STARTEPOCH##",
	"duration": "##DURATION##",
	"threshold": "##THRESHOLD##",
	"value": "##VALUE##",

	"customerCode": "##customer.code##",

	"agentId": "##AGENTID##",
	"backupAgentId": "##BACKUPAGENTID##",
	"agentDescription": "##AGENT_DESCRIPTION##",
	"backupAgentDescription": "##BACKUPAGENT_DESCRIPTION##",
	"externalTicketId": "##EXTERNALTICKETID##",
	"end": "##END##",
	"webSite": "##WEBSITE##",
	"checkPoint": "##CHECKPOINT##",
	"detail": "##DETAIL##",
	"webSiteDescription": "##WEBSITEDESCRIPTION##",
	"webSiteGroup": "##WEBSITEGROUP##",
	"url": "##URL##",
	"webSiteRequest": "##WEBSITEREQUEST##",
	"webSiteResponse": "##WEBSITERESPONSE##",

	"hostName": "##HOSTNAME##",
	"bjDescription": "##BJDESCRIPTION##",
	"cmdLine": "##CMDLINE##",
	"stdOut": "##STDOUT##",
	"stdErr": "##STDERR##",
	"userData": "##USERDATA##",
	"exitCode": "##EXITCODE##",
	"finish": "##FINISH##",

	"eventSource": "##EVENTSOURCE##",
	"limitedMessage": "##LIMITEDMESSAGE##",

	"eventCode": "##EVENTCODE##",
	"type": "##TYPE##",
	"message": "##MESSAGE##",
	"user": "##USER##",
	"logFile": "##LOGFILE##",
	"sourceName": "##SOURCENAME## ",

	"timeStamp": "##TIMESTAMP##",

	"trapOid": "##TRAPOID##",
	"enterpriseOid": "##ENTERPRISEOID##",
	"sysUptime": "##SYSUPTIME##",
	"generalCode": "##GENERALCODE##",
	"specificCode": "##SPECIFICCODE##",

	"facility": "##FACILITY##",

	"admin": "##ADMIN##",
	"alertType": "##ALERTTYPE##",

	"system_hostname": "##system.hostname##",

	"endpointSerialNumber": "##auto.endpoint.serial_number##",
	"entPhysicalSerialNumber": "##auto.entphysicalserialnum##",
	"source": "LogicMonitor"
}

Configure the following response details. For the JSON Path, use:

• auditItem.azureFunctionsInvocationId

Configure Recipient Groups and Escalation Chains

We recommend using LogicMonitor Recipient Groups for all Escalation Chain configuration. If you ARE already using LogicMonitor Recipient Groups, simply add the Integration to an existing Recipient Group:

If you will not be using Recipient Groups, you can simply add the Integration as a recipient on your Escalation Chain.

For more details on setting up LogicMonitor, please review the LogicMonitor documentation or contact LogicMonitor support.

Configuring Cisco Meraki

Meraki alerts can reach AlertMagic in two ways:

• Meraki webhooks - in the Meraki dashboard, configure a webhook HTTP server pointing at your AlertMagic endpoint (the URL and credentials from the General configuration section above), then select it as a recipient for the alert types you care about.
• Via DataMagic - if DataMagic monitors your Meraki estate, its monitoring (for example wireless health) can raise alerts into AlertMagic directly, with no Meraki-side webhook configuration required.

We usually set this up with you as part of onboarding - contact support and we will gladly help.

Configuring Microsoft Azure

Azure alerts are delivered through Azure Monitor action groups. Create an action group containing a webhook action that points at your AlertMagic endpoint (the URL and credentials from the General configuration section above), then attach the action group to your alert rules. Using Azure's common alert schema keeps the JSON payload consistent across the different alert types.

We usually set this up with you as part of onboarding - contact support and we will gladly help.