NexJ Logo

Creating mapping files and generating import packages

Once you have obtained a set of CSV files containing the contact data you want to import and the target definition file, you must create mapping files. The mapping files allow NexJ CRM to load contact data into the appropriate columns in the database. You need one field mapping file for each CSV file and one file mapping file that lists all the CSV and XML files included in the package.

Use the NexJ Data Mapping Tool to generate the file mapping and field mapping files and to create the import package containing all the files used by NexJ CRM during the import process.

To create the mapping files using the NexJ Data Mapping Tool:

  1. Open the NexJ Data Mapping Tool.
  2. Click Create New Mapping.
  3. In the dialog that appears, specify the following information:
    • Data Location
      The directory where the CSV files containing your data are stored.
    • Target Definition File
      The definition file you generated in NexJ CRM using Contact Import > Generate Definition File.
    • Mapping Template
      If you have been provided with a mapping template file or if you are continuing work on an existing mapping file, specify the name and location of the file. Otherwise, leave blank. To ensure the mapping template file appears in the drop-down list, place the file in the directory specified in the Data Location field. Otherwise, use the Browse button to navigate to the mapping template location.
  4. Click OK. All CSV files you generated are listed in the Source Files in Data Location column; all possible target field categories are listed in the Target Field column; and the number of columns in each CSV file is listed in the Mapping Fields column.
  5. For each CSV file, select the type of data in the Type of Data in File drop-down.
    The Source Field drop-down fields and Target Field names display.
  6. For each CSV file, assign a target field category. If you only have one source file or if there is no likely equivalence between a CSV file and any target category, assign the All field category. Assigning a field category limits which fields are displayed when you are assigning a source field to a target field.
  7. Specify how null fields are treated. By default, any null field is converted into a null field. If you want to specify a different value for null fields, select the Use Null Converter option. The Null Converter column appears below. You can specify the default value which will be used for all null fields in the Value field and click the Apply Null Converter button. Otherwise, you can specify the value to be used for each field in the Null Converter column. To remove the default value from all fields, click the Erase Null Converter button.
  8. Using the drop-down lists, map a column name from the Source Fields column to a field in the Target Fields column. When a source column has been assigned to a target field, a green check mark appears next to the column name in the drop-down list. In addition, the plug icon next to the field name appears plugged in. For details, see Mapping one-to-one fields and Mapping many-to-one fields.

    The drop-down lists contain the column name as well as a sample value for that column. The sample value is populated with an available value from within the first 1,000 records in the import package.

    For any field in your legacy data that has no equivalent in the NexJ CRM data structure, create a new User Field subcollection attribute. Assign the source field to this new User Field. To unmap a source field, click the Unmap Field button. You do not need to map every column in a source file to a target field. However, any columns not mapped to a field will not be imported into NexJ CRM.

  9. If you want to save the mapping information, either to share it with other users or to continue working later, click Export Mapping Template. In the Create Mapping Template dialog, specify where you want to save the mapping file and click Save.
  10. When you have completed all mapping work, click Generate Import Package. In the Create Import Package dialog, specify where you want to save the package and click Save.

After creating your import package, verify its size and contents.

The import package must be less than 10MB. If it is greater than 10MB, you will not be able to import the package. If this is the case, you should split the data into multiple data sets and rerun the package generation for each data set separately.

The generated package should contain the following files:

  • One or more CSV files containing your legacy data.
  • One file mappings file called fileMappings.xml. It lists all the CSV files containing the legacy data and the related XML field mapping files.

    You can specify the encoding character set to be used for the import process in fileMappings.xml by adding the encodingType property to the source code:

    <mapping encodingType="characterSet">

    where characterSet is the value you provide for the encoding character set. For example, specify CP-1252 to indicate that the import package data is using the CP-1252 encoding. By default, the UFT-8 encoding is used. The character set for the generated package must match the character set you specified.

  • One field mapping file for each CSV file. The mapping file names are based on the names of the CSV files. For example, if the CSV file is called TBL_CONTACT.csv, then the mapping file is called TBL_CONTACT_mappings.xml.