Skip to main content

Demo video: Create a custom integration ►

*Please note Moogsoft is now part of Dell's IT Operations solution called APEX AIOps, and changed its name to APEX AIOps Incident Management. The UI in this video may differ slightly but the content covered is still relevant.

After watching this video, you will be able to configure a custom integration to bring data from your monitoring source into Incident Management. You will be able to identify when to choose this over other integration options, ingest data in JSON format into Incident Management, map data from your monitoring software to Incident Management event fields, and set up and test a deduplication key to reduce operational noise.

1_CYOI.png

Incident Management offers a few different ways to ingest source data. You can install a data collector to the system you want to monitor...

1_CYOI7_25.png

...or integrate with specific monitoring tools.

2_CYOI7_25.png

Or you can build your own custom integration. You should choose a custom integration when there is no collector for your environment, and there is no specific integration available for your monitoring tool.

3_CYOI7_25.png

Creating your own integration has several benefits. First, you are not limited to particular monitoring tools. You can set up a custom integration with any monitoring source that can send data in JSON format.

5_CYOI.png

Second, you will use real data to design and test your integration. The Create Your Own Integration feature makes it easy to inspect source data before you map it.

4_CYOI7_25.png

And finally, creating a custom integration is simple. When you configure a webhook in a monitoring tool, you usually have to write code to modify the outgoing data payload. The Create Your Own Integration feature does all the mapping right in the Incident Management user interface, with no code.

5_CYOI7_25.png

After you have ingested data using a custom integration, you can transform and enrich it using the Incident Management Workflow Engine.  Still without writing any code.

6_CYOI7_25.png

Let’s step through setting up a custom integration together. Let’s say we have source data in JSON format that’s structured like this:

8_CYOI.png

We want to ingest the events so we can deduplicate and correlate them in Incident Management.

9_CYOI.png

And we need to map them to the Incident Management event fields.

10_CYOI.png

We also want to map the values for severity. Our source events only have four severity levels: NONE, INFO, WARN, and PROBLEM. We want to map these values to Incident Management severity levels like this.

11_CYOI.png

This is where you can set up a custom data ingestion. We are going to set up a new integration. Our source data in this example events, but note that we support metrics also.

7_CYOI7_25.png

We just created a custom endpoint for our integration.

8_CYOI7_25.png

Grab that, and the API Key for our Incident Management instance which is found here.

9_CYOI7_25.png

We’ve input those values in the source system. And now, Incident Management is receiving raw data from our source. Note that up to 10 of the most recent events are cached. You can click the reload button to refresh the list of data payloads.

10_CYOI7_25.png

We can examine the data for each event here.

11_CYOI7_25.png

Note that some of these events have blank hostnames, and for some the hostnames are populated.

12_CYOI7_25.png

Let’s see how the payload and target fields line up. Incident Management automatically matched the obvious ones.

13_CYOI7_25.png

We don’t have a value for source, which is a required field.  So we need to map something to that field.

14_CYOI7_25.png

Let’s look at the data again. We want to map hostname to source, but we know it’s blank in some cases, and required fields can’t be blank.

15_CYOI7_25.png

Let’s do this. We’ll map hostname to source if it exists, and if not we’ll use ip_address.

16_CYOI7_25.png

We’ll map hostname to source first. Then we’ll add a second mapping, and map ip_address. Incident Management will use the first mapping if a value exists and is valid. Otherwise, it will move on and use the next mapping.

17_CYOI7_25.png

This defines the condition that generates the event.

18_CYOI7_25.png

We’ll map the Type field to check.

19_CYOI7_25.png

Next let’s take care of the severity. Our monitoring service has only four severity levels: NONE, INFO, WARN, and PROBLEM. So we’ll map them to the Incident Management severity levels like this...

20_CYOI7_25.png

With that we took care of all the required fields. Let’s see what other fields we might want to bring in. Let’s say we want to keep region. And let’s add a custom tag for ip_address.

21_CYOI7_25.png

The last step before we save our integration is to configure the deduplication key. Here’s how deduplication works. Incident Management uses the fields in the deduplication key to assign multiple events to the same alert and reduce noise. The idea behind deduplication is that events with the same context should become part of the same alert.

27_CYOI.png
28_CYOI.png

For example, we might find out about a condition that affects one of our hosts with a warning event, which then escalates to a critical event. Since the key context is the same, Incident Management would assign those events to the same alert.

29_CYOI.png

Here comes another event, and since the dedupe key is different, it is categorized into a separate alert. Like this, selecting the right fields for your use case is the key factor for successful deduplication. The default is set to be the combination of the Source, Service, and Check fields, but you can select what works for you.  Just ask yourself, what should be the common factors for two events to be considered duplicates.

30_CYOI.png

Going  back to our custom integration, these are the default fields for deduplication. You can change them if you wish, but Incident Management recommends you use the defaults unless your business needs require that you use different fields.

22_CYOI7_25.png

In our case we don’t have a value for class, so we’ll remove that from the default keys.

23_CYOI7_25.png
24_CYOI7_25.png

Let’s test. Success! Here are the resulting deduplication keys.

25_CYOI7_25.png

Based on these values, some of the events have been assigned to the same alert.

26_CYOI7_25.png

Our custom integration is ready to go. Let’s save and activate it.  Note that it will stay in provisioned status until Incident Management processes an event.

27_CYOI7_25.png

The monitoring data is flowing into Incident Management through our custom integration. Thanks for watching!

28_CYOI7_25.png