Reference Data (Master Data)
Reference data — also called master data — is the set of pre-defined, slowly-changing lookup values that the rest of Vruksha ERP draws on. Locations, stock categories, amenities, status labels, document types, and the like are not transactions in their own right; they are the building blocks that every transaction (a stock purchase, a subproject, a unit, a document upload) selects from.
Getting master data right is the single most important thing you can do before going live, because almost every other module depends on it. If a salesperson cannot pick a village when creating a stock record, it is because no village was configured. If a project manager cannot tag a unit as "Booked", it is because that status label was never added. Configure master data first, in the correct dependency order, and the rest of the system falls into place.
Where to find it: the Masters section of the main navigation.
:::tip Set up master data before anything else Master data is foundational. We strongly recommend completing the entire Masters section — in the dependency order shown below — before you create your first partner, project, stock, or unit. Skipping ahead leads to half-filled forms and rework. :::
Why order matters
Master entities are not independent. Many of them reference another master, and a few transactional modules reference master data directly. You cannot create a record until everything it points to already exists:
- Locations must exist before you can place a project, subproject, or stock on the map.
- Stock categories must exist before stock subcategories, and both must exist before you create stocks.
- Subproject types must exist before subprojects, and before unit types (which map to subproject types).
- Unit types must exist before you create units.
- Document types must exist before you classify an uploaded document.
- Status labels and usage tags should exist before you start moving records through their lifecycles.
The diagram below shows the recommended setup order. Solid arrows mean "must exist before".
Dotted arrows show masters (status, usage tags) that records consume throughout their lifecycle rather than at creation time.
The master entities at a glance
| Master | What it defines | Has custom fields? | Configure before |
|---|---|---|---|
| Locations | Geographic hierarchy down to the sub-registration office | No | Projects, subprojects, stocks |
| Stock Categories | Top-level stock classification | Yes | Stock subcategories, stocks |
| Stock Subcategories | Second-level stock classification | Yes | Stocks |
| Subproject Types | Type of subproject (Layout, Apartment, Villa…) | Yes | Subprojects, unit types |
| Unit Types | Type of saleable unit, mapped to subproject types | Yes | Units |
| Amenities | Reusable amenity definitions for subprojects and SVG layouts | Yes | Subprojects |
| Status Master | Configurable status labels per entity family | No | Lifecycle transitions |
| Document Types | Classification of uploaded documents | Yes | Documents |
| Usage Tags | Lifecycle tags (Planned / Active / Historical) | No | Stocks, parties |
:::note Multi-tenant scoping Every master record belongs to your organization. You only ever see and edit your own organization's master data; nothing is shared across tenants. :::
The Custom Fields system
Several masters let you attach custom fields so you can capture organization-specific attributes without waiting for a software change. A stock category for agricultural land might need a "Soil Type" field; a document type for a sale deed might need an "Expiry Date" field. You define these once, on the master, and every record created under that master then prompts for them.
How custom field values are stored
When a record (a stock, a subproject, a unit, a document) is saved, the values entered for its custom fields are stored together as a JSONB array of objects, each object pairing a field_name with its value:
{
"custom_field_values": [
{ "field_name": "Survey Number", "value": "SF-245/2A" },
{ "field_name": "Soil Type", "value": "Black Soil" },
{ "field_name": "Water Available", "value": true }
]
}
This flexible structure is why custom fields can be added or retired without database migrations.
Supported field types
When you define a custom field on a master, you pick one of six types. The type controls how the field is rendered and validated on the data-entry form:
| Field type | Captures | Notes |
|---|---|---|
| TEXT | A single line of text | Names, reference numbers |
| TEXT_AREA | Multiple lines of text | Descriptions, notes |
| NUMBER | A numeric value | Areas, counts, amounts |
| DATE | A calendar date | Validity dates, milestones |
| DROPDOWN | One choice from a fixed list | You must supply the list of options (minimum two values) |
| BOOLEAN | A yes/no toggle | Flags such as "Water Available" |
Custom field rules
These rules are enforced consistently wherever custom fields appear:
- Field name and type are mandatory when defining a field.
- A stable field key is generated automatically from the field name (lowercase with underscores) and never changes.
- DROPDOWN fields require their options to be configured (at least two; duplicates are removed).
- A field's type cannot be changed after it is created — existing records may already rely on it. Retire the field and add a new one instead.
- Fields can be marked mandatory so the data-entry form refuses to save without a value.
- Removing a field is a soft delete / inactivation — historical values are preserved, the field just stops appearing on new entry forms.
:::tip Plan your custom fields up front
Because field types are immutable, it pays to think through what you need before you start. Adding a field later is easy; changing a TEXT field into a DROPDOWN is not — you have to retire the old one and re-key existing data.
:::
The masters that support custom fields are: Stock Categories, Stock Subcategories, Subproject Types, Unit Types, Amenities, and Document Types. (Records created from them — Stocks, Subprojects, Units, Documents — are where the values are captured.)
Rules common to all masters
Behaviour is deliberately consistent across the masters so admins only have to learn it once:
- Soft delete. Deleting a master never removes the row outright; it sets a
deleted_attimestamp and hides the record from lists. This keeps historical references intact. - Safe-delete / reference guard. You cannot delete a master that is in use. The system checks for references first and blocks the delete with a clear message — typically suggesting you deactivate instead. For example, a stock category used by existing stocks cannot be deleted.
- Active / Inactive (or Archived). Most masters carry a status. Inactive records stay visible on existing data but disappear from the pickers used to create new records. Some masters (such as stock subcategories) add an Archived state that is hidden by default.
- Case-insensitive uniqueness. Names and codes must be unique within their scope, ignoring case and surrounding whitespace — "Active", " active ", and "ACTIVE" are treated as the same value.
- Validation on submit. Forms validate when you press Save (not while typing), show inline field errors, and jump focus to the first invalid field.
- Auditability. Every create, edit, delete, and status change is recorded in the audit log with who did it and when.
Suggested setup checklist
- Locations — build the country/state/district hierarchy down to the levels you transact in. See Locations.
- Usage Tags and Status Master — confirm the lifecycle labels you need. See Usage Tags and Status Master.
- Document Types — define how uploaded files are classified. See Document Types.
- Stock Categories → Subcategories — set up your stock classification tree with its custom fields. See Categories & Types.
- Subproject Types → Unit Types — define the project structure masters. See Categories & Types.
- Amenities — define the amenities you will map onto subprojects and SVG layouts. See Amenities.
Once these are in place, your team can move on to creating partners, projects, stocks, and units with every dropdown already populated.