Create a Version History for Records

What You'll Learn

This article shows you how to create a version history that captures the actual field values each time a record is created or edited. Every entry in the history is a snapshot of the record at that point in time, so you can see exactly what changed and when.

If you only need to track who made changes and when (without capturing field values), see Creating a Change Log for Records.

Use Case

You have records where you need to see the full history of what values changed over time. For example, a patient record where you need to know what the previous address, insurance, or status was before the most recent edit. Or an inventory item where you need to track price changes over time.

This is especially important for HIPAA apps that require detailed audit trails showing what PHI was modified.

Requirements

• Users enabled in your app with at least one user role. See User Management Fundamentals.
• At least one table with records you want to track
• Familiarity with record actions. See Using Record Actions.

How It Works

The pattern is straightforward: you create a Logs table with fields that match the fields in the table you're tracking. Every time a record is created or edited, a record action copies the current field values into a new log entry. Over time, you build up a series of snapshots that show the state of the record after each change.

Steps

1. Create a Logs Table With Matching Fields

Navigate to the Tables section of the Builder. Create a new table called "Logs" (or a name that fits your app). Add the following fields:

Connection fields:

• Connection to the table you're tracking (e.g., "Item") — one item connects to many logs
• Connection to the user role table (e.g., "Updated By") — one user connects to many logs

Tracking fields:

• Date/Time field (e.g., "Date") — when the change happened

Matching fields — these must match the fields in your source table:

• For every field you want to track in the source table, add a matching field of the same type in the Logs table

For example, if your Items table has "Name" (Short Text), "Colors" (Multiple Choice), and "Price" (Currency), your Logs table should also have "Name" (Short Text), "Colors" (Multiple Choice), and "Price" (Currency).

📘

You don't have to match every field. Only add matching fields for the values you actually want to track in your version history. If a field never changes or isn't important to audit, you can leave it out.

2. Add a Record Action to the Add Form

This step captures the initial values when a record is first created. Without it, your version history only starts at the first edit, and you'll have no record of the original values. There's no way for Knack to retroactively capture those values from an edit form.

To set this up, navigate to Pages in the Builder and open the page with the form that creates new records in the table you're tracking:

1. Click into the form element
2. Go to the Record Actions tab (under Submit Actions)
3. Add a new action: "Insert a connected record"
4. Select your Logs table
5. Map each field value:
   • Name — set to Field Value > Name
   • Colors — set to Field Value > Colors
   • Price — set to Field Value > Price
   • Date — set to "Current Date"
   • Updated By — set to "Logged-In User"

The key here is the field value mapping. For each matching field in the Logs table, you select "Field Value" and then choose the corresponding field from the form. This copies the submitted values into the log entry.

⚠️

Don't skip this step. Most people only add record actions to the edit form and forget the add form. If you skip the add form, your version history has no baseline. You'll see changes but won't know what the original values were.

3. Add a Record Action to the Edit Form

Navigate to the page with the edit form for the same table and repeat the same steps:

1. Click into the edit form element
2. Go to the Record Actions tab
3. Add a new action: "Insert a connected record"
4. Select your Logs table
5. Map the same field values:
   • Name — set to Field Value > Name
   • Colors — set to Field Value > Colors
   • Price — set to Field Value > Price
   • Date — set to "Current Date"
   • Updated By — set to "Logged-In User"

Every time a user edits the record and submits the form, a new log entry is created with the current values. This gives you a snapshot of the record after each edit.

4. Display the Version History in Your Live App

Navigate to Pages in the Builder and open the details page for the record you're tracking. Add a table element to show the version history:

1. On the record's details page, add a new table element
2. Source it from the Logs table
3. Set it to show "Logs connected to this page's Item"
4. Add the columns you want to display (Date, Updated By, Name, Colors, Price, etc.)
5. Set the default sort to show the most recent entries first

Users can now see the full history of changes for any record, with each row showing the state of the record at that point in time.

5. Test Your Setup

1. Log in as a user and create a new item (e.g., Name: "Laptop", Colors: "Black", Price: "$999")
2. Navigate to the item's details page and confirm a log entry was created with those values
3. Edit the item (e.g., change Price to "$899")
4. Check the details page again — you should now see two log entries: the original and the updated version

If both entries appear with the correct values, your version history is working.

Comparing Entries

With this setup, you can compare any two entries in the version history to see what changed. The most recent entry shows the current state. The entry before it shows the previous state. Looking at the differences between rows tells you exactly what was modified.

For example:

In this example, Jane changed the price from $999 to $899.

Common Mistakes

• Skipping the add form record action. This is the most common mistake. Without it, you have no record of the original values. Your history starts at the first edit, and you'll never know what the initial state was.
• Only adding the record action to one edit form. If you have multiple edit forms or inline editing across different pages, each one needs its own record action. Otherwise, changes made through those forms won't be captured.
• Not matching field types. If your source table has a Multiple Choice field and your Logs table has a Short Text field for the same data, the values may not map correctly.

Next Steps

• Creating a Change Log for Records — A simpler approach that tracks who and when without capturing field values
• Building Audit Trails in Knack — Overview of all audit trail options including record history and system fields
• Using Record Actions — Learn more about automating actions on form submit