Introduction

After creating and configuring an import template, the final step is to set up the field mapping. This section allows you to tell the system how to match the fields in the imported file with those in Altamira, as defined in the form associated with the import template.

To access the mapping of an import template, go to Settings > Templates > Import. Select the import template and click the Mapping button.

On this page, click Add to create the mapping of a field. Then add one row for each field you want to import.

Source and Destination Field

The Destination Field is the field where data will be written from a specific field in the file being imported. The name of this field in the file must be indicated in the Source Field.

There are several ways to import/write data into the Destination Field:

• You can use the Source Field by entering the name of the column from the Excel file, for example. It is also possible to combine multiple fields and add text between them using quotation marks. Example: FieldName1 + "/" + FieldName2.
• You can use the Default Value field to insert a value that will be written identically for all imported records.
• You can edit the mapping row by clicking the edit icon to the left of the Source Field. Here you can insert a script that manipulates the data in the import file to decide more specifically what to import. In this case, you do not need to specify anything in the Source Field, since the script will return the value to be written in the Destination Field.

Advanced Mapping Edit

By clicking the edit icon to the left of the Source Field, you can open the advanced editing screen for that mapping row. In this screen, you can use additional fields:

• Source filter: enter a value found in the relevant field of the import file to filter the data. This allows you to import only those rows where a field’s value matches the specified filter — for example, only vacation balances or only candidates from a specific city.
• Lookup view:
  • Below are the fields to configure in order to use a lookup view in the field mapping of the import template (before configuring these fields, make sure to create and properly configure the view as explained in the article Import template: lookup view):
    • Entity: indicates the entity containing the view (of type Report – Table) used as the lookup view.
    • Lookup view: specifies which view to use as the lookup view.
    • Content field in the lookup view: specifies the field within the view to return as the result of the lookup.
  • The lookup view is used in two cases:
    • When there are at least two fields used to filter a secondary entity/table linked to the main one being imported. Since two secondary key fields referring to the same entity cannot be configured in the standard mapping, this method must be used.
    • When you want to link to an entity/table not directly related to the main one. The lookup view allows you to search across any table.
• Script: within this field you can write scripts in C# language. These scripts allow you to manipulate imported data in various situations. Some example scripts are available in the article Import template: Scripts.

Primary Key and Secondary Key

Setting these parameters allows the system to perform specific searches to identify which records to update or create.

• Key field: fields set as keys refer to the table into which data is being imported. The field (or combination of fields) with this option enabled identifies the record to be written.
  • For example, if you are importing employee data, the key field might be the tax code or email address, since these uniquely identify each employee.
  • If the system finds a record matching the imported values, it updates it; otherwise, it creates a new record.
  • If the import template option “Automatically add main items if not already present” is disabled, new records will not be created if the key field values are not found in the database.
• Secondary key: used to link to another entity on which the imported data depends.
  • For example, a secondary key can be used when writing the ID of a different entity (such as EmployeeID) into a field of the main entity, but only another field (like Tax Code) from that entity is available in the import file. 
    In this case, the tax code field from the employee entity (which is not the main entity) must be set as the secondary key. The import engine will retrieve the EmployeeID using the tax code as a filter and write it into the medical certificate record being imported. 
    Note: in this example, the ID field of the medical certificate entity must be present in the file and set as a “Key field”.
  • Both “Key field” and “Secondary key field” should be selected only when the ID field of the secondary entity must be used as a filter to locate the record in the main entity. 
    For example, when importing payslips, the “Tax Code” of employees may be set as both a Key field and Secondary key field, together with the “Month” field of the payslip. This ensures the system filters using both the employee ID and the month when locating or updating the payslip record. 
    Warning: if both flags are selected for a field belonging to the main entity, it will be used to find the record but will not be written during import.
    • You cannot use two secondary key fields that reference the same table. In such cases, you must use lookup views. For example, if you want to use both “Last name” and “First name” as keys for an employee record, you must combine them into one field (e.g. "LastName + ' ' + FirstName") rather than setting both as separate secondary keys.