Integrate ServiceNow with legacy APEX AIOps Incident Management maintenance windows

Note

This topic covers the use of legacy maintenance windows, which involve creating a data catalog and event workflow. To use the built-in APEX AIOps Incident Management maintenance window feature with your ServiceNow integration, read this topic.

If the Enable Moogsoft Maintenance Window integration option is enabled in the ServiceNow integration, then a new catalog and workflow will automatically be created for you in Incident Management. You can use this maintenance catalog and workflow to handle alerts that come from ServiceNow CIs undergoing maintenance.

This topic explains the behavior of the legacy Incident Management maintenance windows feature and provides instructions on how to:

Exclude alerts in maintenance windows from correlation in Incident Management.
Manually create the maintenance catalog, along with any additional workflows.

Important

Make sure that you have installed the update set by following these instructions before you continue.

Enable the legacy maintenance windows feature

To enable the legacy maintenance windows feature:

In ServiceNow, navigate to All > Moogsoft Integration > System > Moogsoft Cloud Properties.
Scroll down and select "Yes" for Enable Moogsoft Maintenance Window integration.
Important
In order to use the legacy maintenance windows feature, make sure that Use New Maintenance Windows Feature is disabled.
Click Save at either the bottom or the top of the page.
Legacy maintenance windows are now enabled for your integration. A new catalog and workflow will automatically be created for you in Incident Management.

How the maintenance catalog behaves

Once in place, ServiceNow will create and maintain a catalog called servicenow_maintenance_windows with details of the CIs under change.

With this option enabled, any ServiceNow change requests that list Affected CIs will create entries in the servicenow_maintenance_windows catalog when the change request enters the Implementation state. The catalog entries will be of the form:

Field name	Type	Required	Example
`ci_name`	STRING	true	Node 1
`description`	STRING	false	This standard change template describes adding a new network switch to a datacenter cabinet.
`change_ref`	STRING	true	CHG0040006
`duration`	NUMBER	true	7200
`actual_start_time`	STRING	true	2021-10-31T10:30:00+0000
`planned_end_time`	STRING	true	2021-10-31T12:30:00+0000
`maintenance`	BOOLEAN	true	true

There will be one such entry for every Affected CI listed in the change request. If the catalog doesn’t exist, it will be created.

At the end of the change window, when the change request in ServiceNow moves out of the Implementation state, all Incident Management servicenow_maintenance_windows catalog entries matching the change are identified and deleted.

To use the catalog for alert suppression during change windows, add an Incident Management event workflow by following the steps in this section.

Exclude alerts in maintenance windows from correlation

To prevent alerts in maintenance windows from creating incidents:

Navigate to Correlate & Automate > Correlation Engine.
Click on an existing correlation definition to open it.
Scroll down to the Definition section.
Under Scope, select "Filter alerts: Consider only alerts that match this filter."
Set the Alert Scope to include the following:
```
tags.maintenance != true
```
For guidance on using the scope filter, refer to Build a scope filter query.
You can preview the effect that a filter has on your data before applying it by clicking Preview. The window displays the last 100 alerts that match your filter. You can click Refresh to make sure you are viewing the latest data.
- Click Columns to show or hide columns, and for pinning and auto-size options.
- Sort the alerts in a column by clicking the header; reverse the sort by clicking it again.
When satisfied with your filter, click Apply to apply it. To exit the preview without applying the filter, click Cancel.
Click Save.
For detailed steps on configuring all parts of a correlation definition, read Create a new correlation definition.

Create catalog and additional workflows manually

The integration installs an initial workflow to implement maintenance windows. You may also manually create the catalog and any additional workflows, if required.

Before you begin:

Navigate to Correlate & Automate > Workflow Engine > Enrichment Data Catalogs and make sure that the servicenow_maintenance_windows catalog has been created. This will be the case if the ServiceNow Incident Management application has processed a change request entering Implementation.

If the catalog has not been created, you can create it manually by running the following cURL request on your terminal, where API_KEY is replaced with a valid Incident Management API Key:

Note

curl -X POST 'https://api.moogsoft.ai/v1/catalogs' \
    --header 'Accept: application/json' \
    --header 'apiKey: API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "name": "servicenow_maintenance_windows",
    "description": "ServiceNow Maintenace Windows",
    "schema": {
        "fields": [
            {
                "name": "ci_name",
                "required": true,
                "type": "STRING"
            },
            {
                "name": "description",
                "required": false,
                "type": "STRING"
            },
            {
                "name": "change_ref",
                "required": true,
                "type": "STRING"
            },
            {
                "name": "duration",
                "required": true,
                "type": "NUMBER"
            },
            {
                "name": "actual_start_time",
                "required": true,
                "type": "STRING"
            },
            {
                "name": "planned_end_time",
                "required": true,
                "type": "STRING"
            },
            {
                "name": "maintenance",
                "required": true,
                "type": "BOOLEAN"
            }
        ]
    }
    }'

To create additional workflows manually:

Create a new Event Workflow by navigating to Correlate & Automate > Workflow Engine > Event Workflows and clicking Add Workflow:
Add a suitable workflow name and description. For example: "Tag ServiceNow Maintenance Windows"
Add an Event Filter if required, to restrict the events that the workflow will process.
From the list of Actions, drag and place a Query Catalog action under the Trigger in the Workflow section.
Select servicenow_maintenance_windows from the drop-down list under Catalog Name.
Update the Lookup Mapping to select a field to lookup against the ci_name in the catalog. For example, in order to match Source to ci_name:
Field
Catalog field
Source
ci_name
Add the following mappings to the Apply Mapping section:
Catalog field
Field
Default value
change_ref
change_ref
description
change_description
duration
change_duration
actual_start_time
change_actual_start
planned_end_time
change_planned_end
maintenance
maintenance
false

Field	Catalog field
`Source`	`ci_name`

Catalog field	Field	Default value
`change_ref`	`change_ref`
`description`	`change_description`
`duration`	`change_duration`
`actual_start_time`	`change_actual_start`
`planned_end_time`	`change_planned_end`
`maintenance`	`maintenance`	`false`

Perform a test by entering appropriate values for the Field and Input for the configured Lookup Mapping. Then click Run Test to confirm the appropriate Output.

For example:

Field	Input	Tags	Comment
`Source`	Node 1	{ "maintenance": false }	Catalog with no matching `ci_name`.
`Source`	Node 1	{ "change_ref": "CHG0040006", "description": "This standard change template describes adding a new network switch to a datacenter cabinet", "duration": 7200, "change_actual_start": "2021-10-31T10:30:00+0000", "change_planned_end": "2021-12-31T10:30:00+0000", "maintenance": true }	Catalog with matching `ci_name`.

Field

Input

Integrate ServiceNow with legacy APEX AIOps Incident Management maintenance windows

Note

Important

Enable the legacy maintenance windows feature

Important

How the maintenance catalog behaves

Exclude alerts in maintenance windows from correlation

Create catalog and additional workflows manually

Note

Search results