​

Customization Model

​

Configuration Tiers

​

SYSTEM_FIXED

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

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

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

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

​

TEMPLATED_OVERRIDE (Pack Defaults + Tenant Override)

• 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

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)

• 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

• ✅ 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)

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

• 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

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

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

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

​

How Templates Work

1. Pack Seeding: Industry pack seeds templates
   Copy

   // Pack provides template
   PaymentTermTemplateSimple {
     code: "NET_30",
     name: "Net 30 Days",
     days: 30
   }
   
2. Tenant Override: Tenant can use template or override
   Copy

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

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

• 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

​

Common Patterns

​

Pattern 1: Enum with “CUSTOM” or “OTHER”

enum IdentifierType {
  GTIN,
  UPC,
  EAN,
  CUSTOM // ← Allows custom identifier types
}

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

​

Pattern 2: Template + Tenant Model

// 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 creates all
BudgetCode {
  organizationId: "org_123",
  code: "BUDGET_001",
  name: "Operating Budget"
}

​

Industry Pack Impact

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

• 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
• Industry Packs
• Organization Settings

​

Permissions & Roles