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.

{
  "cmdbSync": {},
  "resourceTypes": [
    {
      "vROps": {...},
      "serviceNow": {...},
      "identifierMapping": [],
      "groupTypes": [],
      "groupHierarchies": [[]]
    },
    ...
  ],
  "alertingConfigs": [
    {...},
    ...
  ]
}

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"
          }
        ]
      ]
    }
  ]
}

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": {...}}

Type

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

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

ServiceNow

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

"serviceNow": { "type": {...}}

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"}

Identifier Mapping

An array of mappings. Each mapping references one ServiceNow column which maps to a vROps Property, Identifier, Name, or vROps UUID. In most cases, using a unique identifier in combination with the vCenter UUID is preferred.

{ "identifierMapping": [ { "serviceNowId": { "column": "object_id" }, "vropsId": { "type": "IDENTIFIER", "field": "VMEntityObjectID" } }, { "serviceNowId": { "column": "vcenter_uuid" }, "vropsId": { "type": "IDENTIFIER", "field": "VMEntityVCID" } } ]}

ServiceNow ID

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

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

VROps ID

This field describes 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"}

  • Name: This method uses the name of the resource in vROps as the value matched by ServiceNow CI. Set type to NAME and do not specify a field in order to use this method.

"id": { "type": "NAME"}

  • UUID: This method uses the unique ID generated by vROps as the value matched by ServiceNow CI. Set type to UUID and do not specify a field in order to use this method.

"id": { "type": "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"}

Boolean mappings can be used (at the top level) as well. The value returned by the referenced table will use the boolean mapping in this case

{ "serviceNowColumn": "domain_manager.manager.active", "vROpsGroupType": "Domain Manager", "booleanMapping": { "trueValue": "Active", "falseValue": "Inactive" }}

Group Hierarchies

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

"groupHierarchies": [ [ { "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.

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

In the above scenario, 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.

Alert Sync

Alerting configurations for the alert-sync feature define what alerts will be synced between vROps and ServiceNow, and how they will be represented in ServiceNow. The three supported representations are INCIDENT (default), ALERT, and EVENT. 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 or alert in ServiceNow is closed.

  • If an incident or alert 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 or alert 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 or alert.

  • If a synced vROps alert is 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/alert/event cmdb_ci column to the CI representing the resource in ServiceNow. Note: 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/alert/event columns and display the current values in the corresponding vROps alert as a series of notes.

Configuration

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

"alertingConfigs": []

A typical incident config may look like this:

"alertingConfigs": [ { "callerId": "vROps Service User" "propagateAlertUpdates": true, "retrieveIncidentUpdates": true, "incidentElementsToRetrieve": ["assigned_to.name", "state", "cmdb_ci.sys_id"], "incidentReopenState": "In Progress", "incidentCloseState": "Closed", "vropsSuspendMinutes": 30 }]

Each config contains a callerId which identifies which config the ServiceNow incident/alert/event comes from. The callerId does not need to be distinct between alerting configs, however there are some performance benefits if each alertingConfig has a unique callerId. Note that in the rare case where multiple vROps instances are monitoring the same vCenter and are pointing to the same ServiceNow instance, the callerIds should all be distinct between the vROps instances. Note that this list is ordered

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

In each alerting 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.

serviceNowDestination

Enum

One of INCIDENT, ALERT, or EVENT. Specifies which type of Service now alerting record will be created for vROps alerts in this alertingConfig.

serviceNowOpenState

String

Specifies the ServiceNow state an alerting record will be in when it is opened. The default is New. The value must be present in the sys_choice table for the alerting record's state column.

serviceNowReopenState

String

Specifies the ServiceNow state an alerting record will be in when it is reopened. The default is New for Incidents and Events and Reopen for Alerts. The value must be present in the sys_choice table for the alerting record's state column.

serviceNowCloseState

String

Specifies the ServiceNow state an alerting record will be in when it is closed. The default is Closed for Incidents and Alerts and Closing for Events. The value must be present in the sys_choice table for the alerting record's state column.

category

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

subcategory

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

businessService

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

contactType

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

state

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow. Defaults to the value of the corresponding vROps Alert, mapped using ServiceNowOpenState, ServiceNowReopenState, and ServiceNowCloseState.

resolutionCode

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

resolutionNotes

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

onHoldReason

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

impact

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow. For Incident and Alert, defaults to the value of the vROps Alert's impact.

urgency

String

Optional additional metadata for incidents/alerts/events that are opened in ServiceNow.

filters

Object

Set of filters that determine which vROps Alerts will get processed in this alertingConfig. See detail below.

retrieveUpdates

Boolean

When set to true, vROps alerts will be suspended when an incident or alert 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.

vropsSuspendMinutes

Int

Defines how long (in whole minutes) an alert should be suspended when the corresponding ServiceNow alerting record is marked as closed.

serviceNowElementsToRetrieve

Array

A list of strings corresponding to 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 for Incidents; state, assigned_to.name, and priority for Alerts; and state and resolution_state for Events.

CMDB Sync

A cmdbSync configuration can be added to the configuration file in order to enable this adapter to populate the CMDB with resources. The configuration object can include the following, each of which will be described in greater detail.

"cmdbSync": {
   "cmdbSyncMethod": "IRE_API",
   "syncMode": "POPULATE_AND_DELETE_WHEN_NOT_EXISTING",
   "objectIdentifierSource": "MOID",
   "builtInTreeEnabled": true,
   "customTreesEnabled": false,
   "additionalColumns": {},
   "nameFilter": {}
}

Additionally, using CMDB sync requires the user to add a Data Source to the identification rule for each resource type, otherwise columns cannot be updated via IRE.

There are a few CI Class Identification Rules that must be addressed as well.

  • cmdb_ci_vcenter_datacenter:

    • Add a rule that uses object_id and vcenter_uuid together to uniquely identify the datacenter

    • If you have ever used the Discovery plugin, it adds a dependent relationship to cmdb_ci_cloud_service_account. Remove this dependency and allow the Datacenter to be an Independent resource.

  • cmdb_ci_vcenter_datastore

    • Add a dependent containment relationship to the Datacenter (cmdb_ci_vcenter_datastoreContains::Contained by cmdb_ci_vcenter_datacenter)

  • cmdb_ci_esx_server

    • Add a rule that uses object_id and vcenter_uuid together to uniquely identify the datacenter

    • If Discovery is being used, you may also need to disable the correlation_id rule to avoid duplicate objects.

  • cmdb_ci_vcenter

    • Add a rule that uses instance_uuid as the unique identifier

Custom Trees

By default, built-in trees are enabled and custom trees are disabled. If you need to change the identification of the built-in classes, or map these resources to different CIs, disable the built-in tree and create your own custom tree to represent vCenter resources.

Tip:

To add columns to a built-in tree, use additionalColumns rather than defining a custom tree. See Additional Columns below.

To use custom trees, you must enable custom trees in the CMDB Sync Configuration. You must define each custom tree in its own json file under 'work/custom_trees'. When you make the directory 'custom_trees', make sure your vROps user has permission to read from that directory.

Format:

{
    "treeName": "Sample Tree Name",
    "syncClasses": []
}

Tree Name

This is a unique identifier for the tree. It cannot match the name of any other custom trees, or the built-in tree if the built-in tree is enabled.

Sync Classes

Sync classes defined what should be synced to the CMDB. For a tree to be valid, the chosen sync classes must include all identifiers required by the CMDB. Test connection will inform you if there are any issues with any of the sync classes.

{
    "classIdentifier": "Sample Class ID",
    "vROps": {...},
    "serviceNow": {...},
    "identifierMapping: {...},
    "dataColumns": [],
    "relationships": [],
    "propertyFilter": {}
}

Class Identifier This is a unique identifier for the class. It cannot match the identifier of any other custom class, or the built-in class if the built-in tree is enabled.

vROps Definition This is the same object required for ResourceType vROps Definitions

ServiceNow Definition This is the same object required for ResourceType ServiceNow Definitions

Identifier Definition The identifier mapping is our way of linking our resources to ServiceNow's CIs. This is a combination of identifiers which uniquely identify the resource. For example, vROps resources should use the vCenter UUID in combination with the MOID (which is what is shown in the example in the link below).

These do not have to be identifiers on either the CMDB side or the vROps side, though they often will be.

This is the same object required for ResourceType Identifier Mapping

Data Columns Data columns represent the columns that we sync to the CMDB that are not used as part of the identification mapping. See vROps Types and Fields for available options for the vropsType and vropsField parameters.

{
  "cmdbColumn": "cpu_name",
  "vropsType": "PROPERTY",
  "vropsField": "cpu|cpuModel"
}

Relationships Defines all relationships to children. The childClassIdentifier is the unique Class Identifier assigned to the child class. The child class must be a part of this tree. The relationshipType is not required if the CI Class Definition defines only one possible relationship type between the two CI Classes, but is required if there are multiple options.

"relationships": [
    {
      "childClassIdentifier": "CustomDatastore",
      "relationshipType": "Contains::Contained By"
    }
]

Property Filter This is used to filter resources based on properties. An example use-case would be if you wanted to map VMWARE VirtualMachine resources to cmdb_ci_vmware_instance CIs only when the property summary|config|isTemplate is set to false. You could make a second Custom Class which maps to cmdb_ci_vmware_template when summary|config|isTemplate is set to true from the same vROps ResourceType.

If this is not needed for your class, omit the block.

This sample filters only resources that are not templates.

"propertyFilter": {
    "conditions": [
      {
        "vropsField": "summary|config|isTemplate",
        "value": "false",
        "filterOperation": "EQUALS",
        "default": false
      }
    ],
    "joiner": "AND or OR"
}

Property Filter Value Set this to the value to search for in the string returned from the vropsField. If your field is a boolean or an integer, set it to the string representation of that boolean or integer (such as "15" or "true")

Property Filter Operation This specifies how we determine whether the filter condition is met.

Available options:

Option

Behavior

EQUALS

The condition is true if the property value returned by vROps exactly matches the provided value

DOES_NOT_EQUAL

The condition is true if the property value returned by vROps does not match the provided value

CONTAINS

The condition is true if the value returned from vROps contains the provided value

DOES_NOT_CONTAIN

The condition is true if the value returned from vROps does not contain the provided value

Property Filter DefaultThis specifies how we should evaluate the condition if we cannot retrieve the property in vROps. Since the most common reason this could occur is for vROps to discover a new resource but not complete a collection and thus assign properties yet, we recommend defaulting to false. Using false as default will cause the filter to exclude all resources that do not have this property assigned from the sync.

Property Filter Joiner This specifies whether we should include the resource if all of the conditions are met (AND) or if at least one of the conditions are met (OR)

Available options:

Option

Behavior

AND

All property filters must resolve to true in order to include the resource

OR

At least one of the property filters must resolve to true in order to include the resource

Tip:

To map a custom tree representing another technology that vROps can monitor, such as AWS, whilst simultaneously using the built-in tree, enable custom trees and leave the built-in tree also enabled.

Custom Tree Example

{
  "instructions": "Copy this file to work/custom_trees before you begin to modify it. Remove all 'instructions' objects from this json before attempting to collect using the this custom tree.",
  "treeName": "Replace this with a unique string which describes what this tree represents (such as 'vCenter')",
  "syncClasses": [
    {
      "classIdentifier": "Replace this with a unique string which describes what this class represents (such as 'Virtual Machine')",
      "vROps": {
        "type": {
          "resourceKind": "Replace this with the vROps Resource Kind (such as 'Datastore')",
          "adapterKind": "Replace this with the vROps Adapter Kind (such as 'VMWARE')"
        }
      },
      "serviceNow": {
        "type": {
          "cmdbCiClass": "Replace this with the CI class in the ServiceNow CMDB (such as 'cmdb_ci_vcenter_datastore')"
        }
      },
      "instructions": "identifierMapping can include any number of identifiers which, when taken together, uniquely identify the resource. If you are syncing vCenter resources, a combination of VMEntityObjectID and VMEntityVCID is generally recommended. These are for this adapter to map back and forth between ServiceNow and vROps. The columns and vROps fields referenced do not have to be identifiers for their platform, though they often are.",
      "identifierMapping": [
        {
          "serviceNowId": {
            "column": "The CMDB column (such as 'object_id')"
          },
          "vropsId": {
            "instructions": "See documentation for a full description of possible types and how to specify fields for them.",
            "type": "IDENTIFIER",
            "field": "VMEntityObjectID"
          }
        }
      ],
      "instructions": "dataColumns includes all other fields that you which to sync to the CMDB that are not used for our identification.",
      "dataColumns": [
        {
          "instructions": "See documentation for a full description of possible types and how to specify fields for them.",
          "cmdbColumn": "sample_column",
          "vropsType": "METRIC",
          "vropsField": "sample|metric|key"
        }
      ],
      "instructions": "Use the relationships array to define children of the the class. You can only reference classes that are also members of this tree.",
      "relationships": [
        {
          "childClassIdentifier": "Reference To Another Class In This Tree",
          "relationshipType": "This is only required if there are multiple possible relationship types between two CI Classes - if it is not defined, the adapter will read the relationship type from the CMDB. The format for this string is 'Contains::Contained by'"
        }
      ],
      "propertyFilter": {
        "instructions": "This is optional. Remove the propertyFilter object if you don't need it for your resource. If you do need the filter, you can define any number of conditions and whether we should join them all together with AND or OR. Conditions can only be made from vROps properties. Metrics, Identifiers, etc will not work.",
        "conditions": [
          {
            "vropsField": "The property that we will used from the vROps resource to determine if the condition is met (formatted|like|this)",
            "value": "The expected value for the condition. Use a string representation even if this is an int or boolean property",
            "filterOperation": "Whether a resource's property should equal, not equal, contain, or not contain the value in order to be included for this class (acceptable values: EQUALS, DOES_NOT_EQUAL, CONTAINS, DOES_NOT_CONTAIN)",
            "default": "If the property is not present on the resource, the boolean default determines whether or not to include this resource. Our recommendation and the default for this field is false since it is safer to assume the property has not yet initialized for the resource and we should wait until it is before making the determination."
          }
        ],
        "joiner": "AND or OR"
      }
    },
    {
      "instructions": "Define a sync class for every class you want to define and add it to this array."
    }
  ]
}

Additional Columns

To add properties to the CMDB that are not defined by the built-in tree definition, use the 'additionalColumns' parameter.

This is a mapping from class identifier (See table in Name Filter) to a list of additional columns. An additional column has the following fields:

  • cmdbColumn: The key of the column that the vROps field will be send to on the CMDB CI Class

  • vropsType: Where to get this data from in vROps. See the type table below for a list of options

  • vropsField: Represents the field to sync. See the type table below for a list of options

This example syncs the vROps property 'cpu|cpuModel' to the CMDB column 'cpu_name' on all Host System resources:

    "additionalColumns": {
      "builtInHostSystem": [
        {
          "cmdbColumn": "cpu_name",
          "vropsType": "PROPERTY",
          "vropsField": "cpu|cpuModel"
        }
      ]
    }

vROps Types and Fields

When defining a column, this describes available 'vropsType' enums and what should be provided as the 'vropsField' when that type is selected

Type

Applicable Field

PROPERTY

The key of the vROps property to sync such as 'cpu|cpuModel'

IDENTIFIER

The key of the vROps Identifier to sync sync as 'VMEntityVCID'

METRIC

The key of the vROps property to sync such as 'cpu|demand|stress'

NAME

This should be left empty. The name of the resource will be used.

UUID

This should be left empty. The UUID assigned by vROps for the resource will be used. This is unique to each vROps instances so if the same resource is monitored by multiple vROps instances, this is not an ideal metric to use

STATIC_STRING

The value you want assigned to the column. For instance, you could set 'Synced From vROps' to a description column and the column would be set to that value for all resources of the CI Class that we sync.

Data Source

In order to sync data, the following must be done on ServiceNow:

  • Add data_source VMwareTVS to the

    Choice
              List

    (you can search sys_choice.list in the UI or query sys_choice in the REST API) with the Element (element in REST) attribute set to discovery_source and the Value (value) and Label (label) attributes set to VMwareTVS. The Table (table) must be set to cmdb_ci.

  • Add a Reconciliation Rule for your new data_source (VMwareTVS) on each of the CI classes in >Synced Resources

If this is not done, IRE will not be able to update the resource, but the API still returns a successful response so we are not able to alert/fail collection due to this.

Synced Resources

The following resources from the VMWARE adapter will be synced to the CMDB if CMDB Sync is enabled:

vROps Type

CI Class

Datastore

cmdb_ci_vcenter_datastore

Datacenter

cmdb_ci_vcenter_datacenter

HostSystem

cmdb_ci_esx_server

ClusterComputeResource

cmdb_ci_vcenter_cluster

VMwareAdapter Instance

cmdb_ci_vcenter

VirtualMachine

cmdb_ci_vmware_instance

Additional information about what properties and relationships we sync can be found in CMDB Synced Metrics.

CMDB Sync Method

Currently, the only supported sync method is the IRE API (IRE_API). This is the default value and specifying it is not required. IRE_API uses ServiceNow's Identification and Reconciliation Engine to resolve vROps resources to the appropriate ServiceNow resources. For this to work properly, the identification rules for the ci classes this adapter populates should not be altered from what ServiceNow includes by default. If rules are edited or removed, we cannot guarantee how the IRE will resolve resources that this adapter sends it.

CMDB Sync using the IRE is not compatible with ServiceNow's Discovery plugin.

Note: The TableAPI is also used for methods the IRE API cannot accomplish such as adding/deleting relationships that have changed which would affect identification and deleting resources if the sync mode is set to allow deletion.

Sync Mode

This specifies how we should sync CIs to the CMDB.

There are 3 options for syncMode:

  • POPULATE_ONLY: Populates the CMDB, but does not remove CIs. If a resource is Not Existing, it sets the operational status to '6' (retire).

  • POPULATE_AND_DELETE_WHEN_NOT_EXISTING: Populates the CMDB and removes CIs that have been marked as Not Existing in vROps

  • POPULATE_AND_DELETE_WHEN_REMOVED: Populates the CMDB and removes CIs that have been removed from vROps. If a resource is Not Existing, it sets the operational status to '6' (retire).

Object Identifier Source

This is used to select which identifier should be used for objects which have both a UUID and a MOID. Currently, this only applies to Virtual Machine resources. If you are populating your CMDB for the first time, we recommend using MOID. If you are using this adapter to add data to a CMDB that has already been populated, check the format of the identifier in the object_id column for a cmdb_ci_vmware_instance object and choose the option below that matches it.

There are 2 options for Object Identifier Source:

  • MOID (default): Also called MoRef ID, this is a required identifier in vROps and looks like vm-111. It includes a prefix and a number which is generated by a counter.

  • UUID: This is an optional identifier in vROps and looks like a standard UUID. In most cases, this should be present, but there is a chance that it will not be. We have a few VMs in our test environment which are in bad states that don't have UUIDs, but they do have MOIDs.

For further info about identifiers in vCenter, see

Name Filter

A map from ServiceNow CI Class to a regex filter. Every resource with a name that matches this regex will not be synced to the CMDB. This can be omitted if you intend to include all resources. It will look like this if you wish to ignore all VMs that end in the dev:

{ "cmdb_ci_vmware_instance": "^.*dev$"}

Note: VM templates are automatically filtered out so there is no need to add a name filter for VM templates.

Configuration Samples

Some sample configuration files are provided for you. They are pre-installed with the Management Pack and located at /usr/lib/vmware-vcops/user/plugins/inbound/servicenow_adapter3/conf/config_samples. You can use these out-of-the-box, or you can modify the json as described in the (Configuration File)[#Configuration File] section. If you do modify any of the files, it is recommended that you move the modified file to the work directory. Otherwise, the modified file will be overwritten if you update the Management Pack.

If you wish to use an un-modified configuration file, you will need to specify the path starting with the directory inside config_samples in the Adapter Configuration.

For example, if you wish to use moid_alerts.json, you can specify alert/moid_alerts.json. If you copy it to the work directory so that you can modify it, you only need to specify the name of the file.

Since group configurations are custom to specific customer deployments, we do not include any out-of-the-box samples with group configurations

The following sample configurations are available:

Alerts No Mapping

Location in config_samples: alert/alerts_no_mapping.json

This is a basic configuration that will send all vROps alerts to ServiceNow as ServiceNow alerts. It does not apply any filters.

Alerts No Mapping

Location in config_samples: alert/events_no_mapping.json

This is a basic configuration that will send all vROps alerts to ServiceNow as ServiceNow events. It does not apply any filters.

Alerts No Mapping

Location in config_samples: alert/incidents_no_mapping.json

This is a basic configuration that will send all vROps alerts to ServiceNow as ServiceNow incidents. It does not apply any filters.

MOID Alerts

Location in config_samples: alert/moid_alerts.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds except VirtualMachine, which uses MOID and vCenter UUID.

MOID Events

Location in config_samples: alert/moid_events.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds except VirtualMachine, which uses MOID and vCenter UUID.

MOID Incidents

Location in config_samples: alert/moid_incidents.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds except VirtualMachine, which uses MOID and vCenter UUID.

UUID Alerts

Location in config_samples: alert/uuid_alerts.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

UUID Events

Location in config_samples: alert/uuid_events.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

UUID Incidents

Location in config_samples: alert/uuid_incidents.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

CMDB Sync MOID Populate Only

Location in config_samples: cmdb_sync/moid_populate_only.json

This configuration syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, but it does not delete resources from the CMDB.

CMDB Sync MOID Populate and Delete When Not Existing

Location in config_samples: cmdb_sync/moid_populate_and_delete_when_not_existing.json

This configuration syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when vROps marks them as Not Existing

CMDB Sync MOID Populate and Delete When Removed

Location in config_samples: cmdb_sync/moid_populate_and_delete_when_removed.json

This configuration syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

CMDB Sync UUID Populate Only

Location in config_samples: cmdb_sync/uuid_populate_only.json

This configuration syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, but it does not delete resources from the CMDB.

CMDB Sync UUID Populate and Delete When Not Existing

Location in config_samples: cmdb_sync/uuid_populate_and_delete_when_not_existing.json

This configuration syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when vROps marks them as

Not
        Existing

CMDB Sync UUID Populate and Delete When Removed

Location in config_samples: cmdb_sync/uuid_populate_and_delete_when_removed.json

This configuration syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: MOID Alerts and Populate Only

Location in config_samples: combined/moid_alerts_and_populate_only.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: MOID Alerts and Populate Delete When Not Existing

Location in config_samples: combined/moid_alerts_and_populate_when_not_existing.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when vROps marks them as Not Existing

Combined: MOID Alerts and Populate When Removed

Location in config_samples: combined/moid_alerts_and_populate_when_removed.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: MOID Events and Populate Only

Location in config_samples: combined/moid_events_and_populate_only.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: MOID Events and Populate Delete When Not Existing

Location in config_samples: combined/moid_events_and_populate_when_not_existing.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when vROps marks them as Not Existing

Combined: MOID Events and Populate When Removed

Location in config_samples: combined/moid_events_and_populate_when_removed.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: MOID Incidents and Populate Only

Location in config_samples: combined/moid_incidents_and_populate_only.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: MOID Incidents and Populate Delete When Not Existing

Location in config_samples: combined/moid_incidents_and_populate_when_not_existing.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when vROps marks them as Not Existing

Combined: MOID Incidents and Populate When Removed

Location in config_samples: combined/moid_incidents_and_populate_when_removed.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the object_id for cmdb_ci_vmware_instance (Virtual Machine) CIs and the UUID is used as the object_id for all other CI Classes. This configuration populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: UUID Alerts and Populate Only

Location in config_samples: combined/uuid_alerts_and_populate_only.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, but it does not delete resources from the CMDB.

Combined: UUID Alerts and Populate and Delete When Not Existing

Location in config_samples: combined/uuid_alerts_and_populate_when_not_existing.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when vROps marks them as

Not
        Existing

Combined: UUID Alerts and Populate When Removed

Location in config_samples: combined/uuid_alerts_and_populate_when_removed.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow alerts for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: UUID Events and Populate Only

Location in config_samples: combined/uuid_events_and_populate_only.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, but it does not delete resources from the CMDB.

Combined: UUID Events and Populate and Delete When Not Existing

Location in config_samples: combined/uuid_events_and_populate_when_not_existing.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when vROps marks them as

Not
        Existing

Combined: UUID Events and Populate When Removed

Location in config_samples: combined/uuid_events_and_populate_when_removed.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow events for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.

Combined: UUID Incidents and Populate Only

Location in config_samples: combined/uuid_incidents_and_populate_only.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, but it does not delete resources from the CMDB.

Combined: UUID Incidents and Populate and Delete When Not Existing

Location in config_samples: combined/uuid_incidents_and_populate_when_not_existing.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when vROps marks them as

Not
        Existing

Combined: UUID Incidents and Populate When Removed

Location in config_samples: combined/uuid_incidents_and_populate_when_removed.json

This configuration filters vROps alerts to the following ResourceKinds: VirtualMachine, ClusterComputeResource, Datacenter, Datastore, HostSystem. It creates ServiceNow incidents for these vROps alerts and associates them with their CI if it is present in the CMDB. The mapping uses a combination of UUID and vCenter UUID as identifiers for all ResourceKinds.

Also, it syncs vROps resources to the CMDB. The MOID is used as the UUID is used as the object_id for all CI Classes. It populates the CMDB, and deletes resources from the CMDB when they are deleted from vROps.