Mapping file

This topic describes the mapping file used to map an imported object's dependent objects to existing objects on the importing system.

• Overview of mapping
• Using the automatically generated mapping file: mapping.xml
• Mapping file DTD
• Sample mapping file
• Exporting objects without their associated objects
• Supplying required values

Overview of mapping

Suppose you want to import an object that refers to dependent objects that do not exist on the importing system---for example, servers, properties, or containing groups. In this case, you need to use a mapping file that maps these dependent objects to objects that do exist on the importing system.

A mapping file is an XML file that conforms to the DTD listed in Mapping file DTD. A mapping file can contain any number of mappings for any of the legal mapping types:

• Servers
• Server groups
• Properties
• System package types
• Grouped objects
• BLPackages
• Grammars
• Discovery Jobs
• Compliance Jobs
• Deploy Jobs
• Component templates
• Depot software
• Remediation groups
• NSH scripts
• Depot files
• NSH Script Jobs

Using the automatically generated mapping file: mapping.xml

Whenever you export an object (via the GUI or via the BLCLI), the export process automatically creates a mapping file called mapping.xml, and places this file in the directory you specified for export.

When you are ready to import, only the BLCLI import process uses a mapping file. When you import by using the GUI, if the GUI import process finds a mapping file in the directory with the rest of the exported data, it silently ignores the mapping file. The GUI always prompts the user for information, when necessary.

For every type of object that can be mapped in a given export (groups, properties, and so on), the mapping.xml file contains a mapping that links the data in the exported XML file with a corresponding object that already exists on the exporting system.

When you are ready to import the export file onto another system, you will need to do one of the following things before you do the import:

• If all the target objects in the mapping file already exist on the importing system, you can use the mapping.xml file as is.
• If the target objects in the mapping file do not exist on the importing system, but you plan to use other existing objects in their place, you can just edit the mapping.xml file to specify the names of the existing objects on the importing system.
• If the target objects in the mapping file do not exist on the importing system, and you do not plan to use any existing objects on the importing system in their place, then you need to do the following:

1. Create suitable target objects on the importing system (via the GUI or BLCLI).

2. Edit the mapping.xmlfile to point to those newly created objects.

   Note

   The mapping.xml file helps you identify the places where you might need to supply mapping values by placing comments directly before the elements you need to map. For an example, see Sample mapping file.

You do not need to use the automatically generated mapping.xml file. Deleting the mapping.xml file does not affect the integrity of the exported object, as long as you provide some other mapping file when the object is imported on another system. There is no requirement that the mapping file that you use during import be located in the same directory as the rest of the data being imported. That directly is simply the location that is used by the automatically-created mapping files.

Mapping file DTD

Sample mapping file

The following sample mapping file could be used to import a component template that contains a property of a custom type. there is a comment preceding each place where you may need to specify a new value that points to an object on the importing system.

Exporting objects without their associated objects

There are times when you might want to export an object without exporting other objects that are associated with the to-be-exported object.

Example

Suppose that the first time you export a job or component template, you use the exportObject command, so that the exported data includes the job's or component template's associated BLPackages. This export of a BLPackage contains its payload, which can be quite large. In subsequent exports, there are a variety of circumstances in which you might want to export the job or component template, but not include its BLPackages.

To do this, perform the following steps:

• Use one of the exportObject signatures that have Boolean arguments for including or excluding various associated objeccts. For example, the following code snippet exports a component template without its BLPackages:
  TEMPLATE_KEY=`blcli Template getDBKeyByGroupAndName /group1 template1`
  blcli ImportExport exportObject 250 $TEMPLATE_KEY /c/tmp/export_files/templateWithoutPkgs false false false false true false false

• Specify which existing BLPackages to use on the importing system by using the <blpackage_mapping> tag in the mapping file. For example, a <blpackage_mapping>tag might look like this:

  <blpackage_mapping>
  <source_blpackage_location>/blpackages/pkg1-2000001.1</source_blpackage_location>
  <target_blpackage>
  <blpackage_name>pkg2</blpackage_name>
  <blpackage_group>/f2</blpackage_group>
  </target_blpackage>
  </blpackage_mapping>
  

For a scripting example of this process, see Example-of-an-export-and-import-workflow.

Objects That You Can Exclude From Export

Using various signatures of the exportObject command, you can exclude the following associated objects from export:

• BLPackages
• Depot software
• Discovery Jobs
• Compliance Jobs
• Deploy Jobs
• Grammars (these are always excluded, by default)
• Component templates
• NSH scripts
• Depot files
• NSH Script Jobs

Supplying required values

You can use the mapping file to handle a situation where there are similar, but not identical, property dictionaries on the exporting and importing systems, and required properties are in use that have no default values on the importing system.

Scenario

On the importing system, suppose you have a custom property class (CPC) that has a required string property (CPC-RequiredProp). The importing system does NOT have a default value for CPC-RequiredProp.

• Suppose you do the following on the exporting system:
  1. Create a custom property class (CPC) and add a required string property (CPC-RequiredProp). Set a default value for CPC-RequiredProp.
  2. Create a property instance for CPC (CPC-Inst1). Notice that since a default value is specified for CPC-RequiredProp you are not prompted to provide a value on the instance.
  3. Create a component template with any parts.
  4. Create a local property on the template (LocalProp) and set the type to CPC and the default value to CPC-Inst1.
  5. Export the template.
• Returning to the importing system, suppose you now attempt to import the component template you just exported from the exporting system.

This import attempt will fail, because you are trying to import an instance that contains a required property (CPC-RequiredProp) for which the importing system has no value:

• In the importing system, CPC-RequiredProp does not have a default value.
• When you created the instance on the exporting system, you did not need to specify a value for CPC-RequiredProp, because there was a default value on the exporting system, but the export process does not export the default value.

To resolve this problem, you can add one or more <required_value> tags to the mapping file.
 To create a <required_value> tag, you need to know which property or properties are missing, and the corresponding types.
 For example, adding a value to any non-custom property will look something like this:

This works for all types other than custom types. For primitives, the values are just the strings, integers, etc. For enumerated types, the values are one of the strings, integers, etc. from the enumeration.

For custom types, you must describe a property set instance that is the value. For example:

As shown, a <property_set_instance> tag contains one or more <required_value> tags. These can be further nested, if the property instance you are describing also contains properties of another custom type.