Create your own integration

A custom integration is a user-defined endpoint that ingests JSON objects and converts them to Moogsoft events or metrics. Custom integrations enable you to ingest data from third-party systems with different schemas. When you set up a custom integration, you specify how to map the third-party data to Moogsoft-compatible event or event objects.

Custom integrations have the following features:

  • A UI that guides you through the process of creating a custom endpoint and mapping third-party data fields to Moogsoft fields.

    For events, you can also map third-party severities to Moogsoft severities.

  • Support for basic and bearer token authentication using API keys.

  • No limit on the number of unique API endpoints you can create per workspace.

  • Support for testing and validating the mapping.

    You must validate an integration before you enable it. To be considered valid, an API must include mappings for all required event or metric fields. If the incoming payload does not include the data for a required field, you can specify a plain-text placeholder such as "unknown" instead.

  • If your third-party schema does not include a field that corresponds directly to a Moogsoft field, you can create event workflows to enrich and process your data after ingestion. The custom integration example and the event enrichment example together illustrate a simple end-to-end workflow.

Create your own integration example: How it works

This example illustrates how to create a custom API that ingests raw events from an third-party service and automatically converts the data to Moogsoft-compatible events.

You're a DevOps engineer responsible for setting up Moogsoft. Your team uses an open-source tool called mooMON to monitor your infrastructure and applications. You have mooMON set up to post API notifications whenever an event of operational significance occurs.

This example is part of an overall end-to-end workflow for setting up Moogsoft:

  1. In this example, you set up a custom ingestion to ingest your events.

  2. Then you create an events workflow that formats your events into useful alerts.

  3. Finally, you set up a correlation to cluster the resulting alerts into useful incidents.

Compare schemas

Moogsoft uses two different schemas, one for events and one for metrics, to store and process incoming data. To ingest your data, you need to map the mooMon data fields to their equivalents in the Moogsoft events schema.

Moogsoft events schema (required fields)

{
    "description": "CPU spike to 75%",
    "severity": 4,
    "source": "www.your-source.com",
    "check": "cpu",
    "service": [
        "retail",
        "support"
    ]
}

You review the Moogsoft events API. You note that the fields shown above are required. You need to identify which Moogsoft fields have mooMON equivalents and which fields do not. Comparing the two schemas, you notice the following:

  • The source and service fields do not have mooMON equivalents. This is not a problem: you can put in placeholders for now. Later, you can create an automated workflow to enrich the mooMON events after they get ingested.

  • The mooMON schema includes a metadata field with a lot of useful information. This field doesn't have a Moogsoft equivalent. You can map this to a tag when you set up your custom integration.

Table 1. Moogsoft and mooMON field mapping

MoogsoftFields

mooMON fields

Comments

description

trigger_condition

severity

trigger_severity

source

No equivalent. The event source is embedded in the mooMON metadata field, for example:

["ip=172.31.17.101,hostName=websrv01.us=west.myorg.org, id=125989934839832182"]

check

trigger_policy

service

No equivalent. The mooMON schema does not include the service associated with the event.



Create and configure a new endpoint

You know how you want to map your mooMON fields to the Moogsoft Events API. You're now ready to create your custom integration. You log in to the Moogsoft UI and do the following:

  1. Choose Data Config > Integrations > Create your own Integration,, then click Add New Integration .

  2. In Configuration Information, specify the following:

    • Endpoint = moomon-events

    • API Description = mooMON Events API

    • Data Type = Events

  3. Click Save. The setup window for your custom integration appears.

Send your mooMON events to the new endpoint

Now you have an endpoint for your custom integration. You update your mooMON service to send data to the custom endpoint.

At this point the endpoint can ingest any POST notification that has a valid JSON payload and the correct API key.

Map your mooMon data fields to Moogsoft

Now that you have events coming into your new endpoint, you return to the Moogsoft. In the Map your Data section, you do the following:

  1. Select a payload in the Payload View table. the selected payload appears in the pane below.

    view-payload.png
  2. In the Field Mapping table, you map your fields as follows: .

    • For mooMON fields with a one-to-one mapping, map the fields to their Moogsoft equivalents as shown in in Table 1, “Moogsoft and mooMON field mapping above.

    • For the Moogsoft fields source and service, which have no mooMON equivalents, simply enter the string TBD.

      These strings will act as placeholders until you create a workflow that populates these fields with the correct values.

    • Map the metadata field, which has no Moogsoft equivalent, to tags.labels.

    field-mapping.png
  3. In addition to mapping fields, you also need to map the mooMon event severities to their Moogsoft equivalents. You click Map Values and map the severities:

    severity-mapping.png
  4. You return to the setup page for your custom integration, scroll down to the bottom, and click Save and Enable.

    You can also customize how your integration deduplicates events into alerts,, but this is an advanced feature and you accept the default settings.

  5. You return to the Custom APIs window. The table shows that your custom API is now active.

    moomon-in-custom-apis-table.png
  6. You go to the Alerts page and see that your mooMon events are now getting converted to alerts.

    There is still one issue: your alerts all have "TBD" as the source and the service.This is not a problem, because the hostnames are contained in the metadata tag. You can create an enrichment workflow to populate these fields. See Event Enrichment Example: How it Works.