Creating mapping files

A mapping file determines which pieces of data to import into the fields on the target form (mapping) during the import process. You can map all fields in a data file to all fields in a form, or you can map fields individually.

How data fields are matched to form fields

Data Import matches data fields to form fields as follows:

• AR Export or AR XML—Field IDs are matched first, and then field names are matched for fields without matching IDs.
• CSV or ASCII—Only field names are matched.

Defining default mappings

You can define fallback mappings, which are default mappings that direct the Data Import response if a data mapping problem occurs during an import. Fallback mappings are used when the data value is invalid for the destination form field type. For example, if a problem occurs while a value is mapped, the fallback mapping for the field is used if one is defined. If no fallback mapping exists, an error is generated. If a fallback mapping fails, errors are generated on the original failed mapping, not the fallback mapping.

When only the AR System server can detect the error (such as when the data is not an acceptable value), the fallback mapping is not used. For example, the data value is outside the range set for the form field, or a required field has a NULL value.

Tips for mapping all data file fields

Keep the following tips in mind when mapping all data file fields:

• Make sure that all fields map correctly. If necessary, resolve unmatched or incorrectly matched fields by mapping those fields individually.
• If the matching is partially successful, all possible matches are added. To complete the mapping, map remaining fields individually.
• If no matches are found and no entries are in the Form Fields list, an error is generated. You can delete mappings and map fields individually or start the import with the partial mapping.
• If no fields are mapped, an error is generated, and you must load a mapping or map fields manually.

To create a mapping file

1. Log in to Data Import.
2. Select File > New Mapping.

3. In the Mapping File Editor, complete the following fields in the Data File and Server section:

   New Mapping dialog box fields
4. Map the fields in the Field Value Mappings section using either of the following methods.
   1. Click Auto Map to add all fields and map fields to fields of the same name. For more information, see Tips for mapping all data file fields.
      Or
      Click Add.
   2. In the Add Mapping dialog box, select a field name.
   3. Use the Keyword or Field buttons to add a value to the Value field.
      You can also type field names, keywords, or any constant string into the Mapping Value field.
      For example, suppose you select the Create Date field, and you want each record in the destination form to have today's date as the value in the Create Date field. Choose $DATE$ in the Keyword list. The resulting value in the destination form is the date of the import. See Keywords.

   4. Repeat this step for all the fields that you want to map.

      If the data file contains duplicate field titles, an error is generated. If the data is .arx or .xml format, the field titles appears as their field IDs. If the data file is .csv or .asc format, the fields appear with an appended number (for example, fieldTitle1, fieldTitle2, and so on).

5. (Optional) Define fallback mappings for fields.
   For more information, see Defining default mappings.
6. To edit a field value mapping or fallback mapping, select the field, and click Edit.
7. (Optional) Click the Options tab, and change the preferences as needed.
   See Defining Data Import preferences for a description of most of the options. The differences are:
   • The Options tab does not include a Log File field, but it is included in the Preferences window.

   • The Options tab includes the following fields, which are not included in the Preferences window.

     

     Additional Data Handling field on the Options tab
8. (Optional) Save the mapping.
9. Import the data as described in Running-a-data-import.