Configuring Record Matching and Update Logic

Configuring Record Matching and Update Logic

By default, the Import Module updates a person's single most recent record. Record Matching is a powerful feature that overrides this behavior, giving you precise control to update specific, distinct records belonging to the same person. This is essential for any scenario where a person has multiple records of the same type, such as different report cards for each term, multiple assessment results, or ongoing contact logs.

How Record Matching Works

The entire Record Matching process revolves around creating a unique value, or "matching key," for each record. You designate a specific field on your form to hold this key. The system then uses the value in that field to find the exact record that needs to be updated.

The logic follows two key steps:
  1. A Matching Key is Built: For each row in your source file, the system looks at the Expression on your designated matching field. It uses this expression to assemble a unique "matching key" from the data in that row (e.g., 2024-2025).
  2. Rows are Grouped by the Key: The system groups all rows from your import file that produce an identical matching key. This group of rows is then treated as a single data unit for updating a specific record.

How to Set Up Record Matching

Setting up this feature is a two-part process that involves both the Import Configuration and the Form Editor.

Step 1: Enable the Feature in Your Configuration

  1. Navigate to your Import Configuration page.
  2. In the Record Matching Rules section, check the Enable Record Matching box.

Step 2: Select the Matching Element for Each

  1. Click the Configure button. A "Record Match Mapping" popup will appear, listing every form that uses this import's Alias.
  2. For each form in the list, you must click the search icon and select the field that will serve as the Matching Element. This field will hold your matching key.
AlertImportant: You must select a Matching Element for every form you want this feature to apply to. If a form is listed but no Matching Element is selected, that form will not import any data when this configuration is run.

A Practical Example: Updating Yearly Records

This scenario shows how Record Matching uses grouped rows and Indexed Expressions to populate multiple fields on a single record.

The Goal

Update a student's yearly report card. The form has space for four subjects, but the import file only contains data for two subjects for the current year.

The Source File (grades.csv)

  1. StudentID,SchoolYear,Subject,Grade
  2. 12345,2024-2025,English,A
  3. 12345,2024-2025,Math,B
  4. 12345,2023-2024,English,B

The Form Mapping

Your "Yearly Report Card" form has a field named SchoolYear that will be used as the Matching Element. The form also has fields for subjects and grades mapped with indexed expressions:

Form Field
Mapping Expression
Subject 1
{Subject[0]}
Grade 1
{Grade[0]}
Subject 2
{Subject[1]}
Grade 2
{Grade[1]}
Subject 3
{Subject[2]}
Grade 3
{Grade[2]}

The Result

When the import runs for student 12345:
  1. The system identifies the matching key from the SchoolYear column. It bundles the two rows with the key "2024-2025" into a single group.
  2. It then finds all existing report card records for that student where the SchoolYear field is also "2024-2025" and updates them.
  3. The system maps the data from the group into the form fields of the matched record(s):
    1. {Subject[0]} and {Grade[0]} map English and A to the Subject 1 and Grade 1 fields.
    2. {Subject[1]} and {Grade[1]} map Math and B to the Subject 2 and Grade 2 fields.
    3. Since there's no third row in the group, {Subject[2]} and {Grade[2]} map blank values. This will clear any data that may have previously existed in the Subject 3 and Grade 3 fields, but only if the "Import blank values" setting is enabled in your configuration.
  4. Finally, the system processes the last row for student 12345. It creates a new group with the matching key "2023-2024". It then finds a different report card record for that student where the SchoolYear field is "2023-2024" and updates its Subject 1 and Grade 1 fields with English and B.

Behavior by Import Type

How the system uses the matching key logic varies slightly by how the import is run.

Bulk Imports (Automated or Manual "Run Now")

The system compares all groups from the file against all of a person's records. If a record is found with a matching key, it's updated. If no matching record is found, a new one may be created based on your configuration settings. Blank values from the source file will only clear existing data if the "Import blank values" setting is enabled on the Import Configuration page.

On-Demand Imports (from the Form Interface)

This method refreshes the single record you're viewing. The system reads the matching key from your current record (e.g., "2024-2025"), finds the corresponding group of rows in the source file, and imports only that data into the record you're on. For on-demand imports, blank values from the source file will always clear existing data in the form, regardless of other settings.

Rules and Update Logic

  1. Limitation: The field designated as the Matching Element cannot use an Indexed Expression (e.g., {Column[0]}).
  2. If a Match is Found: All specific records with the matching key are updated.
  3. If No Match is Found: The system's behavior depends on the import method:
    1. Automated Imports: A new record is created only if the "Create missing records during the nightly import" box is checked in your configuration.
    2. Manual Imports: A new record is created based on the Record Creation Mode you select on the "Run Now" page. The options are:
      1. Do not create new records: If a matching record isn't found for a group of rows, the data is skipped and no new record is created.
      2. Create missing records: If a matching record isn't found, a single new record is created using the data from that group of rows.
      3. Always create new records: A new record is created for every group of rows, regardless of whether a matching record was found.
Alert
Warning: Use the "Always create new records" mode with extreme care. If your matching key is misconfigured or your source data is incorrect, this option has the potential to create a very large number of unwanted duplicate records. It's highly recommended to test your configuration with a small file first.

Next Steps

With your import configuration and record matching logic defined, the next step is to connect your data to the fields on your form.


    • Related Articles

    • Import Module Terminology

      The Import Module allows you to bring data into your forms from external files. Understanding the terminology is crucial for configuring imports, preparing data, and troubleshooting effectively. This guide defines the key concepts you'll encounter. ...

    • Configuring an Import: A Section-by-Section Guide

      Setting up an Import Configuration involves telling the system how to find, read, process, and match your data. This guide walks you through creating a new configuration and explains every setting available on the configuration page. Creating a New ...

    • Triggers - Record Filtering

      Filtering in the export process allows you to control which records are included in an Export. These filters can be applied at the Trigger level, ensuring that only the relevant data is exported based on specific criteria. This flexibility enables ...

    • An Introduction to Data Imports

      The Import Module is designed to bring external data from structured files like CSV, TSV, JSON, or XML directly into your forms. The entire process is built around a central concept: the Import Configuration. Think of an Import Configuration as a ...

    • Import Error Code Reference

      When an import fails, the system will log an error code to help you diagnose the problem. This guide explains what each error code means and provides step-by-step instructions on how to resolve the issue. E0001: Cannot Read File Problem The system ...