Custom event integration

Introduction

Use a custom integration framework to create webhook and OAuth2 integrations to build data ingestion and capture events in OpsRamp. Use either OpsRamp APIs or user interface to build the integrations.

Custom event integration is configured between OpsRamp and your application if any third-party or other in-house applications are not present in the Available Integrations list.

Using Custom event integration, multiple tenants can inherit properties of a parent integration automatically without using respective configuration.

Configure using OpsRamp API

Configure webhook integration using OpsRamp API.

API endpoint: https://{api-url}/api/v2/tenants/{tenantId}/integrations/install/CUSTOM

Example alert payload in JSON from third-party applications

{
    "severity" : "Warning",
    "eventDetails" : "Test Description",
    "eventResourceName" : "Test ResourceName 1",
    "eventAlertMetric" : "Test Metric",
    "shortDescription" : "Test API Alert for custom webhook integration"
}

Example payload

Given below is the example payload for the above-mentioned JSON sample webhook event to install a custom integration with Webhook authentication and sample webhook mappings. With this payload, the default Alert Source is saved as Custom.git:

{
    "displayName": "API Testing",
    "category": "Monitoring",
    "inboundConfig": {
        "authentication": {
            "authType": "WEBHOOK"
        },
        "mapAttributes": [{
            "name": "Alert state",
            "thirdPartyAttrName": "severity",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event",
            "attrValues": [{
                "attrValue": "Ok",
                "thirdPartyAttrValue": "Ok"
            }, {
                "attrValue": "Warning",
                "thirdPartyAttrValue": "Warning"
            }, {
                "attrValue": "Critical",
                "thirdPartyAttrValue": "Critical"
            }, {
                "attrValue": "Info",
                "thirdPartyAttrValue": "Info"
            }]
        }, {
            "name": "Alert description",
            "thirdPartyAttrName": "eventDetails",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }, {
            "name": "Alert resource name",
            "thirdPartyAttrName": "eventResourceName",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }, {
            "name": "Alert metric",
            "thirdPartyAttrName": "eventAlertMetric",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }, {
            "name": "Alert subject",
            "thirdPartyAttrName": "shortDescription",
            "entityType": "ALERT",
            "thirdPartyEntityType": "Event"
        }]
    }
}

Configure using web interface

From the OpsRamp console, configure a custom event integration for webhook and OAuth2 authentication.

Configure Custom event integration

Follow these steps to configure the integration:

1. Click All Clients, select a client.

2. Click Setup > Account.

3. Select the Integrations tile.

4. The Installed Integrations screen is displayed, with all the installed applications. Click + ADD on the Installed Integrations page.

5. If you do not have any installed applications, you will be navigated to the Available Integrations page. The Available Integrations page displays all the available applications along with the newly created application with the version.
   Note: Search for the application using the search option available. Alternatively, use the All Categories option to search.

6. Click +ADD on the Custom (Event) tile.

   

7. Enter the following information:

   

   CONFIGURE

   Field Name	Field Type	Description
   Use Parent configuration and events	Checkbox	Select this option to inherit properties of a parent integration automatically. Select the Service Provider/Partner's custom integration from the drop-down list as applicable.
   Name	String	Enter a unique name for the integration.
   Alert Source	Dropdown	Select Custom if you do not find the source already available on the list. Based on the selection, the alerts are filtered in the OpsRamp Alerts section. To add a source on the list to filter alerts, contact Support.
   Description	String	Provide a description for the integration.

   Note: If you select Use Parent configuration and events option, the Name, Alert Source, and Description fields are disabled. These fields will be inherited along with other properties like configuration, inbound mapping attributes.

8. Click Next. The INBOUND screen is displayed.

   

   Custom event integration allows for INBOUND (third-party application to OpsRamp) communication.

   Configure INBOUND communication

   AUTHENTICATION:

   Field Name	Field Type	Description
   Authentication Type	Dropdown	OpsRamp supports APIs with OAUTH2 and WEBHOOK for Custom Event integration. Select OAUTH2 or WEBHOOK. Access Key information is displayed.
   Role	Dropdown	Select the role of the user installing the integration. You can execute only those APIs that are associated with the selected role.

   GENERATE KEY: Click to generate the Tenant ID, Key and Secret. Use the copy icon to make a note of the token.
   REVOKE ACCESS TOKEN: Click to revoke access token. This option is displayed only for OAUTH2 authentication type.

   MAP ATTRIBUTES: Map the tenant entity attributes with OpsRamp entity.
   Click +ADD and enter the following information in the ADD MAP ATTRIBUTES window:

   Field Name	Field Type	Description
   OpsRamp Entity	Dropdown	Select OpsRamp entity from the dropdown.
   OpsRamp Property	Dropdown	Select OpsRamp property from the dropdown. It will change based on entity selection.
   CUSTOM-EVENT Entity	String	Enter the Custom Event Entity in the box.
   CUSTOM-EVENT Property	String	Enter the Custom Event Property in the box.

   PARSING CONDITION: To give a parsing condition, provide values in the Operator and Value fields.

   PROPERTY VALUES: Click +PROPERTY VALUE. Enter the following information and click SAVE.
   This section is displayed based on the OpsRamp Property selected.

   Field Name	Field Type	Description
   CUSTOM-EVENT Property Value	String	Enter custom event property value in the box.
   OpsRamp Property Value	Dropdown	Select a value from the dropdown. Based on the OpsRamp Property selected, the options in this field vary.

   • Click SAVE to save the property value(s).
     
     (Or) Default Value: Select a default value from the dropdown. If the above condition does not meet the criteria, the default value is considered.
     
     

9. Click ADD MAP ATTRIBUTES. The mapped information is displayed in the MAP ATTRIBUTES section.

   • Use the three dots menu to edit or remove the map attributes.
   • Use Filter to filter the map attributes.
     
     

   ADDITIONAL SETTINGS: You can configure event ingestion integrations to post events only if the resources are managed by OpsRamp. For resources that are not managed, the events are dropped and not processed.

   • Select the Drop alerts from unmanaged resources checkbox as needed.
     
     

   ENRICH AND CREATE ALERT: Select process definition from the dropdown.
   Note: For the integration to enrich and create an alert, the process definition selected should have the Create Alert task configured.

10. Click FINISH. The custom event integration is installed and displayed under Installed Integrations.

Actions on Integration

You can perform actions like View Logs, Export, Edit, Assign Templates, and Uninstall on the integration.

• See Actions on Integration for more information.

Audit Logs

View Inbound logs from the View Logs option for the integration. You can view if the event was successful or not.

See Audit Logs for more information.

View Alerts

Navigate to the Alert browser to view the alert(s).

Validate

Validate the configurations using any API development tool, for example, POSTMAN.

Example request payload

{
"Alertstate" :"Ok",
"Description":"test description",
"serviceName":"Metric",
"ResourceName":"Host",
"Subject" : "Alert Subject"
}

Post alert through Postman

1. Enter webhook URL copied from OpsRamp.
2. Change the method to POST.
3. Add the mentioned headers ‘Content-Type: application/json’ and ‘Accept: application/json’.
4. Enter the JSON request payload in the body section.
5. View failure or success result.