> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Customization Model

> Understanding SYSTEM_FIXED, TEMPLATED_OVERRIDE, and TENANT_DEFINED configuration patterns

# Customization Model

Better Data SCM uses a three-tier customization model that balances system stability with tenant flexibility. Understanding this model helps you configure your organization effectively.

## Configuration Tiers

### SYSTEM\_FIXED

**Definition**: Core system values that cannot be changed by tenants.

**Characteristics:**

* Fixed by the platform
* Used in core business logic
* Required for system operation
* Examples: Workflow states, RBAC scopes, billing tiers

**Examples:**

* `ShipmentStatus`: DRAFT, CREATED, PENDING, SHIPPED, RECEIVED, etc.
* `RoleScope`: SYSTEM, TENANT, LOCATION
* `PlanTier`: FREE, PRO, ENTERPRISE
* `AuditAction`: CREATE, UPDATE, DELETE, APPROVE, REJECT

**Why Fixed:**

* Used in branching logic throughout the codebase
* Required for audit trails and compliance
* Core to system functionality
* Changing would break system behavior

**What You Can Do:**

* Use these values as-is
* Understand their meaning and usage
* Work within the constraints they provide

### TEMPLATED\_OVERRIDE (Pack Defaults + Tenant Override)

**Definition**: Industry pack provides defaults, but tenants can override or extend.

**Characteristics:**

* Pack-specific defaults seeded from industry packs
* Tenants can override pack defaults
* Tenants can add custom values (where supported)
* Examples: Location types, reason codes, payment terms

**How It Works:**

1. **Pack Defaults**: Industry pack seeds default values
   * Healthcare pack: Location types (CENTRAL\_STORE, WARD, PHARMACY)
   * Retail pack: Location types (STORE\_FRONT, BACKROOM, MFC)
   * Manufacturing pack: Location types (COMPONENT\_STORE, ASSEMBLY\_CELL)

2. **Tenant Override**: You can override pack defaults
   * Modify existing pack defaults
   * Add custom values (where "CUSTOM" or "OTHER" exists)
   * Create tenant-specific configurations

3. **Template Models**: Many configurations use template + tenant pattern
   * `PaymentTermTemplateSimple` (pack) → `PaymentTermSimple` (tenant)
   * `LocationTypeTemplate` (pack) → `LocationType` (tenant)
   * `BudgetCodeTemplate` (pack) → `BudgetCode` (tenant)

**Examples:**

* **Location Types**: Pack provides defaults (CENTRAL\_STORE, WARD), you can add custom types
* **Payment Terms**: Pack provides defaults (NET\_30, NET\_60), you can add custom terms
* **Reason Codes**: Pack provides defaults (SHRINK, DAMAGE), you can add custom codes
* **GL Accounts**: Pack provides templates, you create tenant-specific accounts

**Safe Customization:**

* ✅ Override pack defaults with tenant-specific values
* ✅ Add custom values where "CUSTOM" or "OTHER" exists
* ✅ Modify template-based configurations
* ❌ Don't delete pack defaults (they may be required)
* ❌ Don't change core enum values (use custom values instead)

### TENANT\_DEFINED (Reference Data)

**Definition**: No system defaults; tenants define all values.

**Characteristics:**

* No pack defaults provided
* Tenant creates all values from scratch
* Fully tenant-scoped
* Examples: Budget codes, GL accounts, custom attributes

**Examples:**

* **Budget Codes**: You define all budget codes
* **GL Accounts**: You define all GL accounts
* **Custom Attributes**: You define all product attributes
* **Tags**: You define all tags
* **Categories**: You define all categories

**How It Works:**

1. No system defaults exist
2. You create all values
3. Values are scoped to your organization
4. You have full control

## Understanding Templates

### Template Pattern

Many configurations use a template pattern:

**Template (Pack Level):**

* Defined in industry pack
* Provides defaults for all tenants using that pack
* Examples: `PaymentTermTemplateSimple`, `LocationTypeTemplate`

**Tenant Instance:**

* Created from template or custom
* Overrides template defaults
* Tenant-specific values
* Examples: `PaymentTermSimple`, `LocationType`

### How Templates Work

1. **Pack Seeding**: Industry pack seeds templates
   ```typescript theme={null}
   // Pack provides template
   PaymentTermTemplateSimple {
     code: "NET_30",
     name: "Net 30 Days",
     days: 30
   }
   ```

2. **Tenant Override**: Tenant can use template or override
   ```typescript theme={null}
   // Tenant uses template as-is
   PaymentTermSimple {
     templateId: "template_123",
     // Uses template defaults
   }

   // Tenant overrides template
   PaymentTermSimple {
     templateId: "template_123",
     days: 45, // Override: changed from 30 to 45
   }

   // Tenant creates custom (no template)
   PaymentTermSimple {
     code: "CUSTOM_TERM",
     name: "Custom Payment Term",
     days: 60
   }
   ```

3. **Resolution**: System resolves template + override
   * Checks tenant override first
   * Falls back to template default
   * Uses system default if neither exists

### Safe Customization Guidelines

**✅ Safe to Do:**

* Override template defaults with tenant-specific values
* Add custom values where supported
* Modify tenant-specific configurations
* Create new tenant-defined values

**❌ Avoid:**

* Deleting pack templates (may break functionality)
* Changing SYSTEM\_FIXED values (not possible, but don't try)
* Modifying templates directly (modify tenant instances instead)
* Creating conflicting values

## Configuration Map

See [Configuration Map](/govern/configuration-map) for a complete index of all configuration areas and their customization tiers.

## Common Patterns

### Pattern 1: Enum with "CUSTOM" or "OTHER"

Many enums include a "CUSTOM" or "OTHER" value:

```typescript theme={null}
enum IdentifierType {
  GTIN,
  UPC,
  EAN,
  CUSTOM // ← Allows custom identifier types
}
```

**Usage:**

* Use standard values for common cases
* Use CUSTOM for tenant-specific needs
* System handles both uniformly

### Pattern 2: Template + Tenant Model

Template provides defaults, tenant overrides:

```typescript theme={null}
// Template (pack)
PaymentTermTemplateSimple {
  code: "NET_30",
  name: "Net 30 Days"
}

// Tenant instance
PaymentTermSimple {
  templateId: "template_123",
  // Can override template values
  days: 45 // Override
}
```

### Pattern 3: Tenant-Scoped Reference Data

No templates, tenant defines all:

```typescript theme={null}
// No templates, tenant creates all
BudgetCode {
  organizationId: "org_123",
  code: "BUDGET_001",
  name: "Operating Budget"
}
```

## Industry Pack Impact

Industry packs affect customization:

1. **Pack Selection**: Determines which templates are available
2. **Default Values**: Pack provides default configurations
3. **Industry-Specific**: Pack provides industry-appropriate defaults
4. **Customization**: You can override pack defaults

**Example:**

* **Healthcare Pack**: Provides location types (CENTRAL\_STORE, WARD, PHARMACY)
* **Retail Pack**: Provides location types (STORE\_FRONT, BACKROOM, MFC)
* **Your Override**: You can add custom location types to either pack

## Best Practices

### 1. Start with Pack Defaults

* Use pack defaults when they fit your needs
* Only override when necessary
* Document why you're overriding

### 2. Use Custom Values Sparingly

* Prefer standard values when possible
* Use CUSTOM/OTHER only when needed
* Document custom values

### 3. Understand Dependencies

* Some configurations depend on others
* Changing one may affect others
* Test changes in non-production first

### 4. Document Customizations

* Document why you customized
* Document what you changed
* Keep customization records

***

## Related Pages

* [Configuration Map](/govern/configuration-map)
* [Industry Packs](/concepts/industry-packs)
* [Organization Settings](/govern/organization-settings)

***

## Permissions & Roles

<Warning>
  Understanding the customization model is essential for safe configuration. Incorrect customization can break system functionality. Contact support if you're unsure about customizing a configuration.
</Warning>