Skip Headers

Agile Product Lifecycle Management Import/Export Guide Release 9.3.3 E39290-01 |
| Contents

Previous | Next |

# 8 Mapping Import Fields to Agile Fields

This chapter provides referential and procedural information to map files, key fields and required fields, selecting Change Orders and creating, reusing, and editing mapping files plus mapping PDX and aXML packages.

## 8.1 About Mapping Files

When you import data into the PLM system, you must indicate where to put the data. You do this in the Import Wizard by mapping fields in the source data to Agile fields. Only mapped fields are imported. The Import Wizard ignores any source fields that are not mapped.

Mapping files are XML files that can be reused to map data for subsequent import sessions. You can save the files locally or on a network drive. They are not stored on the PLM system.

Note: The Import Wizard does not support mapping files created with previous Agile Product Cost Management or Agile Product Collaboration releases.

## 8.2 Key Fields and Required Fields

Key fields uniquely identify an object in the PLM system and are required to import all objects, whether they are new or already exist. An example of a key field is the Title Block > Number field for a part. In fact, most key fields for Agile PLM objects are used to set the unique number for the object. When you map fields for import, all key fields in the Edit Mapping File window are shown in blue boldface type.

The following table lists key fields for all objects supported by the Import Wizard. You must map these fields.

Note: If the data is not in the Agile system, you must map all key fields and required attributes. If the data is already in the Agile system (created earlier, or soft deleted), you can bypass mapping the required attributes, but you must map the key fields.

Object | Tab | Key Fields
--- | --- | ---
Currency Conversion | Currency Conversion | Currency Code
Customer Customer | General Info | Customer Name
General Info | Customer Number1
Declaration | Attachment | File Identifier, File Name
Declaration | Cover Page | Name, Supplier
Declaration | Item Composition Item Composition Item Composition | Item Number, Item Revision
Declaration | Substance Name
Declaration | Substance Type
Declaration | Items | Item Number, Revision Number
Declaration | Manufacturer Parts Manufacturer Parts | Mfr. Name
Declaration | Mfr. Part Number
Declaration | Manufacturer Part Composition Manufacturer Parts | Mfr. Name
Declaration | Manufacturer Parts | Mfr. Part Number
Declaration | Manufacturer Parts | Substance Name
Declaration | Manufacturer Parts | Substance Type
Declaration | Part Group Composition Part Group Composition Part Group Composition | Name
Declaration | Substance Name
Declaration | Substance Type
Declaration | Part Groups | Name
Declaration | Specifications | Specification
Item Item Item Item Item Item Item Item Item Item Item | Attachments Attachments | File Identifier
File Name
BOM | Item Number
Compliance | Specification
Manufacturers Manufacturers | Mfr. Name
Mfr. Part Number
Sites | Site Name
Suppliers | Supplier, Change Number
Title Block | Number
Composition | Composition Type, Change Number
Substance | Substance Name, Substance Type
Manufacturer | Attachments Attachments | File Identifier
Manufacturer | File Name
Manufacturer Part Manufacturer Part Manufacturer Part Manufacturer Part Manufacturer Part Manufacturer Part Manufacturer Part Manufacturer Part Manufacturer Part | General Info General Info General Info | Name
File Identifier
File Name
Compliance | Specification
Composition | Composition Type2
General Info General Info | Manufacturer Name
Manufacturer Part Number
Substance | Substance Name
Suppliers | Supplier
Part Group Part Group Part Group Part Group Part Group Part Group Part Group Part Group | Attachments General Info | File Identifier
File Name
Compliance | Specification
General Info | Name
Parts | Part Number
Suppliers | Supplier
Cover Page | Number1
Affected Items | Item Number
Project Item Project Item Project Item Project Item Project Item Project Item | AML AML | Manufacturer Name
Manufacturer Part Number
Attachments Attachments | File Identifier
File Name
BOM | Component Part Number
Items | Number
Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price Published Price | Attachments Attachments | File Identifier
File Name
General Information General Information General Information General Information General Information General Information General Information General Information General Information General Information | Customer
Item Number
Item Revision
Manufacturing Site
Manufacturer Name
Manufacturer Part Number
Number1
Price Type
Program
Supplier
Published Price Lines Published Price Lines Published Price Lines Published Price Lines Published Price Lines | Price Effective From Date
Price Effective To Date
Qty
Ship From
Ship To
Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History Quote History | General Information General Information General Information General Information General Information General Information General Information General Information General Information General Information | Customer
Item Number
Item Revision
Manufacturing Site
Manufacturer Name
Manufacturer Part Number
Number1
Price Type
Program
Supplier
Published Price Lines Published Price Lines Published Price Lines Published Price Lines Published Price Lines | Price Effective From Date
Price Effective To Date
Qty
Ship From
Ship To
Specification Specification Specification Specification | Attachments Attachments | File Identifier
File Name
General Information | Name
Substances | Name, Substances Type
Substance Substance Substance Substance | Attachments Attachments | File Identifier
File Name, Substances Type
Composition | Name
General Information | Name
Supplier Supplier Supplier Supplier Supplier Supplier Supplier Supplier | Commodities Commodities Commodities | Commodity
Continent
Ship-To
General Information General Information | Name
Number1
Manufacturers Manufacturers Manufacturers | Continent
Manufacturer Name
Ship-To
Projects Projects | General Information General Information General Information | Name Name
Projects | Number
Projects | Action Items | Assigned To
Projects | Discussion | Subject
User User | General Information | General Info User ID
User Group | User Group group name
User Group User Group | General Information | General Info Name
User | Users user names in group

Notes:

1. If you don't map the Number field or the data is not provided in the source file, the Import Wizard uses an AutoNumber source to assign a number to a new object it creates. You can set the default AutoNumber sources used by the Import Wizard. For more information, see Setting Default AutoNumber Sources.

2. Composition Type determines what type of substances can be imported into the composition:

   - Substance Composition - Substances and substance groups can be imported.

   - Homogeneous Materials Composition - Subparts, materials, substance groups, and substances can be imported.

   - Part Composition - No substances can be imported.

In addition to key fields, Agile PLM also has required fields. The PLM administrator can configure any field on Page One (Title Block, Cover Page, or General Information), Page Two, or Page Three of an object to be a required field. To import new objects in Agile PLM, you must complete all required fields. However, if you are importing data to existing objects, required fields don't need to be mapped. When you map fields for import, all required fields in the Edit Mapping File window are shown in green boldface type.

For a full list of required Agile PLM fields, print the Agile Classes Report from the Web Client.

Some Agile PLM objects have special mapping requirements. See the following sections for more information.

### 8.2.1 BOM Mapping Requirements

Title Block > Number and BOM > Item Number are required fields. However, BOM > Find Num and BOM > Qty are optional key fields. If you don't map the BOM > Find Num field, the BOM tab shows 0 as the find number for all imported items. If you don't map the BOM > Qty field, all quantities on the BOM tab use the default quantity value set by the Agile PLM administrator.

### 8.2.2 Quote History and Published Price Mapping Requirements

Quote histories and published prices have special mapping requirements due to the multiple required and optional key fields that can be used to import them. For more information about the minimum required fields for Quote Histories, Published Prices, and Published Price Lines, seemporting Quote Histories, Published Prices, and Published Price Lines on page 114.

### 8.2.3 Mapping Classes and Subclasses

For item, BOM, and AML imports, there are two separate target classes that may need to be mapped depending on what the source file contains. If the source file contains both parts and documents, then you must map both the Parts class and Documents class, even if the mappings are the same.

If you do not map the Type field for the object, or the Type column of a particular row is blank, then the default type for the object is used, regardless of whether the object currently exists or not. For example, if your import file contains documents, but you don't map the Type field, documents could be imported as parts if that is the default item type selected in Import preferences. For items in the import file that already exist in the target system, a type mismatch rejection error occurs if the default type assumed by import does not match the existing object in the target system.

For information about how to specify default types for an import session, see Setting Default Types on page 60.

## 8.3 Selecting a Change Order and Mapping File

When the Select Change Order and Mapping File page appears in the Import Wizard, you can specify a change order and select a mapping file using the following options:

- Change Order - If you are importing in Redlining mode (the default), click Details to select a change order. If you are using Authoring mode, you can not specify a change order. For more information about redlining, see Using Redlining or Authoring Mode on page 84.

Note: To change from Redlining mode to Authoring mode, click Preferences, select Business Rule Options, and change the value for the Change Mode field.

- Use an Existing Mapping File - After selecting this option, type the path of a mapping file or click Browse to select one. The mapping file must exist on your local system or on a network computer. Mapping files are not stored on the PLM server.

- Create a New Mapping - After selecting this option, edit Mapping attributes in Step 4 of the Wizard.

- Use Currently Defined Mapping Definition - Use a mapping definition previously selected during this import session. If you have not specified a mapping file yet, this option does not appear.

- Use Default Mapping Definition - Use the default field mappings for the specified file type. This option is not available for Excel files and delimited text files that do not use a predefined template format.

Once you select or create a mapping definition, the Import Wizard stores it in memory for the current import session. After this, you can click Import to begin the import process, or click Next to select other options.

## 8.4 Creating a New Mapping File

If you are importing data from a new source, you need to create a mapping file. To create a mapping file, you select fields from the import data and map them to Agile fields.

To create a new mapping file:

1. In the Import Wizard, proceed to the Select Content Options page.

2. Select the Define attribute Mapping in next step option and click Next.

3. Click a field in the Import Fields list.

   Note: Only one field can be selected at a time in the Specify Attribute Mapping window. However, you can map an import field to multiple Agile PLM fields. Also, if the Specify Attribute Mapping window has no fields, the source file may be invalid. If the source file is a delimited text file, make sure fields in the header row do not have carriage returns or linefeed characters.

4. 6. Navigate to the corresponding field in the Agile Fields list. Click the field to map it. This arrow appears next to the field along with the name of the import field to which it is mapped.

5. 7. Repeat steps 3 and 4 for all fields that you want to map.

6. 8. When you finish mapping all fields, click Save As. The File Download dialog box appears.

7. 9. Select Save this File to Disk. Click OK.

8. 10. Type the name of the file, and click Save.

To unmap a field in the Edit Mapping File window:

1. Click the icon to the right of the mapped field.

To show all fields in the Specify Attribute Mapping window:

1. Click Expand All.

### 8.4.1 Mapping Page Two and Page Three Fields

Only visible Agile fields can be mapped in the Specify Attribute Mapping window. To map source fields to Page Two or Page Three fields, the Agile PLM administrator must configure those fields to be visible.

### 8.4.2 How Fields are Sorted in the Specify Attribute Mapping Window

When you are importing data from a PDX package, the Specify Attribute Mapping window displays import fields sorted in alphabetical order within each node in the package. The following figure shows how fields in a PDX package are sorted for the Item subclass.

Figure 8-1 Sorted PDX package fields for the Item subclass

When you import data from a delimited text file, the Specify Attribute Mapping window does not sort the import fields. Instead, it displays the fields in the order in which they appear in the text file, as shown in the following figure.

Figure 8-2 Fields in the order of appear in the text file

To make it easier to map fields in a text file, you may want to sort the fields in another application, such as Excel, before attempting to import the data.

Figure 8-3 Sorted Agile fields in Agile Classes

Agile fields are sorted in alphabetical order by the tab on which the field appears, as shown in the following figure.

## 8.5 Reusing a Mapping File

If you routinely import data from the same source (such as PDX packages originating from the same source system), you can maintain mapping files that correctly map source fields to Agile fields.

Mapping files are flexible and are designed to be reused for subsequent import sessions. The import source data generally varies from one import session to another. However, it's possible to reuse the same mapping file for multiple source files if the mapping file contains fields common to them. For example, if you create a mapping file that contains mappings for all PDX objects, you can reuse that particular mapping file for any PDX file, including a file that only includes one type of object, such as Items. If a target field is mapped but doesn't exist in the import source file, the Import Wizard ignores the field and doesn't import it.

Target fields in the PLM system can also change from one import session to another. For example, the PLM administrator can make fields invisible that may have been used in your mapping files. When a target field is mapped but isn't visible in the PLM system, the Import Wizard ignores the field and doesn't import it.

If you rename column headings in your import source file, any mapping files that you created for that particular source file will be invalid. To successfully import the data, you need to remap all fields that have been renamed. The Import Wizard ignores any mapped fields that are not found in the source file.

If the PLM administrator renamed classes or attributes used in a mapping file, the Import Wizard resolves target fields by referencing their internal IDs. Therefore, mapping files that reference renamed fields are still valid. The Debug Mapping Window shows a warning message for every field that the Import Wizard resolves to a different name.

To use an existing mapping file:

1. In the Import Wizard, proceed to the Select Content Options page.

2. Select Use a saved mapping file.

3. Type the path of the mapping file, or click Browse to locate and select the path.

   Note: After you select the file, you can confirm the field mappings by clicking Next, and reviewing the mapped fields in the Specify Attribute Mapping page.

4. Click Next to continue.

## 8.6 Editing a Mapping File

If an import file has been modified (for example, new columns of data have been added), you need to modify its associated mapping file. Otherwise, the mapping file could be invalid for the revised data.

To edit a mapping file:

1. In the Import Wizard, proceed to the Select Content Options page.

2. Select Use a saved mapping file.

3. Type the path of the mapping file, or click Browse to select it.

   Note: Mapping files have an XML filename extension.

4. Edit the Mapping File in Step 4 of the Wizard.

   When you reuse a mapping file to import a new source file, the Import Wizard ensures that the mapping file correctly matches the source data. If the mapping file has errors, an Errors/Warnings box appears at the top of the window. You can click an error or warning in the box to highlight its related field.

5. Edit the mappings.

6. Click Save As to save the file. The File Download dialog box appears.

7. Select Save this File to Disk. Click OK.

8. Type the name of the file, and click Save.

## 8.7 Mapping PDX and aXML Packages

When you select Use Default Mapping on the Select Content Options page, the Specify Attribute Mapping page provides default mappings for core Agile fields. Custom fields are not mapped by default; you have to map those fields manually.

Only PDX and aXML elements present in the source file are assigned default mappings. For example, if the file contains only items and no other types of import data, then the Specify Attribute Mapping page shows default mappings for item fields only. If you save the mapping file to reuse it later, you can use it only to import items.

To create a mapping file with mappings for all types of import data, make sure all objects are selected in the Specify File Content page of the Import Wizard. That way, default mappings are assigned for all objects, regardless if all objects are contained in the selected source file.