By default, this product expects the user to supply a configuration file in the work directory; the work directory is $VCOPS_BASE/user/plugins/inbound/servicenow_adapter3/work

The configuration file consists of an array of resourceTypes. Each element is explained below in detail.

{
  "resourceTypes": [
    {
      "vROps": {...},
      "serviceNow": {...},
      "groupTypes": [],
      "hierarchies": [[]]
    },
    ...
  ]
}

vROps

the vROps object in the resourceType defines the type of vROps resource that will be assigned properties based on CMDB columns.

Example:

"vROps": {
  "type": {...},
  "id": {...}
}

Type

This object describes the resource and adapter kinds. Both are required.

"type": {
  "resourceKind": "VirtualMachine",
  "adapterKind": "VMWARE"
}

ID

This field describes the the identification mechanism used to match with a ServiceNow CI. There are 3 different ways this can be defined.

  • Identifier: This method matches based on the value of the specified resource identifier on the resource. Set type to IDENTIFIER and field to the name of the identifier on the ResourceKind.

    "id": {
      "type": "IDENTIFIER",
      "field": "VMEntityName"
    }
  • Property: This method matches based on the latest value assigned to the specified property. Set type to PROPERTY and field to the name of the property on the ResourceKind.

    "id": {
      "type": "PROPERTY",
      "field": "config|name"
    }
  • Unique ID: This method uses the unique ID generated by vROps as the value matched by ServiceNow CI. Set type to VROPS_UNIQUE_ID and do not specify a field in order to use this method.

    "id": {
      "type": "VROPS_UNIQUE_ID"
    }

ServiceNow

The serviceNow object in the resourceType defines the type of ServiceNow CI that should be matched to the vROps resource.

"serviceNow": {
  "type": {...},
  "id": {...}
}

Type

This object describes the CI Class of the CI that will be matched to the defined vROps ResourceKind.

"type": {
  "cmdbCiClass": "cmdb_ci_vmware_instance"
}

ID

The column whose value will be matched to the id specified on the defined vROps ResourceKind.

"id": {
  "column": "vm_instance_uuid"
}

Group Types

The groupTypes array contains a list of mappings from serviceNow columns to vROps groups.

"groupTypes": [
  {...},
  {...}
],

There are two ways to assign these mappings.

  • Standard: This is used for string-based properties in which the literal string value of the serviceNowColumn will be used to create a group named the value specified by vROpsGroupType. All matched resources will be assigned to the group of type vROpsGroupType that matches the value of the column. In the example below, if a CI has u_application = myApp in the CMDB, the vROps resource will be assigned to a group of type Application named myApp.

    {
      "serviceNowColumn": "u_application",
      "vROpsGroupType": "Application"
    }
  • Boolean: This is used for boolean properties only. The serviceNowColumn and vROpsGroupType work as explained above, but instead of assigning the literal value of the column, the adapter will translate it to the values assigned in the booleanMapping. In the example below, if a CI returns u_main_business_unit = true, the vROps resource will be assigned to a group of type Business Unit named Main.

    {
      "serviceNowColumn": "u_main_business_unit",
      "vROpsGroupType": "Business Unit",
      "booleanMapping":
      {
        "trueValue": "Main",
        "falseValue": "Other"
      }
    }
  • Additionally, columns may be a reference to an object in another table. To do this, 'dot notation' is used.

    {
      "serviceNowColumn": "domain_manager.manager.name",
      "vROpsGroupType": "Domain Manager"
    }

Hierarchies

Hierarchies organize the groups. Objects at the top of the hierarchy are considered parents of objects lower on the hierarchy. The resourceKind is the vROpsGroupType from the groupTypes array.

"hierarchies": [
  [
    {
      "resourceKind": "Business Unit"
    },
    {
      "resourceKind": "Application"
    }
  ]
]

It is possible to have multiple hierarchies that reference different vROpsGroupTypes. It is also possible for them to share some of their group types.

"hierarchies": [
  [
    {
      "resourceKind": "Business Unit"
    },
    {
      "resourceKind": "Application"
    }
  ],
  [
    {
      "resourceKind": "Business Unit"
    },
    {
      "resourceKind": "Other Group"
    }
  ]
]

In the above scenerio, Application and Other Group are both related to the Business Unit, but are not considered directly related to one another.

Constraints:

  • Hierarchies must not be cyclic (Business Unit cannot both be a parent and a child of Application). This is for both individual resourceTypes and across all resourceTypes (Business Unit cannot be a parent of Application for a VM, but a child of Application for a Datastore). The hierarchy object can be assigned "adapterKind": "Container", but this can also be omitted since it is the only allowable adapterKind.
  • All groups must be present in at least one hierarchy on the resourceType where it is defined.
  • Similarly, groups in a hierarchy must be defined as a vROpsGroupType on the resourceType where it is defined.

Incident Sync

Incident configurations are used for the alert-sync feature and define what types of alerts will be synced between vROps and ServiceNow. This feature only works on vROps 7.5+ using the built in ServiceNow plugin. It depends on this plugin filter to send initial alerts from vROps to ServiceNow. Once the vROps alert is present in ServiceNow, the ServiceNow Management Pack performs the following additional features:

  • If an alert is cancelled in vROps, the corresponding incident in ServiceNow is closed.
  • If an incident is closed in ServiceNow, the corresponding alert in vROps is suspended. Alerts in vROps are generally triggered automatically by breaching thresholds. Because we cannot control this, if an incident is closed in ServiceNow it should be due to the underlying issue being resolved. Thus, we suspend the Alert in vROps (for a configurable length of time) to allow the alert to resolve. If the threshold(s) is still breached when the alert suspend time has ended, the alert will re-trigger and reopen the ServiceNow Incident.
  • If a vROps alert is triggered on a vROps ResourceKind that is present in one of the resourceTypes sections above, the ServiceNow Management Pack will create a reference from the incident's cmdb_ci column to the CI representing the resource in ServiceNow the alert was triggered on. A resourceType section can be created with empty groupTypes and hierarchies arrays for matching to a resource type, without creating any groupings and hierarchies.
  • The ServiceNow Management Pack can be configured to watch a predefined set of incident columns and display the current values in the corresponding vROps alert as a series of notes.

Incident Configuration

Prerequisites: Set up at least one Notificate Rule in vROps using the Service-Now Notification Plugin. This can be found in Alerts > Alert Settings > Notification Settings. The Caller(s) in the notification rule(s) should be noted as they will be required in the MP Configuration. See VMware documentation for further details.

If incident sync is not desired, incidentConfigs can be omitted entirely, or an empty list can be used:

"incidentConfigs": []

A typical incident config may look like this:

{
  "callerId": "vROps Service User"
  "propagateAlertUpdates": true,
  "retrieveIncidentUpdates": true,
  "incidentElementsToRetrieve": ["assigned_to", "priority", "urgency"],
  "incidentReopenState": "New",
  "incidentCloseState": "Closed",
  "vropsSuspendMinutes": 30
}

One incident config section should be created for each distinct caller used in at least one vROps ServiceNow notification rule. For example, if 10 ServiceNow rules are present, and two use the caller VM Admin and eight use the caller Storage Admin, there should be two incident config sections. The contents of these configs can be customized to each caller, or they can be otherwise identical.

"incidentConfigs": [
  {
    "callerId": "VM Admin",
    ...
  },
  {
    "callerId": "Storage Admin",
    ...
  }
]

In each incident config, the following options are supported:

Parameter Type Description
callerId String The callerId is the ServiceNow caller assigned in vROps ServiceNow plugin configuration. This is the only required field - defaults will be used for all other fields. All incidents in ServiceNow that have this caller id will be treated according to this configuration. Two incident configuration sections cannot have the same caller id.
propogateAlertUpdates Boolean When set to true, ServiceNow incidents will be closed and reopened based on the vROps alert's status. Defaults to true.
retrieveIncidentUpdates Boolean When set to true, vROps alerts will be suspended when an incident is in a closed state. In addition, any elements specified in incidentElementsToRetrieve will be sent to the vROps alert as notes when they change. Defaults to true.
incidentReopenState String Defines what ServiceNow state to set an incident to when it is reopened. Defaults to New.
incidentCloseState String Defines the ServiceNow state for an incident to be considered closed. This is used to determine when to mark a vROps alert as suspended, and as the state to set an incident to when a vROps alert is cancelled. Defaults to Closed.
vropsSuspendMinutes Int Defines how long (in whole minutes) an alert should be suspended when the corresponding ServiceNow incident is marked as closed.
incidentElementsToRetrieve Array A list of strings corresponding to incident table columns that are surfaced in vROps alerts as notes. Columns with dot notation are allowed. The default list is state assigned_to.name priority, and urgency.

Examples of Configuration Files

Below are two examples of functional configuration files:

Configuration File Example A

{
  "resourceTypes": [
    {
      "vROps": {
        "type": {
          "resourceKind": "VirtualMachine",
          "adapterKind": "VMWARE"
        },
        "id": {
          "type": "IDENTIFIER",
          "field": "VMEntityName"
        }
      },
      "serviceNow": {
        "type": {
          "cmdbCiClass": "cmdb_ci_vmware_instance"
        },
        "id": {
          "column": "name"
        }
      },
      "groupTypes": [
        {
          "serviceNowColumn": "u_application",
          "vROpsGroupType": "Application"
        },
        {
          "serviceNowColumn": "u_main_business_unit",
          "vROpsGroupType": "BusinessUnit",
          "booleanMapping":
            {
              "trueValue": "Main",
              "falseValue": "Other"
            }
        }
      ],
      "hierarchies": [
        [
          {
            "adapterKind": "Container",
            "resourceKind": "BusinessUnit"
          },
          {
            "adapterKind":"Container",
            "resourceKind": "Application"
          }
        ]
      ]
    }
  ]
}

Configuration File Example B

{
  "resourceTypes": [
    {
      "vROps": {
        "type": {
          "resourceKind": "VirtualMachine",
          "adapterKind": "VMWARE"
        },
        "id": {
          "type": "PROPERTY",
          "field": "config|name"
        }
      },
      "serviceNow": {
        "type": {
          "cmdbCiClass": "cmdb_ci_vmware_instance"
        },
        "id": {
          "column": "name"
        }
      },
      "groupTypes": [
        {
          "serviceNowColumn": "u_application",
          "vROpsGroupType": "Application"
        },
        {
          "serviceNowColumn": "u_main_business_unit",
          "vROpsGroupType": "BusinessUnit",
          "booleanMapping":
          {
            "trueValue": "Main",
            "falseValue": "Other"
          }
        }
      ],
      "hierarchies": [
        [
          {
            "adapterKind": "Container",
            "resourceKind": "BusinessUnit"
          },
          {
            "adapterKind":"Container",
            "resourceKind": "Application"
          }
        ]
      ]
    }
  ]
}