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

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

<!-- DTD for importing objects mapping file -->
\\
<!ELEMENT source_server (#PCDATA)>
<!ELEMENT target_server (#PCDATA)>
<!ELEMENT server_mapping (source_server, target_server)>
\\
<!--
  source_server_group is the simple group name
  target_server_group is the fully qualified group name
-->
<!ELEMENT source_server_group (#PCDATA)>
<!ELEMENT target_server_group (#PCDATA)>
<!ELEMENT server_group_mapping (source_server_group, target_server_group)>
\\
<!ELEMENT property_set_class (#PCDATA)>
<!ELEMENT source_property (#PCDATA)>
<!ELEMENT target_property (#PCDATA)>
<!ELEMENT property_mapping (property_set_class, source_property, target_property)>
\\
<!ELEMENT source_system_package_type (#PCDATA)>
<!ELEMENT target_system_package_type (#PCDATA)>
<!ELEMENT system_package_type_mapping (source_system_package_type, target_system_package_type)>
\\
<!--
  object_type is the name of the model type of the object (e.g SNAPSHOT_JOB, BLPACKAGE etc)
  containing_group is a fully qualified group name
-->
<!ELEMENT object_type (#PCDATA)>
<!ELEMENT object_name (#PCDATA)>
<!ELEMENT group_id (#PCDATA)>
<!ELEMENT source_object (object_type, object_name, group_id)>
<!ELEMENT containing_group (#PCDATA)>
<!ELEMENT grouped_object_mapping (source_object, containing_group)>
\\
<!ELEMENT remediation_depot_group (#PCDATA)>
<!ELEMENT remediation_job_group (#PCDATA)>
<!ELEMENT remediation_group_mapping (source_object, remediation_depot_group, remediation_job_group)>
\\
<!ELEMENT job_name (#PCDATA)>
<!ELEMENT job_group (#PCDATA)>
<!ELEMENT job_group_id (#PCDATA)>
<!ELEMENT source_discovery_job (job_name, job_group_id)>
<!ELEMENT target_discovery_job (job_name, job_group)>
<!ELEMENT discovery_job_mapping (source_discovery_job, target_discovery_job)>
<!ELEMENT source_compliance_job (job_name, job_group_id)>
<!ELEMENT target_compliance_job (job_name, job_group)>
<!ELEMENT compliance_job_mapping (source_compliance_job, target_compliance_job)>
<!ELEMENT source_deploy_job (job_name, job_group_id)>
<!ELEMENT target_deploy_job (job_name, job_group)>
<!ELEMENT deploy_job_mapping (source_deploy_job, target_deploy_job)>
<!ELEMENT source_nsh_script_job (job_name, job_group_id)>
<!ELEMENT target_nsh_script_job (job_name, job_group)>
<!ELEMENT nsh_script_job_mapping (source_nsh_script_job, target_nsh_script_job)>
\\
<!ELEMENT template_name (#PCDATA)>
<!ELEMENT template_group (#PCDATA)>
<!ELEMENT template_group_id (#PCDATA)>
<!ELEMENT source_template (template_name, template_group_id)>
<!ELEMENT target_template (template_name, template_group)>
<!ELEMENT template_mapping (source_template, target_template)>
\\
<!ELEMENT depot_software_name (#PCDATA)>
<!ELEMENT depot_software_group (#PCDATA)>
<!ELEMENT depot_software_location (#PCDATA)>
<!ELEMENT depot_software_type (#PCDATA)>
<!ELEMENT source_depot_software (depot_software_location, depot_software_type)>
<!ELEMENT target_depot_software (depot_software_name, depot_software_group)>
<!ELEMENT depot_software_mapping (source_depot_software, target_depot_software)>
\\
<!ELEMENT blpackage_name (#PCDATA)>
<!ELEMENT blpackage_group (#PCDATA)>
<!ELEMENT source_blpackage_location (#PCDATA)>
<!ELEMENT target_blpackage (blpackage_name, blpackage_group)>
<!ELEMENT blpackage_mapping (source_blpackage_location, target_blpackage)>
\\
<!ELEMENT nshscript_name (#PCDATA)>
<!ELEMENT nshscript_group (#PCDATA)>
<!ELEMENT source_nshscript_location (#PCDATA)>
<!ELEMENT target_nshscript (nshscript_name, nshscript_group)>
<!ELEMENT nshscript_mapping (source_nshscript_location, target_nshscript)>
\\
<!ELEMENT depot_file_name (#PCDATA)>
<!ELEMENT depot_file_group (#PCDATA)>
<!ELEMENT source_depot_file_location (#PCDATA)>
<!ELEMENT target_depot_file (depot_file_name, depot_file_group)>
<!ELEMENT depot_file_mapping (source_depot_file_location, target_depot_file)>
\\
<!ELEMENT source_grammar (#PCDATA)>
<!ELEMENT target_grammar (#PCDATA)>
<!ELEMENT grammar_mapping (source_grammar, target_grammar)>
\\
<!ELEMENT required_value (property_set_class, target_property, value)>
<!ELEMENT value (#PCDATA | property_set_instance)*>
<!ELEMENT property_set_instance (required_value)*>
\\
<!ELEMENT mapping ((
                      server_mapping | server_group_mapping | property_mapping |
                      system_package_type_mapping | grouped_object_mapping |
                      discovery_job_mapping | compliance_job_mapping |
                      deploy_job_mapping | template_mapping |
                      depot_software_mapping | blpackage_mapping | grammar_mapping |
                      required_value | remediation_group_mapping | nshscript_mapping |
                      depot_file_mapping | nsh_script_job_mapping
                    )*
                  )>

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.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapping SYSTEM "file://bladelogic.com/dtds/Import-Mapping.dtd">
<mapping>
  <grouped_object_mapping>
    <source_object>
      <object_type>TEMPLATE</object_type>
      <object_name>testTemplate</object_name>
    </source_object>
    <!-- This is the relative path to the group in which to store the imported object -->
    <containing_group>/import</containing_group>
  </grouped_object_mapping>
  <property_mapping>
    <property_set_class>TestCustomPropertyClass</property_set_class>
    <source_property>StringProp1</source_property>
    <!-- This is the name of the property on the importing system to use -->
    <target_property>StringProp1</target_property>
  </property_mapping>
  <property_mapping>
    <property_set_class>TestCustomPropertyClass</property_set_class>
    <source_property>StringProp2</source_property>
    <!-- This is the name of the property on the importing system to use -->
    <target_property>StringProp2</target_property>
  </property_mapping>
  <property_mapping>
    <property_set_class>Component Template</property_set_class>
    <source_property>TestProperty</source_property>
    <!-- This is the name of the property on the importing system to use -->
    <target_property>TestProperty</target_property>
  </property_mapping>
</mapping>

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:

<required_value>
 <property_set_class>Name of the class</property_set_class>
 <target_property>Name of the property</target_property>
 <value>Value</value>
</required_value>

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:

<required_value>
 <property_set_class>Name of the class</property_set_class>
 <target_property>Name of the property</target_property>
 <value>
  <property_set_instance>
   <required_value>
    <property_set_class>Name of the class</property_set_class>
    <target_property>Name of the property</target_property>
    <value>Value</value>
   </required_value>
  </property_set_instance>
 </value>
</required_value>

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.

Note

Because this process can become quite complex, you might want to consider using the GUI because the GUI automatically prompts you for the necessary values during import.

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

Comments