Advanced Field Mapping

The Rules for Opening and Closing an Alert advanced setting offers more leverage in controlling alert noise with advanced field mapping.

At a minimum, you must configure the Source, Source Name, Source Id, Status Field, and Source Status control actions (Open, Close, and Update Alert).

Source is a static field which is used both for mapping and grouping alerts. You can also use Source for reporting purposes. The "Source" field refers to the type or category of the integration or source itself. It represents the system, application, or service from which the alerts originate. For example, if you are integrating with an IT monitoring tool like Nagios or New Relic, you would specify "Nagios" or "New Relic" as the source. This also dictates what the integration URL will look like as well. In this integration URL, you can see “ABC-Monitoring” appended to the end. 

Source Name can either be a static or dynamic value using data from the inbound alert. The "Source Name" field allows you to give a more descriptive and recognizable name to differentiate between different instances or setups of the same source. For example, if you have multiple Nagios instances, you can provide distinct source names like "Nagios Production" and "Nagios Development" to easily identify and manage them. This name can be static or dynamically pulled from a field being sent across the API.

Source Id is a unique identifier that is associated with each integration source or system. It helps identify the specific source or system that generates alerts or incidents within AlertOps. It is a numeric or alphanumeric value that uniquely identifies a specific source or integration. This is a Dynamic input field that comes directly from the JSON data sent through the API. The Source ID allows you to differentiate and track alerts based on their origin or the integration they belong to. 

Source Status refers to the current operational status or state of a particular integration or source. It indicates whether the integration or source is active, inactive, or experiencing any issues. The Source Status can have different values depending on the system or platform. Some common source status values can include Active, Inactive, Open, or Closed. 

The API URL is the endpoint where you can send requests to interact with the AlertOps API. The specific API URL may vary depending on the Integration instance you are using based on the integration Source. 

Sample Data The sample data field can store simulated or dummy data used for testing and demonstration purposes. It is designed to mimic the structure and format of real data that would typically be received by AlertOps from the monitoring or alerting system.  

Sample data can come in handy when creating values for dynamic inputs. For example, if you have a dynamic input for the recipient group of an alert, you can use sample data to simulate different group names or identifiers. This enables you to test how AlertOps handles the dynamic nature of the recipient group and ensures that the correct recipients are assigned based on the simulated input. AlertOps makes using sample data convenient by categorizing key value pairs that can be dragged and dropped into text boxes. Once sample data has been pasted and saved in the Sample Data text area, the dynamic keys will be listed on the right and can be dragged and dropped into each text area.  

All of these fields will require mapping to a particular value. This is most commonly a field that is referenced from the Incoming JSON. Below we have descriptions on how to map fields from a JSON. In the case of a basic field at the top level, simply referencing the Key from the Key-Value pair of that field will be sufficient. Below we have examples of more advanced mapping such as nested fields and arrays.

Nested Objects

If you are mapping a field that is composed of nested object data, such as the example above, you can map the id field using the following syntax: issue^id

In this example, this reference will return the value "12345". Likewise, you can map the key as issue^key which would return the value of "abcdefg".

Arrays

• Mapping an Individual Index:
• 

In this example, we want to map an individual field for "metric" from this array. You can do so by using the following syntax: evalMatches_0^metric which will map the value "rabbit_mq_disk_space_free_total"

• Map Arrays as Strings:
• 

To map an Array as a String in order to capture the entire field for "Array", you'd map it as a normal field. In the example above, you would simply use Array. This would map the value "[1,2,3,4,5,6,7,8]".

In the case of a nested array, you'd reference it the same as a normal string field. The mapping to capture the Array field value "[1,2,3,4,5,6,7,8]" from this nested array would be Parent^Array.

Sample Data and API URL

The API URL is the endpoint for the integration and is used to configure the webhook endpoint in your source system.

Sample Data can be used to store a sample JSON body for reference. You can also use the Sample Data to test your configuration. The Sample Data box allows you to store a sample of the JSON data used in this integration. Use this both as a reference and also for testing purposes. You can test your configuration using the Test URL button along with the sample data.

If the value for Source changes, the API URL must be updated. To do this, click on GENERATE URL under URL Mapping after the source name has been changed and update the integration.

Method Setting Options

The Method dropdown has the GET and POST methods to perform HTTP requests.

Content Setting Options

The Content dropdown under URL Mapping has JSON, URL Encoded, and FORM DATA options for the format of the content sent via the selected Method.

Source Name field – Static vs. Dynamic

AlertOps will match each incoming alert to previous alerts using Source and Source Name. These fields can either be static or it can be dynamic.

• For Static values, check the Static box and a static value needs to be provided in the Source Name field.
• For Dynamic values, the inbound JSON/Form field needs to be provided in the Source Name field. Static checkbox needs to be unchecked and the value must be left blank for matching with any inbound field value. If it is not left blank, the value is then used to match with inbound data.

With a dynamic Source Name field you can set up multiple integrations using a single end point. Each of these integrations can then use different processing rules, such as assignment to different groups, or different escalations using Escalation Rules.

Example: Alerts with a Static Source Name

In this example, the Source is ‘Grafana’ and the Source Name is ‘Custom’ and is a Static field. The SourceStatus determines what actions should take place when a new alert is triggered.

• Opening the Alert - If the SourceStatus of the signal is 'Open' and are no alerts in the system with a matching combination of Source and Source Name a new alert will be opened.
•  Closing the Alert - To close an alert, AlertOps looks to see if an alert exists in the system with a matching combination of Source and Source Name. If the SourceStatus of the signal contains the value of "close", the alert will be closed.
• Updating the Alert - In this example an alert in the system contains a matching combination of Source and Source Name. The alert will be updated and a new message is added to the alert message thread.

Example: Alerts with Dynamic Source Name

Alerts with a dynamic source name are set up very similarly to static source names. In this example, the Source is ‘ConnectWise Manage’ and the Source Name field contains the key 'CompanyId'. AlertOps will use the Status to determine what actions should be taken.

• Opening the Alert - If the SourceStatus of the signal is 'Open' and are no alerts in the system with a matching combination of Source and Source Name a new alert will be opened.
•  Closing the Alert - To close an alert, AlertOps looks to see if an alert exists in the system with a matching combination of Source and Source Name. If the SourceStatus of the signal contains the value of "close", the alert will be closed.
• Updating the Alert - In this example an alert in the system contains a matching combination of Source and Source Name. The alert will be updated, and a new message is added to the alert message thread. 

When the status of an alert changes (opens, closes, updates) you can view the status message for the alert in the Inbound Log. The Inbound Log can be found at the bottom of the Inbound Integration page from the Configurations tab on the main menu. When an alert is opened, you can view the alert itself in the Alerts tab of the main menu.