Mapping Through Special Rules
You can write mapping rules to apply to a specific export or import process, or to a set of export or import processes. The rules reside in one or both of the two types of ASCII XML files that can include properties to control import and export operations:
• Client-based files—You select these files by browsing in the graphical user interface. These mapping rules file can have any name and can be located anywhere that the software can access and read them. These files take precedence if they conflict with generalized files.
• Generalized files—These files provide rules for either import operations or export operations. Their names must end in .xml. They are in one of two locations whose names define their functions:
\Windchill\codebase\registry\ixb\export_settings
\Windchill\codebase\registry\ixb\import_settings
You set properties in mapping rules files by editing the files, and you cannot use the xconfmanager utility for this purpose. If you do not set properties through a graphical user interface or in a mapping file, you add or edit properties with the xconfmanager utility.
Examples of both types of files are included in the next two sections. After the examples, there are sections about properties and rules, including rule examples.
Mapping Priorities
The priority order of the four sources that control conflict resolution are as follows:
1. Import window—The Resolve Overridable Conflicts checkbox in the Import window controls the wt.ixb.import.overrideConflicts property in the wt.properties file.
This property enables the automatic resolution of folder and other conflicts. If you do not set properties through a graphical user interface or in a mapping file, you can add or edit properties with the xconfmanager utility.
2. Client-based files of mapping rules
3. Generalized files of mapping rules
4. Entries in the wt.properties file
Client-Based Mapping Rules Files
The rules and property values that appear in a client-based mapping file control Windchill export and import operations. These rules and values overrule conflicting rules and values in the wt.properties file or a generalized mapping rules file. The <debugProperties> element is the location for properties, and it is not required. This element can include the import.parser.validate property that enables you to debug import operations by generating messages when the XML parser detects inconsistencies. The property that enables the automatic resolution of folder and other conflicts is named import.overrideConflicts when it appears in mapping files.
In a client-based mapping file, the mapping rules occur in the <mappingRules> element.
Note that all the following examples can have the tag-value pair:
<path>…</path>
This tag-value pair allows the narrowing down of the elements applicable for the mapping rule. For example, the following mapping rule changes the value for tag <number> from 1 to 4 for all XML files, such as WTPart and WTDocument instances.
<COPY_AS>
<tag>number</tag>
<value>1</value>
<newValue>4</newValue>
</COPY_AS>
If you wanted the preceding example to apply only to WTPart, you could achieve that by specifying the tag <path> and its value in the mapping rule:
In this case, even though the number of a WTDocument instance is 1, its value will still be 1 instead of 4 for both import and export.
Client-Based Mapping Rules File Example
The following example shows the syntax of a client-based mapping rules file:
Generalized Mapping Rules File Example
The following example shows the syntax of a generalized mapping rules file. In this type of file, there is no <mappingRules> or <debugProperties> element. The properties that appear early in the file are not required and repeat properties that appear in the wt.properties file. The rules and property values that appear in a generalized mapping file take precedence if they conflict with entries in the wt.properties file. However, the rules and property values that appear in a generalized mapping file are overruled by conflicting values in a client-based mapping file.
Properties in Mapping Rules Files
The preceding examples showed how to place properties in mapping rules files. The Windchill Export and Import section describes the properties that you can use to control Windchill import. You set properties in mapping rules files by editing the files, and you cannot use the xconfmanager utility for this purpose. If you do not set properties through a graphical user interface or in a mapping file, you add or edit properties with the xconfmanager utility.
Do Not Map Number Attributes for MCAD Documents
The number attribute of an MCAD document in the Windchill database is a string identical to the Creo Parametric file name of a document. If you change the number attribute of an MCAD document by using a mapping rule or altering the object when it is on the local disk, you create data that is incompatible with the assembly files that refer to it. Attempting to repair a number change by reverting to the original information does not succeed because the software perceives an attempt to check in the renamed object as an attempt to duplicate an existing object.
About Mapping Rules
Each mapping rule is an XML element within the mapping rule file. Each mapping rule element, except for one that specifies copying, has at least two sub-elements: <tag> and <value>. These two sub-elements determine whether the rule applies for any given element in an imported or exported XML file. If multiple rules in a file could apply to an element in an imported or exported file, only the first rule applies.
The following examples show the types of rules and how to apply them to a variety of attributes. To work with attributes that do not appear in the following examples, you need to understand XML and read the XML file that you are mapping.
COPY Element
By default, all elements in a source XML file are copied into the resulting XML file, and consequently it is not necessary to specify a rule that copies elements without alteration. If any rule specifies an action other than copying for an element, copying does not occur and the other rule controls the result for the element. The only element in a rule that specifies copying is COPY, and it has no sub-element.
COPY_AS Element
Rules that use the COPY_AS element alter an element from a source XML file and place the altered element in a resulting XML file. A <newValue> sub-element is required in addition to <tag> and <value> sub-elements. The following examples show possible syntaxes:
Mapping an Object's View Source_View to View Local_View
<COPY_AS>
<tag>view</tag>
<value>Source_View</value>
<newValue>Local_View</newValue>
</COPY_AS>
Mapping Any Object's View to View Local_View
<COPY_AS>
<tag>view</tag>
<value>*</value>
<newValue>Local_View</newValue>
</COPY_AS>
Mapping an Object's Number Attribute 2222 to Number Local_2222
<COPY_AS>
<tag>number</tag>
<value>2222</value>
<newValue>Local_2222</newValue>
</COPY_AS>
Mapping Any Object's Number Attribute to a Number Constructed from the Prefix From_Site_AAA_ and the Same Number
This example shows From_Site_AAA being appended to any number. For example, the number 2222 would be mapped to From_Site_AAA_2222 in the resulting file.
<COPY_AS>
<tag>number</tag>
<value>*</value>
<newValue>From_Site_AAA_*</newValue>
</COPY_AS>
Mapping an Object's Version A to Version B
<COPY_AS>
<tag>versionInfo/versionId</tag>
<value>A</value>
<newValue>B</newValue>
</COPY_AS>
Mapping Any Object's Version to Version A and Any Iteration to Iteration 1
<COPY_AS>
<tag>versionInfo/iterationId</tag>
<value>*</value>
<newValue>1</newValue>
</COPY_AS>
Mapping Any Object's Team That Begins with MyTeam to the Default Team
<COPY_AS>
<tag>teamIdentity</tag>
<value>MyTeam*</value>
<newValue>System.Default</newValue>
</COPY_AS>
Mapping Any Object's Folder to Administrator/NewFolder
<COPY_AS>
<tag>folderPath</tag>
<value>*</value>
<newValue>/Administrator/NewFolder</newValue>
</COPY_AS>
Mapping Objects in Subfolders Under the Marketing Folder to the Same Subfolders Under the Publications Folder
<COPY_AS>
<tag>folderPath</tag>
<value>/Marketing/*</value>
<newValue>/Publications/*</newValue>
</COPY_AS>
An asterisk (*) placed in the new and old value strings in folder mapping rules results in the creation of new folders in the position of the asterisk. These new folders duplicate the folders that existed in the old path in the position of the asterisk. The following is the most generalized syntax for such mapping rules:
<COPY_AS>
<tag>folderPath</tag>
<value>PrefixOld*SuffixOld</value>
<newValue>PrefixNew*SuffixNew</newValue>
</COPY_AS>
Any string from PrefixOld, SuffixOld, PrefixNew, or SuffixNew could be an empty string.
IGNORE Element
Rules that use the IGNORE element exclude an element in a source XML file from a resulting XML file. The <tag> and <value> sub-elements are required. The following example shows a possible syntax.
Excluding Life Cycle State Information from a Resulting XML File
<IGNORE>
<tag>lifecycleState</tag>
<value>*</value>
</IGNORE>
IGNORE_PARENT Element
Rules that use the IGNORE_PARENT element exclude the parent of an element in a source XML file and all the child elements of that parent element from a resulting XML file. The <tag> and <value> sub-elements are required. As usual, the <path> element is optional. The following example shows a possible syntax.
Excluding a Reusable Attribute Value Named Price from a Reusable Attribute Holder Such As WTPart
In the preceding example, if the following line were deleted, all parent elements in all XML files with <ibaPath>Price</ibaPath> would be excluded:
<path>WTPart</path>