Skip to main content

Example scenario for CYOI

This example illustrates how to create a custom API using Create your own integration (CYOI) that ingests raw events from a third-party service and automatically converts the data to APEX AIOps Incident Management-compatible events.

You're a DevOps engineer responsible for setting up Incident Management. 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.

Compare schemas

Incident Management 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 Incident Management events schema.

Incident Management example event payload

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

You review the Incident Management Events API.

  • The description, severity, source, and check fields are required.

  • The service field is optional but recommended.

  • Additional fields, for example manager, class, and type, are optional.

  • The optional location field accepts a set of specified subfields as key-value pairs.

  • You can use subfields of the optional tags field to map fields without equivalents in Incident Management as key-value pairs.

You need to identify which Incident Management 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 use default values 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 an Incident Management equivalent. You can map this to a tag when you set up your custom integration.

Here is the mapping you develop after examining the two schemas:

Incident Management

MooMon

description

trigger-condition

severity

trigger-severity

source

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

{agent=SERVER, ip=172.110.122.253, fqdn=websrv1.damenport.org, violationID=751963324, accountID=45322702}

check

trigger-policy

service

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

class

trigger-type

location.data_center

trigger-location

tags.metadata

metadata

Create and configure a new endpoint

You know how you want to map your MooMon fields to the Incident Management events schema. You're now ready to create your custom integration. You log in to Incident Management and do the following:

  1. Choose Integrations > Ingestion Services > Create your own Integration, then click Add New Integration .

  2. In Configuration Information, specify the following:

    Incident Management Endpoint

    moomon

    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 custom endpoint can ingest any POST notification that has a valid JSON or XML payload and the correct API key.

Map your MooMon data fields to Incident Management

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

  1. Select a payload in the Payload View table. The selected payload appears in the pane to the right.

    view-payload.png

    NOTE: If your payloads include multiple events in a list under a top-level object, see Use batch processing with custom integrations for data field mapping instructions.

  2. In the Field Mapping table, map your fields as follows:

    • Map the MooMon fields to their Incident Management equivalents as shown in the table above.

    • Keep the default value "Missing source" for the required field source.

    • Enter "Missing service" as a default value for service.

    • Add a new mapping row to map trigger-location to location.data_center.

    • Add a new mapping row, click Add Tag, and enter "metadata" to map metadata to tags.metadata.

    payloadv2.png

  3. Map the MooMon event severities to their Incident Management equivalents. Click Map Values and add the severities:

    severity1.png

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

  5. Click Save. The integration changes from provisioned to active status when the next event arrives.

  6. Go to the Alerts page and verify that your MooMon events are now getting converted to alerts.

    There is still one issue: the alerts all have missing source and service fields. This is not a problem, because you can configure an event workflow to do the following:

    • Extract the hostnames from tags.metadata

    • Populate the service field using a data catalog

    See Event workflow configuration example for more information.

In this section: