Configuring Update Keys for Smarter Imports and More

Update Keys are one or more fields on a template that Claravine uses to identify whether incoming data matches an existing record. When data comes into Claravine, those fields act as the match criteria to determine whether an incoming row already exists in the dataset and should be updated, or is new and should be created. Data will only update existing rows if all Keys match. 

This behavior applies across all three ways data enters Claravine:

• File imports
• API submissions
• Manual entry (creating or pasting rows directly into a submission table)

Without Update Keys, every submission creates a new row regardless of whether that data already exists. Update Keys automates the matching process, so teams no longer need to manually identify and resolve duplicates by giving the platform a consistent, automatic way to recognize existing records and update them in place across any data entry method.

How to Configure Update Keys

1. Open the template you want to configure.
2. Navigate to the field you want to use as a key and open its Edit sidebar.
3. Check the Update Key checkbox.
4. Repeat for any additional fields if you are building a compound key.
5. Save your changes. The key(s) apply automatically every time data is submitted to that template, regardless of submission method.

Tips and Best Practices

• Choose fields with unique, stable values as your key. Fields like campaign ID, tracking code, or a standardized identifier work well. Avoid fields where values change frequently or are shared across many rows.
• Account for case and spacing. Because matching is exact, make sure submitted data uses consistent formatting. A trailing space or capitalization difference will prevent a match and create a new row instead.
• Use compound keys when a single field is not unique enough. Pairing "Campaign ID" with "Market," for example, can distinguish rows that would otherwise look identical on name alone.
• Communicate key configuration to your team. The import modal surfaces the active key(s) via badge so users can see what is in effect before submitting. For API and manual workflows, make sure your team knows which fields are designated as keys so they prepare data accordingly.
• Test with a small dataset first. Before running a large update, validate matching behavior with a sample to confirm values align as expected.
• Concatenated or read-only fields as keys require a different approach. When using a concatenated field as your identifier, assign the Update Key to the fields that make up the concatenation rather than the concatenation itself. Read-only fields like patterns and concatenations can be designated as Update Keys, but Claravine does not process direct changes to read-only fields. Assigning the key to the source fields ensures the match logic works as intended.

Users' Experience

File Import

When a user imports a file to a template with Update Keys configured, the import modal displays a badge identifying the active key field(s) before the import runs. This gives users visibility into what is driving the match before they confirm. Claravine then processes each row, updating records where a match is found and creating new rows where no match exists.

Manual Entry or Paste

When a user creates a new row or pastes data directly into a submission table, Claravine checks the key field value(s) against existing records in real time. A match updates the existing row rather than creating a new one. Users do not need to take any additional steps for this to happen -- the matching behavior is automatic based on the keys the Admin configured on the template.

API Submission

When data is submitted through the API, Update Keys apply automatically. No additional configuration is required at the API level. Claravine matches each incoming row against the key field(s) and updates or creates records accordingly.