Reference Configuration
The Complete Guide — Building and Managing Reference Lists in OnCoor
| Last updated: August 2026
Contents
- Overview
- Browsing References
- Creating a Reference
- Managing a Reference
- Versions and Deployment
- Quick Reference
1. Overview
What Reference Configuration Is
Most data work depends on small, trusted lists of values that everything else agrees on — a list of country codes, a set of order-status codes, a table of product categories. These lists don't change often, but when something does use them, it needs to use exactly the same version everyone else is using.
Reference Configuration is where you build and look after those lists in OnCoor. Each list you set up here is called a reference — a named, managed table of values that the rest of the platform can point to. Once a reference is in place, your mappings, data-quality rules, and joins can all draw on the same agreed set of values instead of each keeping its own copy.
Think of it as the single, official copy of a lookup list. You set it up once, keep it current, and everything else stays consistent because it all reads from the same place.
WHERE TO FIND IT — Reference Configuration is part of OnCoor. From the OnCoor home screen, open the Migration area and select Reference Configuration; you'll land on the List of References — your home base for everything described here. (Depending on how your organisation's menus and your permissions are set up, exactly where you launch it from may differ slightly.)
Why It Matters
Without a shared reference, the same list tends to get copied into many places, and the copies drift apart over time. One report says "USA", another says "US", a third says "United States" — and suddenly numbers don't add up. A reference solves this by giving everyone one place to look.
What you gain by managing these lists here:
- Consistency — every part of the platform that needs the list reads the same values.
- Control — changes happen in one place, on purpose, with a record of what changed.
- History — references are versioned, so you can keep a dated history and see what a list looked like at any point in time.
- Safety — before a live reference can be changed or switched off, OnCoor checks what else is using it, so nothing breaks by surprise.
Two Ways to Create a Reference
OnCoor gives you two starting points, depending on whether the data already exists in the platform.
| Path | Use it when | What happens |
|---|---|---|
| Conform Data Reference | The values already live in a "Conform Data" table in your pipeline | You point OnCoor at that existing table and promote it into a reference. Fastest — there's no structure to define, because the table already has one. |
| Custom Reference | You're building the list from scratch | A short, guided wizard walks you through defining the columns, linking the data, and creating the table. Use this when there's no existing table to start from. |
You don't have to decide the "right" one in the abstract — if the data is already in a Conform Data table, use the Conform Data path; otherwise, build a Custom Reference. Both are covered step by step in Creating a Reference.
The Life of a Reference
Every reference moves through a series of clear stages. The stage a reference is in tells you what's been done so far and what you can do next. You'll see the current stage shown as a coloured label (a "status chip") wherever the reference appears.
| Stage | What it means |
|---|---|
| Open | The reference has been started but isn't finished. It's still a draft — you can freely edit or delete it. |
| Conform Data Created | The underlying data has been prepared. (Custom references pass through this stage; Conform Data references start with it already done.) |
| DB Object Created | The actual database table behind the reference has been built and is ready to hold data. |
| Active | The reference is live. Other parts of the platform can now use it. |
| Inactive | The reference has been retired from active use. Its history is kept, but nothing new should rely on it. |
A reference generally moves forward through these stages as you complete each step. A Conform Data Reference skips the middle build steps, because its table already exists.
A NOTE ON DELETING — You can delete a reference only while it's still Open (a draft). Once it has been built and especially once it's Active, deleting is no longer offered — instead you retire it by setting it to Inactive. This protects anything that might already depend on it.
Key Words You'll See
A quick glossary so the rest of this guide reads easily.
| Term | Plain meaning |
|---|---|
| Reference | One managed lookup list, set up and maintained in this module. |
| Conform Data | Cleaned, standardised data already prepared in your pipeline. A reference can be built directly from one of these tables. |
| Column | One field in the reference table — for example, a "Code" column and a "Description" column. |
| Join | A rule that describes how this reference connects to other data, so it can be used as a lookup. |
| Version | A dated snapshot of the reference. New versions let you change a list over time while keeping the old one on record. |
| Consumer | Anything elsewhere in the platform — a mapping, a rule, a job — that uses this reference. |
| Deploy | The step that builds or updates the real database table behind the reference. |
| Domain Layer | The area of your data landscape the reference belongs to. You pick this when you create it. |
2. Browsing References
The List of References is the first screen you see in Reference Configuration and the place you'll return to most. It shows every reference that exists, what type each one is, which stage it's at, and gives you a way to act on any of them. From here you can search for a particular reference, narrow the list with filters, open a reference to work on it, create a new one, or export the whole list.
WHERE TO FIND IT — Open Reference Configuration from the OnCoor home screen (in the Migration area). The List of References is the landing screen. A navigation rail on the left keeps Browse, Create, and (once a reference is open) Manage within easy reach.
The List of References
The list is a table, with one reference per row. Each row shows you the essentials at a glance:
- Name — the name you gave the reference, with a short secondary line underneath showing helpful details such as the source table, how many columns it has, or how many joins are defined.
- Type — whether it's a Custom reference or a Conform Data reference (shown as a small badge).
- Domain Layer — the area of your data landscape the reference belongs to.
- Status — the current stage in its life, shown as a coloured label (see Reading the Status of a Reference).
At the end of each row is a set of actions for that particular reference — these change depending on the reference's stage and on your permissions (see Actions on Each Row).
Searching and Filtering
When the list grows long, three tools help you get to what you need.
Search box — start typing a name, and the list narrows to references that match.
Type filter — quick pills let you show only one kind of reference:
| Filter | Shows |
|---|---|
| Custom | References you built from scratch |
| Conform Data | References promoted from an existing Conform Data table |
Status filter — pills let you show only references at a particular stage — for example only Active ones, or only drafts still marked Open. Each pill also shows a count, so you can see at a glance how many references sit at each stage.
You can combine the search box with the filters to zero in quickly — for example, all Active references whose name contains "country".
Reading the Status of a Reference
Every reference carries a status label that tells you exactly where it is in its life. The same five stages introduced above appear here as coloured chips:
| Status | Meaning |
|---|---|
| Open | A draft — still being set up, and safe to edit or delete. |
| Conform Data Created | The underlying data has been prepared. |
| DB Object Created | The database table behind the reference has been built. |
| Active | Live and available for other parts of the platform to use. |
| Inactive | Retired from active use, with its history kept on record. |
Hovering over a status chip shows a short explanation, so you never have to remember what each one means.
Actions on Each Row
The actions offered on a row depend on how far along that reference is and on what you're allowed to do. Common actions include:
| Action | What it does |
|---|---|
| View Data | Opens the actual rows of data held in the reference (available once its table has been built). |
| Versions | Opens the history of the reference so you can see, compare, or create versions. |
| Edit / View Columns | Opens the column definitions (for Custom references). |
| Edit Joins | Opens the join rules that describe how the reference connects to other data. |
| Conform Data | Opens the Conform Data step for that reference. |
| Deploy DB Object | Builds or updates the database table behind the reference. |
| Activate / Inactivate | Turns the reference on for use, or retires it. |
| Delete | Removes the reference — offered only while it's still Open (a draft). |
| More | Opens the reference's detail page (its Overview tab), where the full set of tabs and actions lives. It's a shortcut into the reference, not a pop-up menu of extra actions. |
WHY SOME ACTIONS ARE HIDDEN — OnCoor only shows the actions that make sense for a reference's current stage, and only the ones your role permits. If you expected to see Delete but don't, the reference has probably moved past the draft (Open) stage. If an action you need is missing entirely, your user role may not include it — your administrator can help.
Seeing Past Versions
References are kept as a dated history rather than being overwritten. By default the list shows the current version of each reference. A Show history toggle reveals earlier versions alongside the current ones, so you can see how a reference has changed over time. There's much more you can do with versions — comparing two of them, or creating a new one — all covered in Versions and Deployment.
Exporting the List
An Export button lets you take the list out of OnCoor — handy for sharing, reporting, or keeping an offline record. It offers three formats: Excel (.xlsx), CSV (.csv), and JSON (.json). If Show history is turned on, earlier versions are included in the export as well.
3. Creating a Reference
Creating a reference means telling OnCoor what your lookup list contains and where its data comes from. There are two ways to do this, and OnCoor picks the right screens for you once you've chosen.
WHERE TO FIND IT — From the List of References, use the Create group in the left navigation rail, or the Add Reference action. You'll first be asked which kind of reference you want to build.
BEFORE YOU START — Creating a reference is a permission-controlled action. If you don't see a way to add one, your user role may not include it; your administrator can enable it.
Choosing How to Start
When you start a new reference, OnCoor asks how you'd like to begin. Your answer decides which path you take:
| Choose… | When | Where it goes |
|---|---|---|
| Conform Data Reference | The values already exist in a Conform Data table | A short screen to point OnCoor at that table — see Path A |
| Custom Reference | You're defining the list from scratch | A five-step wizard — see Path B |
The difference is simply whether the data already exists in a prepared table. If it does, the Conform Data path saves you from defining any structure. If it doesn't, the Custom Reference wizard helps you build everything.
Path A — Conform Data Reference
This is the quickest way to create a reference, because the hard part — a table with real, cleaned data — already exists. You're just promoting that table into a managed reference.
Steps
- Choose Conform Data Reference when asked how to start.
- Pick the Conform Data table you want to base the reference on, from the list OnCoor offers.
- Give the reference a name so people can find it later.
- Choose the Domain Layer — the area of your data landscape this reference belongs to.
- Save.
Because the table already exists, a Conform Data reference begins further along its life than a custom one — it doesn't need the middle build steps. From here you can review it and, when you're ready, make it Active so other parts of the platform can use it (see Activating and Retiring a Reference).
Path B — Custom Reference Wizard
Choose Custom Reference when there's no existing table to start from. A guided wizard takes you through five steps in order. You can move forward as each step is complete, and come back to earlier steps if you need to. The five steps are: Metadata → Columns → Conform Data → Reference Join → Deploy to DB.
Step 1: Metadata
This first step captures the basics — what the reference is called and where it belongs.
| Field | What to enter |
|---|---|
| Reference Name | A clear, recognisable name for the list. This is how it appears everywhere else, so make it meaningful. |
| Domain Layer | The area of your data landscape the reference belongs to. Pick from the list. |
| Conform Data source | The prepared data the reference will draw on. You select which Conform Data source applies. |
TIP — Choose the name carefully. It's what everyone else will look for, and it's best kept stable once other things start using the reference.
Step 2: Columns
Here you define the columns — the fields your reference table will hold. A simple code list might have just two (a code and a description); a richer reference might have several. For each column you describe:
| Setting | What it means |
|---|---|
| Name | The column's name (for example, COUNTRY_CODE). |
| Description | A short note on what the column holds, so others understand it. |
| Data type | The kind of value — text, number, date, and so on. |
| Length / Precision / Scale | How big the value can be. Length applies to text; precision and scale describe the size and decimal places of numbers. Fill in only what applies to the chosen data type. |
| Nullable | Whether the column is allowed to be left empty. |
| Primary key | Whether this column (or columns) uniquely identifies each row — the value that makes each entry distinct, such as the code itself. |
| Business attribute link | An optional link tying the column to a defined business attribute, so it connects to your wider data definitions. |
Add a row for each column you need. The columns you define here become the shape of the actual table built in the final step.
Step 3: Conform Data
Step 3: Conform Data
This step turns the columns you just defined into OnCoor's shared Conform Data definitions — the metadata the reference and any downstream mappings rely on. It's a single, guided action rather than a form to fill in.
The screen (Create Conform Data layer) summarises what it's about to do: how many Columns and Primary Keys you've defined, and how many are newly added in this version. A preview table lists each column with its type, whether it's a primary key, whether it's included in this version, and its linked Business Attribute, so you can check everything before committing.
When you're ready, click Create Conform Data. OnCoor then creates the business-attribute metadata for any columns that don't have it yet, plus a Conform Data record with your columns linked to it. No data rows are loaded at this stage — this builds the definitions the table will use.
Before you can run it, two things must be in place (both set on Step 2 · Columns): at least one primary key, and a Business Attribute on every column. If either is missing, OnCoor shows a short checklist of what to finish first and keeps the button disabled until it's done.
IF YOU CHANGE COLUMNS LATER — If you add columns after the Conform Data has been created, a Sync new columns option appears so you can bring the new ones across without starting over. Once this step is complete, use Continue to Joins to move on.
Step 4: Reference Join
A join describes how this reference connects to other data — the rule that lets it act as a lookup. For example, "match this reference's COUNTRY_CODE column to the country code in another table." For each join you set:
| Setting | What it means |
|---|---|
| Key column | The column in this reference used to make the match. |
| Operator / condition | How the match is made (for example, an exact match). |
| Effective-dated | Whether the join should respect effective dates — useful when values are only valid for certain periods. |
Joins are optional depending on how the reference will be used, but defining them here means the reference is ready to plug into your mappings and rules straight away.
Step 5: Deploy to DB
The final step builds the real database table behind your reference from everything you've defined. Until this happens, the reference exists as a design; deploying makes it a physical table that can hold and serve data. OnCoor lets you preview what it's about to build before it does anything, so you can check it first. When you're happy, you confirm and OnCoor creates the table. This deployment step — including previewing, and rolling back if needed — is covered in full in Deploying the Database Table.
NO SURPRISES — Deployment always offers a preview before making changes, and keeps a record of what it did. You're never forced to build blind.
What Happens After You Finish
Once created, your reference appears in the List of References at whatever stage it has reached. A Custom reference that has been through all five steps will have its table built and be ready to make Active; a Conform Data reference is ready sooner. Making a reference Active is what opens it up for the rest of the platform to use. You can also keep refining it — adjusting columns, joins, or data — through its detail tabs, described in Managing a Reference.
4. Managing a Reference
Once a reference exists, you manage everything about it from its own detail page. The page is organised into tabs, each covering one part of the reference — its summary, its columns, its joins, its source data, and the actual rows it holds.
WHERE TO FIND IT — Click a reference in the List of References to open it. The tabs run across the detail page; the Manage group in the left navigation rail lists the same sections and appears once a reference is open.
WHAT YOU CAN CHANGE — Which edits are available depends on the reference's stage and your permissions. A draft (Open) reference can be changed freely; a live (Active) one is protected, and bigger changes are made by creating a new version (see Working With Versions).
Opening a Reference
Selecting a reference from the list opens its detail page. Along the top you'll see the tabs that make up the reference:
- Overview — the summary and key facts.
- Columns — the fields the reference holds (for Custom references).
- Joins — how the reference connects to other data.
- Conform Data — the prepared data behind the reference.
- Versions — the reference's dated history (covered in Versions and Deployment).
- DB Object / Deploy — building and updating the physical table (also in Versions and Deployment).
- Reference Data — the actual rows of data.
Not every tab is meaningful for every reference — for example, a Conform Data reference has less to define by hand than a Custom one — so some tabs simply show that there's nothing to set up.
The Overview Tab
The Overview tab is the reference's summary at a glance. It gathers the key facts in one place so you can understand a reference without digging through the other tabs. Typically it shows the reference's name and type (Custom or Conform Data); its current status; its scope and Domain Layer; the table and schema names behind it; counts of how many columns, joins, and versions it has; and an audit trail of who created or last changed the reference, and when. It's the natural first stop whenever you open a reference: a quick health check before you drill into any one area.
The Columns Tab
For a Custom reference, the Columns tab is where you review and adjust the fields the reference holds. Each column shows its name, description, data type and size, whether it can be empty, whether it's part of the primary key, and any link to a business attribute — the same details you set when the reference was created (see Step 2: Columns). From here you can refine the column set as the reference's needs change. Because columns define the shape of the underlying table, changes to them may need to be carried through to the database — which is where deployment and versioning come in.
NOTE — Conform Data references take their structure from the existing table, so there's little to edit by hand here for that type.
The Joins Tab
The Joins tab holds the rules that describe how the reference connects to other data — the rules that let it act as a lookup. Each join shows the key column it matches on, the condition used to match, and whether it respects effective dates. Here you can review the existing joins and add or adjust them as the way the reference is used evolves. Getting the joins right is what makes the reference easy to plug into your mappings and data-quality rules.
The Conform Data Tab
The Conform Data tab connects the reference to the prepared, cleaned data that fills it. It's where you confirm or revisit which Conform Data source the reference draws on and how that source lines up with the reference's columns. This is the same connection first set up when the reference was created; the tab lets you check it and change it later if the source changes.
The Reference Data Tab
The Reference Data tab shows the actual rows held in the reference — the real values, not just the definition. This is what other parts of the platform see when they use the reference. Because there's no data to show until the reference's table has been built, this tab becomes available once the reference reaches the DB Object Created stage. Before that, it will let you know the table isn't ready yet. Use this tab to spot-check that the reference holds what you expect — the right codes, the right descriptions, nothing missing or out of place.
5. Versions and Deployment
This part covers what keeps your lists trustworthy over time: keeping a dated history of changes, building and updating the real database table safely, and retiring a reference without breaking anything that relies on it. Both live on a reference's detail page — the Versions tab for history, and the DB Object / Deploy tab for building the table.
Why References Have Versions
Reference lists change — a new status code is added, an old category is retired, a description is corrected. But other parts of the platform may be relying on the list exactly as it is today. Overwriting it could quietly change results elsewhere.
Versions solve this. Instead of overwriting a reference, OnCoor keeps each state as a dated version. Each version carries an effective date (when this version starts to apply), an expiry date (when it stops applying, if set), a status (whether the version is Active or Inactive), and a link back to the previous version, so the full history stays connected. The result is a clear, dated trail: you can always see what a reference looked like at any point, and why it changed.
Working With Versions
The Versions tab shows the reference's history as a timeline, newest to oldest. From here you can:
- See every version, each with its effective and expiry dates and whether it's active.
- Create a new version when you need to make changes while keeping the current one on record. Use this rather than editing a live reference in place — the old version stays intact for anything still relying on it.
- Compare two versions to see exactly what changed (see the next section).
Deleting a version works a little differently — it isn't done from the Versions tab. A version can only be deleted while it's still a draft (Open), using the Delete action on that reference's row in the List of References. Once a version is Active or Inactive it can't be deleted — you retire it instead (see Activating and Retiring a Reference). Note that deleting the only version of a reference removes the whole reference along with it.
WHEN TO MAKE A NEW VERSION — Any time you need to change a reference that's already Active and in use. Creating a version lets the change take effect from a date you choose, while the previous version remains available for the period it covered.
Comparing Two Versions
When you're not sure what changed between two versions — or you want to double-check before making a new one live — OnCoor can compare them for you. Pick two versions and it shows the differences at the column and join level: what was added, what was removed, and what was altered. This makes reviews quick and safe: you can see the exact impact of a change laid out plainly, rather than reading two full definitions side by side and spotting differences by eye.
Deploying the Database Table
Behind every reference is a real database table — the thing that actually holds the rows. Deploying is the step that builds that table, or updates it when the reference's design changes. You'll find it on the DB Object / Deploy tab. You deploy when you've finished designing a new Custom reference and need its table built for the first time, or when you've changed a reference's columns and need those changes carried through to the table. OnCoor handles the technical work of creating or altering the table for you. Your job is to review what it's about to do and confirm it — which the next section explains.
Previewing, Approving, and Rolling Back
Building or changing a database table is a significant step, so OnCoor surrounds it with safeguards. You're never asked to make changes blind.
Preview first. Before anything is built, OnCoor shows you a preview of exactly what it intends to do. You can read it over and only continue once you're satisfied.
Approve bigger changes. Some changes are more sensitive than others — for example, removing a column or rebuilding a table, which could affect existing data. For these, OnCoor asks for an explicit approval before it will proceed, so a significant change can't happen by accident.
A record is kept. Every deployment is logged, so there's always a record of what was done and when.
Roll back if needed. If a deployment doesn't go the way you expected, OnCoor can roll it back — undoing the change and returning the table to how it was. Older backups are tidied up automatically over time so things don't pile up.
THE GOLDEN RULE — Preview, then confirm. For sensitive changes, OnCoor will also ask you to approve explicitly. If something's wrong, roll it back. Nothing here is a one-way door taken without warning.
Activating and Retiring a Reference
A reference only becomes usable by the rest of the platform once it's made Active. Activating tells OnCoor the reference is ready and trustworthy for others to rely on. When a reference has served its purpose, you don't delete it — you retire it by setting it to Inactive. This keeps its history on record while signalling that nothing new should use it. (Deleting is only ever offered for drafts still at the Open stage, precisely because a live reference may have things depending on it.) Activating and retiring are done from the reference's row actions or its detail page, and — like creating and deleting — are controlled by your permissions.
Checking Consumers First
Before you retire (inactivate) a live reference or version, OnCoor checks what's actually using it. Anything that relies on the reference is called a consumer — typically things like mappings, data-quality rules, and jobs elsewhere in the platform. If consumers exist, OnCoor shows you the list so you can see what would be affected. This is your chance to update or redirect those consumers first, rather than discovering a broken dependency after the fact.
WHY THIS MATTERS — A reference is only valuable because other things trust it. The consumers check makes sure retiring or changing one is a deliberate, informed decision — never a surprise that quietly breaks a report or a rule downstream.
6. Quick Reference
A fast lookup for the most common actions across the module.
| I want to… | Do this |
|---|---|
| Find a specific reference | Type its name in the search box on the List of References |
| See only live references | Click the Active status filter |
| See only custom-built references | Click the Custom type filter |
| Check how far along a reference is | Read its status chip (hover for an explanation) |
| See earlier versions in the list | Turn on Show history |
| Take the list out of OnCoor | Use Export |
| Turn an existing prepared table into a reference | Create → Conform Data Reference → pick the table → name it → choose Domain Layer → Save |
| Build a list from scratch | Create → Custom Reference → follow the five-step wizard |
| Define what fields my reference holds | Custom wizard, Columns step (or the Columns tab later) |
| Connect my reference so it can be used as a lookup | Custom wizard, Reference Join step (or the Joins tab later) |
| Turn my design into a real table | Deploy it — preview first, then confirm |
| Check what a deploy will do before it runs | Use the preview offered in the Deploy step |
| Undo a deployment that went wrong | DB Object / Deploy tab → roll back |
| Look at the real rows of data | Reference Data tab (once the table is built) |
| Change a live reference safely | Versions tab → Create New Version (keeps the old one) |
| See what changed between two versions | Versions tab → compare two versions |
| Make a reference usable by the platform | Activate it |
| Retire a reference no longer needed | Inactivate it (Delete is only for drafts) |
| Delete a draft I no longer want | Use Delete — only shown while status is Open |
| See what's using a reference before retiring it | Check the consumers list OnCoor shows you |
Source: OnCoor Reference Configuration product documentation, written for end users. For the latest screens and options, always refer to the in-app interface.