How to create upload templates

An upload template tells eCourtDate how to read your file: which column feeds which field, how a row is matched to a record you already have, and what happens to records the file leaves out. You build one template per file format and reuse it for every upload from that source.

### Overview

- **What it is:** A saved set of instructions under **Uploads** > **Upload Templates** that holds your field mapping, processing method, match fields, parsing formats, default values, and post processing settings.
- **Why it matters:** You cannot upload a file without one. Until a template exists, the **Uploads** tab shows "No upload templates found. To upload a file, create an upload template first."
- **Who it is for:** Staff in your agency who load client, event, case, or payment data from a case management system or a vendor feed.
- **Expected outcomes:** Repeatable imports where every column lands in the right field and existing records are updated instead of duplicated.

### Prerequisites

- Access to **Uploads** in the top navigation bar
- The `create_upload_templates` permission to create a template and `update_upload_templates` to change one
- A sample file in CSV, TXT, or XLSX format that matches the layout you plan to upload
- A list of which column in your file feeds which eCourtDate field

### How-To Steps

#### Step 1: Open the Upload Templates tab

1. Click **Uploads** in the top navigation bar.
2. Click the **Upload Templates** tab.
3. Review the existing templates, listed by **Name**, **Method**, **File Format**, **Fields**, **Created**, and **Creator**.

#### Step 2: Create the template

1. Enter a name in the **Name** field of the **Create Upload Template** card.
2. Click **Create**.

You land on the new template's edit page. The name is an internal label used to identify the template when uploading files, and you can change it later in the **Upload Template Name** field.

To start from a prebuilt example instead, open the **File Templates** tab and click **Import** on a sample card. eCourtDate creates a template from that sample and opens it for editing. Click **Sample** on the same card to download a CSV of that sample's column headers.

#### Step 3: Read a sample file

1. Locate the **Upload a Sample File (optional)** card on the right side of the edit page.
2. Select a CSV, TXT, or XLSX file from your computer.
3. Review the detected headers listed after **Fields**.
4. Click **Auto Map Fields** to have eCourtDate suggest a field for each header.

**Auto Map Fields** appears only after a sample file is read, and it uses AI, so the form warns that suggestions "are not deterministic, so review them before saving". You can also map one header at a time by choosing a field in the **Map to Field** dropdown under each detected header, which saves that mapping right away.

#### Step 4: Review the field mapping

1. Scroll to the **Field Mapping** card.
2. Enter your file's exact column header in the input for each eCourtDate field you want to populate.
3. Enter a field name in **Search Fields** to jump to a specific field, or click a model badge such as **Client** or **Event** to filter the list.
4. Select **Map by Column Position** if your file has no headers or the header names change between exports.
5. Click **Save** at the top of the page.

Header matching is case sensitive and must be exact. With **Map by Column Position** selected, each mapping matches the numerical position of the column instead, and the first column is 0. **Map Default Fields** pre-fills mappings using each field's standard name, and **Reset All Fields** clears every mapping. Only the fields you map here are imported, so unmapped columns in your file are ignored.

#### Step 5: Choose a processing method

1. Scroll to **Processing Settings** on the left side of the edit page.
2. Select one option in **Processing Method**:
   - **Update by Matching Fields (incremental)** for files that hold only records created or changed since the last upload. Records that are not in the file are left untouched.
   - **Full Replace: Across All Uploads** for files that are the single source of truth. Any record not in the file, whichever upload created it, may be archived.
   - **Full Replace: This Template Only** for files that own one slice of your data. Records created by other templates are left alone.
3. Select **Load and Replace Clients**, **Load and Replace Contacts**, or **Load and Replace Cases** to choose which record types are archived when they are missing from the file.

The three checkboxes appear only when you pick one of the **Full Replace** methods, and record types you leave unchecked are left untouched.

#### Step 6: Set the match fields

1. Scroll to **Match Existing Records**.
2. Select the fields in **Client Match Fields** that together identify one client.
3. Select the fields in **Event Match Fields**.
4. Select the fields in **Case Match Fields**.
5. Select the fields in **Payment Match Fields**, or leave it empty.
6. Select **Newest rows first (default)** or **Oldest rows first** in **Processing Order**.

These settings apply regardless of the **Processing Method** you chose. The fields you select form a composite identifier, so every one of them must match for a row to count as the same record. If they all match, that record is updated. If none match, a new record is created. Matching is case insensitive. The border color on each picker rates your selection: red is missing, yellow is weak, green is recommended. eCourtDate recommends including **Event Reference** for events and **Case Number** for cases, warns that at least one field is required to create clients, and matches payments on **Payment Reference** and **Payment Amount** together when **Payment Match Fields** is empty. **Processing Order** matters when the same record appears twice in one file, because the last processed row wins.

#### Step 7: Set the parsing formats

1. Scroll to **Parsing Formats**.
2. Select **AUTO**, **CSV**, **TXT**, or **XLSX** in **File Format**.
3. Select **Date Format**.
4. Select **Time Format**.
5. Select **comma**, **pipe**, or **tab** in **Field Delimiter**.
6. Select **Cell Separator**.

**File Format** defaults to CSV, and AUTO detects the format from the file extension. **Date Format** and **Time Format** default to automatic detection, so set them only when your file uses a format the system reads incorrectly. **Field Delimiter** splits each row into columns: use **comma** for standard CSV exports, **tab** for TSV, or **pipe** if your data may contain unquoted commas. **Cell Separator** splits multiple values inside a single cell, such as two phone numbers in one column.

#### Step 8: Set default values

1. Scroll to **Default Values**.
2. Set any of **Default Client Status**, **Default Client Group**, **Default Event Status**, **Default Location**, **Default Flow**, **Default Portal**, **Default Payment Status**, and **Default Payment Amount**.
3. Click **Save**.

Each default is a fallback used when the matching column is not mapped, when a row is blank, or when the value does not match an existing record. The status and amount defaults apply only to newly created records. **Default Flow** includes a **Random** option that assigns a flow at random for each row. **Default Portal** behaves differently from the others: it assigns every imported client and event to that portal regardless of what the file says.

#### Step 9: Configure post processing

1. Scroll to **Post Processing Settings**.
2. Enter a comma separated list of addresses in **Notify Emails**.
3. Select **Notify Assigned Users** to send an in-app notification to everyone assigned to the clients, cases, or events the upload touches.
4. Select **Auto Create Statuses** to create client, event, and payment statuses found in the file that do not exist yet.
5. Click **Save**.

The same card offers **Don't Notify New Contacts**, which creates new contacts with notifications disabled. The form marks it "(Not Recommended)" because each of those contacts then has to opt in manually.

#### Step 10: Exclude rows you do not want

1. Scroll to the **Exclude Rows (optional)** card below the settings form.
2. Select a mapped column in **Exclude Field**.
3. Select a comparison in **Exclude Operator**.
4. Enter the value to compare against in **Exclude Value**.
5. Click **Save** at the top of the page.

**Exclude Field** lists only the fields you have already mapped, so finish your field mapping first. Only one exclusion rule is supported per template, all three parts are required for it to run, and the comparison is case insensitive, so Closed, CLOSED, and closed are treated as the same value.

#### Step 11: Simulate the file

1. Click **Simulate File** at the top of the edit page.
2. Open the downloaded CSV.

**Simulate File** needs at least one mapped field. The file contains your mapped column headers with generated example rows, which makes it a useful format reference to send to whoever produces your data.

#### Step 12: Preview an upload before processing it

1. Click **Uploads** in the top navigation bar.
2. Click **Choose File** and select your data file.
3. Select your template in the **Upload Template** dropdown.
4. Select the **Preview Upload (Skip Processing)** checkbox.
5. Click **Create**.
6. Open the upload and review the row table, where each column shows the mapped field name above your file's header.
7. Click **Process Upload** to queue the file once the mapping looks right.

### What to Expect

Your template appears on the **Upload Templates** tab right away and becomes selectable in the **Upload Template** dropdown on the **Uploads** tab. A file uploaded with **Preview Upload** selected is stored with the status **skipped** and creates nothing until you click **Process Upload**, which sets the upload back to **queued**. A processed upload moves through **queued** and **processing** to **complete**, and its page shows a count tile for file rows, clients, contacts, events, cases, payments, forms, and warrants. When processing finishes, eCourtDate emails a summary of the record counts and any errors to whoever created the upload plus every address in **Notify Emails**, and it emails you if the upload fails. Changes you make to a template apply to uploads processed after the change, not to uploads that already ran.

### Best Practices

- Start with **Update by Matching Fields (incremental)** unless every file is a complete snapshot of your data, since both **Full Replace** methods can archive records that are missing from the file.
- Include a stable identifier in each match field picker, such as **Event Reference** or **Case Number**, and check that the picker border turns green.
- Select **Preview Upload** whenever a file arrives from a new source or with changed column headers.
- Name each template for its source and cadence, for example "Daily Jail Roster" or "Monthly Probation Export", because **Name** is all the **Upload Template** dropdown shows.
- Click **Duplicate** in the **Tools** menu to branch a working template rather than editing one that is already running against live data.

### Frequently Asked Questions

**Q: Which file formats can a template read?**

A: **File Format** offers **AUTO**, **CSV**, **TXT**, and **XLSX**, and the sample file picker accepts .csv, .txt, and .xlsx files. It defaults to CSV, and **AUTO** detects the format from the file extension.

**Q: What happens to columns I do not map?**

A: They are ignored. Only the fields mapped in the **Field Mapping** card are imported, so extra columns in your file are safe to leave in place.

**Q: My file has no header row. Can I still use a template?**

A: Yes. Select **Map by Column Position** in the **Field Mapping** card and enter each column's numerical position instead of a header name. The first column is 0.

**Q: What happens if I leave Payment Match Fields empty?**

A: Payments are matched on **Payment Reference** and **Payment Amount** together. Set the field only when your source system identifies a transaction some other way.

**Q: Does a preview upload create any records?**

A: No. A file uploaded with **Preview Upload** selected is stored with the status **skipped**, and nothing is created until you open the upload and click **Process Upload**.

**Q: Can my whole team use the same template?**

A: Yes. Templates belong to your agency, so everyone who can open **Uploads** sees the same list and can select any template when uploading a file.

### Troubleshooting

**Issue:** A mapped column imports as blank.

**Symptoms:** The upload completes, but fields you mapped are empty on the imported records.

**Solution:** Open the template and check the **Field Mapping** card. Header matching is case sensitive and exact, so a file header of "First Name" does not match a mapping of "first name". Read the sample file again and use **Map to Field** to set each header verbatim.

**Issue:** New records are created instead of existing ones being updated.

**Symptoms:** Every upload adds duplicates of clients, events, or cases you already have.

**Solution:** Review **Match Existing Records**. Every selected field has to match for a row to be treated as the same record, so a picker holding a value that shifts between exports creates a new record each time. Add a stable identifier such as **Event Reference** or **Case Number** and confirm the picker border turns green.

**Issue:** Records disappear after an upload.

**Symptoms:** Clients, contacts, or cases that existed before the upload are archived.

**Solution:** Check **Processing Method**. **Full Replace: Across All Uploads** and **Full Replace: This Template Only** archive records that are missing from the file whenever the matching **Load and Replace Clients**, **Load and Replace Contacts**, or **Load and Replace Cases** checkbox is selected. Switch to **Update by Matching Fields (incremental)** if your file is not a complete snapshot.

**Issue:** Fewer rows are processed than the file contains.

**Symptoms:** The file rows count is lower than the number of rows you sent.

**Solution:** Open the **Exclude Rows (optional)** card. Any row where **Exclude Field** compares true against **Exclude Value** is skipped, and the comparison ignores capitalization. Clear **Exclude Value** to switch the rule off.

### Related Articles

- [How to Upload a Flat File](/how-to-upload-a-flat-file)
- [How to Assign Organizations via Uploads](/how-to-assign-organizations-via-uploads)
- [How to manage statuses](/how-to-manage-statuses)
- [How to Manage Clients](/how-to-manage-clients)