Default language.

Metadata mappings and CMDB

The BMC Remedy Migrator CLI includes metadata mappings to support CMDB and Atrium applications. These mappings are defined as XML elements and can be specified in the CMDBMetaData.xml and CMDBMetaDataEnableDelete.xml files, described in Mapping files.

For more information about working with CMDB and Atrium applications, see the Atrium core documentation.

Important

To prevent possible issues with migrations, be sure that both the source and destination are using the same CMDB version. Also, because BMC Remedy Migrator does not back up metadata, migrate critical files to a .migrator file first for safekeeping. You can then restore these items by migrating from the source backup file to the destination.

In this topic:

 Mapping files

The following mapping files contain the actual mapping details and define how the various CMDB forms relate to each other:

  • CMDBMetaData.xml — When this file is used, extra attributes and indexes that are not found on the source are not deleted on the destination.
  • CMDBMetaDataEnableDelete.xml — When this file is used, BMC Remedy Migrator performs a full synchronization of source and destination, deleting any extra attributes and indexes on the destination that are not found on the source.

Note

When migrating or comparing CMDB classes, use the supplied CMDBConfiguration.xml file. This file is identical to the Migration Configuration file, with some different configuration options.

Mapping types

The mapping design consists of the following mapping types :

  • BMC Remedy AR System form-to-form data mappings
  • BMC Remedy AR System object mappings

Form-to-form data mappings

In form-to-form data mappings, you can map multiple forms to each other in the following relationships:

  • one to one
  • one to many
  • many to many

Within each of these relationships, you can define the fields used to link the entries from the forms.

Every referenced form included in the mapping must be defined within the metadata mapping design.

Object mappings

In object mapping, you can define how one or more forms map to one or more objects, the object type (such as a form), and how the object name is calculated. For example, you might have a mapping includes this information for a field:

  • Field '8'
  • Text ':'
  • Field '5364918'

The field name would be calculated as:

The contents of Field 8 + ':" + the contents of field 5364918.

If Field 8 = Sample and field 5364918 = City, the field name would be calculated as Sample + ':' + City, or Sample:City.

Metadata XML document structure

The following section uses sample entries to explain the metadata XML document structure.

<meta-data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Migration Meta Data.xsd">

The main root element can contain multiple*<meta>* items for each major metadata type, such as CMDB.

meta name

<meta name="CMDB" identifier-form="OBJSTR:Class" description="This is the meta-data for the CMDB application design">

meta name is the root element for a specific meta-data design such as CMDB and contains all the form and object mappings that are specific to this element.

  • meta name — The name of the metadata item. It is used as the "owner" within the instruction XML document when attempting to migrate or compare metadata items within special items.
  • identifier-form — The main form that contains the true name of the metadata. For CMDB, this is the form that contains the class name. This is known as the root form from which all other forms are mapped.
  • description — Text that describes the document.

form name

<form name="OBJSTR:Class" unique-field-id="1" name-field-id="8" extends-form="form-name">

form name identifies a specific form and how the data on that form relates to other definition forms or BMC Remedy AR System objects or both.

  • form name — The name of the form on the AR System server.
  • unique-field-id — The unique identifier for the field. By default, 1 is used.
  • name-field-id — The field that contains the unique name of the entry. It is typically used only when the mapping item is the main identifying form. This is the field that is searched when a name is specified within the instruction document.
  • extends-form — The name of the base form. Entries are mapped using the unique IDs of this form and the form mapping that is defined for the extends form.

object type

<object type="Form" cascade="all">

For BMC Remedy AR System object mapping, this element and its children identify the object to which this form mapping maps.

  • object type — The BMC Remedy AR System object that does not include metadata.
  • cascade — The action to take if the parent entry is deleted. Options are:
    • all — Perfoms both creation and deletion of entries.
    • create-orphan — Creates only entries found on the source but are missing from the destination. Does not delete extra entries found on the destination.
    • delete-orphan — Deletes extra entries found on the destination but not on the source. Does not create extra entries found on the source.

      <field id="1"/> and <text value=":"/>

      These items are contained within the <object> element, and are used to identify the fields and text that make up the name of the BMC Remedy AR System object. The name is built based on the contents of the fields and the text value.

one-to-many form

<one-to-many form=" formName" local-key-id="3" foreign-key-id="2" cascade="all">

One-to-many mapping is used when a single entry in the main form is related to many entries within the specified form.

  • one-to-many form — The name of the external form where many entries match one entry locally.
  • local-key-id — The field ID of the local key used in the external form to make multiple entries from the local form.
  • foreign-key-id — The unique field ID used on the remote form. It is not required, becaus the unique-field-id defined on the form can be used.
  • Cascade — The action to take if the parent entry item is deleted. Options are:
    • all
    • create-orphan (not currently supported)
    • delete-orphan

      The*<local-keys>* and <foreign-keys> can be used if multiple fields are used for each corresponding attributes. These elements override the corresponding attributes.

many-to-one form

<many-to-one form=" formName" local-key-id="3" foreign-key-id="2">

This mapping type is used to define mapping of multiple entries in the local form to a single entry in the foreign form. Because this mapping has no cascade option, deleting or creating entries in this form does not affect the external form.

  • many-to-one form — The name of the external form, where one entry matches many local entries.
  • local-key-id — The field ID of the local key used in the external form to make multiple entries from the local form.
  • foreign-key-id — The unique field ID used on the external form. This ID is not required because the unique-field ID defined on the form can be used.

one-to-one form

<one-to-one form=" formName" local-key-id= "" foreign-key-id="">

In this mapping, every entry in the local form maps to one entry within the specified external form. Cascade is not defined for this mapping type.

  • one-to-one form — The name of the external form where one entry matches one entry locally.
  • local-key-id — The field ID of the local key used in the external form to make multiple entries from the local form.
  • foreign-key-id — The unique field ID used on the external form. This ID is not required because the unique-field ID defined on that form can be used.

many-to-many form

<many-to-many form=" formName" local-key-id="3" foreign-key-id="5" mapping-form="" source-field-id="2" destination-field-id="1">

This mapping allows mapping of multiple entries in the local form to multiple entries in the external form. This mapping uses an intermediate form in which the unique fields from the local form are mapped to the unique fields on the external form.

  • many-to-many form — The name of the external form where many entries matches many local entries
  • local-key-id — The field ID of the local key used in the external form to make multiple entries from the local form.
  • foreign-key-id — The unique field ID used on the external form. This ID is not required because the unique-field ID defined on that form can be used.
  • mapping-form — The name of the intermediate form used in the mapping.
  • source-field-id — The field ID in the mapping form that contains the value of the unique-field ID of the source entry. This value comes either from the local-key-id field or the unique-field-id.
  • destination-field-id — The field ID in the mapping form that contains the value of the unique-field-id of the destination entry. This value comes either from the foreign-key-id field or the unique-field-id of the external form.

The <source-fields> and <destination-fields> can be used to override the attributes and where multiple fields can be defined for each. The source and destination field IDs must be defined for the mapping to succeed.

Important

If you have migrated hierarchical groups (groups that include both parent and child groups), the Differences report might show a difference between source and destination. This could be because a child group was migrated but not its parent. To resolve this difference, migrate both parent and child groups.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*