Using a mapping file with the istool import command

Use the -mapping parameter with the -import command to change the properties of imported assets during a new import.

Purpose

When you use the istool command line to move common metadata assets from one metadata repository to another, the exported properties of some assets might not be suitable in the target metadata repository. For example, the file path of a data file in the exported archive file might be different from the file path in the target metadata repository. If the archive file is imported into the target metadata repository, the import command will create a new data file asset instead of merging the data file with the existing data file in the target metadata repository.

The -mapping parameter allows you to provide a mapping file to instruct the import command to change some properties of imported assets during import, so that the imported assets correctly reconcile with the assets in the metadata repository.

The -mapping parameter does not apply to imports of contract library assets.

You can specify the -mapping parameter with the istool import command for the following asset types:
  • Common metadata assets (-cm)
  • Custom attributes (-ca)
  • Data class and data collection analysis assets (-dca)
  • InfoSphere Information Analyzer assets (-ia)
  • Logical data model assets (-lm)
  • Master metadata assets (-mdm)
Note: When you use a mapping file to import an archive with multiple types of assets, be sure that the mapping affects only those assets that you want to change. For example, if you change the name of a host, the identity of any common metadata asset that is both contained by that host and present in the archive file will change.

Prerequisites

You must have the required roles to import whatever types of assets are in the mapping file. These are the same roles that were required to run the original import command successfully.

In InfoSphere® Information Server, Versions 8.7.0.1 and 8.7.0.2, you need to apply the following patch to use the mapping file parameter with the istool import command: patch_JR52293_XMETA_CMS_all_8701-02.

Using a mapping file to import assets

The mapping file is in an extensible markup language (XML) format. Property values that are mentioned in the mapping file are case-sensitive. You must use the internal names of assets and asset properties. The mapping file for imports is saved with the name Mapping.xml.
Note: The packageNsUri element in the XML tag that is used in the mapping file must be updated for your particular release. For example, the packageNsUri element is http:///4.0/ASCLModel.ecore in the following example: 
<Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="HostSystem" attrname="name"/>
To obtain the packageNsUri element for your release, you can issue the listModels command with the xmetaAdmin.bat or xmetaAdmin.sh script, which lists all the models deployed in the repository with their current version. The script is located in the ASBServer\bin directory. To run the script, issue the following command:
  • Linux cue graphicUNIX cue graphicASBServer/bin/xmetaAdmin.sh listModels -dbfile ../conf/database.properties
  • Windows cue graphic ASBServer\bin\xmetaAdmin.bat listModels -dbfile ..\conf\database.properties
Table 1. List of attributes for Versions 9.1, 11.3, and 11.5 that can be mapped and the XML tags with the internal names to be used in the mapping file for these attributes
Asset Attribute name XML tag to be used in mapping file
Host name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="HostSystem" attrname="name"/>
Database name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="Database" attrname="name"/>
Database schema name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataSchema" attrname="name"/>
Database table name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataCollection" attrname="name"/>
Stored procedure name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="StoredProcedure" attrname="name"/>
Data file name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataFile" attrname="name"/>
Data file file path <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataFile" attrname="path"/>
Data file structure name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataCollection" attrname="name"/>
Data item definition name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="name"/>
Data item definition qualifier <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="nameQualifier"/>
Database domain name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="name"/>
Database domain qualifier <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="nameQualifier"/>
Physical data model namespace <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="PhysicalModel" attrname="namespace"/>
Physical data model name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="PhysicalModel" attrname="name"/>
Design table name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataCollection" attrname="name"/>
Design stored procedure name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="StoredProcedure" attrname="name"/>
Physical domain name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="name"/>
Physical domain qualifier <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="nameQualifier"/>
BI server name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="BIServer" attrname="name"/>
BI folder name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="BIFolder" attrname="name"/>
BI model name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPModel" attrname="name"/>
BI collection namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCollection" attrname="nameSpace"/>
BI collection name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCollection" attrname="name"/>
Cube namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCube" attrname="nameSpace"/>
Cube name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCube" attrname="name"/>
BI report name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportDef" attrname="name"/>
BI report section namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportGroup" attrname="nameSpace"/>
BI report section name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportGroup" attrname="name"/>
BI report query namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportDataSet" attrname="nameSpace"/>
BI report query name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportDataSet" attrname="name"/>
Logical data model namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="LogicalModel" attrname="namespace"/>
Logical data model name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="LogicalModel" attrname="name"/>
Logical entity name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="Entity" attrname="name"/>
Logical relationship name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="Relationship" attrname="name"/>
Entity generalization name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="Generalization" attrname="name"/>
Logical domain name qualifier <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="Domain" attrname="nameQualifier"/>
Logical domain name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="Domain" attrname="name"/>
Subject area name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="SubjectArea" attrname="name"/>
Logical model diagram name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="Diagram" attrname="name"/>
Subject area diagram name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLLogicalModel.ecore" classname="Diagram" attrname="name"/>
Data connection name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataConnection" attrname="name"/>
Data file connection name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataConnection" attrname="name"/>
Custom attribute name <Attribute packageNsUri="http:///2.0/ASCLCustomAttribute.ecore" classname="CustomAttribute" attrname="name"/>
Table 2. List of attributes for Versions 8.7.0.1 and 8.7.0.2 that can be mapped and the XML tags with the internal names to be used in the mapping file for these attributes
Asset Attribute name XML tag to be used in mapping file
Host name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="HostSystem" attrname="name"/>
Database name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="Database" attrname="name"/>
Database schema name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataSchema" attrname="name"/>
Database table name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataCollection" attrname="name"/>
Stored procedure name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="StoredProcedure" attrname="name"/>
Data file name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataFile" attrname="name"/>
Data file file path <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataFile" attrname="path"/>
Data file structure name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataCollection" attrname="name"/>
Data item definition name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="name"/>
Data item definition qualifier <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="nameQualifier"/>
Database domain name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="name"/>
Database domain qualifier <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="nameQualifier"/>
Physical data model namespace <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="PhysicalModel" attrname="namespace"/>
Physical data model name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="PhysicalModel" attrname="name"/>
Design table name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataCollection" attrname="name"/>
Design stored procedure name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="StoredProcedure" attrname="name"/>
Physical domain name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="name"/>
Physical domain qualifier <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataItemDef" attrname="nameQualifier"/>
BI server name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="BIServer" attrname="name"/>
BI folder name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="BIFolder" attrname="name"/>
BI model name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPModel" attrname="name"/>
BI collection namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCollection" attrname="nameSpace"/>
BI collection name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCollection" attrname="name"/>
Cube namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCube" attrname="nameSpace"/>
Cube name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="OLAPCube" attrname="name"/>
BI report name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportDef" attrname="name"/>
BI report section namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportGroup" attrname="nameSpace"/>
BI report section name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportGroup" attrname="name"/>
BI report query namespace <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportDataSet" attrname="nameSpace"/>
BI report query name <Attribute packageNsUri="http:///ASCLModel/3.0/ASCLBI.ecore" classname="ReportDataSet" attrname="name"/>
Logical data model namespace <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="LogicalModel" attrname="namespace"/>
Logical data model name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="LogicalModel" attrname="name"/>
Logical entity name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="Entity" attrname="name"/>
Logical relationship name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="Relationship" attrname="name"/>
Entity generalization name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="Generalization" attrname="name"/>
Logical domain name qualifier <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="Domain" attrname="nameQualifier"/>
Logical domain name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="Domain" attrname="name"/>
Subject area name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="SubjectArea" attrname="name"/>
Logical model diagram name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="Diagram" attrname="name"/>
Subject area diagram name <Attribute packageNsUri="http:///ASCLModel/2.0/ASCLLogicalModel.ecore" classname="Diagram" attrname="name"/>
Data connection name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataConnection" attrname="name"/>
Data file connection name <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataConnection" attrname="name"/>
Custom attribute name <Attribute packageNsUri="http:///2.0/ASCLCustomAttribute.ecore" classname="CustomAttribute" attrname="name"/>
The following XML code makes the changes shown in the table in an exported common metadata archive file.
Table 3. Sample of how properties in the in an exported common metadata archive file are mapped
Property Original value in exported archive file Changed value in the repository
File path of data file /source_folder1/source_folder2 /target_folder1/target_folder2
Host name old_host new_host
Below are sample contents of the mapping file:
<?xml version="1.0" encoding="UTF-8"?> 
<!-- =================================================================== --> 
<!-- Sample Mapping File --> 
<!-- =================================================================== --> 
<Mapping xsi:schemaLocation="SampleArchiveMappingFile.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<ObjectMappings> 
<!--============================================================================== --> 
<!-- Example to change Data file path in the imported data --> 
<!-- from "/source_folder1/source_folder2" to "/target_folder1/target_folder2" --> 
<!-- ============================================================================== --> 
<ObjectMapping> 
<Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="DataFile" attrname="path"/> 
<CurrentValue val="/source_folder1/source_folder2" /> 
<NewValue val="/target_folder1/target_folder2" /> 
</ObjectMapping>  
<!-- ============================================================================== --> 
<!-- Example to change Host name in the imported data from "old_host" to "new_host" --> 
<!-- ============================================================================== --> 
<ObjectMapping> <Attribute packageNsUri="http:///4.0/ASCLModel.ecore" classname="HostSystem" attrname="name"/> 
<CurrentValue val="old_host" /> 
<NewValue val="new_host" /> 
</ObjectMapping> 
</ObjectMappings> 
</Mapping>
If you want to change other attributes that are not listed in the example above in the mapping file, you must contact IBM support.

Examples

The following command imports all common metadata assets using the mapping of attribute values:
istool import -dom ABC:9080 -u user1 -p pass1
-archive "c:\customer.isx" -commonmetadata '-mapping C:\\Folder1\\Mapping.xml'
The following command imports all the logical data model assets using the mapping of attribute values: 
istool import -dom ABC:9080 -u user1 -p pass1
-archive "c:\customer.isx" -logicalmetadata ‘-mapping /Folder1/Mapping.xml’
The following command imports all the custom attributes using the mapping of attribute values:
istool import -dom ABC:9080 -u user1 -p pass1
-archive "c:\custom_attributes.isx" -customattributes ’-mapping /Folder1/Mapping.xml’