This documentation supports the 20.02 version of BMC CMDB.

To view an earlier version, select the version from the Product version menu.

Overlay datasets

 BMC CMDB offers overlay datasets, which enable you to:

  • Make changes in a separate partition without overwriting your production data.
  • See your changes in context with the unchanged portions of your data.
  • Avoid duplicating your entire production dataset.
  • Create multiple overlay datasets that reuse one set of reconciliation definitions for merging each into the production dataset.


Overlay dataset functionality applies only to BMC CMDB API clients. Using CMDB Portal or the class forms to view or modify instances can lead to unpredictable results and compromised data integrity.

How overlays work

When you create an overlay dataset, you must specify an existing regular dataset for it to overlay. Although an overlay dataset starts out empty like any other dataset, any request for an instance in the overlay dataset passes through the overlay dataset and returns that instance from the underlying dataset.

When you modify an instance in the overlay dataset the first time, it is copied there from the underlying dataset with your modifications. You can also create instances in the overlay dataset. The underlying dataset still holds the unmodified versions of its original instances, but it does not hold the modified instances. A request to the overlay dataset for a modified instance returns that instance from the overlay dataset, and a request to the overlay dataset for an unmodified instance returns it from the underlying dataset.


Requests made to the underlying dataset always return instances from that dataset, never from an overlay dataset.

The following figure illustrates queries against an overlay dataset, one for a modified instance and one for an unmodified instance. Notice that the modified instance shares the same reconciliation ID with its unmodified counterpart, but not the same instance ID.

 Query to an overlay dataset


Use an overlay dataset to make changes during a day, and then reconcile it into your production dataset at the end of the day when the change requests for the overlay datasets are approved.

Result of deleting instances from an overlay dataset

If you attempt to delete from an overlay dataset an instance that actually exists there, the instance is deleted only from the overlay dataset and remains in the underlying dataset. If you attempt to delete from an overlay dataset an instance that exists only in the underlying dataset, the instance is deleted from the underlying dataset.

You can mark an instance as deleted regardless of whether it already exists in the overlay dataset. In either case, this results in an instance in the overlay dataset that is marked as deleted.

Instance ID and identity in overlay datasets

When an instance is first created in an overlay dataset as the result of a modification, it retains the reconciliation identity of the instance in the underlying dataset, but is assigned a new instance ID.

If the underlying instance has not yet been identified when it is modified in the overlay dataset, the instance has no reconciliation identity in either dataset. This is not a problem. When you eventually identify and merge the two datasets, your identify rules should be able to match these instances so that they receive the same identity.


For each modification that you make to an instance before it is identified, an instance is created in the overlay dataset. Hence, you must identify instances before modifying them a second time in the overlay dataset.

If you decide to keep the changes that you modeled in an overlay dataset, you can merge the overlay dataset into the underlying regular dataset.

Was this page helpful? Yes No Submitting... Thank you