Skip to main content

Integrate ServiceNow with legacy Moogsoft Cloud 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 Moogsoft Cloud 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 Moogsoft Cloud. 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 Moogsoft Cloud maintenance windows feature and provides instructions on how to:

  • Exclude alerts in maintenance windows from correlation in Moogsoft Cloud.

  • 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:

  1. In ServiceNow, navigate to All > Moogsoft Integration > System > Moogsoft Cloud Properties.

  2. 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.

  3. 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 Moogsoft Cloud.

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 Moogsoft Cloud servicenow_maintenance_windows catalog entries matching the change are identified and deleted.

To use the catalog for alert suppression during change windows, add a Moogsoft Cloud 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:

  1. Navigate to Correlate & Automate > Correlation Engine.

  2. Click on an existing correlation definition to open it.

  3. Scroll down to the Definition section.

  4. Under Scope, select "Filter alerts: Consider only alerts that match this filter."

  5. Set the Alert Scope to include the following:

    tags.maintenance != true
  6. Click Save.

  7. 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 Moogsoft Cloud 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 Moogsoft Cloud 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:

  1. Create a new Event Workflow by navigating to Correlate & Automate > Workflow Engine > Event Workflows and clicking Add Workflow:

  2. Add a suitable workflow name and description. For example: "Tag ServiceNow Maintenance Windows"

  3. Add an Event Filter if required, to restrict the events that the workflow will process.

  4. From the list of Actions, drag and place a Query Catalog action under the Trigger in the Workflow section.

  5. Select servicenow_maintenance_windows from the drop-down list under Catalog Name.

  6. 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

  7. 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

  8. 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.

  9. Save and Enable the workflow.