Configuration > SevOne NMS to SevOne Data Insight Drillback URL Configuration Tutorial

The drillback URL configuration tutorial can also be found in SevOne NMS User Guide > section Webhook Definition Manager.
IMPORTANT
NMS cluster must be on SevOne NMS 6.3.1 or higher.

This section explains the SevOne Data Insight URL structure, how to create the structure from SevOne NMS > Events > Configuration > Webhook Definition Manager, the origin of each of its constituent URL components, and the prerequisites required in SevOne Data Insight and SevOne NMS for this integration to work.

SevOne Data Insight Setup

As of SevOne Data Insight 3.14, flag FF_UI_REDIRECT has been added to provide the capability to redirect the user interface using the redirect option in the URL.

URL Redirector API
The URL redirector is a URL-based API for translating simple resource information into complex Data Insight user interface data types for webhooks and other linking purposes.
Routing
The default redirector route is at /redirect/v1/reports. At present, reports are supported for redirection and URL translation. If you are not logged in, you will be prompted to log in and then, redirection will continue.

With the new URL redirector API (i.e., flag FF_UI_REDIRECT), you can easily create, view, and understand webhook drillback URLs. By default, this flag is set to false. In order to use the FF_UI_REDIRECT flag, you must set it to true.

  1. SSH into your SevOne Data Insight machine and log in as sevone and at the Password prompt, enter sevone.

    $ ssh sevone@<virtual machine IP address or hostname>

  2. Using a text editor of your choice, edit /opt/SevOne/chartconfs/di_custom.yaml file to set flag, FF_UI_REDIRECT, and then, save it.

    If /opt/SevOne/chartconfs/di_custom.yaml file does not exist, please create one and add the following to it. 
    ui:
  env:
    FF_UI_REDIRECT: true

  3. Apply the change made to /opt/SevOne/chartconfs/di_custom.yaml file.

    $ sevone-cli playbook up --tags apps

Before configuring a webhook containing drillback URL, a SevOne Data Insight report must exist; this will be the destination for the drillback and ideally, this report will be shared with all the users. This will ensure that all users who will click the link in the webhook, will be able to access the desired report.

The webhook URL sends the resources to the report. These resources are intended to provide context from the generating alert to the report to place a user, in context, within the report. It is highly recommended that the chosen report has variables configured for the report to accept these resources. From SevOne Data Insight, a report can be prepared for the resources that will be passed from the webhook URL. Using a web browser of your choice, enter your SevOne Data Insight IP address or hostname of the machine to which you want to add the report variables. Please refer to SevOne Data Insight User Guide > section Create > Report Options > Variables for details.

Example

deviceSummary
The dynamic URL creation process references the selected resource types that are used in SevOne Data Insight OOTB (out-of-the-box) reports.

SevOne NMS Setup

Any SevOne NMS sending out webhooks containing drillback URLs must already be configured as a datasource on an instance of SevOne Data Insight. Administrators creating Webhook Definitions must already know the IP address / hostname or the URL of SevOne Data Insight instance and the names of any SevOne Data Insight reports which will be referenced in the drillback URL.

This feature is designed such that SevOne NMS clusters must have the same name as their SevOne Data Insight datasource name in multi-datasource use-cases.

To create a webhook definition, please refer to SevOne NMS User Guide > section Webhook Definition Manager > subsection Add Webhook Definition for details. In addition to this, you will also find details on how to configure Slack channel.

Sections Edit Webhook Definition and Delete Webhook Definition provide details on how to edit or delete an existing webhook.

SevOne Data Insight drillback URLs are configured inside Webhook Definitions as part of the message body. Administrators can build their own definitions or reference the starter template for Slack message.

SevOne Data Insight Drillback URL Structure

To create a SevOne Data Insight drillback URL inside Webhook Definition, the following is required.

  1. address of SevOne Data Insight instance which the URL will reference
  2. name of SevOne Data Insight report the user will be navigated to
  3. resources that will be referenced from the alert dynamically as variable $DIDataResources. This variable contains alert-specific information about the threshold violating the following.
    1. Datasource / Cluster Name
    2. Plugin Name
    3. Object Types
    4. Device Name
    5. Object Name(s)
    6. Indicator Type(s)
    7. Relative Timespan

Example: Create SevOne Data Insight URL in SevOne NMS Alert
Generic URL
http://<SevOne Data Insight IP address or hostname>/redirect/v1/reports?&$DIDataResources

Example# 1
Let's assume the following.

  • SevOne Data Insight address or hostname: localhost
  • SevOne Data Insight report name: Alert Details Report
  • Resources: this is automated by passing variable $DIDataResources in the URL

Your URL will be, http://localhost/redirect/v1/reports?reportName=Alert\%Details%Report&$DIDataResources where, the parameter is reportName.

Example# 2
Let's assume the following.

  • SevOne Data Insight address or hostname: 10.128.10.24
  • SevOne Data Insight report name: Alert Details Report
  • Resources: this is automated by passing variable $DIDataResources in the URL

Your URL will be, http://10.128.10.24/redirect/v1/reports?reportName=Alert%Details%Report&$DIDataResources where, the parameter is reportName.

For the list of available parameters, please refer to section Parameters.

Once you have created a valid SevOne Data Insight drillback URL, it will send the webhook's parameters to the Data Insight instance running at localhost. When this instance of Data Insight receives the URL, it will open Alert Details Report and automatically fill out the variables with the values provided by the webhook.

Single Datasource

This feature is designed to work with single NMS cluster as a datasource, with no additional configuration necessary.

Multi Datasource

To navigate users to the correct report resources in environments where there are multiple NMS clusters set up as Data Insight datasources, the Cluster Name of each NMS cluster sending webhook alerts must match the Data Insight datasource. $DIDataResources automatically appends the value of the Cluster Name as parameter, datasourceName, to the URL. In the event of a mismatch, the administrator can change to the desired datasource inside SevOne Data Insight. This design approach is chosen to require consistent naming and navigation to the correct resources.

Example: Functional URL

https://localhost/redirect/v1/reports?reportName=Alert%20Details%20Report&datasourceName=MyClusterName&indicators=SNMP%26%26Interface%26%26SNMPDevice%201%26%26Fa0%2F11%26%26ifInErrors%7C%7CSNMP%26%26Interface%26%26SNMPDevice%201%26%26Fa0%2F11%26%26ifOutErrors%7C%7CSNMP%26%26Interface%26%26SNMPDevice%201%26%26Fa0%2F11%26%26ifInDiscards%7C%7CSNMP%26%26Interface%26%26SNMPDevice%201%26%26Fa0%2F11%26%26ifOutDiscards&startTime=1667409663000
where,
Base URL is,
  • SevOne Data Insight address: https://localhost/redirect/
  • API version: v1
  • API function: reports
  • Report Name: Alert Details Report

Dynamic Alert Variables are,

  • Datasource / Cluster Name: MyClusterName
  • DIDataResources:
    • Plugin: SNMP
    • Object Type: Interface
    • Device Name: SNMPDevice 1
    • Object Name: Fa0/11
    • Indicator Type: ifInErrors
      • OR
    • Plugin: SNMP
    • Object Type: Interface
    • Device Name: SNMPDevice 1
    • Object Name: Fa0/11
    • Indicator Type: ifOutErrors
      • OR
    • Plugin: SNMP
    • Object Type: Interface
    • Device Name: SNMPDevice 1
    • Object Name: Fa0/11
    • Indicator Type: ifInDiscards
      • OR
    • Plugin: SNMP
    • Object Type: Interface
    • Device Name: SNMPDevice 1
    • Object Name: Fa0/11
    • Indicator Type: ifOutDiscards
  • Relative Timespan: 1667409663000 (as Epoch timestamp)
URL Legend
The URL ASCII character encoding has been omitted from URL legend above for readability.
  • %20 = space
  • %26 = &
  • %2f = /
  • %7C = |

Parameters

Parameters are provided in query search format.

http://localhost:8080/redirect/v1/reports?reportName=Indicator Summary&datasourceName=CX NMS

where,

  • reportName = Indicator Summary
  • datasourceName = CX NMS

URLs must be URL-encoded before being passed to the redirect route.

Combined Parameters

Some fields require information to be in a combined format and have optional support for multiple parameters of a type. In the case of a combined input, fields must be separated by &&. For example, (Device Name)&&(Object Name) for an object input.

Use || as a separator for fields with optional multiple parameters. For example, (Device Name 1)&&(Object Name 1)||(Device Name 2)&&(Object Name 2).

reportId

Is the report ID parameter. It takes the report ID and sets it as the redirect target. This will override any ID passed in reportName parameter.

reportName

Is the report name parameter. It translates a report name into the report ID and sets it as the target of the redirect when using the reports redirect route.

datasourceId

Is the datasource ID parameter. It takes a given datasource ID and sets it as the target datasource. It overrides any provided datasourceName parameter.

datasourceName

Is the datasource name parameter. It translates a datasource name into an ID and sets it as the target datasource.

startTime / endTime

Are the specific time parameters where startTime and endTime are UNIX timestamps. It takes a UNIX timestamp startTime and optional endTime and sets it as the timespan for the report. If no endTime is provided, it defaults to the current UNIX timestamp. This will always override both timespan and customTimespan parameters.

timespan

Is the SevOne timespan parameter. It takes a SevOne timespan for example, PAST_24HOURS, and sets it as the timespan for the report.

customTime

Is the custom time string parameter. It takes a custom time string for example, PAST 24 Hours, and sets it as the timespan for the report.

timezone

Is the timezone string parameter. It takes a timezone string and applies it to the timespan parameter. For example, America/Anchorage.

deviceGroups

Is the [Device Group Path] parameter separated by /. It takes a set of device group paths and translates them into device groups useable by report variables.

devices

Is the [Device Name] parameter. It takes a set of device names and translates them into devices useable by report variables.

objects

Is the [Plugin Name + Device Name + Object Name] parameter. It takes a set of plugin, device and object names and translates them into objects useable by report variables. At present, the object report variable only uses the first object.

indicators

Is the [Plugin Name + Object Type Path (separated by /) + Devcie Name + Object Name + Indicator Type Name] parameter. It takes a set of plugin, object type, device, object and indicator type names and translates them into indicators useable by report variables.