> For the complete documentation index, see [llms.txt](https://docs.rubica.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rubica.au/households/revenue/setting-up-an-institution-config.md).

# Setting Up an Institution Config

Before you can process revenue files from a new institution, you need to tell rubica how to read them — which columns map to which fields, how dates are formatted, and how to identify the file. You do this once per institution; every upload after that is automatic.

**Where to find this:** Revenue page → **Config** tab.

### Steps

#### 1. Upload a sample file from the institution

Drag a CSV, Excel, or PDF file onto the upload area — or click **Paste column headers instead** if you only have the header row as text.

The file is used to detect the column structure. It doesn't need to contain real client data — a single-row header-only file works.

> Excel and PDF files are automatically converted to CSV via the Workato extraction service. This can take a few seconds.

#### 2. Add the institution

Add the Institution name and Internal Code for your reference.

#### 3. Set the filename pattern

Enter a short string that will always appear in filenames from this institution — e.g. `NEOS Life` or `BT Panorama`.

When a file is uploaded later, this is the first thing checked. Keep it specific enough to avoid false matches but not so specific that different report types won't match.

> If the filename pattern can't reliably identify the file (e.g. the institution names files generically), leave it blank and rely on the Header Row Identifier instead.

#### 4. Set the header row identifier

Enter a word or phrase that appears in the row containing the column headers — typically the name of a key column like `Account Number` or `Client Ref`.

The preview table below updates in real time as you type — a green status indicator confirms the row was found in your uploaded file.

> **Has metadata preamble?** Enable this if the file has summary rows above the column headers (common in BT Panorama exports). When enabled, the parser skips everything before the identified header row.

#### 5. Set the date format

Choose how dates appear in this institution's files:

| Format                             | Example    |
| ---------------------------------- | ---------- |
| `DD/MM/YYYY` — Australian standard | 30/04/2026 |
| `YYYY-MM-DD` — ISO format          | 2026-04-30 |

***

#### 6. Map columns to standard fields

Each column detected from your uploaded file appears as a row. Use the dropdown on each row to assign it to a standard Rubica field, or leave it as **— Ignore —** if the column isn't needed.

Two fields are required:

* **Account Ref ★** — the client identifier used to match to a Salesforce account
* **Amount Incl GST ★** — the revenue amount

Map as many columns as the file contains — the more context captured (adviser name, product, description), the more useful each revenue record will be.

#### 7. Map revenue types *(if applicable)*

If you mapped a **Revenue Type** column in the previous step, a second mapping panel appears showing the distinct values found in your file. Assign each one to a standard category (Trail, Upfront, Insurance, etc.).

These mappings are saved to the config so future uploads categorise automatically.

#### 8. Save and deploy

Click **Save**. The config is deployed as a Custom Metadata record — Salesforce runs this asynchronously, so a deploying state will show for roughly 20–40 seconds.

Once the confirmation appears, the institution is ready to use in the Upload tab.

> If it times out and you don't see the confirmation, wait a minute and try uploading the file anyway — the deployment likely completed in the background.

***

### Field reference

| Field                 | Purpose                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Account Ref ★         | The column containing the client or account identifier. Used to match rows to Salesforce Financial Account or Contact records. |
| Account Name          | Client name — used as a hint when exact ref matching fails.                                                                    |
| Adviser ID / Name     | Links the revenue row to an adviser. Used for reporting splits.                                                                |
| Amount Incl GST ★     | Primary revenue amount. Required for record creation.                                                                          |
| Amount Excl GST / GST | Stored alongside the total for breakdowns. Optional.                                                                           |
| Revenue Date          | Date the revenue applies to. Falls back to Bank Deposit Date if blank.                                                         |
| Bank Deposit Date     | Date money was deposited. Can be supplied at upload time if not in the file.                                                   |
| Revenue Type          | Category column — Trail, Upfront, etc. Triggers the type mapping step.                                                         |
| Product / Description | Informational fields stored on the revenue record.                                                                             |
| Financial Account Ref | Used by the financial account lookup strategy when Account Ref alone isn't enough.                                             |
| Insurance Policy Ref  | Links the row to an Insurance Policy record.                                                                                   |

### Editing an existing config

To update an existing config — add a new revenue type mapping, fix a column assignment, or change the filename pattern:

1. Go to the **Config** tab on the Revenue page
2. Select the institution from the dropdown — the existing config loads automatically
3. Make your changes
4. Click **Save** — this deploys a new version of the metadata record, overwriting the previous one

> **New revenue type values appearing in a file?** Upload the new file in the Config tab (not the Upload tab). The onboarding component will detect the existing config, show the current mappings, and let you add the new values before saving.