How to Assign Organizations via Uploads

Map an **Organizations** column in your upload template and every client row in your file links itself to the organizations you name in it, so you never open a client record to attach one by hand.

### Overview

- **What it is:** **Organizations** is one of the system fields in an upload template's **Field Mapping** card. Whatever column you map to it is read as the list of organizations for the client that row creates or updates.
- **How the match works:** eCourtDate splits the cell on the template's **Cell Separator**, then matches each value against the organization's **Reference**. The organization **Name** is never used for matching.
- **Who uses it:** Staff who can open **Uploads** and **Admin** > **Settings** > **Organizations**.
- **Expected outcomes:** Clients arrive already grouped by organization, visible in the **Choose Organizations** card on each client record and in the organization badges on the **Clients** search sidebar.

### Prerequisites

- Access to **Uploads** in the top navigation bar and to **Admin** > **Settings** > **Organizations**
- An upload template that already maps the client fields your file uses
- A CSV, TXT, or XLSX file with one column holding the organization values for each row
- An organization record for every value in that column, with its **Reference** set to that value

Organizations are never created by a client upload. Any value that matches no existing organization is skipped.

### How-To Steps

#### Step 1: Confirm the Reference on each organization

1. Go to **Admin** > **Settings** > **Organizations**.
2. Read the **Reference** column to see the value each organization currently matches on.
3. Click the **Edit** button next to an organization you need to change.
4. Enter the value your file uses in **Reference**.
5. Click **Save**.

When you create an organization from the **Create Organization** card, eCourtDate fills **Reference** for you from the **Name**: lowercased, with spaces turned into hyphens and punctuation dropped. "Probation Services" becomes `probation-services`, which is what your file has to contain unless you edit **Reference** afterwards.

#### Step 2: Add an organizations column to your file

1. Add one column that holds the organization **Reference** for each row.
2. Separate multiple references inside a single cell with a comma, a pipe, or a tab.
3. Keep the client columns your template matches on in the same row, because organizations attach to the client that row produces.

A comma-delimited file with pipe-separated organizations looks like this:

```
first_name,last_name,client_id,organizations
John,Doe,10001,probation-services
Jane,Roe,10002,probation-services|legal-aid
```

#### Step 3: Map the Organizations field

1. Go to **Uploads** > **Upload Templates**.
2. Click the **Edit** button next to the template you use for this file.
3. Enter `Organizations` in the **Search Fields** box of the **Field Mapping** card.
4. Enter your file's column header in the **Organizations** field, matching the header exactly, including capitalization.
5. Click **Save**.

If the template has **Map by Column Position** checked, enter the numerical position of the column instead, counting the first column as 0.

#### Step 4: Set the Cell Separator

1. Scroll to **Parsing Formats** on the same template.
2. Select **comma**, **pipe**, or **tab** in **Cell Separator** so it matches the character that separates references inside one cell.
3. Click **Save**.

**Cell Separator** defaults to **comma** and applies to every multi-value cell in the file, not just organizations. Skip this step if each row names only one organization.

#### Step 5: Upload the file

1. Go to **Uploads**.
2. Click **Choose File** and select your file.
3. Select your template in **Upload Template**.
4. Click **Create**.

### What to Expect

The status badge moves through **QUEUED** and **PROCESSING** to **COMPLETE**. Once it completes, the count cards show how many records the upload touched. Click the **clients** card to open the clients from this upload, click the **Edit** button next to one, and check the **Choose Organizations** card on the client record. Assigned organizations are listed there, above the **Assign Organization** select.

What happens to organizations a client already had depends on the template's **Processing Method**:

- **Update by Matching Fields (incremental)** keeps existing assignments and adds the ones in the file. An organization already linked to that client is skipped, so re-running the same file never doubles up.
- **Full Replace: Across All Uploads** and **Full Replace: This Template Only** clear every organization on the client first, then apply the file, so the client ends up with exactly what the row lists.

A row with a blank organizations cell changes nothing, even under a full replace. Values that match no organization are skipped and reported as `Organization not found:` lines in the summary email sent when processing finishes, which goes to the addresses in the template's **Notify Emails** field and to whoever created the upload.

### Best Practices

- Set **Reference** yourself on every organization instead of relying on the value generated from **Name**, so your primary system's ID is what your files carry.
- Check **Preview Upload** when you create the first upload, review the mapped columns on the upload page, then click **Process Upload** once the **Organizations** column reads correctly.
- Enter an address in **Notify Emails** under **Post Processing Settings** so the `Organization not found:` lines reach someone who can fix them.
- Use the **Upload Organizations** card on the **Organizations** page to create many organizations at once from a file with **Name** and **Reference** columns.
- Leave **Reference** alone once files are running against it, because changing it breaks the match for every future upload.

### Frequently Asked Questions

**Q: Does my file need the organization Name or the Reference?**

A: The **Reference**. eCourtDate matches your column values against **Reference** only, so an organization named "Legal Aid" with a **Reference** of `legal-aid` is found by `legal-aid` and not by "Legal Aid".

**Q: Can I assign more than one organization to a client in a single row?**

A: Yes. Put every reference in the one mapped column, separated by the character selected in **Cell Separator**, which offers **comma**, **pipe**, and **tab**.

**Q: Does re-uploading the same file duplicate the assignments?**

A: No. Under **Update by Matching Fields (incremental)** an organization already linked to the client is skipped, so the client keeps one link per organization.

**Q: Does the value have to match the reference exactly?**

A: Yes, it has to be the whole reference. eCourtDate trims spaces and lowercases the value before matching, but a partial value fails: `org-a` does not find an organization whose **Reference** is `org-a-full`.

**Q: What happens if I leave the organizations cell blank for a row?**

A: That client's existing assignments stay exactly as they are, including under the two **Full Replace** methods, which only clear assignments for rows that carry a value.

### Troubleshooting

**Issue:** No organizations are assigned after the upload completes.

**Symptoms:** The upload reaches **COMPLETE** with the expected client count, but the **Choose Organizations** card on those client records is empty.

**Solution:**

1. Open the template and confirm the **Organizations** field in **Field Mapping** holds your file's exact column header, since header matching is case sensitive.
2. Compare the values in that column against the **Reference** column at **Admin** > **Settings** > **Organizations**.
3. Open the summary email and read the `Organization not found:` lines, which name every value that matched nothing.

**Issue:** A cell listing several organizations produces one assignment or none.

**Symptoms:** Clients whose row named two or more organizations end up with a single organization or an empty **Choose Organizations** card.

**Solution:**

1. Open the template and scroll to **Parsing Formats**.
2. Set **Cell Separator** to the character actually used inside the cell, because the default is **comma** and a pipe-separated cell read as one value never matches.
3. Save the template, then open the upload and click **Tools** > **Replay Upload** to process the same file again.

**Issue:** A value matches nothing even though the organization was set up.

**Symptoms:** The summary email lists `Organization not found:` for a reference you know your agency created, and that reference is missing from the **Organizations** list.

**Solution:**

1. Check **Archived** or **Trashed** in the **Search Organizations** card and click **Search**, since archived and trashed organizations are hidden from the list and excluded from the match.
2. Open the organization and click **Tools** > **Restore** to bring it back.
3. Confirm the **Reference** contains no commas or pipes, which are stripped from your file's values before matching and so can never form part of a match.

If the assignments are still wrong, click the **Help** button, then click **New support ticket**.

### Related Articles

- [How to Upload a Flat File](/how-to-upload-a-flat-file)
- [How to create upload templates](/how-to-create-upload-templates)
- [How to manage organizations](/how-to-manage-organizations)