Custom Fields

The Custom Fields system allows tenants to define dynamic data attributes, complex validation rules, and computed values on any entity — without database schema migrations. Fields are defined per-tenant per-entity-type and stored as JSONB on entity rows.

Architecture

1. Shared Package (packages/custom-fields)

Platform-agnostic logic that runs on both Node.js and browser:

2. API Plugin (plugins/custom-fields.ts)

A Fastify plugin that decorates every request with request.customFields, providing 4 methods:

Plugin dependencies: redis-plugin, licenses-plugin.

3. API Module (modules/custom-fields/)

CRUD for field definitions themselves. Repository, service with Redis caching, routes with RBAC.

4. Filter Utility (utils/custom-fields-filter.ts)

Converts parsed filters into Prisma-compatible customFields: { path: [...], ... } JSONB queries with AND composition.

Plugin Context

The plugin automatically builds a RuleContext from the request, available to all rules and formulas:

{
  entity: { ...requestBody },        // The form data being submitted
  user: {                             // From request.user (if authenticated)
    id, name, email, role, branchId
  },
  organization: {                     // From license cache
    id, slug, companyName, companyAbbreviation,
    modules, accountingType, customFields
  },
  timestamp: new Date(),              // Current time
  ...additionalContext                // Module-provided (customer, product, etc.)
}

Modules can pass additional context (e.g., a customer record, branch data) that becomes available in rules and formulas.

Module Integration Pattern

Custom fields are used in 8 modules across the codebase (access-control, organization, crm, ledger, financial-config, product-rules, reference-data, licenses). The integration follows a consistent 3-point pattern:

CREATE — request.customFields.process()

// 1. Process custom fields (evaluate defaults, validate)
const { customFields } = await request.customFields.process("Role", body);

// 2. Pass merged customFields to service
const role = await service.createRole(tenantId, { ...body, customFields });

The process() method:

1. Fetches active field definitions for the tenant + entity type
2. Builds context from request (user, organization, entity data, timestamp)
3. Evaluates defaults (static → rule-based → computed, with multi-pass for dependencies)
4. Merges: user-provided values override defaults
5. Validates all fields against definitions + context
6. Returns { customFields, definitions }

UPDATE — request.customFields.validate()

// Only validate if customFields are being updated
if (body.customFields) {
  await request.customFields.validate(
    "Role",
    body.customFields as Record<string, unknown>,
    body,
  );
}

const { original, updated } = await service.updateRole(tenantId, id, body);

No default evaluation on update — existing values are preserved.

LIST — request.customFields.parseFilters()

// Separate custom field filters from standard query params
const { standardQuery, customFieldsWhere } = request.customFields.parseFilters(
  request.query as Record<string, unknown>,
  ["name", "slug", "status"],  // Standard entity fields
);

// Pass both to repository
const result = await service.listRoles(tenantId, standardQuery, customFieldsWhere);

The filter parser uses __ (double underscore) operator syntax in query strings:

GET /api/v1/roles?name=Admin&tax_id__contains=ABC&priority__gte=5

• name=Admin → standard field (exact match)
• tax_id__contains=ABC → custom field filter
• priority__gte=5 → custom field filter

Data Model

Table: remoteEaze_custom_field_definitions

Core Fields

Strategy and Logic

Validation

UI and Meta

Constraints and Indexes

@@unique([tenantId, entityType, fieldKey])  // One definition per key per entity per tenant
@@index([tenantId, entityType])             // Efficient lookup for field lists
@@map("remoteEaze_custom_field_definitions")

Enums

CustomFieldType: STRING | NUMBER | BOOLEAN | DATE | COMPUTED | JSON | SELECT

DefaultStrategy: STATIC | RULE_BASED | COMPUTED

JSON Data Structures

Validation Rules (validation)

{
  "min": 10,
  "max": 1000,
  "minLength": 5,
  "maxLength": 50,
  "pattern": "^[A-Z]+$",
  "enum": ["USD", "EUR", "KES"],
  "minDate": "2023-01-01",
  "maxDate": "2025-12-31"
}

UI Configuration (uiConfig)

{
  "placeholder": "Enter amount...",
  "hidden": false,
  "readOnly": true,
  "options": [
    { "label": "Savings", "value": "SAVINGS" },
    { "label": "Current", "value": "CURRENT" }
  ]
}

The Rule Object

Used in defaultRules (default value logic) and validationRules (conditional validation). Rules are sorted by priority (higher runs first); first match wins.

{
  "name": "High Value Transaction Check",
  "priority": 10,
  "when": {
    "operator": "AND",
    "conditions": [
      { "field": "entity.amount", "operator": "greaterThan", "value": 10000 },
      { "field": "customer.tier", "operator": "equals", "value": "GOLD" }
    ]
  },
  "then": {
    "required": true,
    "defaultValue": "PENDING_APPROVAL"
  },
  "else": {
    "required": false,
    "defaultValue": "AUTO_APPROVED"
  }
}

The then and else blocks can set:

• required — override the field's isRequired flag
• defaultValue — provide a contextual default
• validation — override or extend validation rules

Rule Engine

Condition Operators

Logical Operators

Condition groups support AND (all must match) and OR (any must match).

Field Path Resolution

Conditions use dot notation to access context: entity.amount, customer.country, user.role, organization.modules.

Formula Engine

Used for computedFormula on fields with defaultStrategy: "computed". Executes via new Function() with a sandboxed scope (no eval).

Available Context

entity, customer, user, organization — same context as rule engine.

Built-in Functions

Examples:

round(entity.amount * 0.16, 2)
entity.subtotal + entity.tax
customer.vip_status === 'Gold' ? 0.2 : 0.1

Multi-Pass Evaluation

Computed fields that depend on other computed fields are resolved via multi-pass evaluation (up to 5 passes, like Excel recalculation). Non-computed defaults are evaluated first, then computed fields iterate until values stabilize.

Validation

The validator handles each field type:

Validation merges static rules (validation field) with rule-based conditional rules (validationRules). Rule-based results override static rules when matched.

Query Filter Operators

For filtering entities by custom field values in LIST endpoints:

API Endpoints

The custom fields definition CRUD is registered under /api/v1/custom-fields (prefix applied by parent scope). All routes require authentication and custom_field_definition entity permissions.

Schema Validation

Create/update schemas enforce business rules via Zod refinements:

• Computed fields require a computedFormula
• Rule-based strategy requires defaultRules array with at least one rule
• Select fields require uiConfig.options with at least one option
• Update schema makes all fields optional and prevents changing entityType and fieldKey (immutable after creation)

Redis Caching

• Key pattern: custom-fields:{tenantId}:{entityType}
• TTL: 1 hour (3600 seconds)
• Read-through: Request → Redis → DB → Redis → Response
• Invalidation: Cache cleared immediately on create, update, or delete

Client Layer (PWA)