Better Data

Admin

Customization Model

Edit this page

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

    1"cmt">// Pack provides template
    2PaymentTermTemplateSimple {
    3  code: "NET_30",
    4  name: "Net 30 Days",
    5  days: 30
    6}

  2. Tenant Override: Tenant can use template or override

    1"cmt">// Tenant uses template as-is
    2PaymentTermSimple {
    3  templateId: "template_123",
    4  "cmt">// Uses template defaults
    5}
    6 
    7"cmt">// Tenant overrides template
    8PaymentTermSimple {
    9  templateId: "template_123",
    10  days: 45, "cmt">// Override: changed from 30 to 45
    11}
    12 
    13"cmt">// Tenant creates custom (no template)
    14PaymentTermSimple {
    15  code: "CUSTOM_TERM",
    16  name: "Custom Payment Term",
    17  days: 60
    18}

  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 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:

1enum IdentifierType {
2  GTIN,
3  UPC,
4  EAN,
5  CUSTOM "cmt">// ← Allows custom identifier types
6}

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:

1"cmt">// Template (pack)
2PaymentTermTemplateSimple {
3  code: "NET_30",
4  name: "Net 30 Days"
5}
6 
7"cmt">// Tenant instance
8PaymentTermSimple {
9  templateId: "template_123",
10  "cmt">// Can override template values
11  days: 45 "cmt">// Override
12}

Pattern 3: Tenant-Scoped Reference Data

No templates, tenant defines all:

1"cmt">// No templates, tenant creates all
2BudgetCode {
3  organizationId: "org_123",
4  code: "BUDGET_001",
5  name: "Operating Budget"
6}

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

Permissions & Roles